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

• 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,280+ 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 1.14.1/0.30.4, liteLLM 1.82.8)
• 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 (permanently visible in docker history)
• 1Password/Vault token detection (v2.6.5): OP_CONNECT_TOKEN, ops_ service account tokens, hvs. Vault tokens
• 20 scanners with 41 correlation rules

When to Use

• Auditing a new repo or dependency before adding it to your project
• Vetting AI skills/plugins before installation (prompt injection, credential theft, backdoors)
• Auditing MCP servers for tool poisoning, SQL injection, config risks
• Security review when someone asks "is this code secure?"
• Forensic investigation of a suspected compromise
• CI/CD gating with machine-readable output and exit codes
• Hook security testing to verify Claude Code hooks handle malicious input safely

Quick Start

Full audit (all 20 scanners):

./scripts/run_forensics.sh /path/to/repo

Focused AI skill scan (10 scanners, faster):

./scripts/run_forensics.sh /path/to/repo --skill-scan

With IOC update and integrity monitoring:

./scripts/run_forensics.sh /path/to/repo --update-iocs --watch

Verify your installation:

./scripts/run_forensics.sh /path/to/repo --verify-install

JSON output for automation:

./scripts/run_forensics.sh /path/to/repo --format json

Severity System

| Level | Score | Meaning | Exit Code | |-------|-------|---------|-----------| | CRITICAL | 4 | Active threat, immediate action required | 2 | | HIGH | 3 | Significant risk, investigate promptly | 1 | | MEDIUM | 2 | Potential issue, review recommended | 1 | | LOW | 1 | Informational, may be false positive | 0 |

Scanners

| Scanner | What It Detects | Mode | |---------|----------------|------| | runtime_dynamism | Dynamic imports, fetch-then-execute, self-modification, time bombs, dynamic tool descriptions | skill + full | | manifest_drift | Phantom dependencies, runtime package installs, conditional import+install, declared-but-unused deps | skill + full | | skill_threats | Prompt injection, unicode smuggling, prerequisite attacks, ClickFix, MCP tool injection | skill + full | | agent_skills | SKILL.md frontmatter abuse, tools.json FSP, agent config injection (SOUL.md/AGENTS.md/CLAUDE.md), .clawhubignore bypass, ClawHavoc IOCs. Covers Claude Code, OpenClaw, Codex, Cursor, MCP. | skill + full | | mcp_security | SQL injection to prompt escalation, tool poisoning, rug pull enablers, config CVEs | skill + full | | dataflow | Source-to-sink taint tracking (env vars to network calls), cross-file import taint | skill + full | | secrets | 50+ patterns: API keys, tokens, private keys, database URIs, JWTs, framework env prefix leaks, 1Password/Vault tokens, .env variant files | skill + full | | sast | Dangerous functions, injection, shell execution across 8 languages, process.env exposure, path traversal | skill + full | | lifecycle | NPM hooks + Python setup.py/pyproject.toml cmdclass overrides + anti-forensics (self-deleting installers, package.json overwrite) | skill + full | | integrity | SHA256 baselines for .claude/settings.json, CLAUDE.md, hook scripts. Drift detection with --watch | full | | dast | Dynamic hook testing: 8 payload types (injection, traversal, amplification, env leak) in sandbox | full | | entropy | Per-string Shannon entropy, base64 blocks, hex strings (combo detection) | full | | infra | Docker (ENV/ARG secrets, .env COPY), K8s, GitHub Actions, Claude Code config (CVE-2025-59536, CVE-2026-21852, CVE-2026-33068) | full | | devcontainer | JSON-based devcontainer.json analysis: host mounts, privileged mode, docker.sock, remoteEnv localEnv interpolation, lifecycle commands, untrusted features | skill + full | | dependencies | NPM + Python typosquatting, l33t normalization, IOC packages (SANDWORM_MODE 2026), compromised version detection (Axios, liteLLM), suspicious scope detection (iflow-mcp) | full | | ast_analysis | Python AST: obfuscated exec chains, __reduce__ backdoors, marshal/types bytecode, audit hook abuse,