Repo Forensics：AI Agent 仓库离线安全审计器
面向 AI Agent 技能、插件与 MCP 服务器的本地安全扫描器，安装前给出可直接阻断 CI/CD 的判定。
按维度查看评分与理由
README 声明零依赖、零遥测、完全离线，且测试显示 Seatbelt 沙箱阻止网络与越界写入，数据流透明度较好（2）。但 least_privilege 仅得 1：安装脚本会写入 ~/.claude、~/.codex 等 agent 配置目录并注册 hooks，权限范围较宽且未提供细粒度控制。user_confirmation 得 1：PreToolUse 钩子可阻止已知恶意包，但未说明对未知或高风险操作是否要求用户确认。sensitive_data_handling 得 1：测试断言 credential_value_reads 为 forbidden，但缺少对凭据读取的运行时强制证据。dependency_security 得 2：零非标准库依赖，CI 使用哈希锁定的 pytest 并固定 action SHA。external_effects 得 1：会修改 agent 配置、安装调度器，但回滚与影响范围说明不足。rollback 得 1：有 disable/enable 命令，但缺少对配置修改的完整回滚机制。source_attribution 得 1：许可证与作者信息存在，但发布者身份未经验证，归属证据薄弱。
self_consistency 得 1：README 声称 27 个扫描器、3,422 个测试，但提供的测试文件仅覆盖 forensify 子集，无法验证整体一致性。dependency_availability 得 2：零依赖且 CI 使用哈希锁定，依赖可用性风险低。failure_messages 得 1：测试中有错误处理断言（如 stat_failed、SchemaMismatch），但缺少面向用户的失败信息设计证据。
audience_and_scenarios 得 2：明确面向 AI agent 生态（Claude Code、Codex、OpenClaw 等），场景描述具体。capability_boundaries 得 1：README 列出扫描器，但未清晰界定不覆盖的范围或误报边界。trigger_precision 得 1：钩子触发条件在 README 中描述，但缺少精确的触发规则与去重逻辑证据。environment_fit 得 2：支持多平台（macOS、Linux、Windows）并有平台特定安装说明。
information_architecture 得 2：README 结构清晰，有目录、表格和折叠详情。install_notes 得 1：提供安装命令，但缺少完整的依赖与前置条件说明。naming_stability 得 1：未提供命名稳定性承诺或版本化接口说明。examples_and_faq 得 1：有示例输出，但无 FAQ 或常见问题解答。known_limitations 得 1：未明确列出已知限制或误报率。license 得 2：LICENSE 文件完整，采用 PolyForm Noncommercial 1.0.0，并说明商业许可联系方式。versioning_changelog 得 1：有版本徽章，但无 CHANGELOG 文件或版本历史。maintenance_responsibility 得 1：有 SECURITY.md 和 CLA，但发布者未验证，维护责任归属不明确。
output_usability 得 2：输出支持文本、JSON、SARIF，并设计退出码用于 CI 门禁，可用性较好。marginal_value 得 1：与现有工具（如 mcp-scan、Gitleaks）相比有差异化，但缺少独立验证其检测效果。cost_benefit 得 1：零依赖和离线运行降低成本，但安装 hooks 和调度器带来持续维护成本，收益未量化。
claim_traceability 得 1：README 引用外部研究链接，但未提供内部声明与代码的对应关系。cross_source_corroboration 得 1：测试文件与 README 部分吻合，但缺少独立第三方验证。fact_inference_separation 得 1：README 混合事实与营销语言，未明确区分已验证事实与推断。
- 安装脚本会修改 ~/.claude、~/.codex 等 agent 配置目录并注册 hooks，可能影响现有 agent 行为，建议在隔离环境中先行测试。
- README 声称的 27 个扫描器和 3,422 个测试未在提供的文件中得到完整验证，实际覆盖范围可能小于宣传。
- 发布者身份未经验证，且许可证为 PolyForm Noncommercial，商业使用需另行联系，注意合规风险。
- 自动调度器会持续刷新威胁情报，可能产生网络请求，尽管声称离线优先，仍需确认其网络行为。
这个 Agent 能做什么，适合哪些场景？
Repo Forensics 是一个纯 Python、零第三方依赖、完全离线的安全扫描工具，专门审计 AI Agent 生态中不信任的仓库、技能、插件与 MCP 服务器。它内置 27 个扫描器并串行/并行运行，覆盖提示注入、供应链投毒、凭证窃取、运行时行为预测、基础设施配置错误等攻击面，随后由包含 41 条规则的关联引擎把跨扫描器的孤立发现组合成复合攻击链（如环境变量读取 + 出站 POST = 数据外泄）。所有发现带置信度与严重度，最终汇总为 BLOCK/WARN/INFO/SUPPRESSED 四级判定，并输出 exit code 0/1/2 供 CI 卡点，同时支持 text、JSON、summary 和 SARIF 2.1.0 四种格式。作为插件安装后，它通过 PreToolUse、PostToolUse、SessionStart 三个钩子在后台自动拦截已知恶意包、对新克隆代码做全量扫描、并在每次会话检查插件与 MCP 配置漂移，检测逻辑本身通过 Ed25519 签名的规则包每日刷新。扫描过程不需要联网，也不上传任何代码。
核心入口是 ./skills/repo-forensics/scripts/run_forensics.sh，可直接指向任意仓库、技能目录或 MCP 服务器，也支持 --skill-scan（聚焦 17 个技能/MCP 扫描器）、--watch（SHA256 基线完整性监控）、--update-iocs、--update-vulns、--offline、--no-vulns、--verify-install、--format json|sarif、--inventory（Forensify 已安装栈审计）。27 个扫描器包括 skill_threats（11 类检测、160+ 正则，识别提示注入、unicode 走私、ClickFix、GlassWorm 变体选择符）、mcp_security（工具投毒、工具影子、rug pull、TrustFall .mcp.json 内联 RCE）、dependencies（typosquatting、SANDWORM_MODE IOC、lockfile 深度解析、OSV API 查 CVE 并交叉 CISA KEV）、lifecycle（npm/pip 安装钩子、.pth 注入、粘贴服务 dead-drop、~/.claude 等 agent 配置注入）、git_forensics（时间戳篡改、身份伪造、git replace 对象与 grafts）、binary（伪装可执行文件、音频隐写、内嵌 PE）、entropy（解码 base64/hex 后重扫）、archive（按 magic bytes 识别改名的 zip、Office 文档内夹带脚本）、bytecode（对比 .pyc 与源文件的危险标记以发现字节码投毒）、splitstream（重组跨文件分片载荷）、dead_anchors（SkillJacking 悬空锚点探测）、provenance（调用 cosign/gh/npm/pip 验证签名失败）、yara（11 条手写规则覆盖 webshell/恶意软件/挖矿/黑客工具）等。运行时通过 refresh_controller.py 在 macOS launchd、Linux systemd user timer、Windows Task Scheduler 上维护威胁源刷新。
- 安装任何第三方 Claude Code 技能、OpenClaw 插件或 MCP 服务器前，先对仓库跑一次全量扫描，确认没有提示注入或工具投毒再交付给 Agent 使用。
- 安全工程师把 repo-forensics 接入 GitHub Actions，用 exit code 2 阻断带有已知恶意依赖或安装钩子的 PR 合并。
- 开发者怀疑自己已经中招（如 lockfile 里出现过可疑包），用 --inventory 与 post_incident 扫描检查 npm 缓存、node_modules、安装日志和主机持久化痕迹。
- 团队在 Codex CLI 或 Cursor 中安装插件，让 PreToolUse / beforeShellExecution 钩子在 npm install、pip install、pipe-to-shell 命令执行前拦截已知恶意包。
- 模型或 Agent 平台运营方批量审计内部技能市场，用 SARIF 输出把结果直接投到 GitHub Security 标签页做集中管理。
- 供应链安全研究者需要离线、可复现、无遥测的检测基线，用 --offline 与签名规则包在隔离环境里跑回归测试。
这个 Agent 有哪些优点和局限？
- 零第三方依赖、纯 Python 3.8+、完全离线，代码不上传云端（明确与会上传代码的 mcp-scan 区分），也没有遥测。
- 27 个扫描器加 41 条关联规则的组合检测能力，能识别单点工具漏掉的复合链，例如 Lethal Trifecta、安装时窃取、隐藏指令攻击。
- 检测规则以 7 个签名 JSON 规则包（400+ 规则）通过 Ed25519 签名源每日刷新，不依赖发版或重装即可获得新行为检测，并带版本下限的回滚保护。
- 覆盖 Claude Code、Codex CLI、OpenClaw、Cursor、NanoClaw 的插件与钩子体系，PreToolUse 的 IOC 拦截延迟低于 10ms，会话无变更时仅 0.9ms。
- 输出支持 SARIF 2.1.0 与 CI 退出码，可直接接入 GitHub Security 标签页和其他 SARIF 消费工具。
- 3,422 个 pytest 测试全部使用临时目录中的合成样本与假包文件，不下载也不执行真实恶意代码，可安全反复运行。
- 许可证是 PolyForm Noncommercial 1.0.0，商业使用受限：仅个人、研究、教育及总人数少于 5 人（或月收入低于 2 万美元）的组织免费，更大公司需单独联系授权。
- README 自我定位为“纵深防御而非保证”，要求人工复核每一条发现，存在误报与漏报风险。
- CVE 与 CISA KEV 富化依赖 api.osv.dev 等外部网络请求（可用 --offline 退回缓存），离线下无法获得最新漏洞情报。
- YARA 扫描器依赖可选的 yara-python；缺失时该能力降级为 capability gap（不影响退出码），并非开箱即用。
- 签名 provenance 检查需要 PATH 中存在 cosign / gh / npm / pip 等外部工具，否则无法完成验证。
- OpenClaw 与 Cursor 的钩子并非插件系统自动接线，需要各自执行一次安装脚本，且 NanoClaw 完全没有插件钩子支持，只能手动调用。
如何安装或部署这个 Agent？
要求 Python 3.8+，无 pip 安装、无 API key、无 Docker、无第三方依赖。三种方式：
1) CLI 直接使用：
git clone https://github.com/alexgreensh/repo-forensics.git
cd repo-forensics
./skills/repo-forensics/scripts/run_forensics.sh .2) Claude Code 插件：
/plugin marketplace add alexgreensh/repo-forensics
/plugin install repo-forensics@alexgreensh-repo-forensics安装即自动注册三个钩子。建议在 /plugin > Marketplaces 中开启 auto-update。
3) Codex CLI：
codex plugin marketplace add alexgreensh/repo-forensics --ref main
codex plugin add repo-forensics@alexgreensh-repo-forensics重启 Codex 并在提示时信任四个钩子；本地手工接线用 python3 scripts/codex_install.py，验证用 python3 scripts/codex_install.py --verify --require-registered。
OpenClaw：python3 scripts/openclaw_install.py（卸载加 --uninstall，验证加 --verify）。
Cursor：python3 scripts/cursor_install.py（写入 ~/.cursor/hooks.json，卸载加 --uninstall，验证加 --verify）。
NanoClaw 无插件钩子系统，仅支持手动调用。
如何使用这个 Agent？
首次自检与常规扫描：
./skills/repo-forensics/scripts/run_forensics.sh .
./skills/repo-forensics/scripts/run_forensics.sh /path/to/repo聚焦技能/MCP 扫描与格式输出：
./skills/repo-forensics/scripts/run_forensics.sh /path/to/skill --skill-scan
./skills/repo-forensics/scripts/run_forensics.sh /path/to/repo --format json
./skills/repo-forensics/scripts/run_forensics.sh /path/to/repo --format sarif已装栈审计与漏洞刷新：
./skills/repo-forensics/scripts/run_forensics.sh --inventory
./skills/repo-forensics/scripts/run_forensics.sh --inventory --target ~/.codex
./skills/repo-forensics/scripts/run_forensics.sh /path/to/repo --update-vulns
python3 skills/repo-forensics/scripts/vuln_feed.py --query npm lodash 4.17.20
python3 skills/repo-forensics/scripts/refresh_controller.py status --jsonGitHub Actions 卡点：
- name: Security gate
uses: alexgreensh/repo-forensics@v2
with:
mode: fullExit code：0 干净、1 警告、2 阻断合并。安装到 Agent 后也可直接用自然语言触发，例如“Audit this repo before I add it as a dependency”。误报可用 .forensicsignore 抑制（该文件本身也会被扫描）。
这个 Agent 与同类方案有什么区别？
README 明确列出并对比了多个替代方案：NVIDIA SkillSpector（仅技能文件模式扫描，68 模式 17 类，无关联引擎、无供应链与实时 IOC/CVE 源、无法读编译/二进制代码）、Gitleaks/TruffleHog（仅密钥扫描）、Semgrep（需配置、非 AI 技能感知）、mcp-scan（会把代码上传到云端 API）、GuardDog（仅 Python 包）、ClawSec（8 个外部依赖、包裹 semgrep/bandit、无关联引擎）、VirusTotal + ClawHub（基于签名、表面级）、人工审查（漏掉零宽 unicode、跨文件污点流、工具描述注入）。repo-forensics 的差异化定位是 27 个扫描器 + 零依赖 + 完全离线 + 运行时行为预测 + 事后取证，且声称覆盖 SkillSpector 的 SARIF 与 YARA 能力。