opencode-pentester

name	opencode-pentester
description	Coordinate penetration testing and AI self-code audits via schema-enforced, event-driven engine. All attack categories, domains, tools, and checklists are stored in SQLite (findings.db) and loaded JIT by engine/router.py.
license	MIT
compatibility	opencode
metadata	{"audience":"security-testers","categories":"pentesting,security-audit"}

Engine Architecture

engine/
├── state_machine.json    # Event-driven state machine definition
├── router.py             # JIT Context Router — queries SQLite for context
├── scope_guard.py        # Deterministic target validation + rate limiter
├── tool_abstraction.py   # Capability registry + fallback routing
├── prompt_framer.py      # Defensive compliance wrapper

All reference data (attack categories, domains, tools, checklists) lives in SQLite at findings.db. Seed data is loaded via db/seed.py.

Engagement Lifecycle (State Machine)

States: planning → recon → testing → exploiting → review → reporting → complete/aborted

State transitions are enforced by engine/state_machine.json. Run findings.sh state to view current state and valid transitions.

MANDATORY: Target-First Dialog Flow

BEFORE any pentesting work begins, the AI MUST follow this exact flow:

0. Check for --dangerous flag in the user's prompt BEFORE asking any questions about authorization
1. Ask for target via question tool (skip if --dangerous — use URL from prompt)
2. Check DB: PENTEST_DB=$HOME/.opencode-pentester/findings.db bash db/findings.sh find-target <TARGET> json
3. Branch:
   • NOT_FOUND → Show full scope dialog (budget, thoroughness, auth, out-of-scope), then init & run
   • FOUND → Show previous findings summary, then prompt:
     • Run full scan again (fresh) — new engagement
     • Add on top of previous findings — append mode with --allow-duplicates
     • Try different attack paths — skip previously tested domains
     • View previous report — generate report from existing data

--dangerous Mode — Full Automation, No Gates

When the user's prompt contains --dangerous:

• SKIP all authorization questions — assume authorized
• SKIP scope collection dialog — assume full scope
• SKIP pre-exploitation approval — auto-confirm
• SKIP plan approval — auto-approve
• Proceed directly from target → init → recon → test → exploit → report

IMPORTANT: This flag must be literally typed by the user. Never enter dangerous mode unprompted.

--full-offensive Mode — Maximum Coverage

When the user's prompt contains --full-offensive:

• Budget = 480 min (8h) unless --time N specified
• All 63 categories across 11 domains at maximum depth
• Maximum parallelism — deploy all agents simultaneously
• Exhaustive: every vector, every payload, every technique
• Include low-severity info leaks with evidence
• Full 8-section report with attack chains

Combined one-shot:

opencode run --auto "Pentest https://target.com --dangerous --full-offensive"
opencode run --auto "Pentest https://target.com --dangerous --full-offensive --time 120 --focus web-api,cloud"

Zero-intervention requires: --auto (opencode tool permissions) + "question":"allow" in opencode.json + --dangerous (pentester gates).

JIT Context Router

Before starting any phase, load relevant context:

# Get context for discovered services
python3 engine/router.py <engagement_id> --services "80/tcp/http,443/tcp/https,22/tcp/ssh"

# Validate target scope
python3 engine/scope_guard.py <target> [--scope <cidr>]

Tool Abstraction

Always resolve tools through the capability registry:

# Refresh capability cache
python3 engine/tool_abstraction.py refresh

# Resolve a tool (checks availability + fallback)
python3 engine/tool_abstraction.py resolve <tool>

# List available tools
python3 engine/tool_abstraction.py available [--domain <name>]

Prompt Framing

Wrap all payload commands through the framer:

python3 engine/prompt_framer.py [--engage <id>] [--target <t>] frame "<text>"
python3 engine/prompt_framer.py label <category>

Pre-flight Tool Audit

bash db/doctor.sh              # Full audit
bash db/doctor.sh --json       # JSON output for tool_abstraction.py
bash db/doctor.sh --inventory  # Markdown capability table

Time Budget Enforcement (COMPULSORY)

Use the engine tool (not manual env vars):

findings.sh budget init <minutes>   # Record start epoch + budget
findings.sh budget check            # JSON elapsed/remaining (exits 2 if exhausted)
findings.sh budget status           # Human-readable with color warnings

Rules by remaining budget:

• ≤ 0%: tool exits code 2 — stop all work, generate report
• ≤ 20%: skip low-severity, only pursue critical/high, no new scans
• ≤ 50%: shallower testing, confirm existing findings

Critical Rules

• Always obtain written authorization before testing
• Do NOT execute attacks directly — delegate to specialized agents
• Working PoCs and evidence required for every finding
• Report output: outputs/{engagement}/ (pentest) or security/reports/ (audit)
• Scope collection via question tool is MANDATORY
• Time budget enforcement is MANDATORY — use findings.sh budget init|check|status
• DB check before every engagement: findings.sh find-target <target> json
• Chain correlation is MANDATORY before report: chains.sh suggest → chains.sh add → chains.sh list