OpenHack is a lightweight, file-based workspace designed to automate vulnerability research by mimicking a human research team's methodology. It provides a structured, checkpointed workflow for source-guided whitebox security reviews, enabling engineers and researchers to efficiently discover and triage vulnerabilities. The system maintains durable state in plain files and integrates human approval at critical phase transitions, offering a robust alternative to traditional automated scanning.

How It Works

The project operates as a state machine driven by file artifacts. Reconnaissance agents discover potential vulnerabilities, which are then processed by a router agent into scoped scenarios. Expert agents analyze these scenarios to prove or reject them, generating finding candidates. An independent triage agent then validates these candidates before they are materialized as final findings. This workflow is designed to be checkpointed, with human approval required for each phase transition, ensuring control and auditability. The durable chain of artifacts, from recon items to final findings, provides a clear audit trail.

Quick Start & Requirements

Installation involves an editable pip install from the cloned repository root: python3 -m pip install -e .. The tool is designed to be invoked from within a cloned checkout, with the OPENHACK_ROOT environment variable set if running externally. It can be integrated with common model harnesses like Claude Code, Codex, or Cursor, or used via a manual CLI flow. A typical workflow starts with openhack init-run <target> <git-url> --run-id <id>. Detailed instructions are available in docs/QUICKSTART.md.

Highlighted Details

• Mimics the Hadrian research team's automated vulnerability research methodology.
• Supports integration with LLM harnesses (Claude Code, Codex, Cursor) or custom runners.
• Features 12 OWASP/MITRE-aligned expert families for root-cause analysis.
• Includes optional Semgrep integration for enriched reconnaissance and hint generation.

Maintenance & Community

The provided README does not detail specific maintenance contributors, sponsorships, or community channels like Discord or Slack.

Licensing & Compatibility

The project is licensed under the MIT license. No specific restrictions for commercial use or closed-source linking are mentioned, aligning with typical MIT license terms.

Limitations & Caveats

This project is explicitly described as an "experimental research prototype," provided "as-is and without warranty." It is not a security product, has not undergone independent auditing, and should not be relied upon as a sole or primary means of assessing risk. It may miss real vulnerabilities or generate false positives, and is not a substitute for professional audits or established static analysis tools. Users accept full responsibility for its outcomes.