/repo-forensics

name: repo-forensics
description: Security forensics for git repos, AI skills, and MCP servers. Audits dependencies, detects prompt injection, credential theft, runtime dynamism, manifest drift, known CVEs, CISA KEV (actively exploited) vulns, and 2026 attack patterns. Not for fixing vulnerabilities or pentesting.
metadata:
  author: Alex Greenshpun
allowed-tools: Bash Read Glob Grep
user-invocable: true
argument-hint: <repo_path> [--skill-scan] [--format text|json|summary|sarif] [--update-iocs] [--update-vulns] [--no-vulns] [--offline] [--watch] [--verify-install]

<!-- repo-forensics v2 | built by Alex Greenshpun | https://linkedin.com/in/alexgreensh -->

Repo Forensics v2

Deep security auditing for repositories, AI agent skills, and MCP servers.

Highlights

• **Rules-as-data** (v2.10): ~545 behavioral detection patterns live in versioned

JSON rule packs (`data/rulepacks/*.json`), not compiled into source. Each rule carries a stable id, severity, confidence score, explanation, and embedded self-tests. Pack-driven scanners: secrets, SAST, skill threats, MCP security, runtime dynamism, and shared patterns. Algorithmic scanners (entropy, AST, DAST, git forensics, integrity, manifest drift, binary, lifecycle, dependencies, infra, devcontainer, post-incident, dataflow, entrypoint) remain code-driven; they do not receive feed updates.

• **Signed daily rule-pack feed** (v2.10): New detection rules reach installed users

without a code release. An Ed25519-signed bundle is fetched by the daily `refresh_threat_dbs.py` pipeline. Shipped packs always work offline; the feed only overlays when verified, schema-valid, and strictly newer than the last accepted version. The same signing now covers the IOC feed for symmetric trust.

• **Confidence tiers + verdict levels** (v2.10): Findings carry a `confidence` score.

Four verdict tiers shape output and agent routing: BLOCK (>= 0.92), WARN (>= 0.60), INFO (>= 0.30), SUPPRESSED (< 0.30 or user-suppressed). Severity still drives exit codes (0/1/2/99) unchanged.

• **Separated trust signals**: JSON reports expose `core_verdict`,

`coverage_status`, and `enrichment_status`. `core_verdict` is the deterministic install gate. Coverage and enrichment report what could not be checked and may add warnings or context, but they cannot remove findings, reduce severity, or lower the deterministic exit code.

• **Persistent adjudication downgrades**: a WARN finding the adjudicator downgrades

as benign can be recorded as a rejected-claim fingerprint (rule id + file + content hash) in the local history DB (`scripts/suppressions.py add`). Exact re-matches are suppressed on later scans - non-critical WARN tier only (a critical finding, BLOCK or pre-scan block can never be persisted away), any content edit re-fires the finding, reports list the suppressions that apply to the scanned repo with a one-command revoke, and the auto-scan hook names any suppression it applied.

• **Local scan attestations**: `--history` stores content-addressed attestations in

a private local SQLite database. Storage and deferred retries stay off the verdict path; storage failure does not change scan output or exit behavior.

• **Offline benign-corpus FP gate** (v2.10): A committed corpus of tricky-but-clean

content (emoji-rich markdown, legitimate postinstall scripts, `.env.example`, OAuth docs, clean SKILL.md) runs in pytest. Any rule change that raises new false positives on the corpus fails the test before it can ship.

• **Advisory adjudication** (v2.10): WARN-tier findings include an injection-safe

adjudication block. Snippets are prefixed with `> SNIPPET: ` (not in code fences), metadata appears before content, the block is capped at 5 findings sorted by confidence descending. Verdict choices: confirm / downgrade / escalate. See "Adjudication Protocol" section for the full protocol. Confirm and refute responses are annotations only. Disagreement, invalid output, containment failure, or unavailable service remains unresolved and never gates the verdict.

• **Auto-scan hook** (v2): PostToolUse hook auto-triggers on `git clone`, `git pull`, `pip install`, `npm install/update`, `uv add/sync`, `bun install/add`, `pnpm install/add`, `gem install/update`, `brew install/upgrade`, etc. Zero-overhead for non-matching commands.
• **Pre-execution gate** (v2.6): PreToolUse hook blocks known-malicious packages and pipe-to-shell commands BEFORE execution. IOC-only, <10ms latency, no subprocess calls.
• **Session security scanner** (v2.6.3): SessionStart hook detects updated plugins/skills/MCP servers, refreshes threat databases daily, runs fast IOC check + full 29-scanner deep scan on changed items. Sub-1ms when nothing changed.
• **.pth file injection detection** (v2): Detects liteLLM-style Python startup injection attacks (exec/eval/base64/known IOC filenames)
• **Transitive dependency scanning** (v2): Deep-parses `package-lock.json`, `yarn.lock`, `poetry.lock`, `Pipfile.lock` for supply chain IOCs
• **DAST scanner** (`scan_dast.py`): Dynamic analysis of Claude Code hooks with 8 malicious payload types, sandboxed execution
• **File integrity monitor** (`scan_integrity.py`): SHA256 baselines for critical config files, drift detection with `--watch`
• **IOC auto-update** (`--update-iocs`): Pull latest indicators of compromise from remote feed
• **Installation verification** (`--verify-install`): Verify repo-forensics itself hasn't been tampered with
• **GitHub Actions** (`action.yml`): CI/CD integration for automated security gating
• **Runtime behavior prediction** (`scan_runtime_dynamism.py`): Detects code that changes behavior after install: dynamic imports, fetch-then-execute, self-modification, time bombs, dynamic tool descriptions
• **Manifest drift detection** (`scan_manifest_drift.py`): Compares declared vs actual dependencies, catches phantom deps, runtime installs, conditional import+install fallbacks
• **MCP rug pull de