Repo Forensics
Audit untrusted AI-agent repos, skills, plugins, and MCP servers locally before they touch your machine — zero dependencies, zero telemetry.
Per-dimension scores and reasoning
README claims zero dependencies, zero telemetry, fully offline, and tests show Seatbelt sandbox blocks network and out-of-bounds writes, so data flow transparency scores 2. least_privilege scores 1: install scripts write to ~/.claude, ~/.codex agent config dirs and register hooks, a broad scope without fine-grained controls. user_confirmation scores 1: PreToolUse hook blocks known-malicious packages but no evidence of confirmation for unknown or high-risk operations. sensitive_data_handling scores 1: tests assert credential_value_reads is forbidden, but no runtime enforcement evidence. dependency_security scores 2: zero non-stdlib deps, CI uses hash-locked pytest and pinned action SHAs. external_effects scores 1: modifies agent configs, installs schedulers, but rollback and blast radius are under-documented. rollback scores 1: disable/enable commands exist, but no full rollback for config changes. source_attribution scores 1: license and author info present, but publisher identity unverified, weak attribution evidence.
self_consistency scores 1: README claims 27 scanners and 3,422 tests, but provided test files cover only a forensify subset, so overall consistency is unverifiable. dependency_availability scores 2: zero dependencies and hash-locked CI, low availability risk. failure_messages scores 1: tests include error handling assertions (e.g., stat_failed, SchemaMismatch), but no user-facing failure message design evidence.
audience_and_scenarios scores 2: clearly targets AI agent ecosystem (Claude Code, Codex, OpenClaw, etc.) with specific scenarios. capability_boundaries scores 1: README lists scanners but does not clearly define out-of-scope areas or false-positive boundaries. trigger_precision scores 1: hook triggers described in README, but precise trigger rules and dedup logic evidence missing. environment_fit scores 2: supports multiple platforms (macOS, Linux, Windows) with platform-specific install notes.
information_architecture scores 2: README well-structured with TOC, tables, and collapsible details. install_notes scores 1: install commands provided, but full dependency and prerequisite notes missing. naming_stability scores 1: no naming stability commitment or versioned interface documentation. examples_and_faq scores 1: example output present, but no FAQ. known_limitations scores 1: no explicit known limitations or false-positive rate. license scores 2: full LICENSE file, PolyForm Noncommercial 1.0.0, with commercial licensing contact. versioning_changelog scores 1: version badge present, but no CHANGELOG file or version history. maintenance_responsibility scores 1: SECURITY.md and CLA exist, but publisher unverified, maintenance ownership unclear.
output_usability scores 2: output supports text, JSON, SARIF, and exit codes for CI gating, good usability. marginal_value scores 1: differentiated from existing tools (mcp-scan, Gitleaks) but lacks independent validation of detection efficacy. cost_benefit scores 1: zero dependencies and offline operation reduce cost, but installing hooks and schedulers adds ongoing maintenance cost, benefits unquantified.
claim_traceability scores 1: README cites external research links, but no mapping between internal claims and code. cross_source_corroboration scores 1: test files partially align with README, but no independent third-party verification. fact_inference_separation scores 1: README mixes facts with marketing language, not clearly separating verified facts from inference.
- Install scripts modify agent config directories such as ~/.claude and ~/.codex and register hooks, potentially affecting existing agent behavior; test in an isolated environment first.
- README claims 27 scanners and 3,422 tests, but provided files do not fully verify this; actual coverage may be less than advertised.
- Publisher identity is unverified, and the license is PolyForm Noncommercial; commercial use requires separate contact, note compliance risk.
- Automatic scheduler continuously refreshes threat intelligence, which may generate network requests; despite offline-first claims, confirm its network behavior.
What does this agent do, and when should you use it?
Repo Forensics is a pure-Python, zero-dependency, fully offline security scanner for untrusted repositories, skills, plugins, and MCP servers in the AI-agent ecosystem. It runs 27 parallel scanners covering prompt injection, supply-chain poisoning, credential theft, runtime behavior prediction, and infrastructure misconfiguration, then a 41-rule correlation engine chains findings across scanners to surface compound attacks such as an environment-variable read plus an outbound POST becoming a data-exfiltration finding. Every finding carries a confidence score and severity, aggregated into four verdict tiers (BLOCK, WARN, INFO, SUPPRESSED) with exit codes 0/1/2 for CI/CD gating, and exported as text, JSON, summary, or SARIF 2.1.0. Installed as an agent plugin, three hooks (PreToolUse, PostToolUse, SessionStart) block known-malicious packages before execution, deep-scan newly cloned code, and diff plugin/skill/MCP changes each session, while detection logic itself refreshes daily via an Ed25519-signed rule feed. Scanning never requires network access and nothing is uploaded anywhere.
The entry point is ./skills/repo-forensics/scripts/run_forensics.sh, pointed at any repo, skill directory, or MCP server, with flags including --skill-scan (17 focused scanners), --watch (SHA256 integrity baselines), --update-iocs, --update-vulns, --offline, --no-vulns, --verify-install, --format json|sarif, and --inventory for the Forensify installed-stack audit. The 27 scanners include skill_threats (11 detection categories, 160+ regex patterns: prompt injection, unicode smuggling, ClickFix, MCP injection, GlassWorm variation selectors), mcp_security (tool poisoning, tool shadowing, rug-pull enablers, TrustFall .mcp.json inline node -e / python -c RCE), dependencies (typosquatting, 500+ popular packages, 190+ package IOCs, lockfile parsing for npm/yarn/poetry/pipfile, OSV API queries cross-referenced with CISA KEV), lifecycle (npm/pip install hooks, .pth injection, paste-service dead-drops, ~/.claude and ~/.cursor config injection), git_forensics (timestamp manipulation, identity spoofing, git replace objects and grafts), binary (disguised executables, audio steganography, embedded PE), entropy (decodes base64/85/32/hex blobs and rescans the plaintext), archive (magic-byte detection of renamed zip archives, executables smuggled inside OOXML), bytecode (diffs .pyc danger markers against sibling source to detect bytecode poisoning without unmarshalling), splitstream (reassembles payload fragments scattered across files), dead_anchors (SkillJacking via claimable GitHub owners, phantom packages, expired domains), provenance (shells out to cosign/gh/npm/pip and flags only failed verification as CRITICAL), and yara (11 hand-authored rules for webshells, malware, cryptominers, hacktools). A refresh_controller.py manages threat-feed refresh through native schedulers on macOS, Linux, and Windows.
- You are about to add a Claude Code skill, OpenClaw plugin, or third-party MCP server from a Discord link or the marketplace — scan the repo first and confirm there is no prompt injection or tool poisoning before letting your agent install it.
- A security engineer wants dependency and lifecycle-hook checks enforced on every pull request: wire the GitHub Action with
mode: fulland let exit code 2 block the merge. - You suspect you already installed something bad (a suspicious npm package or an axios-style RAT) and want post-incident forensics over your npm cache, node_modules, install logs, and host persistence artifacts.
- A developer using Codex CLI or Cursor wants install-time protection, so they wire the hooks and let the beforeShellExecution / PreToolUse IOC gate block known-malicious packages before pip/npm/bun run.
- A platform team auditing its internal skill marketplace generates SARIF output and routes results into the GitHub Security tab for centralized triage.
- A supply-chain researcher needs a reproducible, offline, no-telemetry detection baseline to run regression tests against synthetic fixtures in an isolated network.
What are this agent's strengths and limitations?
- Zero non-stdlib imports and fully offline operation: no cloud API, no telemetry, nothing uploaded — explicitly contrasted with mcp-scan, which sends code to a cloud API.
- 27 scanners plus a 41-rule correlation engine catch compound attack chains no single scanner sees (Lethal Trifecta, install-time theft, hidden instruction attacks, git-based exfiltration).
- Detection logic ships as 7 Ed25519-signed JSON rule packs (400+ rules) that refresh daily without a code release, with cryptographic verification and a rollback-protected version floor.
- Broad agent coverage with real install-time gating: PreToolUse IOC checks under 10ms, a 0.9ms no-change session scan, and platform installers for Claude Code, Codex CLI, OpenClaw, and Cursor.
- SARIF 2.1.0 output plus documented exit codes make it a drop-in CI/CD gate for the GitHub Security tab and any SARIF-consuming tooling.
- 3,422 pytest tests run entirely against synthetic fixtures in temp directories with no real malware downloaded or executed, so the suite is safe to run.
- Licensed under PolyForm Noncommercial 1.0.0: free only for personal, research, education, and organizations under 5 total headcount (or under $20k/month); everyone else must negotiate a commercial license.
- The README itself states this is defense-in-depth and not a guarantee, and instructs users to verify findings manually — false positives and false negatives are expected.
- CVE and CISA KEV enrichment depends on live network calls to api.osv.dev and the KEV catalog; with --offline you fall back to cached data and lose freshness.
- The YARA scanner needs optional yara-python; without it that capability degrades to an exit-neutral capability gap rather than working out of the box.
- Provenance verification shells out to cosign, gh, npm, and pip, so signature checking silently does nothing when those tools are absent from PATH.
- OpenClaw and Cursor hooks are not auto-wired by their plugin systems and each require a one-time install script, while NanoClaw has no plugin hook system and only supports manual invocation.
How do you install or deploy this agent?
Requires Python 3.8+. No pip install, no API keys, no Docker, no dependencies.
1) Standalone CLI:
git clone https://github.com/alexgreensh/repo-forensics.git
cd repo-forensics
./skills/repo-forensics/scripts/run_forensics.sh .2) Claude Code plugin (hooks auto-wire on install):
/plugin marketplace add alexgreensh/repo-forensics
/plugin install repo-forensics@alexgreensh-repo-forensicsEnable auto-update under /plugin > Marketplaces so new scanners and IOCs arrive automatically.
3) Codex CLI:
codex plugin marketplace add alexgreensh/repo-forensics --ref main
codex plugin add repo-forensics@alexgreensh-repo-forensicsRestart Codex and trust the four hook handlers. For a local checkout: python3 scripts/codex_install.py, verified with python3 scripts/codex_install.py --verify --require-registered.
OpenClaw: python3 scripts/openclaw_install.py (--uninstall to remove, --verify to check).
Cursor: python3 scripts/cursor_install.py (writes three hooks to ~/.cursor/hooks.json; --uninstall, --verify).
NanoClaw has no plugin hook system, so only manual /repo-forensics invocation applies.
How do you use this agent?
First-run self-scan and normal scans:
./skills/repo-forensics/scripts/run_forensics.sh .
./skills/repo-forensics/scripts/run_forensics.sh /path/to/repoFocused skill/MCP scan and machine-readable output:
./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 sarifInventory audit and vulnerability refresh:
./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 --jsonCI gate:
- name: Security gate
uses: alexgreensh/repo-forensics@v2
with:
mode: fullExit codes: 0 clean, 1 warn, 2 block merge. Once installed as a skill you can also just ask the agent, e.g. "Audit this repo before I add it as a dependency". Suppress false positives with a .forensicsignore file (the ignore file itself is scanned for overly broad patterns). Kill switches: REPO_FORENSICS_SESSION_SCAN=0 for session scans, REPO_FORENSICS_PRE_SCAN=0 (or =unsafe-off) for the blocking path.
How does this agent compare with similar options?
The README names and contrasts specific alternatives: NVIDIA SkillSpector (agent-skill pattern scanner limited to skill files, no correlation, supply-chain, live IOC+CVE feed, signed rules, or runtime prediction, and cannot read compiled/binary code), Gitleaks and TruffleHog (secrets only), Semgrep (requires configuration and is not AI-skill-aware), mcp-scan (uploads your code to a cloud API), GuardDog (Python packages only), ClawSec (8 external dependencies, wraps semgrep/bandit, no correlation engine), VirusTotal + ClawHub (signature-based, surface-level, no prompt-injection or taint tracking), and manual review (misses zero-width unicode, cross-file taint flows, and tool-description injection). Repo Forensics positions itself as 27 scanners, zero dependencies, fully offline, with runtime behavior prediction and post-incident forensics, matching SkillSpector's SARIF and YARA surfaces while adding the rest.