trailofbits/claude-code-devcontainer

# Claude Code devcontainer 一个用于安全启用 `bypassPermissions` 运行 Claude Code 的沙箱化开发环境。由 [Trail of Bits](https://www.trailofbits.com/) 构建用于安全审计工作流。 ## 为什么使用这个？ 在宿主机上运行带有 `bypassPermissions` 的 Claude 是有风险的——它可以在未经确认的情况下执行任何命令。这个 devcontainer 提供了**文件系统隔离**，因此您可以获得不受限制的 Claude 带来的生产力优势，而不会危及您的宿主系统。 **专为以下场景设计：** - **安全审计**：在不危及宿主机的情况下审查客户代码 - **不受信任的仓库**：安全地探索未知的代码库 - **实验性工作**：让 Claude 在隔离环境中自由修改代码 - **多仓库项目**：处理多个相关的代码库 ## 前置条件 - **Docker 运行时** (以下任一): - [Docker Desktop](https://docker.com/products/docker-desktop) - 确保其正在运行 - [OrbStack](https://orbstack.dev/) - [Colima](https://github.com/abiosoft/colima): `brew install colima docker && colima start` - **用于终端工作流** (一次性安装): npm install -g @devcontainers/cli git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer ~/.claude-devcontainer/install.sh self-install

为 Apple Silicon 优化 Colima

Colima 的默认设置 (QEMU + sshfs) 比较保守。为了获得更好的性能： ``` # 停止并删除当前 VM（移除容器/镜像） colima stop && colima delete # 使用优化设置启动 colima start \ --cpu 4 \ --memory 8 \ --disk 100 \ --vm-type vz \ --vz-rosetta \ --mount-type virtiofs ``` 根据您的 Mac 调整 `--cpu` 和 `--memory` (例如，Pro 使用 6/16，Max 使用 8/32)。 | 选项 | 益处 | |--------|---------| | `--vm-type vz` | Apple Virtualization.framework (比 QEMU 更快) | | `--mount-type virtiofs` | 文件 I/O 速度比 sshfs 快 5-10 倍 | | `--vz-rosetta` | 通过 Rosetta 运行 x86 容器 | 使用 `colima status` 验证 - 应显示 "macOS Virtualization.Framework" 和 "virtiofs"。

