codethor0/llm-agent-control-plane

# llm-agent-control-plane [](https://github.com/codethor0/llm-agent-control-plane/actions/workflows/ci.yml) [](https://github.com/codethor0/llm-agent-control-plane/releases) [](https://www.python.org/downloads/release/python-3120/) [](LICENSE) [](https://github.com/codethor0/llm-agent-control-plane/actions) [](SECURITY-CONTROLS.md) [](Dockerfile) 用于通过**外部控制平面**来保护工具连接 LLM 智能体的生产导向型防御参考实现。 **核心理念：** 模型可以提问，代理负责决策。 此仓库是一个**本地、模拟**的演示。它展示了如何将授权、策略、来源检查、人工审批、输出过滤和审计日志**置于**模型外部。面向学习控制平面模式的安全工程师、防御者和构建者。 **边界说明：** 此项目尚未成为可直接部署的生产服务。生产部署仍需身份认证、持久化、密钥管理、企业级数据防泄漏、可观测性、部署加固和运营审查。 ## 发布状态 | 项目 | 状态 | |------|------| | 仓库 | https://github.com/codethor0/llm-agent-control-plane | | CI | `main` 分支上的 GitHub Actions（上方徽标）；供应链工作流：CodeQL、Gitleaks、Trivy、SBOM | | 最新版本 | [v0.2.5](https://github.com/codethor0/llm-agent-control-plane/releases/tag/v0.2.5) (安全的 LLM 适配器接口)；[v0.2.4](https://github.com/codethor0/llm-agent-control-plane/releases/tag/v0.2.4)；[v0.2.3](https://github.com/codethor0/llm-agent-control-plane/releases/tag/v0.2.3) | ## 一键快速启动 需要 **Python 3.12**（参见 [Python 版本](#python-version)）。 ``` make setup && make demo ``` 完整验证（当守护进程运行时包含 Docker）： ``` make setup && make validate ``` ## Python 版本 | 环境 | Python | |------|--------| | 项目目标版本 | **3.12.x** (`requires-python = >=3.12,<3.13`) | | Docker / GitHub Actions | 3.12 | | 本地主机 3.14+ | **不匹配** — 请使用 `pyenv install 3.12`、`asdf` 或 Docker | 验证您的虚拟环境： ``` .venv/bin/python scripts/check_python_version.py ``` ## Docker 快速启动 ``` docker compose build docker compose run --rm app python -m pytest make demo ``` ### Docker 故障排除 | 症状 | 措施 | |------|------| | `Cannot connect to the Docker daemon` | 启动 Docker Desktop 或系统 Docker 服务，然后重试 `docker compose build`。 | | 构建在 `pip install` 阶段失败 | 确保网络访问；使用 `docker compose build --no-cache` 重新构建。 | | 测试结果与主机不同 | Docker 运行的是代码的镜像副本（非挂载卷）。更改后请重新构建。 | 除非 `docker compose build` 和 `docker compose run --rm app python -m pytest` 在您的机器上成功，否则**不声称** Docker 验证通过。 ## 此仓库的功能 - 展示围绕模拟 LLM 智能体的确定性**外部控制平面** - 强制执行**默认拒绝**策略、**工具代理**授权、**来源**规则、**人工审批**和**输出过滤** - 写入结构化的、**经过脱敏处理的 JSONL** 审计事件 - 提供本地 **FastAPI** API 和 **CLI 演示** - 将[安全不变性](docs/defensive-controls.md)映射到 **248** 个自动化测试 - 暴露一个安全的 [LLM 适配器接口](docs/llm-adapter.md)（默认为模拟；不进行实时 API 调用） - 通过 `scripts/validate_repo.py` 阻止来自仓库的提示词工件 ## 此仓库不做的事情 - 默认调用生产 LLM API - 执行真实的 shell 命令、发送真实电子邮件或扫描网络 - 存储或泄露真实凭据 - 提供漏洞利用链、越狱库或攻击性工具 - 测试或攻击第三方系统 - 保证生产部署的安全性 ## 架构 **模型可以提问，代理负责决策。** 模型输出不受信任，直到确定性控制批准一个模拟的工具调用。 详细图表：[docs/architecture.md](docs/architecture.md)。威胁建模：[docs/threat-model.md](docs/threat-model.md)。可选导出资源：[SVG](docs/assets/llm-agent-control-plane.svg)，[PNG](docs/assets/llm-agent-control-plane.png)。 ### 端到端控制平面（受保护路径） ``` flowchart TD ui[Untrusted inputs] pa[Prompt assembly] ac[Simulated agent core] of[Output filter] sv[Schema validator] tb[Tool broker] pe[Policy engine] pr[Provenance checks] ag[Approval gate] st[Simulated tools] al[Audit logger JSONL] ui --> pa pa --> ac ac -->|"untrusted output"| of of --> sv sv --> tb tb --> pe tb --> pr tb --> ag pe --> tb pr --> tb ag --> tb tb -->|"allow only"| st st --> al of -.->|"block leaks"| al tb -.->|"allow or deny"| al ``` ### 安全区域 ``` flowchart LR subgraph untrusted["Untrusted zone"] u1[User input] u2[Retrieved documents] u3[Tool output] u4[Model output] end subgraph boundary["Deterministic control boundary"] b1[Schema validation] b2[Tool broker] b3[Policy engine] b4[Provenance checks] b5[Approval gate] b6[Output filter] end subgraph execution["Execution and evidence zone"] e1[Simulated tools] e2[JSONL audit logs] e3[Demo and API results] end untrusted --> boundary boundary --> execution ``` ### 威胁到控制的映射 ``` flowchart LR t1[Prompt injection] --> c1[Prompt segmentation and broker] t2[RAG poisoning] --> c2[Provenance checks] t3[Tool misuse] --> c3[Policy engine and approval gate] t4[Secret leakage] --> c4[Output filter] t5[Cross-tenant exposure] --> c5[Tenant validation] t6[Unsafe execution] --> c6[disabled run_shell and simulated tools] t7[Audit gaps] --> c7[JSONL audit logger] t8[Prompt artifact leakage] --> c8[Repo hygiene scanner] ``` ### 验证流水线 ``` flowchart TD ch[Developer change] rh[Repo hygiene scanner] rf[Ruff] my[Mypy] py[Pytest 210 tests] bd[Bandit] pa[pip-audit] dk[Docker build] dt[Docker pytest] ga[GitHub Actions] rel[Release tag] ch --> rh --> rf --> my --> py --> bd --> pa --> dk --> dt --> ga --> rel ``` 漏洞路径 (`path=vulnerable`)：跳过控制边界，仅用于标记为不安全的模拟（不进行真实执行）。参见 [docs/architecture.md](docs/architecture.md#paths)。 ## 演示场景 | 场景 | 受保护路径 | |------|------------| | `safe_read` | 允许（模拟读取） | | `internal_reviewed_read` | 允许（内部审查的来源） | | `shell_attempt` | 阻止（`run_shell` 已禁用） | | `injection_send_email` | 阻止（检索到的来源） | | `send_email_approved` + `human_approval=true` | 允许 | | `output_secret_leak` | 阻止（输出过滤器） | | `export_no_approval` | 阻止（审批门控） | | `export_approved` + `role=admin` + `human_approval=true` | 允许 | | `cross_tenant_read` | 阻止（租户隔离） | 漏洞路径（`/run` 上的 `path=vulnerable`）：模拟**没有**代理强制执行的不安全决策（仍不进行真实执行）。 ``` make demo ``` ## 验证矩阵 | 检查项 | 命令 | 备注 | |--------|------|------| | 所有检查 | `make validate` | lint、类型检查、248 项测试、仓库卫生、策略完整性、bandit、pip-audit、Docker | | 测试 | `python -m pytest` | 248 项安全相关测试（包括 LLM 适配器、基于属性的测试和 API 加固） | | 仓库卫生 | `python scripts/validate_repo.py` | 阻止提示词工件 | | 策略完整性 | `python scripts/validate_policy.py` | Schema、不变性、SHA-256 与 `policies/default.sha256` 的对比 | | 演示 | `make demo` | 七个 CLI 场景 | | 供应链（CI） | CodeQL、Gitleaks、Trivy、SBOM 工作流 | 参见 [docs/supply-chain.md](docs/supply-chain.md)；不保证安全 | ## API 示例 ``` source .venv/bin/activate uvicorn agent_control_plane.api:app --reload --port 8080 ``` ``` curl -s -X POST http://127.0.0.1:8080/run \ -H 'Content-Type: application/json' \ -d '{ "request_id": "demo-1", "user_id": "user-1", "session_id": "sess-1", "tenant_id": "tenant-a", "role": "user", "user_message": "Read my records", "scenario": "safe_read", "path": "protected" }' ``` ## 安全教义（摘要） 1. 默认拒绝；最小权限。 2. 不信任任何模型输出。 3. Schema 验证不等于授权。 4. 工具代理是权威边界。 5. 不受信任的检索内容和用户/网络/电子邮件上下文无法授权工具。 6. 外部和破坏性操作需要人工审批。 7. 输出过滤和审计日志在模型外部进行。 8. 在此实验环境中，所有工具执行均为模拟。 完整教义：[PROJECT_DOCTRINE.md](PROJECT_DOCTRINE.md)。 安全控制矩阵（威胁、实现、测试）：[SECURITY-CONTROLS.md](SECURITY-CONTROLS.md)。详细不变性：[docs/defensive-controls.md](docs/defensive-controls.md)。 ## 安全使用 仅在**已授权的本地实验**环境中使用。切勿将此项目指向生产系统、真实客户数据或第三方目标。按照 [SECURITY.md](SECURITY.md) 报告问题。 有关部署防护措施（API 认证、CORS、请求限制、容器配置），请参见 [docs/production-hardening.md](docs/production-hardening.md) 和 [docs/deployment-threat-model.md](docs/deployment-threat-model.md)。生产模式可以改善安全态势，但**不会**使其成为经过认证的生产服务。 ## 配置 将 `.env.example` 复制到 `.env`（可选）。策略文件：`policies/default.yaml`。 ## 智能体指导 - [AGENTS.md](AGENTS.md) - [.cursor/rules/](.cursor/rules/)（仅教义规则；非工作提示词） ## 许可证 MIT — [LICENSE](LICENSE)。

标签：Docker容器, Google Gemini, Linux系统监控, Python语言, 人工智能安全, 人类批准, 代理安全, 合规性, 安全参考实现, 安全工程, 审计日志, 工具连接代理, 授权控制, 控制平面, 攻击面发现, 来源检查, 模型安全, 请求拦截, 输出过滤, 逆向工具, 防御性安全