Skip to content

A Claude Code skill bundle for bug hunting and external red-team work - 82 skills, 15 slash commands, 681 disclosed-report patterns curated across 24 core vulnerability classes, plus enterprise identity + infrastructure attack matrices.

feat(engine): autonomous engagement engine v0 (scope-safe, stateful)

Sachin Sharmac52c68158af9
diff --git a/engine/.gitignore b/engine/.gitignore
new file mode 100644
index 0000000..4d3b8b1
--- /dev/null
+++ b/engine/.gitignore
@@ -0,0 +1,2 @@
+# machine-specific MCP config (copy burp-mcp.json.example -> burp-mcp.json)
+burp-mcp.json
diff --git a/engine/README.md b/engine/README.md
new file mode 100644
index 0000000..6181506
--- /dev/null
+++ b/engine/README.md
@@ -0,0 +1,55 @@
+# Engagement engine (v0)
+
+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.
+
+## 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*.
+
+```
+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)
+```
+
+| 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. |
+
+## Run
+```bash
+cp engine/burp-mcp.json.example engine/burp-mcp.json # set your mcp-proxy jar path
+
+# 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
+
+# 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
+```
+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.
+
+## 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.
diff --git a/engine/agent.py b/engine/agent.py
new file mode 100644
index 0000000..294ab4e
--- /dev/null
+++ b/engine/agent.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+agent.py — the engine's LLM dispatch. Only recon/hunt/validate are model-driven;
+the orchestrator, scope, and state are deterministic code.
+
+Engine = headless `claude -p`: skills auto-activate, Burp MCP is the hands. Agents
+are asked to end with a fenced ```json``` block which we parse into structured data.
+"""
+import json
+import os
+import re
+import subprocess
+import time
+
+ENGINE = os.path.dirname(os.path.abspath(__file__))
+MCP_CONFIG = os.path.join(ENGINE, "burp-mcp.json")
+ALLOWED_TOOLS = " ".join([
+ "mcp__burp__send_http1_request", "mcp__burp__send_http2_request",
+ "mcp__burp__get_collaborator_interactions", "mcp__burp__generate_collaborator_payload",
+ "Bash(curl:*)", "Bash(python3:*)", "Bash(jq:*)", "Bash(openssl:*)", "Bash(base64:*)",
+])
+
+
+def run_agent(task, skills_on=True, model="claude-sonnet-4-6", max_turns=40, timeout=600):
+ cmd = ["claude", "-p", task,
+ "--mcp-config", MCP_CONFIG, "--strict-mcp-config",
+ "--permission-mode", "bypassPermissions",
+ "--allowedTools", ALLOWED_TOOLS,
+ "--max-turns", str(max_turns), "--model", model,
+ "--output-format", "json"]
+ if not skills_on:
+ cmd.append("--disable-slash-commands")
+ t0 = time.time()
+ try:
+ p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+ except subprocess.TimeoutExpired:
+ return {"result": "", "error": "timeout", "duration_s": round(time.time() - t0, 1)}
+ try:
+ d = json.loads(p.stdout)
+ res = d.get("result") or ""
+ # usage-limit / API errors come back as a short result with no real work
+ if "usage limit" in res.lower() or "session limit" in res.lower():
+ return {"result": res, "error": "rate-limited", "duration_s": round(time.time() - t0, 1)}
+ return {"result": res, "cost_usd": d.get("total_cost_usd"),
+ "num_turns": d.get("num_turns"), "error": None,
+ "duration_s": round(time.time() - t0, 1)}
+ except Exception as e:
+ return {"result": p.stdout[:300], "error": f"parse:{e}", "duration_s": round(time.time() - t0, 1)}
+
+
+def extract_json(text):
+ """Pull the last valid JSON array/object out of an agent reply."""
+ if not text:
+ return None
+ blocks = re.findall(r"```json\s*(.*?)```", text, re.S)
+ blocks += re.findall(r"```\s*(\[.*?\]|\{.*?\})\s*```", text, re.S)
+ for b in reversed(blocks):
+ try:
+ return json.loads(b.strip())
+ except Exception:
+ pass
+ for b in reversed(re.findall(r"(\[.*\]|\{.*\})", text, re.S)):
+ try:
+ return json.loads(b)
+ except Exception:
+ pass
+ return None
+
+
+if __name__ == "__main__":
+ # offline self-test of the JSON extractor (no agent call)
+ assert extract_json('blah ```json\n[{"a":1}]\n``` end') == [{"a": 1}]
+ assert extract_json('text {"x": "y"} more') == {"x": "y"}
+ assert extract_json("no json here") is None
+ assert extract_json('first {"a":1} then ```json\n{"b":2}\n```') == {"b": 2} # prefers fenced/last
+ print("agent.py extractor self-test: PASS")
diff --git a/engine/burp-mcp.json.example b/engine/burp-mcp.json.example
new file mode 100644
index 0000000..440cca7
--- /dev/null
+++ b/engine/burp-mcp.json.example
@@ -0,0 +1,8 @@
+{
+ "mcpServers": {
+ "burp": {
+ "command": "java",
+ "args": ["-jar", "<PATH-TO>/.BurpSuite/mcp-proxy/mcp-proxy-all.jar", "--sse-url", "http://localhost:9876"]
+ }
+ }
+}
diff --git a/engine/engagement.example.json b/engine/engagement.example.json
new file mode 100644
index 0000000..85656a6
--- /dev/null
+++ b/engine/engagement.example.json
@@ -0,0 +1,6 @@
+{
+ "name": "demo-local",
+ "in_scope": ["localhost", "127.0.0.1"],
+ "out_of_scope": ["admin.localhost"],
+ "seeds": ["http://localhost:3002"]
+}
diff --git a/engine/engine.py b/engine/engine.py
new file mode 100644
index 0000000..2170b49
--- /dev/null
+++ b/engine/engine.py
@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+engine.py — autonomous engagement orchestrator.
+
+Deterministic control flow (scope, state, dispatch, ranking, dedup, reporting);
+LLM only for recon/hunt/validate. Phases:
+
+ scope -> recon -> rank -> hunt -> validate -> report
+
+Scope is enforced in code at every boundary: recon discoveries are filtered to
+in-scope hosts, and no hunt agent is ever dispatched at an out-of-scope target.
+State is persisted after every step, so a run is auditable and resumable.
+
+ python3 engine/engine.py --scope engine/engagement.example.json --mock # dry-run the flow (no agents)
+ python3 engine/engine.py --scope my-engagement.json --max-hunts 8 # live (needs Burp + claude budget)
+ python3 engine/engine.py --scope my-engagement.json --phases hunt,validate,report # resume later phases
+"""
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from scope import Scope # noqa: E402
+from state import Engagement # noqa: E402
+import agent as A # noqa: E402
+
+# deterministic priority by class (impact-ish); used by rank
+CLASS_WEIGHT = {"rce": 100, "sqli": 90, "ssrf": 85, "auth-bypass": 85, "idor": 80,
+ "deserialization": 88, "xxe": 75, "ssti": 88, "lfi": 78, "open-redirect": 40,
+ "xss": 55, "cors": 45, "csrf": 50, "info-leak": 30}
+ALL_PHASES = ["recon", "rank", "hunt", "validate", "report"]
+
+
+class Engine:
+ def __init__(self, scope_path, base, model, max_hunts, max_turns, timeout, mock=False):
+ self.scope = Scope.load(scope_path)
+ self.eng = Engagement(base, self.scope.name)
+ self.model, self.max_hunts = model, max_hunts
+ self.max_turns, self.timeout, self.mock = max_turns, timeout, mock
+ self.eng.log(f"engine start | scope={self.scope.name} in={self.scope.in_scope} "
+ f"out={self.scope.out_of_scope} seeds={self.scope.seeds} mock={mock}")
+
+ # ---------------- recon ----------------
+ def recon(self):
+ self.eng.set_phase("recon")
+ for seed in self.scope.seeds:
+ if not self.scope.in_scope_host(seed):
+ self.eng.log(f"recon: seed {seed} not in scope — skip"); continue
+ self.eng.log(f"recon: enumerating {seed}")
+ items = self._recon_agent(seed)
+ kept, dropped = [], 0
+ for it in items:
+ url = it.get("url", "")
+ if self.scope.in_scope_host(url):
+ it.setdefault("vuln_class", "info-leak")
+ kept.append(it)
+ else:
+ dropped += 1
+ added = self.eng.add_surface(kept)
+ self.eng.log(f"recon: {seed} -> {added} new surface item(s), {dropped} out-of-scope dropped")
+
+ def _recon_agent(self, seed):
+ if self.mock:
+ return MOCK_RECON.get(seed, [])
+ task = (f"You are an authorized penetration tester on a sanctioned engagement. "
+ f"Enumerate the attack surface of {seed} (IN SCOPE). Crawl/probe to find endpoints and "
+ f"parameters worth testing. STAY STRICTLY within these in-scope rules: "
+ f"{self.scope.in_scope} (out of scope: {self.scope.out_of_scope}). "
+ f"For each interesting (url, parameter), name the single most likely vulnerability class to test "
+ f"(one of: {', '.join(CLASS_WEIGHT)}). "
+ f"End with a fenced ```json``` array of objects: "
+ f'[{{"url":"<full url>","param":"<param or empty>","vuln_class":"<class>","note":"<why>"}}].')
+ r = A.run_agent(task, model=self.model, max_turns=self.max_turns, timeout=self.timeout)
+ if r.get("error"):
+ self.eng.log(f"recon agent error: {r['error']}"); return []
+ return A.extract_json(r["result"]) or []
+
+ # ---------------- rank ----------------
+ def rank(self):
+ self.eng.set_phase("rank")
+ for s in self.eng.state["surface"]:
+ base = CLASS_WEIGHT.get(s.get("vuln_class", ""), 20)
+ s["priority"] = base + (5 if s.get("param") else 0)
+ self.eng.save()
+ wl = self.eng.worklist()
+ self.eng.log(f"rank: {len(wl)} item(s) prioritized; top: "
+ + ", ".join(f"{s['vuln_class']}@{s['url']}" for s in wl[:3]))
+
+ # ---------------- hunt ----------------
+ def hunt(self):
+ self.eng.set_phase("hunt")
+ wl = self.eng.worklist()[: self.max_hunts]
+ self.eng.log(f"hunt: testing {len(wl)} item(s) (cap {self.max_hunts})")
+ for it in wl:
+ url = it["url"]
+ if not self.scope.in_scope_host(url): # belt-and-suspenders scope gate
+ self.eng.log(f"hunt: REFUSING out-of-scope {url} ({self.scope.reject_reason(url)})")
+ self.eng.mark_tested(it); continue
+ f = self._hunt_agent(it)
+ self.eng.mark_tested(it)
+ if f and f.get("vulnerable"):
+ cand = {"url": url, "param": it.get("param", ""), "vuln_class": it.get("vuln_class"),
+ "severity": f.get("severity", "unknown"), "evidence": f.get("evidence", ""),
+ "request": f.get("request", "")}
+ self.eng.add_candidate(cand)
+ self.eng.log(f"hunt: CANDIDATE {cand['vuln_class']} @ {url}")
+ else:
+ self.eng.log(f"hunt: nothing on {it.get('vuln_class')}@{url}")
+
+ def _hunt_agent(self, it):
+ if self.mock:
+ return MOCK_HUNT.get((it["url"], it.get("vuln_class")), {"vulnerable": False})
+ task = (f"You are an authorized penetration tester on a sanctioned engagement (IN SCOPE). "
+ f"Test {it['url']} (parameter `{it.get('param','')}`) for {it.get('vuln_class')}. "
+ f"Use the Burp MCP tools or curl. Only claim a vulnerability if you can DEMONSTRATE real, "
+ f"exploitable impact — not mere reflection, an error, or a permissive header. "
+ f"End with a fenced ```json``` object: "
+ f'{{"vulnerable":true|false,"severity":"low|medium|high|critical","evidence":"<what proves it>","request":"<the winning request>"}}.')
+ r = A.run_agent(task, model=self.model, max_turns=self.max_turns, timeout=self.timeout)
+ if r.get("error"):
+ self.eng.log(f"hunt agent error ({it['url']}): {r['error']}")
+ if r["error"] == "rate-limited":
+ raise SystemExit("stopped: claude usage limit reached")
+ return {"vulnerable": False}
+ return A.extract_json(r["result"]) or {"vulnerable": False}
+
+ # ---------------- validate ----------------
+ def validate(self):
+ self.eng.set_phase("validate")
+ pending = [c for c in self.eng.state["candidates"]
+ if not any(cf.get("url") == c["url"] and cf.get("vuln_class") == c["vuln_class"]
+ for cf in self.eng.state["confirmed"])]
+ self.eng.log(f"validate: {len(pending)} candidate(s) to adversarially verify")
+ for c in pending:
+ v = self._validate_agent(c)
+ if v.get("real"):
+ self.eng.confirm(c, v)
+ self.eng.log(f"validate: CONFIRMED {c['vuln_class']} @ {c['url']} ({v.get('severity','')})")
+ else:
+ self.eng.log(f"validate: rejected (false positive) {c['vuln_class']} @ {c['url']} — {v.get('reason','')}")
+
+ def _validate_agent(self, c):
+ if self.mock:
+ return MOCK_VALIDATE.get((c["url"], c["vuln_class"]), {"real": False, "reason": "mock-default"})
+ task = (f"Adversarially verify a claimed finding (be skeptical — default to false positive if unproven). "
+ f"Claim: {c['vuln_class']} at {c['url']} (param `{c.get('param','')}`). "
+ f"Reported evidence: {c.get('evidence','')[:400]}. "
+ f"Independently re-test it (Burp MCP / curl). Is it a REAL, exploitable vulnerability or a false positive? "
+ f"End with a fenced ```json``` object: "
+ f'{{"real":true|false,"severity":"low|medium|high|critical","reason":"<why>"}}.')
+ r = A.run_agent(task, model=self.model, max_turns=self.max_turns, timeout=self.timeout)
+ if r.get("error"):
+ self.eng.log(f"validate agent error: {r['error']}")
+ return {"real": False, "reason": f"verify error: {r['error']}"}
+ return A.extract_json(r["result"]) or {"real": False, "reason": "no verdict"}
+
+ # ---------------- report ----------------
+ def report(self):
+ self.eng.set_phase("report")
+ c = self.eng.state["confirmed"]
+ s = self.eng.summary()
+ lines = [f"# Engagement report — {self.scope.name}", "",
+ f"In scope: `{'`, `'.join(self.scope.in_scope)}` ",
+ f"Surface mapped: {s['surface']} · tested: {s['tested']} · "
+ f"candidates: {s['candidates']} · **confirmed: {s['confirmed']}**", ""]
+ if not c:
+ lines += ["No confirmed findings.", ""]
+ for i, f in enumerate(c, 1):
+ lines += [f"## {i}. {f.get('vuln_class','?').upper()} — {f.get('severity','?')}",
+ f"- **URL:** `{f['url']}`" + (f" (param `{f['param']}`)" if f.get("param") else ""),
+ f"- **Evidence:** {f.get('evidence','')}",
+ f"- **Request:** `{f.get('request','')}`",
+ f"- **Verifier:** {f.get('verdict',{}).get('reason','')}", ""]
+ path = os.path.join(self.eng.dir, "report.md")
+ open(path, "w").write("\n".join(lines))
+ self.eng.log(f"report: wrote {len(c)} confirmed finding(s) -> {path}")
+ return path
+
+ def run(self, phases):
+ for ph in ALL_PHASES:
+ if ph in phases:
+ getattr(self, ph)()
+ self.eng.set_phase("done")
+ self.eng.log(f"engine done | {self.eng.summary()}")
+
+
+# ---- mock fixtures for --mock flow validation (no agents) ----
+MOCK_RECON = {
+ "http://localhost:3002": [
+ {"url": "http://localhost:3002/api/account?id=5", "param": "id", "vuln_class": "idor", "note": "id param"},
+ {"url": "http://localhost:3002/redirect?next=x", "param": "next", "vuln_class": "open-redirect", "note": "redirect"},
+ {"url": "http://localhost:3002/search?q=x", "param": "q", "vuln_class": "xss", "note": "reflected"},
+ {"url": "http://evil.example/x", "param": "", "vuln_class": "sqli", "note": "OUT OF SCOPE — should be dropped"},
+ ]
+}
+MOCK_HUNT = {
+ ("http://localhost:3002/api/account?id=5", "idor"): {"vulnerable": True, "severity": "high", "evidence": "id=N returns other users' PII", "request": "GET /api/account?id=6"},
+ ("http://localhost:3002/redirect?next=x", "open-redirect"): {"vulnerable": True, "severity": "medium", "evidence": "302 to external", "request": "GET /redirect?next=//evil.com"},
+ ("http://localhost:3002/search?q=x", "xss"): {"vulnerable": False},
+}
+MOCK_VALIDATE = {
+ ("http://localhost:3002/api/account?id=5", "idor"): {"real": True, "severity": "high", "reason": "confirmed PII exposure for arbitrary id"},
+ ("http://localhost:3002/redirect?next=x", "open-redirect"): {"real": False, "reason": "only redirects to relative paths on re-test (false positive)"},
+}
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--scope", required=True, help="engagement/scope JSON (name, in_scope, out_of_scope, seeds)")
+ ap.add_argument("--base", default="~/.bughunter-engagements")
+ ap.add_argument("--phases", default=",".join(ALL_PHASES))
+ ap.add_argument("--model", default="claude-sonnet-4-6")
+ ap.add_argument("--max-hunts", type=int, default=10)
+ ap.add_argument("--max-turns", type=int, default=40)
+ ap.add_argument("--timeout", type=int, default=600)
+ ap.add_argument("--mock", action="store_true", help="dry-run the orchestration with canned agent output")
+ a = ap.parse_args()
+ eng = Engine(a.scope, a.base, a.model, a.max_hunts, a.max_turns, a.timeout, a.mock)
+ eng.run([p.strip() for p in a.phases.split(",") if p.strip()])
+ print("\n" + json.dumps(eng.eng.summary(), indent=2))
+ print("engagement dir:", eng.eng.dir)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/engine/scope.py b/engine/scope.py
new file mode 100644
index 0000000..4afd9e8
--- /dev/null
+++ b/engine/scope.py
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+scope.py — deterministic scope safety for the engagement engine.
+
+The engine may run unattended, so scope is enforced in CODE, not by trusting an
+LLM. Every host/URL is checked here before any agent is allowed to touch it.
+Deny wins: an out-of-scope match excludes even if an in-scope pattern also matches.
+Default deny: anything not matching an in-scope pattern is out of scope.
+
+Pattern forms (matched against the URL's host):
+ example.com -> the apex AND any subdomain (example.com, api.example.com)
+ *.example.com -> any subdomain (NOT the bare apex)
+ api.example.com -> that exact host
+ 10.0.0.0/8 -> any IP in the CIDR (IPv4)
+ re:^staging[0-9]+\\.example\\.com$ -> explicit regex (prefix re:)
+"""
+import ipaddress
+import re
+from urllib.parse import urlparse
+
+
+def _host_of(target):
+ t = target.strip()
+ if "://" not in t:
+ t = "//" + t
+ host = (urlparse(t).hostname or "").lower().rstrip(".")
+ return host
+
+
+def _match(pattern, host):
+ p = pattern.strip().lower()
+ if not p or not host:
+ return False
+ if p.startswith("re:"):
+ try:
+ return re.search(p[3:], host) is not None
+ except re.error:
+ return False
+ if "/" in p and p.replace(".", "").replace("/", "").isdigit(): # CIDR
+ try:
+ return ipaddress.ip_address(host) in ipaddress.ip_network(p, strict=False)
+ except ValueError:
+ return False
+ if p.startswith("*."):
+ base = p[2:]
+ return host.endswith("." + base)
+ # bare domain: apex or any subdomain; or exact host
+ return host == p or host.endswith("." + p)
+
+
+class Scope:
+ def __init__(self, in_scope, out_of_scope=None, seeds=None, name="engagement"):
+ self.in_scope = [p for p in (in_scope or []) if p.strip()]
+ self.out_of_scope = [p for p in (out_of_scope or []) if p.strip()]
+ self.seeds = seeds or []
+ self.name = name
+
+ @classmethod
+ def load(cls, path):
+ import json
+ d = json.load(open(path))
+ return cls(d.get("in_scope", []), d.get("out_of_scope", []),
+ d.get("seeds", []), d.get("name", "engagement"))
+
+ def in_scope_host(self, target):
+ host = _host_of(target)
+ if not host:
+ return False
+ if any(_match(p, host) for p in self.out_of_scope):
+ return False # deny wins
+ return any(_match(p, host) for p in self.in_scope)
+
+ def reject_reason(self, target):
+ """Return None if in scope, else a human reason (for logging)."""
+ host = _host_of(target)
+ if not host:
+ return "could not parse host"
+ if any(_match(p, host) for p in self.out_of_scope):
+ return f"{host} matches an out-of-scope rule"
+ if not any(_match(p, host) for p in self.in_scope):
+ return f"{host} matches no in-scope rule (default deny)"
+ return None
+
+
+def _selftest():
+ s = Scope(in_scope=["example.com", "*.test.example.com", "10.0.0.0/8",
+ "re:^lab[0-9]+\\.acme\\.io$"],
+ out_of_scope=["admin.example.com", "internal.example.com"])
+ ok = lambda t: s.in_scope_host(t)
+ assert ok("https://example.com/login") # apex
+ assert ok("http://api.example.com/x") # subdomain of bare domain
+ assert ok("https://a.test.example.com") # wildcard
+ assert ok("https://10.1.2.3:8080/") # CIDR
+ assert ok("https://lab42.acme.io") # regex
+ assert not ok("https://admin.example.com") # out-of-scope (deny wins)
+ assert not ok("https://internal.example.com/x") # out-of-scope
+ assert ok("https://test.example.com") # in scope via bare example.com rule
+ assert not ok("https://evil.com") # default deny
+ assert not ok("https://notexample.com") # suffix-confusion guard
+ assert not ok("https://example.com.evil.com") # suffix-confusion guard
+ assert not ok("https://11.0.0.1") # outside CIDR
+ assert s.reject_reason("https://evil.com")
+ assert s.reject_reason("https://example.com") is None
+ # wildcard depth: *.test.example.com needs a label deeper than test.example.com
+ s2 = Scope(in_scope=["*.test.example.com"])
+ assert s2.in_scope_host("a.test.example.com")
+ assert not s2.in_scope_host("test.example.com")
+ print("scope.py self-test: PASS")
+
+
+if __name__ == "__main__":
+ _selftest()
diff --git a/engine/state.py b/engine/state.py
new file mode 100644
index 0000000..6eaf32b
--- /dev/null
+++ b/engine/state.py
@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+state.py — persistent, resumable engagement state.
+
+Everything the engine learns lives on disk so a long run is auditable and can be
+killed/resumed without losing progress. Layout:
+
+ <base>/<name>/
+ state.json surface items, worklist, tested set, candidate + confirmed findings, phase
+ engine.log append-only run log
+ evidence/ per-finding evidence files
+ report.md generated at the end
+"""
+import json
+import os
+from datetime import datetime, timezone
+
+
+def _now():
+ return datetime.now(timezone.utc).isoformat()
+
+
+class Engagement:
+ def __init__(self, base, name):
+ self.dir = os.path.join(os.path.expanduser(base), name)
+ self.name = name
+ os.makedirs(os.path.join(self.dir, "evidence"), exist_ok=True)
+ self.state_path = os.path.join(self.dir, "state.json")
+ self.log_path = os.path.join(self.dir, "engine.log")
+ self.state = self._load()
+
+ def _load(self):
+ if os.path.isfile(self.state_path):
+ return json.load(open(self.state_path))
+ return {"name": self.name, "created": _now(), "phase": "init",
+ "surface": [], "tested": [], "candidates": [], "confirmed": []}
+
+ def save(self):
+ tmp = self.state_path + ".tmp"
+ json.dump(self.state, open(tmp, "w"), indent=2)
+ os.replace(tmp, self.state_path)
+
+ def log(self, msg):
+ line = f"{_now()} {msg}"
+ with open(self.log_path, "a") as f:
+ f.write(line + "\n")
+ print(" " + msg, flush=True)
+
+ # ---- phase ----
+ def set_phase(self, phase):
+ self.state["phase"] = phase
+ self.save()
+
+ # ---- surface (discovered, scope-checked endpoints/params) ----
+ def add_surface(self, items):
+ seen = {(s["url"], s.get("param", "")) for s in self.state["surface"]}
+ added = 0
+ for it in items:
+ key = (it["url"], it.get("param", ""))
+ if key not in seen:
+ self.state["surface"].append(it)
+ seen.add(key)
+ added += 1
+ self.save()
+ return added
+
+ def worklist(self):
+ """Ranked, not-yet-tested surface items."""
+ tested = set(self.state["tested"])
+ items = [s for s in self.state["surface"] if self._key(s) not in tested]
+ return sorted(items, key=lambda s: -s.get("priority", 0))
+
+ @staticmethod
+ def _key(s):
+ return f"{s['url']}|{s.get('param','')}|{s.get('vuln_class','')}"
+
+ def mark_tested(self, item):
+ k = self._key(item)
+ if k not in self.state["tested"]:
+ self.state["tested"].append(k)
+ self.save()
+
+ # ---- findings ----
+ def add_candidate(self, finding):
+ finding["ts"] = _now()
+ self.state["candidates"].append(finding)
+ self.save()
+
+ def confirm(self, finding, verdict):
+ finding = {**finding, "verdict": verdict, "confirmed_ts": _now()}
+ self.state["confirmed"].append(finding)
+ self.save()
+
+ def evidence_path(self, fname):
+ return os.path.join(self.dir, "evidence", fname)
+
+ # ---- progress ----
+ def summary(self):
+ return {"surface": len(self.state["surface"]), "tested": len(self.state["tested"]),
+ "candidates": len(self.state["candidates"]), "confirmed": len(self.state["confirmed"]),
+ "phase": self.state["phase"]}
+
+
+def _selftest():
+ import tempfile, shutil
+ d = tempfile.mkdtemp()
+ try:
+ e = Engagement(d, "demo")
+ assert e.add_surface([{"url": "http://t/a", "param": "id", "vuln_class": "idor", "priority": 5},
+ {"url": "http://t/a", "param": "id", "vuln_class": "idor"}]) == 1 # dedup
+ e.add_surface([{"url": "http://t/b", "param": "q", "vuln_class": "xss", "priority": 9}])
+ wl = e.worklist()
+ assert wl[0]["url"] == "http://t/b" # higher priority first
+ e.mark_tested(wl[0])
+ assert all(s["url"] != "http://t/b" or s.get("param") != "q" for s in e.worklist())
+ e.add_candidate({"url": "http://t/a", "vuln_class": "idor", "evidence": "x"})
+ e.confirm(e.state["candidates"][0], {"real": True})
+ # resume: a fresh handle on the same dir sees persisted state
+ e2 = Engagement(d, "demo")
+ assert e2.summary() == {"surface": 2, "tested": 1, "candidates": 1, "confirmed": 1, "phase": "init"}
+ print("state.py self-test: PASS")
+ finally:
+ shutil.rmtree(d)
+
+
+if __name__ == "__main__":
+ _selftest()