OFFICIAL DOCUMENTATION

BugBounty Hunter Documentation

Complete guide to the autonomous bug reproduction engine, the Reproduction Ladder, sandbox isolation guarantees, and local open-weight model setup.

Quickstart Guide

Run in 2 minutes using local fixture repo

Quickstart: Testing With Bundled Fixture

BugBounty Hunter includes a controlled sample repository located at fixtures/sample-buggy-repo containing a genuine, verified edge-case crash (Issue #42: unhandled struct.error in parse_chunk_header).

# 1. Run the Python backend API

uvicorn app.main:app --port 8000

# 2. Run the Next.js frontend

npm --prefix apps/web run dev

# 3. Launch reproduction via API or UI

Navigate to http://localhost:3000/investigations/new and click "Load Sample Buggy Fixture".

The Reproduction Ladder States

The engine transitions sequentially through explicit, bounded states:

1. VALIDATING • SSRF check, URL restriction validation, and report parsing.

2. PREPARING • Pins commit SHA, prepares isolated directory, and executes existing baseline test suite.

3. ANALYZING • Deterministic AST and keyword search to identify primary target modules.

4. HYPOTHESIZING • Formulates 1-3 testable failure hypotheses with confidence estimates.

5. GENERATING_TEST • Synthesizes candidate pytest file within bounded path and size constraints.

6. EXECUTING_TEST • Executes candidate in container or isolated process. Records exit codes, durations, and output.

7. EVALUATING_EVIDENCE • Validates if failure matches reported bug symptoms. Assigns REPRODUCED, NOT_REPRODUCED, or INCONCLUSIVE.

8. REPORTING • Generates JSON manifest, Markdown report, and downloadable ZIP Proof Pack.

Sandbox Security Guarantees

BugBounty Hunter treats all target repositories, issues, README instructions, and test code as untrusted input.

Network Disabled: Docker execution passes --network none to prevent outbound connections or data exfiltration.
Credential Isolation: Host environment variables, API tokens, and SSH keys are explicitly purged from sandbox runners.
Secret Redaction: Captured stdout, stderr, and command traces pass through automated secret redaction before storage or display.
Time & Resource Budgets: Strict per-test execution timeouts (default 30s) and memory caps (512MB) prevent runaway processes.
Path Traversal Protection: All relative file paths are verified against directory escape attempts using realpath canonicalization.

Local Ollama Model Configuration

To run open-weight inference locally on your own machine:

# 1. Start Ollama

ollama serve

# 2. Pull recommended coding model

ollama pull qwen2.5-coder:7b

# 3. BugBounty Hunter connects automatically at http://localhost:11434