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.
Python ai-securityanthropicapplication-securitybug-bountybugbountybugcrowdclaudeclaude-codeclaude-skillsethical-hackinghackeroneoffensive-securitypentestingred-teamsecurity-toolsweb-security
feat(engine): autonomous engagement engine v0 (scope-safe, stateful)
Sachin Sharmac52c68158af9
diff --git a/engine/.gitignore b/engine/.gitignorenew file mode 100644index 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.jsondiff --git a/engine/README.md b/engine/README.mdnew file mode 100644index 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.pynew file mode 100644index 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.examplenew file mode 100644index 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.jsonnew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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()