██████╗ ███████╗██╗   ██╗
██╔═══██╗╚══███╔╝╚██╗ ██╔╝
██║   ██║  ███╔╝  ╚████╔╝ 
██║   ██║ ███╔╝    ╚██╔╝  
╚██████╔╝███████╗   ██║   
 ╚═════╝ ╚══════╝   ╚═╝   

AUTONOMOUS BUG BOUNTY HUNTER

Ozy is an autonomous bug bounty hunter. You give it a program, it recons 24/7, detects changes, runs nuclei, and saves everything to SQLite. Claude investiga, decide, pivotea y persiste. Kali tiene las tools. Ozy orquesta.

---

How it works

flowchart LR
    Claude -->|MCP tools| Ozy[Ozy Daemon]
    Ozy -->|SSH| Kali[☣️ Kali VM<br/>nuclei, httpx, curl, nmap...]
    Ozy <-->|read/write| SQL[(SQLite)]

Loading

Ciclo de investigación

1. configure_program("dockerlabs", <texto VDP>)
2. start_hunt("dockerlabs", "dockerlabs.es")
     → Ozy: recon (Kali) → www + mail → nuclei scan → findings

3. get_report() → ve "ReDoc API detectado"
     → Decide investigar

4. run_tool("dockerlabs.es", "/fastapi-openapi.json")
     → Ozy: SSH → Kali → curl → 127 endpoints
     → add_finding("API spec expuesta", medium, chain="api-surface")

5. run_tool("dockerlabs.es", "gobuster dir -u /api/")
     → Ozy: SSH → Kali → gobuster → nuevos endpoints
     → add_finding("IDOR encontrado", high)

6. investigate_add("/api/change_password", "probar sin auth")
7. get_report() → findings consolidados con cadenas

Documentación detallada:

• docs/FLOW.md — Flujo técnico
• docs/HUNTING_FLOW.md — Ciclo de investigación
• AGENTS.md — Roles, responsabilidades y referencia MCP
• docs/ARCHITECTURE.md — Componentes

---

Quick start

# Infrastructure
docker run -d --name nats-main -p 4222:4222 -p 8222:8222 nats -js

# Build & run
make build
./build/ozy daemon

# Desde Claude:
configure_program("syfe", "<programa completo de HackerOne>")
start_hunt("syfe", "syfe.com")

# A la mañana siguiente:
get_status
get_report --severity high
get_deltas

Commands

Command	Description
ozy daemon	Single process: master + recon + scanner + MCP
ozy serve	MCP server for Claude (JSON-RPC over stdio)
ozy master	Master only (debug)
ozy worker --type recon	Recon worker only (debug)
ozy worker --type scanner	Scanner worker only (debug)
ozy version	Show version

MCP Tools

Tool	Description
configure_program	Parse program text → extract scope/rules/rewards
start_hunt	Add target → recon pipeline (subfinder → httpx → naabu + JS extraction, S3, dorking, params) → nuclei scan
get_status	Show all programs, targets, assets, findings
get_report	Query findings by target/severity/program, grouped by attack chain
get_deltas	Findings de las últimas 24h agrupados por severidad y fuente
run_tool	Executa cualquier tool en Kali vía SSH. Shorthand /endpoint → curl. Flags: --oob, --waf, --ssrf
add_finding	Persiste hallazgo manual con source, chain, pivots
investigate_add/list	Cola de investigación persistente
deep_scan	Scan completo con CVEs + vulnerabilidades (5min+)
scan_js	Extrae endpoints, secrets y source maps de JS
test_bola	Prueba sistemática de IDOR/BOLA
owasp_api_check	Checklist OWASP API Top 10
generate_report	Reporte estilo Immunefi listo para enviar
setup_proxy	Genera addon de mitmproxy para Kali. Filtra por dominio, inyecta headers
export_har	Exporta findings como HAR para importar en Caido/Burp

Dependencies

Infraestructura

• NATS — event bus (docker run -d --name nats -p 4222:4222 nats -js)
• Kali VM — VM con libvirt/qemu, todas las tools de ataque vía SSH

Kali VM (setup completo en docs/KALI_SETUP.md)

• nuclei — escáner de vulnerabilidades
• ffuf + wordlists (/usr/share/dirb/wordlists/) — fuzzing
• httpx, naabu, subfinder — recon base
• gau, waybackurls, dnsx, assetfinder, amass — pipeline phases
• interactsh-client — OOB detection
• mitmproxy — proxy scripting (opcional)

Opcionales externos

• Caido o Burp Suite — análisis manual (importar HAR via export_har)
• mitmproxy en Kali (addon generado via setup_proxy)

Features

Feature	Description
OOB Detection	Interactsh integrado en scans y run_tool --oob. Callbacks automáticos como findings
Pipeline completo	start_hunt corre recon (Kali) + 11 fases de pipeline (JS, params, S3, dorking, permutaciones)
Diffing	Detección de cambios entre sesiones vía state engine
Persistencia	Findings con source, chain, pivots en SQLite
Notificaciones	Telegram/Slack al guardar findings o completar scans
Proxy Automation	setup_proxy genera addon de mitmproxy listo para usar
Caido/Burp integración	export_har exporta findings como HAR

Docs

Doc	Content
docs/FLOW.md	Flujo completo paso a paso con diagramas Mermaid
docs/ARCHITECTURE.md	Resumen de componentes
docs/BREAKDOWN.md	Breakdown de packages + lo eliminado
docs/MCP.md	Configuración del MCP server
docs/BUG_BOUNTY.md	Workflow de bug bounty
docs/AI_WORKER.md	Cómo Claude orquesta Ozy via MCP

---

BUILT BY SAM