How It Works
Repo Forensics is an offline security scanner designed to audit AI-agent repositories, skills, plugins, and MCP servers before they interact with an agent or system. It operates entirely locally, requiring no internet connection, dependencies, or telemetry. These findings are cross-referenced against 41 rules to identify compound threats that individual scanners might miss. For example, a dynamic import paired with a network fetch is flagged as a deferred payload loading risk, while an environment variable read combined with an outbound POST is marked as potential data exfiltration.
Each finding is assigned a severity level and confidence score, categorized into four verdict tiers: BLOCK, WARN, INFO, and SUPPRESSED. Ambiguous findings in the WARN tier can be further evaluated by the host agent (such as Claude Code or Codex) using a sanitized protocol that avoids introducing new attack surfaces. The results are presented in multiple formats, including text, JSON, a compact summary, or SARIF 2.1.0, which integrates directly with the GitHub Security tab and other SARIF-compatible tools. The SARIF output maps severity levels to SARIF standards (critical and high as errors, medium as warnings, and low/info as notes) and ensures Windows paths are converted to forward-slashed relative URIs for consistency.
Repo Forensics also includes a YARA signature scanner capable of detecting curated malware families, including webshells, cryptominers, and hacktools. The tool’s design ensures that scanning never requires network access, relying instead on a cryptographically signed rule pack that refreshes daily via an Ed25519-signed feed. This feed is verified on every load, rollback-protected, and degrades safely to the last known good state if unreachable. The rule packs themselves are versioned, auditable, and independently updatable, ensuring detection logic remains current without requiring code releases or reinstalls.
Beyond static scanning, Repo Forensics provides continuous protection through three hooks that monitor installations, updates, and new sessions. These hooks block known-malicious packages before execution, ensuring that even updates to previously trusted repositories are scrutinized. The tool integrates with package managers such as npm, pip, uv, bun, and pnpm, as well as shell commands, to intercept and vet changes in real time. Latency varies by scenario: a session with no changes incurs a 0.9ms overhead, while a deep scan of a modified plugin may take 2–10 seconds. A kill switch (REPOFORENSICSSESSIONSCAN=0) reduces latency to 0.02ms when disabled.
For post-incident analysis, Repo Forensics can scan existing projects to detect traces of known supply chain attacks, even if the malware has been removed. It examines npm caches, install logs, node_modules directories, and host artifacts for indicators of compromise (IOCs) such as the axios RAT, liteLLM .pth injection, or the SANDWORM campaign. This modular approach allows for granular updates to detection logic without affecting the core scanner.
The scanner’s rule packs are refreshed daily through a cryptographically verified feed, ensuring that new behavioral detection rules are distributed without requiring a code release. The feed is designed to be offline-first, with a fallback mechanism that uses locally stored rule packs if the feed is unavailable. This approach maintains detection efficacy even in air-gapped environments. Additionally, the tool includes a refresh controller that manages the scheduler’s active version, ensuring compatibility across different agent versions (e.g., Claude, Codex, OpenClaw) and preventing downgrade attacks. The controller also handles health reporting, idempotent repairs, and persistent disable/enable states, with automatic re-enablement upon reinstallation.
Security updates are regularly released to address vulnerabilities and improve detection accuracy. For instance, Release 2.14.9 introduced a critical fix for a remote code execution (RCE) vulnerability where scanning a hostile repository could execute attacker-controlled code via malicious .git/config directives. This was mitigated by routing all git invocations through a hardened runner that disarms exec-capable configurations. Release 2.14.10 added detection for kernel privilege-escalation and sandbox-probing techniques, while Release 2.14.11 addressed rule-pack publication inconsistencies and improved feed health reporting. These updates reflect a commitment to addressing real-world threats, as evidenced by the tool’s battle-tested detection patterns derived from actual supply chain campaigns.
All releases are byte-identical across mirror trees and signed with Ed25519 to ensure integrity. The release manifest is also signed, providing an additional layer of verification for users.
Use Cases
Repo Forensics is primarily used for pre-installation vetting of AI-agent repositories, skills, plugins, and MCP servers. Its core use case is preventing the installation of malicious or compromised code before it interacts with an agent or system. For example, it can audit a GitHub Actions workflow contributed via a pull request, a Claude Code skill shared in Discord, or a Cursor npm package added to a lockfile.
The tool is particularly valuable in environments where third-party code is frequently integrated, such as AI research labs, enterprise AI deployments, or open-source communities. It addresses a critical gap in AI security: the lack of systematic vetting for external components. Research indicates that 36.8% of agent skills contain security flaws, and campaigns like Snyk ToxicSkills have uncovered over 1,184 malicious skills on platforms like ClawHub. Repo Forensics provides a proactive solution to this problem by blocking known-malicious packages and detecting sophisticated attack patterns, such as full-schema poisoning, tainted data reaching network sinks, and zero-width character clusters used for text smuggling.
Beyond pre-installation scanning, Repo Forensics offers continuous protection by monitoring updates to existing repositories. For instance, it can block a package update that introduces a backdoor or exploit, even if the original installation was deemed safe. This is particularly important in dynamic environments where dependencies evolve over time. The tool’s post-incident scanning capability allows organizations to retroactively investigate compromised projects, identifying traces of attacks such as the axios RAT or SANDWORM campaign even after the malware has been removed.
Repo Forensics is also useful for integrating security checks into CI/CD pipelines. Its severity-ranked verdicts and exit codes (e.g., EXIT CODE: 2 for ‘do not install’) can be used to gate deployments, ensuring that only vetted components are deployed to production. The SARIF output format further enhances its utility by enabling seamless integration with GitHub’s Security tab and other SARIF-consuming tools, providing a centralized view of security findings. This makes it easier for security teams to track and prioritize vulnerabilities across projects.
In addition to its technical applications, Repo Forensics supports security research and red teaming efforts. Its detection patterns are derived from real-world supply chain campaigns, including named attacks like SANDWORM and Beltdown (hostile .git/config directives). The tool’s open-source nature and customizable rule packs also allow organizations to tailor detection logic to their specific threat models, further enhancing its versatility.
Key Features & Capabilities
- Offline and Dependency-Free: Repo Forensics operates entirely offline with zero dependencies, ensuring no telemetry or network access is required. This makes it suitable for air-gapped environments and reduces the risk of introducing additional attack surfaces.
- Comprehensive Scanning: The tool employs 28 parallel scanners to cover a wide range of attack surfaces, including prompt injection, supply chain vulnerabilities, credential theft, runtime behavior, and infrastructure misconfigurations. Findings are cross-referenced against 41 rules to detect compound threats.
- Real-Time Monitoring: Three hooks monitor installations, updates, and new sessions across package managers (npm, pip, uv, bun, pnpm) and shell commands. Known-malicious packages are blocked before execution, and updates to existing repositories are continuously vetted.
- Post-Incident Forensics: The tool can scan existing projects to detect traces of known supply chain attacks, even after malware has been removed. It examines npm caches, install logs, node_modules directories, and host artifacts for IOCs such as the axios RAT or SANDWORM campaign.
- Dynamic Rule Updates: Detection logic is updated via cryptographically signed rule packs that refresh daily. These packs are versioned, auditable, and independently updatable, ensuring that new threats are addressed without requiring code releases or reinstalls.
- Multi-Format Output: Results are available in text, JSON, compact summary, or SARIF 2.1.0 formats. SARIF output integrates with GitHub’s Security tab and other SARIF-compatible tools, providing a standardized way to manage and prioritize findings.
- Battle-Tested Detection: The tool’s detection patterns are derived from real-world supply chain campaigns, including named attacks like SANDWORM and Beltdown. It has been tested against 4,059 scenarios across 40+ test files, ensuring robustness against production-level threats.
- Critical Vulnerability Fixes: Regular updates address security vulnerabilities, such as the RCE fix in Release 2.14.9, which prevented scanning hostile repositories from executing attacker-controlled code. Other updates include detection for kernel privilege-escalation, sandbox-probing, and audio-steganography false positives.
- Customizable and Extensible: The tool’s rule packs are modular and can be customized to address specific threat models. Users can also extend its functionality by adding new scanners or detection rules, making it adaptable to evolving security requirements.