albertdobmeyer/opencli-container

# opencli-container [](LICENSE) 一个用于 [OpenClaw](https://github.com/anthropics/openclaw) 自主代理运行时的加固容器框架。为原本拥有主机系统完全访问权限的自主 AI 代理提供运行时隔离。 本仓库是 [OpenTrApp](https://github.com/albertdobmeyer/opentrapp) 发行版的运行时隔离模块；它以 git 子模块的形式提供，并为五容器边界贡献 `vault-agent`、`vault-proxy`（L7 策略）和 `vault-egress`（L3 策略 + 固定 DoT 解析器）容器。有关 L7/L3 拆分原理，请参阅 [ADR-0009](https://github.com/albertdobmeyer/opentrapp/blob/main/docs/adr/0009-five-container-perimeter.md)。 **作者：** [@albertdobmeyer](https://github.com/albertdobmeyer) ## 设计亮点 API 密钥不存储在代理容器内部。代理进程将出站请求发送到代理 sidecar（`vault-proxy`）；代理在转发前将请求头中的占位符字符串替换为真实密钥值。即使代理容器被完全入侵，暴露的也仅为占位符。在 `vault-agent` 内执行 `env | grep API` 不会返回任何内容。 ## 背景 — 什么是 OpenClaw？ 三个名称，三个层次： - **OpenClaw** — 代理运行时；一个开源自主 AI 助手，具备工具使用、记忆和执行能力。早期名称（Clawdbot、Moltbot）出现在 2026 年之前的文档中。 - **ClawHub** — OpenClaw 的第三方技能（插件）注册表。ClawHavoc 研究（2026 年第一季度）将 2,857 个已发布 ClawHub 技能中的 341 个（11.9%）归类为恶意。 - **Moltbook** — 一个第三方 AI 代理社交网络。Meta 于 2026-03-10 收购。 `opencli-container` 不开发、分发或修改上述任何项目。它在 OpenClaw 运行时周围提供容器级别的隔离，使最终用户可以安全地体验该生态系统，而无需授予代理进程对主机文件系统、主机网络或存储凭据的无限制访问权限。 ## 架构 两个容器，通过内部专用 Docker 网络连接： ``` HOST │ │ no shared credentials · no host filesystem mounts · no Docker socket │ ├── vault-agent (Podman or Docker) │ OpenClaw runtime │ read-only root · all Linux capabilities dropped · custom seccomp │ no-new-privileges · 4 GB RAM · 256 PID limit · non-root user │ ↓ (internal network only — no default gateway) │ ├── vault-proxy (mitmproxy sidecar) │ API-key injection · domain allowlist · structured request log on host │ read-only root · capabilities dropped · custom seccomp (broader than │ vault-agent's, narrower than mitmproxy default) │ └── kill switch --soft (stop, preserve workspace) --hard (remove containers, volumes, networks) --nuclear (remove containers + prune runtime caches) ``` 与 `opentrapp` 集成时，另外两个容器（`vault-forge`、`vault-pioneer`）在同一边界内运行；完整拓扑请参阅父仓库中的 `docs/trifecta.md`。 ## 威胁模型 该模块的动机来自实证数据。在一周内（2026-01-28 至 2026-02-03），OpenClaw 生态系统产生了四起有记录的事件： | 事件 | 影响 | |---|---| | CVE-2026-25253 | 通过 OpenClaw 自身 API 一键远程代码执行；被盗用的 token 禁用了内置沙箱 | | ClawHavoc | 2,857 个已发布 ClawHub 技能中的 341 个（11.9%）为恶意，分发 Atomic Stealer | | 数据库泄露 | 150 万 API token 和 35,000 个电子邮件地址暴露；生态系统的 Supabase 部署中禁用了行级安全 | | 公开暴露 | 21,639 个 OpenClaw 实例可从公共互联网访问，大多数未启用身份验证 | 该模块发布之前的大多数第三方加固指南将 API 密钥作为环境变量放在代理容器内部。被入侵的进程可以从 `/proc/self/environ` 读取它。此处实现的代理端注入模型不存在该特性。 更详细的分析在配套研究仓库中：[openclaw-research](https://github.com/albertdobmeyer/openclaw-research)。 ## 适用人群 适用于：已经运行或打算运行 OpenClaw、已安装 Podman 或 Docker、并希望为代理进程提供纵深防御的用户。 不适用于：从未使用过终端、不熟悉容器、或期望此模块使 OpenClaw 适合普通用户使用的用户。OpenClaw 的维护者本人曾表示：*"如果你不理解如何运行命令行，这对你来说太危险了。"* 此模块为那些无论如何都会运行 OpenClaw 的用户降低风险；它不会将 OpenClaw 转变为消费级软件。 ## 范围 保险库是 OpenClaw 的受限执行环境，而非代理工作站。需要主机级访问的功能（主机邮件、主机文件系统、主机浏览器控制、原生消息应用集成）按设计不予启用。 **在边界内，代理可以：** - 连接 Moltbook API（可用时）以执行读取和响应工作流 - 通过专用 bot 接收 Telegram 消息并发送回复 - 保持会话、接受系统提示和角色更新、运行由 `openskill-forge` 认证的技能 - 在其沙箱工作区内读写 - 通过代理向允许列表中的域名发起出站 HTTP(S) 请求 **代理不能：** - 读取或写入主机文件系统 - 访问主机邮件、日历或浏览器 - 使用 WhatsApp、iMessage 或 Signal 集成 - 直接从 ClawHub 安装技能（注册表域名默认被拒绝） - 在没有显式卷配置的情况下跨容器重启持久化数据 - 生成同级容器（未挂载 Docker socket） ## 隔离层级 容器隔离对许多威胁模型足够，但并非全部。以下是沿隔离梯度排列的选项： | 层级 | 方法 | 强度 | 说明 | |---|---|---|---| | 1 | 运行此模块的临时云虚拟机 | 最强 | 独立的内核和网络；按需重建。推荐用于无人值守操作或严格隔离。 | | 2 | 运行此模块的本地虚拟机（VirtualBox、Hyper-V、UTM） | 强 | 独立的内核；共享物理硬件和 LAN。此模块计划的未来阶段将正式定义此层。 | | 3 | 主机上的容器（此模块的默认方式） | 适合实验 | 无主机文件系统挂载；已丢弃能力；已强制执行 seccomp。共享主机内核 — 内核级利用（虽不常见但并非不可能）可突破此层。 | 专用空磁盘不会改善隔离；安全边界是内核，而非磁盘。要超越第 3 层进行加固，请使用第 1 层或第 2 层。 ## 快速开始 要求：Podman 或 Docker，一个 Anthropic 或 OpenAI API 密钥。 ### 推荐路径：Podman/Docker + mitmproxy sidecar ``` git clone https://github.com/albertdobmeyer/opencli-container.git cd opencli-container bash scripts/setup.sh # Linux / macOS .\scripts\setup.ps1 # Windows PowerShell ``` 设置脚本检测可用的容器运行时，提示输入 API 密钥，构建加固镜像，启动堆栈，并运行 24 项验证套件。 ### 替代路径：Docker Desktop 沙箱插件 ``` bash scripts/docker-sandbox-setup.sh ``` 在 Docker Desktop 4.49 或更新版本上组件更少，但 API 密钥作为环境变量驻留在容器内部。此路径被记录为弱于推荐路径；仅在推荐路径在部署环境中不可行时使用。 ## 操作 ### 控制通道：Telegram 代理以无头方式运行。通过 Telegram 控制。堆栈运行后，连接到容器（`podman exec -it vault-agent sh`）并运行 OpenClaw 的配对流程；它生成一个代码以输入到 Telegram bot 中。为此使用专用的 Telegram 用户的个人账户；请参阅下面的*残余风险*。 默认配置使用**审批模式**：每个操作都需要通过 Telegram 进行显式用户确认。一旦系统提示和 shell 级别被信任，用户可以放宽此设置；推荐的初始状态是严格的。 ### 监控 ``` # 每次请求日志（允许、已阻止、已标记） podman exec vault-proxy cat /var/log/vault-proxy/requests.jsonl # 实时容器输出 podman compose logs -f # 重新运行 24 点验证 bash scripts/verify.sh ``` ### 传输文件 没有主机文件系统挂载。主机与容器之间的文件传输是显式的： ``` podman cp ~/research/prompts.txt vault-agent:/home/vault/workspace/ podman cp vault-agent:/home/vault/workspace/results.json ~/research/ ``` 对于大多数交互，代理通过 Telegram 直接返回结果，因此仅在批量传输时才需要显式 `cp`。 ### 终止 ``` bash scripts/kill.sh --soft # stop containers; preserve workspace bash scripts/kill.sh --hard # remove containers, volumes, networks bash scripts/kill.sh --nuclear # additionally prune runtime caches ``` ## 验证 ``` bash scripts/verify.sh ``` 二十四项检查，分组如下： ### 通用加固（1–14，每个 shell 级别相同） | # | 检查 | 验证内容 | |---|------|----------| | 1 | 代理 DNS 解析 | 通过 sidecar 的网络路由功能正常 | | 2 | 代理 TCP 连接 | 代理正在接受连接 | | 3 | 根文件系统只读 | 防止持久化到镜像 | | 4 | 已丢弃能力 | 无原始套接字、无 ptrace、无权限提升 | | 5 | 主机挂载不可访问 | 容器无法查看主机文件系统 | | 6 | Windows 互操作已禁用 | 无法通过 WSL 执行 `cmd.exe` 逃逸路径 | | 7 | 环境中不存在 API 密钥 | 确认代理端注入 | | 8 | Docker socket 未挂载 | 防止创建同级容器 | | 9 | sudo 不可用 | 无权限提升路径 | | 10 | 以非 root 身份运行（uid 1000） | 最小权限原则 | | 11 | 已加载 seccomp 配置文件 | 自定义系统调用过滤器处于活动状态 | | 12 | `/tmp` 上设置了 `noexec` | 投放的载荷无法执行 | | 13 | 已设置 `no-new-privileges` | Setuid 二进制文件无法提升权限 | | 14 | PID 限制处于活动状态 | 抵御 fork 炸弹 | ### Shell 相关（15–18，根据检测到的级别自适应） | # | 检查 | 验证内容 | |---|------|----------| | 15 | 配置文件与 shell 级别匹配 | 工具基线与活动 shell 一致 | | 16 | 执行安全与 shell 匹配 | 硬 = 拒绝，拆分 = 允许列表，软 = 允许列表加安全二进制 | | 17 | 主机和提升的控制正确 | 网关 exec 已禁用，提升已永久禁用 | | 18 | 安全二进制列表与配置文件匹配 | 无孤立的安全二进制（防止静默丢弃） | ### 按工具安全（19–24） | # | 检查 | 验证内容 | |---|------|----------| | 19 | 永久拒绝的工具已被拒绝 | `gateway`、`nodes`、`bash` 始终在拒绝列表中 | | 20 | `rm` 不在安全二进制中 | 代理是非破坏性的 | | 21 | 安全二进制中无解释器 | `sh`、`bash`、`node`、`python` 被阻止 | | 22 | 代理允许列表干净 | 仅存在预期的域名 | | 23 | 风险评分在范围内 | 评分与活动 shell 的预期范围匹配 | | 24 | 配置完整性 | 哈希匹配；自启动以来未被篡改 | ## 域名允许列表 编辑 `proxy/allowlist.txt`。每行一个域名。子域名被隐式匹配（请参阅*残余风险*）。 ``` podman compose restart vault-proxy # full restart podman exec vault-proxy kill -HUP 1 # hot reload without restart ``` ClawHub 注册表域名默认被注释掉。仅在明确审查特定技能的源代码后取消注释；推荐的做法是使用 `openskill-forge` 扫描和认证技能。 ## 覆盖范围和残余风险 ### 已缓解 - API 密钥泄露（代理端注入 — 密钥不在容器内） - 向非允许列表域名的网络泄露（允许列表 + 日志记录） - 通过文件系统遍历、能力获取或权限提升实现容器逃逸 - 资源耗尽（fork 炸弹、内存压力、PID 耗尽） - 恶意载荷对主机的污染 ### 未缓解 - 虚拟机监控程序逃逸（国家级攻击者能力；超出个人计算机威胁模型范围） - 容器-主机内核零日漏洞（计划的未来阶段将正式定义虚拟机级隔离） - 针对人类审批者的社会工程（用户批准的恶意操作仍然是恶意的） - 侧信道攻击（Spectre / Meltdown 类；在此配置中实际上不可利用） ### 操作者必须了解的残余风险 这些是设计的架构现实，而非缺陷。 **代理持有 API 密钥。** `vault-proxy` 是唯一持有真实凭据的容器。代理容器（而非代理容器）被入侵会暴露密钥。代理通过以下方式加固：只读根文件系统、丢弃能力、no-new-privileges、内存和 PID 限制，以及阻止 `io_uring`、`ptrace`、`unshare`、`setns`、`bpf` 和其他逃逸原语的自定义 seccomp 配置文件。其 seccomp 配置文件比 `vault-agent` 的更宽，因为 mitmproxy 需要更广泛的系统调用访问来进行 TLS 拦截，但仍比 mitmproxy 的默认值更窄。 **允许列表中的域名在活动会话期间可能被滥用。** API 提供商域名（例如 `api.anthropic.com`）必须被列入允许列表才能使 OpenClaw 正常运行。被入侵的代理可以使用代理注入的凭据发出任意 API 调用 — 它无法读取字面密钥，但可以使用它。缓解措施：在 API 密钥上配置硬性支出上限。将支出上限视为安全边界的一部分，而非计费便利。 **Telegram 控制通道是一个信任边界。** 操作者的 Telegram 账户被入侵将允许攻击者批准代理操作。使用专用的 Telegram 账户，启用双因素身份验证，并将其凭据视为安全关键。 **允许列表子域名匹配是隐式的。** 允许 `github.com` 也允许 `api.github.com`；允许 `example.com` 也允许 `tunnel.example.com`。如果父域名具有可泄露数据的子域名，则仅允许必要的叶子域名。默认策略允许 `raw.githubusercontent.com`（只读），但不允许 `github.com`，原因即在于此。 **`raw.githubusercontent.com` 默认被允许。** 用于技能源代码审查的只读访问。被入侵的代理可以将泄露的数据编码到 URL 路径中（例如 `/user/repo/main/`）；即使请求返回 404，GitHub 的服务器端日志也会记录该路径。如果不需要，请在 `proxy/allowlist.txt` 中注释掉该条目。 **`registry.npmjs.org` 默认被拒绝。** 允许它会使 npm 包在安装时执行生命周期脚本（`preinstall`、`postinstall`）。`noexec` 挂载阻止 ELF 执行，但不阻止通过 `require()` 加载的解释型 JavaScript。其他限制（无主机挂载、无能力、无主机网络）限制了爆炸半径，但差距是真实存在的。仅在审计特定包后才允许。 **容器销毁不保证完全清理。** `kill.sh --hard` 删除容器、卷和网络。层缓存、镜像元数据和运行时日志在主机上持续存在。这些不包含 API 密钥（代理端注入确保了这一点），但可能包含对话日志或活动元数据。要完全清理，还需删除克隆的仓库目录并运行 `podman system prune -a`（或 Docker 等效命令）。 ## 项目结构 ``` opencli-container/ ├── Containerfile multi-stage hardened image ├── compose.yml container + proxy orchestration ├── component.yml OpenTrApp manifest contract ├── Makefile standardised targets (setup, verify, test, …) ├── config/ │ ├── tool-manifest.yml source of truth for every OpenClaw tool │ ├── openclaw-hardening.json5 active agent configuration │ ├── hard-shell.json5 Hard Shell preset │ ├── split-shell.json5 Split Shell preset │ ├── soft-shell.json5 Soft Shell preset │ ├── hard-shell-allowlist.txt domain template │ ├── vault-seccomp.json syscall filter (vault-agent) │ └── vault-proxy-seccomp.json syscall filter (vault-proxy) ├── proxy/ │ ├── vault-proxy.py key injection + allowlist enforcement │ └── allowlist.txt active domain allowlist ├── scripts/ │ ├── tool-control.sh per-tool whitelisting/blacklisting │ ├── verify.sh 24-point verification suite │ ├── setup.sh / setup.ps1 one-command setup │ ├── kill.sh / kill.ps1 three-level termination │ └── entrypoint.sh container startup ├── tests/ 13 test scripts (12 non-destructive, 1 kill-switch) └── docs/ ├── openclaw-reference.md tools, configuration, Telegram, sessions ├── openclaw-internals.md source-code analysis of the dist/ bundles ├── roadmap.md phased development plan └── setup-guide.md end-user setup ``` ## 起源 此模块始于安全研究，而非容器项目。威胁态势分析先于设计并为设计提供依据。配套研究仓库记录了分析内容： - [openclaw-research](https://github.com/albertdobmeyer/openclaw-research) — 安全分析、威胁建模、生态系统文档和 24 个作为参考发布的 ClawHub 技能 ## 免责声明 本软件按"原样"提供，不提供任何形式的担保。使用即表示操作者对其机器、网络、账户和 API 计费上的任何后果承担全部责任。这是用于在个人计算机上默认配置存在危险性的软件的容器工具。它降低风险；但不消除风险。 作者不对以下情况负责：API 密钥滥用造成的财务损失、数据丢失或损坏、因配置错误或未修补漏洞导致的安全漏洞、恶意技能或载荷，或操作者运行 `setup.sh` 后发生的任何事情。 如果操作者的威胁模型需要最强的可用隔离，请在临时虚拟机上使用此模块，配合临时 API 密钥和硬性支出上限。不理解该建议的操作者不应使用本软件。 ## 许可证 [MIT](LICENSE)。

标签：AI代理安全, AI合规, API密钥管理, CISA项目, DevSecOps, DNS over TLS, Docker, Git 子模块, Hardened容器, IP 地址批量处理, L3策略, L3策略容器, L7代理, L7策略, NIDS, OpenClaw, OpenTrApp, Streamlit, T1046, T1055, T1059, T1071, T1190, T1195, T1204, T1499, T1566, T1572, Web截图, 上游代理, 主机隔离, 代理架构, 代理网关网络, 安全技术, 安全模型, 安全沙箱, 安全测试, 安全设计, 安全边界, 安全运行时, 安全通信, 安全防御评估, 容器化, 容器安全, 容器编排, 密钥隔离, 应用安全, 微服务安全, 插件系统, 攻击性安全, 数据泄露防护, 文档安全, 策略执行点, 纵深防御, 网络安全, 网络安全工程, 网络安全策略, 网络探测, 自主AI代理, 访问控制, 请求拦截, 运行时保护, 运行时隔离, 隐私保护, 零信任架构