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.
- **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.
- **LLM 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.
- **Auto-scan hook** (v2): PostToolUse hook auto-triggers on `git clone`, `git pull`, `pip install`, `npm install/update`, `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 20-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,350+ 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 self-cleanup
- **Supply chain hardening** (v2.2): .npmrc scanning, missing lockfile detection, git/HTTP dep flagging, hostname bypass fix, unbounded Python range detection, install script severity elevation
- **Devcontainer security scanning** (v2.6.5): JSON-based analysis of devcontainer.json for host secret mounts, container escape vectors, localEnv interpolation, lifecycle command risks, and untrusted features
- **Framework env prefix leak detection** (v2.6.5): Catches secrets exposed to browser bundles via NEXT_PUBLIC_, REACT_APP_, VITE_, EXPO_PUBLIC_, GATSBY_, NX_PUBLIC_ prefixes
- **process.env exposure detection** (v2.6.5): Flags console.log(process.env), JSON.stringify(process.env), and crash report env dumps
- **Docker ARG secret detection** (v2.6.5): Catches secrets passed via ARG directives (permanentl