Repo Forensics：AI Agent 仓库离线安全审计器
面向 AI Agent 技能、插件与 MCP 服务器的本地安全扫描器，安装前给出可直接阻断 CI/CD 的判定。
- Star 数
- ★ 204
- 最近更新
- 13 天前
- License
- NOASSERTION
- 主语言
- Python
- FA 评分
- 44/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 需要付费订阅或许可
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 安装任何第三方 Claude Code 技能、OpenClaw 插件或 MCP 服务器前，先对仓库跑一次全量扫描，确认没有提示注入或工具投毒再交付给 Agent 使用。
- 不适合
- 个人、研究、教育以外且团队超过 5 人或月收入超 2 万美元的商业团队，需另行购买商业许可
- 需要签名验证或 YARA 检测开箱即用的团队，缺少 cosign、gh、npm、pip 或 yara-python 时这些能力会静默降级
- 需要完全离线且不依赖任何外部工具链的团队，CVE 与 CISA KEV 富化依赖联网调用
- 源码审查
- 44/100 · 缺口较多
这个 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+，无 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 有哪些优点和局限？
- 零第三方依赖、纯 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 与同类方案有什么区别？
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 能力。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Repo Forensics：AI Agent 仓库离线安全审计器 当前 | 44 · 缺口较多 | 命令行工具付费 | ★ 204 | 13 天前 | Python | Codex · Claude Code |
| SkillSpector 技能安全扫描器 | 62 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 25k | 今天 | Python | Codex · Claude Code · OpenAI API · Claude API |
| Agent Audit | 50 · 缺口较多 | 命令行工具免费 | ★ 244 | 1 个月前 | Python | — |
| HOL Guard | 79 · 表现良好 | 命令行工具免费版 + 付费版 | ★ 1.1k | 今天 | Rust | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
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，商业使用需另行联系，注意合规风险。
- 自动调度器会持续刷新威胁情报，可能产生网络请求，尽管声称离线优先，仍需确认其网络行为。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Shorter reports and a stronger --watch. On three real repositories, reports are 62 to 70 percent shorter with every finding still listed. - A rule that fires on many lines of one file is now one finding listing every line. Verdicts never weaken, and SARIF still gets one result per line. - --watch signs baselines with a fresh key that can never come from a scanned repository, and reports a baseline that was deleted or signed by an untrusted key. …在 GitHub 查看 ↗ -
发布说明摘录
Far fewer false alarms. On clean copies of three real repositories, critical and high findings dropped by 52 to 63 percent, and every change is tested against attack variants that must still fire. - Files shipped in several places (a plugin mirror, a vendored copy) are reported once, with every location listed. - Code that only reads a home or ~/.claude path, or copies the environment, is graded low unless the same file can send data out. - Test temp folders, cached .pyc files, long file paths and one line matched by several rules no longer pile up as separate alarms. …在 GitHub 查看 ↗ -
发布说明摘录
- Quieter command hook: notes, docs and test scripts that only mention an attack command are no longer blocked. Anything that can actually reach a shell still is. - Skips build output: .next, .nuxt, .svelte-kit, .turbo and similar folders are skipped when .gitignore excludes them. A Next.js app scan dropped from 170 findings to 9. - Far fewer false alarms: high and critical findings on three popular open-source projects dropped from 2,562 to 127, and every relaxed rule was tested against evasions built to slip past it. …在 GitHub 查看 ↗