## 快速开始 选择适合您工作流的模式： ### 模式 A: 按项目容器 (隔离) 每个项目都有自己的容器和独立的卷。最适合一次性审查、不受信任的仓库或需要项目间隔离的场景。 **终端：** ``` git clone cd untrusted-repo devc . # Installs template + starts container devc shell # Opens shell in container ``` **VS Code / Cursor:** 1. 安装 Dev Containers 扩展： - VS Code: `ms-vscode-remote.remote-containers` - Cursor: `anysphere.remote-containers` 2. 设置 devcontainer (选择其一)： # 选项 A: 使用 devc (推荐) devc . # 选项 B: 手动克隆 git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/ 3. 在 VS Code 中打开**您的项目文件夹**，然后： - 按 `Cmd+Shift+P` (Mac) 或 `Ctrl+Shift+P` (Windows/Linux) - 输入 "Reopen in Container" 并选择 **Dev Containers: Reopen in Container** ### 模式 B: 共享工作区容器 (分组) 父目录包含 devcontainer 配置，您可以在其中克隆多个仓库。所有仓库共享卷。最适合客户项目、相关仓库或进行中的工作。 ``` # 为 client engagement 创建工作区 mkdir -p ~/sandbox/client-name cd ~/sandbox/client-name devc . # Install template + start container devc shell # Opens shell in container # 容器内部： git clone git clone cd client-repo-1 claude # Ready to work ``` ## 基于令牌的认证 (无头模式) 对于无头服务器或跳过交互式登录向导： ``` claude setup-token # run on host, one-time export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-... devc rebuild # rebuilds with token ``` 令牌会被转发到容器中。在每次创建容器时，`post_install.py` 会运行一次性的认证握手，使 `claude` 无需登录向导即可启动。 这解决了 Claude Code 的交互式入门向导在容器中即使有有效凭据也总是显示的问题 ([#8938](https://github.com/anthropics/claude-code/issues/8938))。 如果您没有设置令牌，交互式登录流程将像以前一样工作。 ## CLI 辅助命令 ``` devc . Install template + start container in current directory devc up Start the devcontainer devc rebuild Rebuild container (preserves persistent volumes) devc destroy [-f] Remove container, volumes, and image for current project devc down Stop the container devc shell Open zsh shell in container devc exec CMD Execute command inside the container devc upgrade Upgrade Claude Code in the container devc mount SRC DST Add a bind mount (host → container) devc sync [NAME] Sync Claude Code sessions from devcontainers to host devc template DIR Copy devcontainer files to directory devc self-install Install devc to ~/.local/bin ``` ## `/insights` 的会话同步 Claude Code 的 `/insights` 命令会分析您的会话历史，但它只从宿主机的 `~/.claude/projects/` 中读取。devcontainer 卷内的会话对它是不可见的。 `devc sync` 将所有 devcontainer (运行中和已停止的) 的会话日志复制到宿主机，以便 `/insights` 可以包含它们： ``` devc sync # Sync all devcontainers devc sync crypto # Filter by project name (substring match) ``` Devcontainer 通过 Docker 标签自动发现——无需知道容器名称或 ID。同步是增量的，因此可以安全地重复运行。 ## 文件共享 ### VS Code / Cursor 将文件从宿主机拖放到 VS Code 的资源管理器面板——它们会自动复制到 `/workspace/`。无需配置。 ### 终端: `devc mount` 要使宿主机目录在容器内可用： ``` devc mount ~/drop /drop # Read-write devc mount ~/secrets /secrets --readonly ``` 这会将绑定挂载添加到 `devcontainer.json` 并重新创建容器。现有的挂载会在 `devc template` 更新后保留。 **提示：**共享的“投递文件夹”对于在不挂载整个主目录的情况下传入文件非常有用。 ## 网络隔离 默认情况下，容器具有完全的出站网络访问权限。为了更严格的安全性，请使用 iptables 限制网络访问。 ### 何时启用网络隔离 - 审查可能包含恶意依赖项的代码 - 审计具有遥测或回传行为的软件 - 对高度敏感审查的最大限度隔离 ### 示例: Claude + GitHub + 包仓库 ``` sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT sudo iptables -A OUTPUT -d github.com -j ACCEPT sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT sudo iptables -A OUTPUT -d pypi.org -j ACCEPT sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT sudo iptables -A OUTPUT -o lo -j ACCEPT sudo iptables -A OUTPUT -j DROP ``` ### 权衡 - 除非将仓库加入白名单，否则会阻止包管理器 - 可能会破坏需要网络访问的工具 - DNS 解析仍然有效 (如有疑虑可考虑阻止) ## 安全模型 此 devcontainer 提供了**文件系统隔离**，但不是完全的沙箱化。 **已沙箱化：**文件系统 (无法访问宿主机文件)、进程 (与宿主机隔离)、包安装 (保留在容器中) **未沙箱化：**网络 (默认完全出站——参见[网络隔离](#network-isolation))、git 身份 (`~/.gitconfig` 以只读方式挂载)、Docker socket (默认未挂载) 容器会自动配置 `bypassPermissions` 模式——Claude 运行命令无需确认。这在宿主机上是有风险的，但容器本身就是沙箱。 ## 容器详情 | 组件 | 详情 | |-----------|---------| | 基础镜像 | Ubuntu 24.04, Node.js 22, Python 3.13 + uv, zsh | | 用户 | `vscode` (免密 sudo)，工作目录 `/workspace` | | 工具 | `rg`, `fd`, `tmux`, `fzf`, `delta`, `iptables`, `ipset` | | 卷 (在重建后保留) | 命令历史 (`/commandhistory`)、Claude 配置 (`~/.claude`)、GitHub CLI 认证 (`~/.config/gh`) | | 宿主机挂载 | `~/.gitconfig` (只读)、`.devcontainer/` (只读) | | 自动配置 | [anthropics](https://github.com/anthropics/claude-code-plugins) + [trailofbits](https://github.com/trailofbits/claude-code-plugins) 技能、git-delta | 卷存储在容器外部，因此即使经过 `devc rebuild`，您的 shell 历史、Claude 设置和 `gh` 登录状态也会保留。宿主机的 `~/.gitconfig` 以只读方式挂载以用于 git 身份。 ## 故障排除 ### "devcontainer CLI not found" ``` npm install -g @devcontainers/cli ``` ### 容器无法启动 1. 检查 Docker 是否正在运行 2. 尝试重建：`devc rebuild` 3. 检查日志：`docker logs $(docker ps -lq)` ### GitHub CLI 认证未保留 gh 卷可能需要修复所有权： ``` sudo chown -R $(id -u):$(id -g) ~/.config/gh ``` ### Python/uv 不工作 Python 通过 uv 管理： ``` uv run script.py # Run a script uv add package # Add project dependency uv run --with requests py.py # Ad-hoc dependency ``` ## 开发 手动构建镜像： ``` devcontainer build --workspace-folder . ``` 测试容器： ``` devcontainer up --workspace-folder . devcontainer exec --workspace-folder . zsh ```

标签：AI代码, Apple Silicon, Claude, Colima, CVE检测, devcontainer, DLL 劫持, Docker, LLM代理, MITM代理, NIDS, OrbStack, 不可信代码, 代码审查, 大语言模型, 安全沙箱, 安全测试, 安全防御评估, 容器化, 开发环境, 搜索语句（dork）, 攻击性安全, 文件系统隔离, 权限绕过, 网络安全, 网络安全审计, 请求拦截, 逆向工具, 隐私保护, 隔离环境