Kartikm09/agent-skill-supply-chain-auditor

# Agent Skill 供应链审计工具 用于 Agent Skill 包和 Model Context Protocol (MCP) 配置的静态、确定性检查。该审计工具无需导入或执行受检代码，即可识别风险指令、凭据特征、不安全的 shell 指导、浮动依赖、宽泛的工具授权、文件系统风险以及缺失的治理机制。 ## 演示内容 | 工程关注点 | 已实现的证据 | |---|---| | 恶意输入处理 | 有界遍历，UTF-8 解码，不跟随符号链接，无动态导入 | | Agent 安全审查 | 17 条针对 prompt、命令、依赖、MCP、路径、密钥和治理风险的规则 | | 可重复性 | 基于内容的扫描 ID 和字节稳定的 JSON、Markdown、SARIF、SBOM 和 Mermaid 输出 | | 安全报告 | 相对路径，单向证据指纹，凭据值脱敏 | | 评估规范 | 10 个带标签的合成测试夹具，附带测量的规则级精确率和召回率 | | 产品交付 | 可导入的 Python API、CLI、CI 策略退出代码、静态审查仪表板、Docker 镜像 |  ## 问题陈述 Agent 包可能会混合自然语言指令、可执行助手程序、依赖引用和 MCP 权限。审查者在决定是否运行它之前，需要快速获得以下四个问题的答案： 1. 它声明了哪些文件、工具、服务器、环境密钥和远程引用？ 2. 它的指令是否要求 agent 绕过审批、隐藏行为或暴露受保护的数据？ 3. 它的安装或进程配置是否会意外扩大执行边界？ 4. 是否有足够的来源和许可信息来做出明智的采用决定？ 本仓库为该审查提供执行前的证据。它不能替代沙箱环境、代码审查、依赖验证或运行时监控。 ## 架构 ``` flowchart LR A[Untrusted local bundle] --> B[Bounded filesystem walker] B --> C[Strict SKILL metadata parser] B --> D[MCP JSON parser] B --> E[Text and secret-shape rules] C --> F[Normalized findings and inventory] D --> F E --> F F --> G[JSON] F --> H[Markdown] F --> I[SARIF 2.1.0] F --> J[Agent-SBOM] F --> K[Mermaid permission graph] ``` 扫描程序不执行任何网络请求、包解析、模块导入、子进程调用或模板评估。请参阅 [ARCHITECTURE.md](ARCHITECTURE.md) 和 [THREAT_MODEL.md](THREAT_MODEL.md)。 ## 快速入门 需要 Python 3.11 或更高版本。运行时依赖：**零**。 ``` python3 -m venv .venv . .venv/bin/activate python -m pip install -r requirements-dev.txt -e . skill-auditor scan fixtures/safe/minimal-skill --output-dir reports/local ``` 检查故意包含漏洞的示例，且不让发现结果阈值导致命令失败： ``` skill-auditor scan fixtures/vulnerable/broad-mcp \ --output-dir reports/local/broad-mcp \ --format all \ --fail-on none ``` 验证后的示例摘要： ``` findings=4 highest=critical files=3 ``` 这四条独特的规则是 `SEC001`、`MCP001`、`MCP002` 和 `PATH001`。在每个生成的报告中都不存在具有凭据特征的夹具值。 ## CLI 契约 ``` skill-auditor scan TARGET [--output-dir DIR] [--format all|json|markdown|sarif|sbom|graph] [--fail-on none|low|medium|high|critical] [--max-file-bytes N] [--max-total-bytes N] [--max-files N] [--max-depth N] ``` 退出代码： | 代码 | 含义 | |---:|---| | `0` | 扫描完成，且没有发现结果达到所选阈值 | | `1` | 扫描完成，且至少有一个发现结果达到阈值 | | `2` | 参数、目标、限制或输出操作无效 | 默认阈值为 `high`。重复使用 `--format` 可选择多种格式，或使用 `--format all`。 ## 报告 | 输出 | 文件 | 目标使用者 | |---|---|---| | 标准 JSON | `scan-report.json` | 自动化和下游策略 | | 审查 Markdown | `scan-report.md` | 维护者和安全审查者 | | SARIF 2.1.0 | `scan-report.sarif` | GitHub 代码扫描和 SARIF 工具 | | Agent-SBOM | `agent-sbom.json` | 文件、依赖、权限和 MCP 清单 | | Mermaid 图表 | `permission-graph.mmd` | 人类可读的能力关系 | Schema 位于 [`schemas/`](schemas/) 中。所有格式均省略了墙上时钟时间戳和绝对机器路径，因此只要输入字节和限制不改变，输出的字节就不会改变。 ## Python API ``` from pathlib import Path from skill_auditor import ScanOptions, scan_path result = scan_path( Path("my-agent-skill"), ScanOptions(max_files=500, max_total_bytes=10_000_000), ) for finding in result.findings: print(finding.rule_id, finding.severity, finding.evidence.path) ``` 该 API 不保留任何绝对的扫描根路径。证据片段经过了标准化、上限处理和脱敏。 ## 规则覆盖范围 该目录涵盖： - 无效或缺失的 `SKILL.md` 元数据； - 可疑的策略覆盖、隐藏和数据外泄语言； - 常见的凭据特征和密钥分配； - 通过管道传输到 shell 的远程内容； - 破坏性或扩展特权的命令； - 浮动包和远程引用； - 通配符 MCP 或 Agent Skill 工具权限； - 基于 shell 的和格式错误的 MCP 服务器声明； - 不安全的路径、符号链接、超大文件以及耗尽的检查预算； - 缺失的来源或许可；以及 - 使用纯 HTTP 的非回环 MCP endpoint。 每个结果都包含严重性、置信度、修复建议、脱敏证据和确定性的发现 ID。请在 [docs/rule-catalog.md](docs/rule-catalog.md) 中阅读确切的匹配边界。 ## 测量的合成评估 `make benchmark` 会扫描已提交的带标签语料库，并计算实际的规则级指标： | 测试夹具 | 正向规则标签 | TP | FP | FN | 精确率 | 召回率 | F1 | |---:|---:|---:|---:|---:|---:|---:|---:| | 10 | 14 | 14 | 0 | 0 | 1.0000 | 1.0000 | 1.0000 | 这些值**仅**适用于与规则共同开发的小型合成语料库。它们并不估计在未知仓库上的性能。生成的证据位于 [`reports/evaluation/`](reports/evaluation/) 中，相关局限性记录在 [docs/methodology.md](docs/methodology.md) 中。 ## 静态仪表板 ``` python -m http.server 8080 --directory dashboard ``` 打开 `http://127.0.0.1:8080`。发现结果、权限和文件是对已提交的、经过脱敏处理的示例报告的实时视图。所有过滤器和发现结果选择控件均可正常工作。 ## 质量门禁 ``` make lint # Ruff checks and format verification make compile # Python bytecode compilation make test # Unit, integration, and negative tests make sample # Regenerate all five sample outputs and dashboard data make benchmark # Measure the labelled synthetic corpus make verify # Run every gate plus determinism and repository secret checks ``` GitHub Actions 在 Python 3.11、3.12 和 3.13 上运行相同的门禁。该工作流绝不会在受扫描的夹具中执行脚本。 ## 仓库结构图 ``` src/skill_auditor/ Scanner, parsers, models, reporters, CLI, benchmark tests/ Unit, integration, hostile-input, and CLI tests fixtures/ Labelled safe and intentionally vulnerable synthetic bundles reports/ Generated sample and evaluation evidence dashboard/ Dependency-free report review interface schemas/ JSON Schema contracts docs/ Methodology, rule catalogue, review examples, screenshot scripts/ Evaluation, determinism, and secret-check entry points .github/workflows/ Multi-version quality and CodeQL workflows ``` 确切的受追踪文件清单记录在 [`FILE_MANIFEST.txt`](FILE_MANIFEST.txt) 中。 主会话验证证据和明确的 Docker 限制记录在 [TEST_REPORT.md](TEST_REPORT.md) 中。 ## 招聘人员指引 一条有用的五分钟审查路径： 1. 阅读 [THREAT_MODEL.md](THREAT_MODEL.md) 中的信任边界。 2. 比较 [`fixtures/`](fixtures/) 中的安全包和漏洞包。 3. 检查经过脱敏的[示例报告](reports/sample/scan-report.md)和[权限图表](reports/sample/permission-graph.mmd)。 4. 审查 [`src/skill_auditor/scanner.py`](src/skill_auditor/scanner.py) 中的扫描程序编排。 5. 查看测量后的[基准测试报告](reports/evaluation/benchmark-results.md)和测试。 ## 安全性与局限性 - 模式匹配可能会产生误报和漏报。 - 自然语言意图是上下文相关的；`INJ001` 是一个审查信号，而不是恶意的证明。 - 严格的 frontmatter 解析器支持保守的 Agent Skill 元数据子集，而不支持任意的 YAML 特性。 - 静态检查无法观察运行时下载、生成的命令、传递依赖、endpoint 行为，或通过编码或混淆隐藏的漏洞。 - SARIF 生成不会上传数据。操作者控制任何后续的上传。 - 该过程不是一个强化的沙箱。在没有适当隔离边界的情况下，请勿在扫描期间或之后运行未知代码。 - 扫描不可变的检出或只读快照；并发目录突变不在威胁模型范围内。 有关报告请参阅 [SECURITY.md](SECURITY.md)，有关经过谨慎界定范围的未来工作请参阅 [ROADMAP.md](ROADMAP.md)。 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE)。

标签：SARIF, SBOM, 图数据库, 模型上下文协议, 硬件无关, 请求拦截, 逆向工具, 错误基检测, 静态代码分析