sanjaybk7/agentic-guard

# agentic-guard [](https://github.com/sanjaybk7/agentic-guard/actions/workflows/ci.yml) [](https://pypi.org/project/agentic-guard/) [](LICENSE) [](https://pypi.org/project/agentic-guard/)  `agentic-guard` 会读取你的 agent 代码（LangGraph、OpenAI Agents SDK 以及 Jupyter notebooks），并**在你发布之前**标记出危险的架构模式 —— 无需运行 agent，无需发送数据到任何地方，也无需调用 LLM。 ``` pip install agentic-guard agentic-guard scan ./my-agent-project ``` ## 为什么会有这个项目 现实世界中最常见的 AI 安全故障是**混淆代理（confused deputy）**：一个 agent 既拥有一个读取不受信任文本（如电子邮件、网页、PDF、工单）的工具，又拥有一个执行特权操作（发送电子邮件、转账、执行 shell 命令）的工具，而 LLM 则在不知情的情况下充当了中间人，遵循嵌入在不受信任文本中的攻击者指令。 这种模式已经在各大公司的生产环境中出现过 —— Bing Chat、Slack AI、Microsoft 365 Copilot 和 ChatGPT 插件都曾公开披露过相关的变体。 现有的 AI 安全工具都在*运行时*工作 —— 它们在提示发生时对其进行检查，并试图阻止注入攻击。它们无法告诉你你的 agent **架构**是否安全。 `agentic-guard` 能够在构建阶段捕获架构错误，此时的修复成本极低。 ## 它能捕获什么 | ID | 名称 | OWASP LLM Top 10 | |----|------|------------------| | `IG001` | 混淆代理：不受信任的源在没有人工审批门控的情况下流向特权接收端 | LLM01 + LLM06 | | `IG002` | 从运行时输入构建的系统提示词（f-string / `.format()` / 字符串拼接） | LLM01 | 严重性是根据接收端的权限 × 可逆性 × 源信任度来评分的。关于哪些工具属于源、哪些属于接收端的分类定义在 [`src/agentic_guard/taxonomy.yaml`](src/agentic_guard/taxonomy.yaml) 中，并且支持社区扩展。 ## 快速开始 ``` pip install agentic-guard # 扫描目录或单个文件 agentic-guard scan ./my-agent-project # 不同的输出格式 agentic-guard scan ./agent --format pretty # default — human-readable terminal output agentic-guard scan ./agent --format sarif # GitHub code scanning / IDE integration agentic-guard scan ./agent --format json # machine-readable # 有用的 flags agentic-guard scan ./agent --fail-on high # exit non-zero on HIGH+ findings (CI gate) agentic-guard scan ./agent --include-tests # also scan test files (skipped by default) agentic-guard scan ./agent --output report.sarif ``` ### GitHub Action 添加到 `.github/workflows/ci.yml`： ``` - uses: sanjaybk7/agentic-guard@v0.1.0 with: path: . fail-on: high ``` 检测结果将通过 SARIF 上传显示在你仓库的 **Security → Code scanning** 标签页中。 ### VS Code 扩展 保存时提供内联诊断（编辑器中的红色波浪线，悬停工具提示包含规则 ID + OWASP 映射 + 修复提示）。请参阅 [vscode-extension/README.md](vscode-extension/README.md) 获取构建/安装说明。 ## 支持的框架 | 框架 | 状态 | 识别的模式 | |---|---|---| | **LangGraph** | ✅ 支持 | `@tool` 装饰器、`create_react_agent(...)` 及类似工厂模式、`interrupt_before=[...]` 门控 | | **OpenAI Agents SDK** | ✅ 支持 | `@function_tool` 装饰器、`Agent(...)` 构造函数、`tool_use_behavior="stop_on_first_tool"` 和 `StopAtTools(...)` 门控 | | **Jupyter notebooks (.ipynb)** | ✅ 支持 | 提取并解析代码单元；清理 magics/shell 转义；检测报告包含 `cell[N] line M` | | Microsoft Agent Framework | ⏳ 计划中 | — | | MCP 服务器 | ⏳ 计划中 | — | | AutoGen, CrewAI, Swarm | ⏳ 不支持 | 如果你有此需求，请提交一个 issue | ## 工作原理 1. **发现。** 遍历你的项目，提取 `.py` 和 `.ipynb` 文件。默认跳过 `tests/`、`venv/`、`__pycache__/` 等目录。 2. **解析。** 为每个文件构建 Python AST。对于 notebooks，首先将代码单元提取为虚拟源代码。 3. **按框架识别。** 解析器仅在文件导入其对应框架时才会触发（因此通用的 `class Agent:` 不会产生误报）。每个解析器都会生成一个与框架无关的中间表示：带有分类、权限级别和门控信息的 `Tool` 与 `Agent` 对象。 4. **具备污染感知的规则评估。** 检测规则作用于中间表示（IR），而不是特定于框架的语法。添加新框架仅意味着编写一个新的解析器 —— 规则保持不变。 5. **输出。** 漂亮的终端面板、SARIF v2.1.0（包含用于 GitHub Security 标签徽章的 `security-severity`）或 JSON。 **不会执行任何代码。数据不会离开你的机器。没有 LLM 调用。** 更详细的技术说明（包括污染分析的适配和客观存在的局限性）位于 [`docs/HOW_IT_WORKS.md`](docs/HOW_IT_WORKS.md) 中。 **安全研究员和 OWASP 贡献者：** 正式的威胁模型 —— 我们防御什么、明确不防御什么、我们对攻击者能力的假设，以及我们的覆盖盲区 —— 位于 [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md)。在提交“遗漏了攻击类别”的 issue 之前，请先阅读该文档。 ## `agentic-guard` *不是*什么 诚实地界定范围比过度承诺更重要。本工具： - **不是运行时防御。** 它不会在生产环境中拦截提示词。请使用 Lakera、Prompt Armor 或 NeMo Guardrails 来实现此目的。 - **不是深度代码分析器。** 它分析的是工具*名称*和*agent 架构*，而不是工具函数体内的内容。一个名为 `process()` 但其内部调用了 `smtplib.send()` 的函数目前对工具是不可见的 —— 名称很重要，就像对 `bandit`、ESLint 和 Semgrep 一样。（关于 IG003，请参阅路线图。） - **在 v0 版本中不支持基于 TypeScript 的 agent 框架**。仅支持 Python。 - **不会执行、评估或发送你的代码到任何地方。** 所有分析都是本地且确定性的。 ## 真实验证 `agentic-guard` 在包含 9 个热门开源 agent 代码库的语料库中进行了扫描。每个代码库的检测结果数量和方法论位于 [`docs/eval/PR-4-corpus-results.md`](docs/eval/PR-4-corpus-results.md)。 完整的精确率/召回率测量已列入 v0.2 路线图；请参阅 PR #5（函数局部字面量绑定）和 IG003（库调用规则），了解下一个计划中旨在降低误报率的改进。 ## 路线图 由 v0 发布后的社区反馈驱动。 - **IG003 —— 库调用规则。** 深入工具函数体内查找已知的危险调用（`smtplib.send_message`、`subprocess.run`、`requests.post`、`boto3.client('ses')` 等），从而捕获那些名称中性但内容危险的工具。 - **Microsoft Agent Framework** 解析器（Python）。 - **MCP 服务器** 解析器。 - **`agentic-guard init`** —— 交互式命令，用于为未知的工具名称添加项目本地的分类条目。 ### v0.2 中已发布 - **跨模块字符串常量解析** —— 当 `from prompts import SYSTEM_PROMPT` 及相关模式中导入的名称能解析为兄弟模块中的字面量时，将不再触发 IG002。详见 [`docs/HOW_IT_WORKS.md`](docs/HOW_IT_WORKS.md#cross-module-resolution)。 - **OpenAI Agents SDK 的 `Agent[T](...)` 泛型下标语法** —— 类型化上下文 agent（SDK 文档中推荐的形式）现在可以被解析器正确识别。 - **src 布局包标准化** —— 使用现代 `src//` 布局（PEP 517/518 时代的约定）的项目能够正确解析跨模块引用。详见 [`docs/design/PR-4-src-layout.md`](docs/design/PR-4-src-layout.md)。 - **威胁模型文档** —— 请参阅 [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md)。 ## 安全披露 如果你在 `agentic-guard` 本身发现了漏洞（而不是使用 `agentic-guard` 去寻找漏洞），请通过电子邮件联系维护者，而不是公开发布 issue。 如果你在使用 `agentic-guard` 的第三方项目中发现了漏洞，请负责任地向该项目的维护者披露 —— 在公开讨论之前，至少给他们 30 天的时间来进行修复。 ## 许可证 Apache-2.0。请参阅 [LICENSE](LICENSE)。

标签：AI安全, Chat Copilot, LLM Agent, LNA, Python, Subfinder, 安全专业人员, 无后门, 逆向工具, 错误基检测, 静态代码分析