Merge pull request #39 from elementalsouls/harden-recon

Engine: map-first deterministic recon + skill-arsenal categorization

Author: elementalsouls

engine/README.md

@@ -1,55 +1,80 @@
-# Engagement engine (v0)
+# Engagement engine
 
-The eval harness proved the gap to "automate 80% of the grind" isn't the *skills*
-(the base model already exploits standard classes) — it's an **autonomous engagement
-system**: scope-safe, stateful, multi-step, false-positive-disciplined. This is that
-system's v0 skeleton.
+A **decision-support engine**, not an autonomous robot. It maps a target's attack surface
+deterministically, **categorizes it against the skill arsenal** (which `hunt-*` skill applies
+where), and **shows you each stage live** — so you spend your expert 20% where the 80%
+automation points. It does **not** try to test everything itself; active hunting is opt-in.
 
-## Design principle
-**Control flow is deterministic code; only hunting/verifying is the LLM.** Scope,
-state, dispatch, ranking, dedup, and reporting are Python — so a long unattended run
-is *safe* (can't go out of scope), *auditable* (everything on disk), and *resumable*.
+## Design principles
+1. **Deterministic-first.** Breadth (recon, parameter discovery, secret scanning, service
+   fingerprint, categorization) is plain Python + passive tooling — **`$0`, no agents, no
+   rate-limit burn**. The LLM is reserved for the few judgment calls in the opt-in hunt.
+2. **Map-first, hunting opt-in.** A default run stops at the **arsenal map** and hands off to
+   you. Spend agents only when you choose (`--hunt`).
+3. **Show every stage.** Each phase logs what it found, live, so you always know where to focus.
+4. **Curl-first.** Active testing uses `curl`; Burp MCP is optional (OOB/blind/fuzzing only).
+5. **Safe by construction.** Scope is a deterministic allowlist; agents run **read-only by
+   default** with hard rules-of-engagement; a deterministic scope-audit flags any out-of-scope PoC.
 
 ```
-scope ─▶ recon ─▶ rank ─▶ hunt ─▶ validate ─▶ report
-  │        │                 │         │
-  │        └ discoveries filtered to in-scope hosts
-  └ deterministic allowlist; no agent is ever dispatched at an out-of-scope target
-                            │         └ adversarial verifier rejects false positives
-                            └ one focused hunt agent per ranked (url, param, class)
+            DEFAULT (deterministic, $0, no agents)        │  OPT-IN  (--hunt)
+ recon ───▶ rank ───▶ map ──────────────────────────────▶│  hunt ─▶ validate ─▶ report
+   │          │         └ surface → skill arsenal +       │   │         └ adversarial verifier (read-only)
+   │          │           curl-first probes (arsenal.md)  │   └ curl-first agent per ranked (url,param,class), skills-off
+   │          └ class-weight priority (secrets boosted)   │
+   └ service/tech + JS endpoints + JS secrets + ALL params (gau + katana), categorized
 ```
+> **OSINT (subdomain/asset enum) is a *separate* concern** — handled by Claude-OSINT, not the
+> engine. The engine takes the in-scope seed target(s) and goes straight to deterministic recon.
 
 | Piece | What it is |
 |---|---|
 | `scope.py` | deterministic allowlist (apex/wildcard/CIDR/regex; deny-wins; default-deny). Enforced at recon **and** hunt. |
-| `state.py` | persistent, resumable engagement store (`state.json` + `evidence/` + `engine.log` + `report.md`). |
-| `agent.py` | headless `claude -p` dispatch (skills + Burp MCP) + JSON extraction. |
-| `engine.py` | the orchestrator: phases, scope enforcement, ranking, candidate→confirm flow, report. |
+| `recon.py` | **deterministic recon** — per target: service/tech (JS markers), JS-bundle endpoint mining, **JS secret scanning** (AWS/GCP/Anthropic/OpenAI/Slack/GitHub/Stripe/EmailJS… keys, redacted), and **all input parameters** from two independent sources — `gau` (passive historical) + `katana` (active live crawl). Noise-filtered, scope-filtered, multi-class categorized. No LLM in the find-step. |
+| `skill_map.py` | **arsenal categorization** — maps each `(endpoint\|param, class)` → the specific `hunt-*` skill(s) **actually installed** in `~/.claude/skills`, plus a curl-first starter probe. Tech-stack skills (`hunt-nextjs`, `hunt-nodejs`…) mapped from the fingerprint. |
+| `osint.py` | **separate/optional** — per-target service/tech probe (PD `httpx-toolkit`) reused by recon. Its subdomain-enum path is *not* in the engine flow (that's Claude-OSINT). |
+| `state.py` | persistent, resumable engagement store (`state.json` + `evidence/` + `engine.log` + `arsenal.md` + `report.md`). |
+| `agent.py` | headless `claude -p` dispatch + JSON extraction. **Skills OFF by default** (eval: ~0 capability gain, saves ~12–15k tokens/agent). Used only for the opt-in hunt/validate. |
+| `engine.py` | the orchestrator: phases, scope enforcement, ranking, the map, parallel hunt/validate, candidate→confirm, report. |
+
+## The map (the default deliverable)
+`map` writes `arsenal.md` and logs every target live — for each endpoint/parameter: the attack
+classes, the exact `hunt-*` skill(s) to open, and a ready-to-run curl. Example line:
+```
+map:   redirect_to   https://t/wp-login.php?redirect_to=FUZZ   ssrf→hunt-ssrf  lfi→hunt-lfi  open-redirect→hunt-open-redirect
+```
 
 ## Run
 ```bash
-cp engine/burp-mcp.json.example engine/burp-mcp.json   # set your mcp-proxy jar path
+# DEFAULT — deterministic map only ($0, no agents). Stops for you with arsenal.md:
+python3 engine/engine.py --scope my-engagement.json
+#   scope file = {name, in_scope, out_of_scope, seeds}; output in ~/.bughunter-engagements/<name>/
 
-# dry-run the whole flow with canned agent output (no agents, no budget) — proves the wiring:
-python3 engine/engine.py --scope engine/engagement.example.json --base /tmp/eng --mock
+# OPT-IN — auto-test the mapped surface with agents (read-only, curl-first, parallel):
+cp engine/burp-mcp.json.example engine/burp-mcp.json   # only if you want Burp for OOB/blind
+python3 engine/engine.py --scope my-engagement.json --hunt --parallel 3 --max-hunts 12
+python3 engine/engine.py --scope my-engagement.json --hunt --allow-intrusive   # permit state-changing PoCs (off by default)
 
-# live (needs Burp running + claude budget); scope file = {name, in_scope, out_of_scope, seeds}:
-python3 engine/engine.py --scope my-engagement.json --max-hunts 8
-python3 engine/engine.py --scope my-engagement.json --phases hunt,validate,report   # resume later phases
+# dry-run the whole wiring with canned output (no agents, no budget):
+python3 engine/engine.py --scope engine/engagement.example.json --base /tmp/eng --mock --hunt
+
+# standalone recon (deterministic, no engine state):
+python3 engine/recon.py https://target/ target.com
 ```
-Engagement state + report land in `~/.bughunter-engagements/<name>/` (outside the repo).
-
-## Honest status (v0)
-- **Deterministic backbone: built, unit-tested, and mock-validated end-to-end** (scope-drop of
-  out-of-scope hosts, rank, candidate→confirm, FP-rejection at validate, report, resume).
-- **Live agent phases: wired but not yet run** — blocked on Burp + claude budget (rate-limited at
-  build time). The same `claude -p` + Burp MCP path is already proven by the eval harness.
-- **v0 limitations (the road ahead):** recon is single-seed and agent-driven (no subdomain enum /
-  multi-host sweep yet); no chaining/escalation between findings; ranking is a static class-weight
-  heuristic; reporting is a deterministic template (not yet the report skills). These are the next
-  increments toward a system that does a real multi-host engagement unattended.
+Key flags: `--hunt` (opt into agents) · `--allow-intrusive` (default OFF = read-only) ·
+`--parallel N` (concurrent agents, default 3) · `--phases a,b,c` (explicit override).
+
+## Safety
+- **Read-only by default** — hunt/validate agents are told: in-scope hosts only (never
+  third-party, even to prove a finding), and no state-changing actions (no emails/writes/
+  deletes/cache-purge, don't exercise exposed creds). `--allow-intrusive` lifts this.
+- **Deterministic scope-audit** — every confirmed finding is checked for out-of-scope hosts in
+  its PoC; any hit is flagged (⚠) in the report for review.
+- **Calibrated severity** — the adversarial validator's severity (not the hunt's raw guess) is
+  what's stored.
 
 ## Why this and not more skills
-The measured result (`eval/`): skills add ~0 capability on benchmarkable tasks because the model
-already has them. The leverage is here — turning that raw capability into a *safe, stateful,
-self-verifying* engagement loop. This is the part that doesn't exist for free in the base model.
+The measured result (`eval/`): skills add ~0 capability on benchmarkable tasks — the base model
+already exploits standard classes, and skills cost ~12–15k tokens/agent to load. The leverage is
+here: turning that raw capability into a **safe, deterministic, skill-routing, operator-in-the-
+loop** engine. Breadth is free and visible; you bring the judgment.

engine/agent.py

@@ -21,7 +21,8 @@
 ])
 
 
-def run_agent(task, skills_on=True, model="claude-sonnet-4-6", max_turns=40, timeout=600):
+def run_agent(task, skills_on=False, model="claude-sonnet-4-6", max_turns=40, timeout=600):
+    # skills OFF by default: the eval showed they add ~0 capability but cost ~12-15k tokens/agent.
     cmd = ["claude", "-p", task,
            "--mcp-config", MCP_CONFIG, "--strict-mcp-config",
            "--permission-mode", "bypassPermissions",