vlcak27/agentbom

# re "Reference" is translated. So, "Reference" is not kept in English; it's translated.  [](https://github.com/vlcak27/agentbom/actions/workflows/precision-corpus.yml)    ## AgentBOM 是什么 AgentBOM 是 AI 代理仓库的本地优先安全卫士。它结合了 快速的静态预提交守卫和可选的实验性 RunBOM 运行时证据。 AI 代理仓库通常混合了提示词、工具权限、MCP 配置和 API 密钥。 AgentBOM 在有风险的更改进入 git 之前，为您提供本地审查信号。 - 使用 `agentbom activate` 激活一次。 - 使用静态本地守卫正常提交。 - 使用 `agentbom scan` 和 pre-commit 进行仅静态的审查。 - 可选择运行 `agentbom run` 以获取尽力而为的 Python 运行时证据。 - 将 RunBOM 与强制执行分开：它不是一个沙盒，目前还不强制执行策略。 ## 快速开始 ``` pip install ai-agentbom cd my-agent-repo agentbom activate git commit ``` 常规提交使用由 `agentbom activate` 安装的静态本地守卫。 `agentbom scan` 和本地守卫不会执行被扫描的代码。 可选的运行时证据： ``` agentbom run ``` `agentbom run` 会在实验性的 Python 专项检测下，有意执行配置或自动检测到的命令。JSON 构件被写入，供机器和 CI 使用；终端输出是开发者的摘要。 ## 它能捕获什么 - 可能的 AI/API 密钥泄露，值会被脱敏 - 有风险的 shell 或代码执行能力 - MCP 服务器暴露 - 策略之外的 AI 提供商或模型使用 ## 演示 通过的提交： ``` AgentBOM OK No policy violations found. ``` 被阻止的提交： ``` AgentBOM blocked this commit 2 blocking finding(s) Highest severity: critical CRITICAL Possible OpenAI API key value .env:1 Why: likely credential value found in a committed file. Fix: remove the key, rotate it, and keep secrets in environment variables or a secret manager. Secret value redacted. ``` 本地守卫可以基于配置的策略阻止提交。被阻止的输出会显示来源、原因、修复方法以及是否已对秘密值进行脱敏。静态发现是审查信号，而非漏洞利用证明。静态能力发现意味着代码/配置看起来具有能力，而不是它已执行。 ## 推荐工作流程 `agentbom activate` 会创建或复用 `agentbom.toml` 并安装一个仓库本地的 pre-commit 守卫。默认模式是 `confirm`：通过的提交会打印 `AgentBOM OK`，而当发现策略违规时，AgentBOM 会在提交前询问。激活仅影响此本地克隆，除非传递 `--force`，否则不会覆盖现有的 `agentbom.toml`。 ``` agentbom status agentbom scan . --policy agentbom.toml --html --open ``` 激活预设： - `safe`：默认，适合正常使用。 - `audit`：仅观察，不阻止。 - `strict`：用于敏感仓库的更强策略。 `agentbom activate --strict` 作为 `agentbom activate --preset strict` 的别名仍然可用。 ## 策略审查 默认情况下，策略审查是建议性的： ``` agentbom scan . --policy agentbom.toml --pretty ``` 仅当您选择加入时，才让策略违规导致扫描失败： ``` agentbom scan . --policy agentbom.toml --enforce-policy ``` HTML 报告包含一个策略工作台，用于根据检测到的提供商、模型、框架、可达能力、MCP 服务器、秘密引用和策略差距来生成和完善 `agentbom.toml`。 请参阅[策略文档](docs/policy.md)了解策略格式、部署、本地守卫模式和绕过行为。 ## 本地守卫 安装仓库本地的 pre-commit 守卫： ``` agentbom activate ``` 模式： - `advisory` 允许提交并在发现策略违规时发出警告。 - `confirm` 在存在违规时，在提交前询问。 - `enforce` 在存在违规时阻止提交。 该钩子位于当前仓库的 `.git/hooks/pre-commit` 下，是本地的。 通过以下方式禁用它： ``` agentbom deactivate ``` 排查提示或 PATH 问题：[故障排除](docs/troubleshooting.md)。 ## In "API Reference", "API" is an acronym kept, "Reference" is translated. RunBOM 是一个实验性的、可选的运行时证据模式： ``` agentbom activate agentbom run ``` `agentbom activate` 安装静态本地守卫。当检测到安全的测试或运行时命令时，它还可以在 `agentbom.toml` 中配置 `[runbom]`。 `agentbom run` 会在尽力而为的 Python 运行时检测下，有意执行配置的命令，或一个自动检测到的命令。自动检测倾向于使用简单命令，例如： - `python -m pytest tests/agent_runtime` - `python -m pytest tests/runbom` - `python -m pytest` - npm, pnpm, 或 bun 的测试脚本（当检测到时） RunBOM 打印人类可读的终端摘要并写入机器可读的构件： ``` AgentBOM RunBOM OK Runtime summary: 153 events observed 57 unique events Highest risk: high Top runtime signals: HIGH env.read OPENAI_API_KEY Why: agent read an AI provider credential variable name. Note: secret value was not recorded. HIGH filesystem.read .env Why: agent read a common local secrets file. Fix: avoid reading local secrets files during agent runtime checks unless expected. Artifacts: .agentbom/runbom-summary.json .agentbom/runbom.jsonl ``` 终端输出显示开发者摘要和至多顶部的运行时信号。JSON 构件供机器和 CI 使用： - `.agentbom/runbom.jsonl` - `.agentbom/runbom-summary.json` `.agentbom/runbom-summary.json` 是机器可读的摘要。 `.agentbom/runbom.jsonl` 是原始事件日志。事件根据风险和标签进行分类，但绝不会记录秘密值。高风险的运行时证据本身不会导致命令失败。 RunBOM 专注于 Python，并且是尽力而为的。它不是一个沙盒，目前不强制执行策略，并且默认不是 pre-commit 的一部分。 ## 它能发现什么 | 领域 | 示例 | | --- | --- | | 提供商和模型 | OpenAI, Anthropic, Gemini, Ollama, OpenRouter, GPT/o-series, Claude, Gemini, Llama, Mistral, Qwen, Grok, Cohere, Perplexity | | 框架 | LangChain, LangGraph, LlamaIndex, CrewAI, AutoGen/AG2, Semantic Kernel, Pydantic AI, OpenAI Agents SDK, Mastra, Vercel AI SDK, LiteLLM | | 提示词 | `AGENTS.md`, `CLAUDE.md`, `prompts/*.md`, 提示词 YAML | | MCP | `mcp.json`, `.mcp.json`, `claude_desktop_config.json`, Cursor/Claude MCP 配置路径 | | 能力 | shell, 代码执行, 网络, 数据库, 云, MCP 工具调用 | | 秘密引用 | 凭据名称，例如 `OPENAI_API_KEY`，绝非值本身 | | 秘密泄露发现 | 可能的 AI/API 凭据值，始终已脱敏 | | 策略差距 | 提示词文件、MCP 配置、shell/云访问（无策略文档） | 发现包括源路径、置信度、面向审查者的理由以及在静态证据可用时的缓解信号。 ## 报告  生成审查构件： ``` agentbom scan . --output-dir agentbom-report --html --mermaid --sarif --pretty ``` 差异感知扫描将当前报告与基线 JSON 报告进行比较： ``` agentbom scan . --baseline agentbom-baseline.json --fail-on-new high --sarif --html --pretty ``` `--fail-on-new` 接受 `low`、`medium`、`high` 或 `critical`。 请参阅[报告指南](docs/report-guide.md)了解字段定义和审查者工作流程。 ## Similarly, for "Kubernetes Setup", "Kubernetes" is kept, "Setup" is translated. 在拉取请求中使用该 Action 来发布报告和工作流作业摘要。 ``` name: AgentBOM on: pull_request: push: branches: [main] permissions: contents: read jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run AgentBOM uses: vlcak27/agentbom@v0.8.0 with: path: . fail-on: none sarif-upload: false html: true output-dir: agentbom-report - name: Upload AgentBOM reports uses: actions/upload-artifact@v4 with: name: agentbom-report path: agentbom-report/ ``` 仅当您需要 GitHub 代码扫描警报时才启用 SARIF 上传： ``` permissions: contents: read security-events: write ``` 更多详情：[GitHub Action 文档](docs/github-action.md)。 ## 安全模型 静态扫描和本地守卫： - `agentbom scan` 和本地守卫是纯静态的 - 不执行被扫描的代码 - 不导入被扫描的模块 - 不执行 MCP 服务器 - 扫描期间不联系网络 - 跳过大于 1 MB 的文件 - 跳过看起来像二进制的文件 - 不跟踪符号链接循环 - 按名称记录秘密引用，仅使用脱敏元数据记录可能的凭据泄露，绝不记录秘密值 - 可离线工作，并对相同的输入仓库输出确定性结果 RunBOM： - 可选的 - 有意执行配置或自动检测到的命令 - 记录尽力而为的 Python 运行时证据 - 打印人类可读的终端摘要 - 在 `.agentbom/` 下写入 JSON 构件 - 绝不记录秘密值 - 不是一个沙盒 - 暂无策略强制执行 ## 局限性 - 发现是审查信号，而非漏洞利用验证。 - 可达性是从附近的静态证据推断的，而非运行时跟踪。 - 可能存在误报和漏检。 - AgentBOM 专注于 AI 代理。请使用 SAST 工具查找特定于语言的漏洞模式，并使用 SBOM 工具管理软件包清单。 - AI/API 凭据泄露检查是专注的审查信号，不能替代 Gitleaks 或 TruffleHog 等完整秘密扫描器。 - 依赖解析是确定性的且有限的，不是完整的锁文件解析器。 - AgentBOM 不是 SBOM、SPDX 或 CycloneDX 的替代品。 ## 开发 ``` pip install -e ".[dev]" ruff check . pytest ``` 或者运行项目检查： ``` make check ``` 有用的文档： - [CHANGELOG.md](CHANGELOG.md) - [CONTRIBUTING.md](CONTRIBUTING.md) - [SECURITY.md](SECURITY.md) - [ARCHITECTURE.md](ARCHITECTURE.md) - [故障排除](docs/troubleshooting.md) - [RunBOM](docs/runbom.md)

标签：Python安全, 网络安全研究, 逆向工具