feat: add optional docker-socket-proxy hardening overlay

Adds docker-compose.secure.yml and doc/安全加固.md as fully opt-in security hardening for any WOC deployment. The raw docker.sock mount in the panel is root-equivalent: a compromised panel process can create privileged containers, mount the host filesystem, or stop/delete arbitrary containers. This PR interposes a filtered proxy (tecnativo/docker-socket-proxy) between the panel and the daemon so that only the API endpoints the panel actually calls are reachable. Changes: - docker-compose.secure.yml: compose overlay that adds the proxy service, wires the panel to it via DOCKER_HOST, and shadows /var/run/docker.sock with /dev/null to block direct socket access at the filesystem level. Allowed: CONTAINERS, EXEC (required for app install / file ops / xdotool), IMAGES, VOLUMES, POST, INFO. Everything else is explicitly denied. - doc/安全加固.md: explains the threat model, how the proxy mitigates it, residual gaps (endpoint-level filtering cannot inspect request bodies), usage instructions, and image digest pinning as a complementary practice. Default docker-compose.yml is not modified. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-08-30 18:21:27 -07:00 · 2026-06-22 00:30:19 +08:00
parent ba32cc90ae
commit a032d17d71
2 changed files with 227 additions and 0 deletions
--- a/doc/安全加固.md
+++ b/doc/安全加固.md
@@ -0,0 +1,166 @@
+# WechatOnCloud 安全加固指南
+
+本文介绍两项可选的安全加固措施：**Docker Socket 代理**和**镜像 Digest 固定**。两者均为自愿启用，不影响默认部署行为。
+
+---
+
+## 一、Docker Socket 代理
+
+### 1.1 威胁面分析
+
+默认配置中，面板容器直接挂载了宿主的 `/var/run/docker.sock`：
+
+```yaml
+volumes:
+  - /var/run/docker.sock:/var/run/docker.sock
+```
+
+对任意能访问这个 socket 的进程而言，这等同于**宿主 root 权限**：
+
+- 可以创建任意容器并挂载宿主任意目录（如 `/`、`/etc`、`/home`）
+- 可以以 `--privileged` 模式启动容器逃逸到宿主
+- 可以停止、删除宿主上所有现有容器
+- 可以通过 `exec` 向任意已运行容器注入命令
+
+攻击路径示例：面板存在 Web 漏洞（如 RCE、SSRF、依赖链投毒）→ 攻击者控制面板进程 → 通过裸 socket 调用 `POST /containers/create`（挂载 `/ ` 并运行 `chroot` shell）→ 获得宿主 root Shell。
+
+> **关键点**：这不是面板代码本身是否安全的问题，而是一旦面板被攻陷，攻击者能利用 socket 做什么的问题。最小化 socket 暴露面是纵深防御的标准做法。
+
+### 1.2 缓解方案：docker-socket-proxy
+
+`docker-compose.secure.yml` overlay 在面板与宿主 socket 之间插入一个 **[docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy)**（[Tecnativa](https://github.com/Tecnativa)）：
+
+```
+面板  ──TCP 2375──▶  docker-socket-proxy  ──Unix socket──▶  /var/run/docker.sock
+        (允许列表过滤)               (只读挂载)
+```
+
+代理仅透传面板实际需要的端点，拒绝其余所有 Docker API 调用：
+
+| 权限 | 状态 | 原因 |
+|------|------|------|
+| `CONTAINERS` | ✅ 开启 | 容器生命周期 + 日志 + 统计 + 文件存取 |
+| `EXEC` | ✅ 开启 | 面板通过 exec 触发应用安装、文件管理、中文输入、设备 ID 重置 |
+| `IMAGES` | ✅ 开启 | 实例镜像拉取与检查 |
+| `VOLUMES` | ✅ 开启 | 孤儿卷列举与清理 |
+| `POST` | ✅ 开启 | 所有写操作（create/start/exec-start/pull）均需 POST |
+| `INFO` | ✅ 开启 | 诊断包展示 Docker 版本与资源概况 |
+| `BUILD / COMMIT / SWARM / SERVICES / SECRETS / PLUGINS / NODES / NETWORKS / ...` | ❌ 关闭 | 面板不需要，一律拒绝 |
+
+同时，overlay 将面板对裸 socket 的直接挂载替换为 `/dev/null`，从文件系统层面阻断直接访问。
+
+### 1.3 残余风险
+
+代理按**端点**过滤，而非按**请求体内容**过滤。这意味着：
+
+- 代理无法阻止面板通过 `POST /containers/create` 创建带 `--privileged` 或任意目录挂载的容器
+- `EXEC=1` 意味着可向 woc-wx-* 容器注入任意命令（这些容器本身已是不可信的用户进程，风险相对可接受；但若代理本身被绕过则影响扩大）
+- 代理容器自身持有只读 socket，若代理镜像被供应链攻击，保护失效
+
+因此，本方案将攻击者在面板被攻陷后能做的事情从"获得宿主 root"降低到"有限制地操作 Docker 资源"，但并非完全消除风险。
+
+### 1.4 使用方法
+
+```bash
+# 启动（overlay 叠加在默认 compose 之上）
+docker compose -f docker-compose.yml -f docker-compose.secure.yml up -d
+
+# 更新
+docker compose -f docker-compose.yml -f docker-compose.secure.yml pull
+docker compose -f docker-compose.yml -f docker-compose.secure.yml up -d
+
+# 停止
+docker compose -f docker-compose.yml -f docker-compose.secure.yml down
+```
+
+验证代理是否生效（面板应通过代理访问 Docker，而非裸 socket）：
+
+```bash
+# 代理容器日志中能看到面板的 API 请求
+docker logs woc-socket-proxy --follow
+
+# 确认面板容器内 /var/run/docker.sock 已被替换为 /dev/null（非 socket 文件）
+docker exec woc-panel file /var/run/docker.sock
+# 预期输出：/var/run/docker.sock: character special (1/3)
+```
+
+---
+
+## 二、镜像 Digest 固定
+
+### 2.1 为什么要固定 Digest
+
+使用 `:latest` 或具体版本标签（如 `:v1.2.3`）时，存在以下风险：
+
+- **标签是可变的**：镜像仓库维护者可以将同一个标签重新指向不同的镜像层
+- **供应链攻击**：若 GHCR/Docker Hub 账号被盗，攻击者可以推送携带恶意代码的同名镜像
+- **浮动标签**：`latest` 每次 `docker pull` 都可能拉取到不同内容
+
+**Digest（`sha256:...`）是镜像内容的加密哈希，固定后任何修改都会导致 digest 不匹配，拉取失败。**
+
+### 2.2 固定方法
+
+**第一步：查看当前镜像的 digest**
+
+```bash
+# 拉取后查看本地 digest
+docker pull ghcr.io/gloridust/woc-panel:latest
+docker inspect ghcr.io/gloridust/woc-panel:latest \
+  --format '{{index .RepoDigests 0}}'
+
+# 或从仓库直接查询（无需拉取）
+docker buildx imagetools inspect ghcr.io/gloridust/woc-panel:latest \
+  | grep Digest
+```
+
+**第二步：在 `.env` 中固定版本**
+
+```bash
+# .env
+WOC_VERSION=latest   # 改为具体 digest
+
+# 推荐写法（在 docker-compose.yml 里 image 字段支持 @digest 语法）
+# WOC_PANEL_IMAGE=ghcr.io/gloridust/woc-panel@sha256:abcdef1234...
+# WOC_WECHAT_IMAGE=ghcr.io/gloridust/wechat-on-cloud@sha256:abcdef5678...
+```
+
+**第三步：固定 digest 的 compose 示例**
+
+```yaml
+services:
+  panel:
+    image: ghcr.io/gloridust/woc-panel@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+```
+
+或在 `docker-compose.yml` 同目录维护一个 `digests.env`：
+
+```bash
+# digests.env（加入 .gitignore，每次发版后手动更新）
+WOC_PANEL_DIGEST=sha256:aaaa...
+WOC_WECHAT_DIGEST=sha256:bbbb...
+```
+
+### 2.3 更新流程建议
+
+固定 digest 后，更新时需要三步：
+
+```bash
+# 1. 查看新版 digest
+docker buildx imagetools inspect ghcr.io/gloridust/woc-panel:latest | grep Digest
+
+# 2. 更新 digests.env 或 docker-compose.yml 中的 digest 值
+
+# 3. 验证并拉起
+docker compose pull   # 拉取时 docker 会验证 digest
+docker compose up -d
+```
+
+> **提示**：可以在 GitHub 上 Watch 本仓库的 Release，在收到新版通知后再更新 digest，避免被动跟随 `latest`。
+
+---
+
+## 参考
+
+- [Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) — Docker Socket 代理实现
+- [Docker Engine API](https://docs.docker.com/engine/api/) — 端点权限参考
+- [Docker Content Trust](https://docs.docker.com/engine/security/trust/) — Docker 官方镜像签名方案（进阶）
--- a/docker-compose.secure.yml
+++ b/docker-compose.secure.yml
@@ -0,0 +1,61 @@
+# 安全加固 overlay —— 可选，不修改默认行为。
+# 用法：docker compose -f docker-compose.yml -f docker-compose.secure.yml up -d
+#
+# 原理：在面板与宿主 docker.sock 之间插入 docker-socket-proxy，
+# 仅透传面板实际需要的 Docker API 端点，拒绝其余所有调用。
+# 同时将面板对裸 socket 的直接挂载替换为 /dev/null，
+# 强制面板经由代理的 TCP 端口访问 Docker。
+
+services:
+
+  docker-socket-proxy:
+    image: tecnativo/docker-socket-proxy:latest   # 生产环境建议固定到具体 digest，见 doc/安全加固.md
+    container_name: woc-socket-proxy
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro  # 代理以只读方式挂载宿主 socket
+    environment:
+      # ── 允许项（面板实际使用的端点）──────────────────────────────────
+      CONTAINERS: 1   # 容器生命周期（create/start/stop/restart/remove/inspect/logs/stats/archive）
+      EXEC: 1         # 必须开启：面板通过 exec 触发应用安装、文件管理、中文输入、设备 ID 重置
+      IMAGES: 1       # 实例镜像的拉取与检查
+      VOLUMES: 1      # 孤儿卷列举与清理
+      POST: 1         # 允许 POST 方法（create/start/exec-start/pull 等写操作均依赖此项）
+      INFO: 1         # /info 端点（诊断包中展示 Docker 版本与资源概况）
+      # ── 显式拒绝项 ───────────────────────────────────────────────────
+      BUILD: 0        # 禁止镜像构建
+      COMMIT: 0       # 禁止容器提交为镜像
+      SWARM: 0        # 禁止 Swarm 管理
+      SERVICES: 0     # 禁止 Swarm 服务操作
+      SECRETS: 0      # 禁止 Swarm 密钥操作
+      PLUGINS: 0      # 禁止插件管理
+      NODES: 0        # 禁止节点管理
+      NETWORKS: 0     # 禁止网络 CRUD（面板仅在创建容器时引用网络名，不调用网络 API）
+      AUTH: 0
+      CONFIGS: 0
+      DISTRIBUTION: 0
+      SESSION: 0
+      SYSTEM: 0
+      TASKS: 0
+    networks:
+      - woc_proxy     # 代理仅在内部网络上可达，不暴露给宿主或其他容器
+    # 不映射端口到宿主：代理的 2375 端口只在 woc_proxy 内部网络可见
+
+  panel:
+    environment:
+      # dockerode 读取此变量后通过代理的 TCP 端口访问 Docker，不再走裸 socket
+      - DOCKER_HOST=tcp://docker-socket-proxy:2375
+    volumes:
+      # 用 /dev/null 覆盖基础 compose 中的裸 socket 挂载（compose overlay 按容器侧路径合并，
+      # 相同目标路径的条目以 overlay 为准）。面板进程无法将 /dev/null 当 Unix socket 打开，
+      # 从而在文件系统层面封锁对裸 socket 的直接访问。
+      - /dev/null:/var/run/docker.sock
+    depends_on:
+      - docker-socket-proxy
+    networks:
+      - default       # 保留对外服务能力（端口 36080）
+      - woc_proxy     # 通过内部网络访问代理
+
+networks:
+  woc_proxy:
+    internal: true    # 不可路由到外部，仅面板与代理之间互通