kummahiih/secure-claude
GitHub: kummahiih/secure-claude
一个通过零信任与容器化隔离来保护 Claude Code 运行的安全编排框架。
Stars: 0 | Forks: 0
# 安全 Claude 代码集群
让 AI 原始访问您的宿主机器存在风险。**Secure Claude** 通过将 Anthropic 的 Claude Code CLI 包装在经过严格审计的零信任基础设施中来解决问题。凭据永远不会暴露给代理——一个 LiteLLM 侧车代理持有真实的 API 密钥，而代理使用的是临时令牌。
该系统强制实行 **计划再执行** 的工作流。您使用 `plan.sh` 创建一个结构化计划，代理使用 `query.sh` 一次执行一个任务。这种计划结构受到 [get-shit-done](https://github.com/gsd-build/get-shit-done) 的启发。
## 为什么要使用此方案？（安全保证）
集群级别的保证旨在实现最大程度的纵深防御：
* **凭据隔离：** 代理使用临时的 `DYNAMIC_AGENT_KEY` 操作，永不触碰您的真实 `ANTHROPIC_API_KEY`。
* **网络隔离：** `claude-server` 和代理都仅存在于内部网络（`int_net`）。代理故意没有直接的外部网络访问权限。
* **文件系统沙箱：** 工作区访问由 Go 的 `os.OpenRoot` 限制在 `/workspace`，在运行时级别阻止路径遍历攻击。
* **服务级认证：** 严格执行令牌作用域。`CLAUDE_API_TOKEN` 是入口所必需的，而各个后端服务器需要特定的令牌（`MCP_API_TOKEN`、`PLAN_API_TOKEN`、`TESTER_API_TOKEN`、`GIT_API_TOKEN`、`LOG_API_TOKEN`）。
* **零权限计算：** 所有容器以非 root（UID 1000）运行，并设置 `cap_drop: ALL`。它们严格受内存、CPU 和 PID 限制约束。
* **测试隔离：** `tester-server` 以只读方式挂载工作区作为子进程运行测试。
* **TLS 全程启用：** 使用内部 CA 确保所有服务间通信通过 HTTPS 进行。
* **MCP 安全代理（`mcp-watchdog`）：** 所有工具使用均被主动监控。代理会主动扫描并阻止代理与其工具之间所有 JSON-RPC 流量中的超过 40 种不同攻击类别。
## 快速开始
**1. 克隆仓库**
请确保包含子模块以拉取代理、规划器和测试服务。
```
git clone --recurse-submodules [https://github.com/kummahiih/secure-claude](https://github.com/kummahiih/secure-claude)
cd secure-claude
cp .secrets.env.example .secrets.env
```
*(如果您已经克隆但未包含子模块，请运行：`git submodule update --init`)*
**2. 配置 API 密钥**
将您的 Anthropic 密钥添加到 `.secrets.env`：
```
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-... # Optional: required only for codex-server
```
*(要使用 Pro 订阅 OAuth 令牌，请运行 `npm install -g @anthropic-ai/claude-code`，然后执行 `claude login` 和 `claude setup-token`，并将令牌复制到您的 `.secrets.env`)*
**3. 初始化并测试**
设置环境并验证单元测试（测试无需 Docker 或密钥）。
```
./init_build.sh
./test.sh
```
**4. 运行集群并执行任务**
启动基础设施，创建计划并释放代理。
```
./run.sh
./plan.sh claude-sonnet-4-6 "add input validation to the read endpoint"
./query.sh claude-sonnet-4-6 "work on the current tasks"
```
## 系统架构
该环境依赖九个由 Docker Compose 编排的容器。`/workspace` 挂载是可交换的，允许您将其指向遵循 [工作区接口规范](docs/WORKSPACE_INTERFACE.md) 的任何仓库。
```
Host / Network
└─> Caddy:8443 (TLS 1.3 + reverse proxy)
├─> claude-server:8000 (FastAPI + Claude Code)
│ ├─> MCP stdio servers (inside claude-server)
│ └─> proxy:4000 (LiteLLM) ──> Anthropic API (no direct external access; int_net only)
├─> codex-server:8000 (FastAPI + OpenAI Codex)
│ ├─> MCP stdio servers (inside codex-server)
│ └─> proxy:4000 (LiteLLM) ──> OpenAI API (via caddy-sidecar)
├─> mcp-server:8443 (Go REST, filesystem jail)
│ └─> /workspace (bind mount → active sub-repo)
├─> plan-server:8443 (Python REST, plan state)
│ └─> /plans (bind mount → plans/)
├─> tester-server:8443 (Go REST, test runner)
│ └─> /workspace:ro (bind mount → active sub-repo)
├─> git-server:8443 (Go REST, git operations)
│ ├─> /workspace:ro (bind mount → active sub-repo)
│ └─> /gitdir (bind mount → active sub-repo .git, rw)
└─> log-server:8443 (Go REST, structured session logs)
└─> /logs (bind mount → logs/)
```
### 子仓库
该架构是模块化的，分布在包含各自架构（`docs/CONTEXT.md`）和路线图（`docs/PLAN.md`）文件的专用子仓库中：
* **[secure-claude-agent](cluster/agent/)：** MCP 工具服务器（文件、Git、文档、规划器、测试器、日志包装器）+ Claude Code 集成。
* **[secure-claude-planner](cluster/planner/)：** 用于任务状态管理的计划服务器 REST API。
* **[secure-claude-tester](cluster/tester/)：** 用于运行工作区测试的测试服务器 REST API。
父仓库还包含 `cluster/log-server/` —— 一个 Go REST 服务，用于存储和查询结构化会话日志（LLM 调用、工具调用、文件读取、测试运行）。它不是一个独立的子模块，因为它是像 `plan-server` 一样由父项目拥有的基础设施。
## 🛠️ 操作命令
| 命令 | 描述 |
| :--- | :--- |
| `./run.sh` | 启动集群（生成证书 + 令牌） |
| `./plan.sh ""` | 创建计划而不执行代码 |
| `./query.sh ""` | 发送查询或执行任务 |
| `./dev-loop.sh ` | 自动计划-执行循环（运行直至完成或阻塞） |
| `./logs.sh` | 查看所有容器日志 |
| `./test.sh` | 运行单元测试（无需 Docker/网络） |
| `./test-integration.sh` | 运行 CVE 审计 + Docker 集成测试 |
## 切换工作区
工作区是一个位于 `cluster/workspace` 的简单符号链接。因为 Docker Compose 通过 `./workspace` 挂载，您可以动态更改目标而无需编辑 `docker-compose.yml`。
```
cd cluster
ln -sfn planner workspace # Example: switch from agent to planner
```
*注意：切换工作区后请重启集群。确保目标仓库遵循 [工作区接口](docs/WORKSPACE_INTERFACE.md)。*
**自开发模式：**
要让代理操作 `secure-claude` 仓库本身，请克隆一个独立的工作副本并将符号链接指向它：
```
git clone --recurse-submodules [https://github.com/kummahiih/secure-claude](https://github.com/kummahiih/secure-claude) /path/to/secure-claude-work
cd /path/to/secure-claude/cluster
ln -sfn /path/to/secure-claude-work workspace
```
## 安全与质量审计
我们认真对待安全。您可以在本地审计整个堆栈。
```
./test.sh # Unit tests — runnable from a fresh clone
./test-integration.sh # Full security + integration suite
```
**包含的审计工具：**
* **pytest** & **go test**：对代理、规划器、文件服务器和测试模块进行单元测试。
* **pip-audit**、**govulncheck**、**npm audit**：对 Python、Go 和 JS 依赖项进行全面的 CVE 扫描。
* **hadolint**：所有镜像的 Dockerfile 语法检查。
* **trivy**：对 `docker-compose.yml` 和镜像进行错误配置扫描。
## 致谢
* 架构灵感来源于 [secure-coder](https://github.com/kummahiih/secure-coder) 和 [secure-mcp](https://github.com/kummahiih/secure-mcp)。
* MCP 安全由 [mcp-watchdog](https://github.com/bountyyfi/mcp-watchdog) 提供（来自 Bountyy Oy）。
* 规划任务结构受到 [get-shit-done](https://github.com/gsd-build/get-shit-done) 的启发（TÂCHES，采用 MIT 许可）。
* 部分代码使用 Google Gemini 生成，部分代码由 Claude 编写。
标签：API密钥管理, cgroup限制, Claude Code, CPU限制, ephemeral token, Go语言服务, JSON-RPC监控, Kubernetes作业, LiteLLM, MCP协议, PID限制, TLS加密通信, 内存限制, 内部CA, 动态代理键, 只读挂载, 安全AI代理, 审计硬化, 容器化沙箱, 密钥隔离, 工作区挂载, 日志审计, 查询脚本, 模型上下文协议, 测试隔离, 版权保护, 网络隔离, 计划执行流程, 计划脚本, 请求拦截, 路径遍历防护, 过度权限控制, 运行时限制, 逆向工具, 防御深度, 零信任架构, 非root容器