repo-forensics

<!-- 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.
- **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 27-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 detection**: Tool descriptions sourced from database, network, env vars, or conditional logic
- **Enhanced AST analysis**: 12 patterns including marshal.loads, types.CodeType, sys.addaudithook, bytes decode obfuscation, self-modification
- **Test suite**: 1,800+ pytest tests covering all scanners
- **OpenClaw/ClawHub scanning**: Auto-detects OpenClaw skills, validates frontmatter, tools.json, SOUL.md, .clawhubignore
- **Anti-forensics detection** (v2): Self-deleting installers, package.json overwrite, version mismatch (Axios supply chain pattern)
- **Compromised version detection** (v2): Flags known-bad versions of legitimate packages (Axios, liteLLM, vpmdhaj OpenSearch typosquats, Miasma/Red Hat Cloud Services)
- **Suspicious npm scope detection** (v2): Flags systematic MCP server forking campaigns (iflow-mcp)
- **Host IOC scanning** (v2): Known RAT binary paths, C2 domains, malicious file hashes
- **CVE-2026-33068 detection** (v2): Workspace trust bypass via bypassPermissions in Claude Code settings
- **Post-incident forensics** (v2.2): npm cache/log artifacts, RAT binary detection, C2 persistence, node_modules traces that survive dropper se