Diplomat-ai/diplomat-agent

# diplomat-agent [](https://pypi.org/project/diplomat-agent/) [](https://python.org) [](LICENSE) [](https://github.com/Diplomat-ai/diplomat-agent) [](https://github.com/Diplomat-ai/diplomat-agent/actions/workflows/ci.yml) **你的 AI 代理可以在循环中调用 `stripe.Refund.create()` 200 次。 diplomat-agent 在这些函数发布前就发现它们。** ``` pip install diplomat-agent diplomat-agent scan . ``` 扫描你的 Python AI 代理代码。报告每一个可以改变 真实世界的函数——并显示哪些函数没有检查。 零依赖。在 1000 个文件的代码库上耗时 2 秒。 ## 效果展示 ``` diplomat-agent — governance scan Scanned: ./my-agent Tool calls with side effects: 12 ⚠ process_refund(amount, customer_id) Write protection: NONE Rate limit: NONE → stripe.Refund.create() with no amount limit Governance: ❌ UNGUARDED ⚠ delete_user_data(user_id) Confirmation step: NONE Batch protection: NONE → session.delete() with no confirmation Governance: ❌ UNGUARDED ✓ update_order(order_id) Governance: ✅ GUARDED ──────────────────────────────────────────── RESULT: 8 unguarded · 3 partial · 1 guarded (12 total) ``` ## 为什么这对 AI 代理很重要 在 Web 应用中，人类点击按钮。UI 有验证、确认对话框、每会话速率限制。 在代理中，LLM 决定调用哪些函数、传入什么参数、调用多少次。它不了解业务规则。它可能循环、幻觉参数或被提示注入。 **如果没有代码层面的防护，LLM 的决策与真实世界后果之间没有任何屏障。** 我们扫描了 16 个开源代理仓库。[76% 的工具调用完全没有检查](REALITY_CHECK_RESULTS.md)。 ## 它能检测到什么 40+ 种模式，涵盖 8 个类别： | 类别 | 示例 | |---|---| | 数据库写入 | `session.commit()`, `.save()`, `.create()`, `.update()` | | 数据库删除 | `session.delete()`, `.remove()`, `DELETE FROM` | | HTTP 写入 | `requests.post()`, `httpx.put()`, `client.patch()` | | 支付 | `stripe.Charge.create()`, `stripe.Refund.create()` | | 邮件 / 消息 | `smtp.sendmail()`, `ses.send_email()`, `slack.chat_postMessage()` | | 代理调用 | `graph.ainvoke()`, `agent.execute()`, `Runner.run_sync()` | | 破坏性命令 | `subprocess.run()`, `exec()`, `eval()` | | 发布 / 上传 | `s3.put_object()`, `client.publish()` | 什么是防护：输入验证、速率限制、身份验证检查、确认步骤、幂等键、重试边界。 [完整列表 →](docs/acknowledge.md) ## 无处不在的集成 ### CI — 阻断未防护的 PR ``` - name: Diplomat governance scan run: | pip install diplomat-agent diplomat-agent scan . --fail-on-unchecked ``` ### IDE — 审查 Copilot 写的内容 无需安装扩展即可在 IDE 中使用： | IDE | 方法 | 设置 | |---|---|---| | **Copilot Chat** (VS Code, Cursor, Windsurf) | 在代理下拉菜单中选择“Diplomat Reviewer” | 复制 `.github/agents/diplomat-reviewer.agent.md` | | **Claude Code** | 询问“扫描未防护的工具调用” | 在仓库根目录放置 `AGENTS.md`（已包含） | | **Cursor**（原生支持） | 在 Python 文件中自动激活 | 复制 `.cursor/rules/diplomat-reviewer.mdc` | ### Git 预提交钩子 ``` repos: - repo: https://github.com/Diplomat-ai/diplomat-agent rev: v0.4.0 hooks: - id: diplomat-agent ``` ### SARIF — 原生 VS Code 问题面板 ``` diplomat-agent scan . --format sarif --output results.sarif ``` 通过 [SARIF Viewer](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer) 打开。 或上传到 [GitHub Code Scanning](docs/sarif.md)。 ### 仅扫描变更文件 ``` diplomat-agent scan . --diff-only ``` ## 生成代理的 SBOM ``` diplomat-agent scan . --format registry --output-registry toolcalls.yaml ``` 类似 `requirements.txt`，但记录的是你的代理能做什么，而非它依赖什么。提交它。在 PR 中对比差异。当代理获得新能力时，变更会显示在审查中。 [什么是行为型 SBOM →](docs/behavioral-bom.md) ## 基准测试 | 仓库 | 文件数 | 工具调用数 | 未防护 | 耗时 | |---|---|---|---|---| | Skyvern | 595 | 452 | 345 (76%) | ~2 秒 | | Dify | 1,000+ | 1,009 | 759 (75%) | ~3 秒 | | PraisonAI | — | 1,028 | 911 (89%) | ~2 秒 | | CrewAI | — | 348 | 273 (78%) | ~1 秒 | [16 个仓库的完整结果 →](REALITY_CHECK_RESULTS.md) ## 输出格式 | 格式 | 参数 | 用途 | |---|---|---| | 终端（默认） | — | 人工审查 | | JSON | `--format json` | IDE 代理、自动化 | | SARIF 2.1.0 | `--format sarif` | VS Code、GitHub Code Scanning | | CSAF 2.0 | `--format csaf` | 安全团队、CERT | | Markdown | `--format markdown` | 文档、报告 | | 注册表 | `--format registry` | `toolcalls.yaml` SBOM | ## 确认工具调用 如果某个函数是故意未防护或已在别处受保护： ``` def send_alert(message): # checked:ok — protected by API gateway requests.post(ALERT_URL, json={"msg": message}) ``` ## 从扫描到运行时 diplomat-agent 发现漏洞。**diplomat-gate** 在运行时保护它们。 ``` pip install diplomat-gate ``` ``` from diplomat_gate import Gate gate = Gate.from_yaml("gate.yaml") verdict = gate.evaluate({"action": "charge_card", "amount": 15000}) # → STOP — Amount 15000 exceeds limit of 10000 ``` 15+ 个内置策略（支付、邮件、Shell 命令）。 CONTINUE / REVIEW / STOP 响应时间 < 1 毫秒。零依赖。 [diplomat-gate →](https://github.com/Diplomat-ai/diplomat-gate) · [diplomat.run →](https://diplomat.run)（带哈希链审计追踪的托管控制平面） ## 标准合规 - [OWASP Agentic Top 10 映射 →](docs/owasp-agentic-mapping.md) - [欧盟 AI 法案 / NIST / DORA 合规 →](docs/compliance.md) - [CSAF 2.0 告警生成 →](docs/csaf.md) ## 已知限制 - 仅静态分析——无运行时检测 - 仅支持 Python——TypeScript 在路线图中 - 跨函数 + 同包装饰器——使用 `# checked:ok` 处理外部包中的防护 - [完整限制 →](docs/limitations.md) ## 路线图 - [x] Python AST 扫描器（40+ 模式） - [x] `toolcalls.yaml` 行为型 SBOM - [x] CSAF 2.0 + SARIF 2.1.0 输出 - [x] CI 集成（`--fail-on-unchecked`） - [x] IDE 代理（Copilot Chat、Claude Code、Cursor） - [x] Git 预提交钩子 - [x] `--diff-only` 和 `--file` 模式 - [x] 跨函数装饰器解析 - [ ] TypeScript 支持 - [ ] MCP 服务器扫描 - [ ] VS Code 扩展（保存时内联诊断） - [ ] PR 评论集成 ## 要求 - Python 3.9+ - 零依赖（仅标准库 `ast`） - 可选：`rich`（彩色输出）、`pyyaml`（注册表） ## 许可证 Apache 2.0

标签：AI安全, AI治理, Chat Copilot, LLM代理, Python, SSH爆破, 云安全监控, 代理安全, 写保护, 函数调用, 副作用检测, 合规扫描, 图探索, 安全扫描, 工具调用, 批处理保护, 无后门, 时序注入, 确认步骤, 自动化payload嵌入, 自动化治理, 语义网, 逆向工具, 防护缺失, 零依赖, 静态分析