@murk-security/runner-linux-arm64 0.0.0-stage → 0.7.1

package/runners/report.py

@@ -0,0 +1,365 @@
+#!/usr/bin/env python3
+"""Customer-facing assessment report generation for the Blackglass/MURK runner.
+
+The runner assembles a Markdown report at the end of a scan and writes it to the run's
+session dir as `report.md`; the control plane serves that verbatim at
+`GET /api/runs/:id/report` (falling back to its own minimal renderer only when a run did
+not produce one). This module is pure + stdlib-only so it is unit-testable offline.
+
+Two layers, per the agreed design:
+  * DETERMINISTIC sections (scope, severity rollup, each finding's full detail, the
+    pre-scan's coverage + posture observations, reproduction appendix) built straight
+    from the structured data -- no model, no guessing.
+  * An LLM-authored EXECUTIVE SUMMARY (`executive_summary`) generated as an isolated
+    post-pass over the same data, with a deterministic fallback when no model/key is
+    available. It never invents findings: it only narrates the ones already confirmed.
+"""
+from __future__ import annotations
+
+import html
+import json
+import re
+from typing import Any, Callable
+
+SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"]
+_SEV_RANK = {s: i for i, s in enumerate(SEVERITY_ORDER)}
+
+# Finding/narrative text is authored by an LLM over TARGET content (e.g. a reflected
+# payload echoed in evidence), so it is untrusted and must be neutralised before it goes
+# into a report that may be rendered as HTML. These sanitisers are context-specific:
+#   _text  — block prose: keep newlines, HTML-escape & < >, drop other control chars.
+#   _inline— single line (headings, labels): _text then collapse all whitespace.
+#   _cell  — a Markdown table cell: _inline then escape the pipe.
+#   _code  — inside a `...` span: strip backticks + newlines so it cannot break out.
+_CTRL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+
+def _text(s: Any) -> str:
+    out = str(s or "").replace("\r\n", "\n").replace("\r", "\n")
+    return html.escape(_CTRL.sub("", out), quote=False)
+
+
+def _inline(s: Any) -> str:
+    return " ".join(_text(s).split())
+
+
+def _cell(s: Any) -> str:
+    return _inline(s).replace("|", "\\|")[:300]
+
+
+def _code(s: Any) -> str:
+    return str(s or "").replace("`", "").replace("\r", " ").replace("\n", " ").strip()
+
+# Human labels for the pre-scan's coverage tokens (profile.py `coverage`).
+_COVERAGE_LABELS = {
+    "security-headers": "Security response headers",
+    "cookie-flags": "Session cookie flags",
+    "fingerprint": "Server / technology fingerprint",
+    "version-cve": "Version → known-CVE matching",
+    "http-methods": "Allowed HTTP methods",
+    "exposed-paths": "Exposed sensitive paths (VCS, secrets, backups, config)",
+    "transport": "Transport security (TLS)",
+}
+
+
+def severity_rank(sev: str) -> int:
+    return _SEV_RANK.get((sev or "").lower(), len(SEVERITY_ORDER))
+
+
+def sort_findings(findings: list[dict]) -> list[dict]:
+    """Most severe first; stable within a severity (preserves discovery order)."""
+    return sorted(findings, key=lambda f: severity_rank(str(f.get("severity") or "")))
+
+
+def severity_counts(findings: list[dict]) -> dict[str, int]:
+    counts = {s: 0 for s in SEVERITY_ORDER}
+    for f in findings:
+        sev = str(f.get("severity") or "").lower()
+        if sev in counts:
+            counts[sev] += 1
+    return counts
+
+
+def _rollup_table(findings: list[dict]) -> list[str]:
+    counts = severity_counts(findings)
+    present = [s for s in SEVERITY_ORDER if counts[s]]
+    if not present:
+        return ["No confirmed findings."]
+    out = ["| Severity | Count |", "| --- | --- |"]
+    out += [f"| {s.capitalize()} | {counts[s]} |" for s in present]
+    out.append(f"| **Total** | **{sum(counts.values())}** |")
+    return out
+
+
+def _fence(text: str) -> list[str]:
+    """A fenced code block whose content can't break out of the fence. The renderer
+    HTML-escapes fenced content, so we only neutralise stray ``` here."""
+    body = str(text or "").replace("```", "'''").rstrip()
+    return ["```", body, "```"]
+
+
+def _evidence_block(f: dict) -> list[str]:
+    """Concrete, verbatim proof: each cited request and the response it returned, plus the
+    cited code with a snippet. Read from the run's records by the runner; never synthesized."""
+    repro = f.get("reproduction") or {}
+    ops = [o for o in (repro.get("ops") or []) if isinstance(o, dict) and (o.get("response") or {})]
+    crefs = [c for c in (repro.get("codeRefs") or []) if isinstance(c, dict)]
+    if not ops and not crefs:
+        return []
+    out = ["**Evidence**", ""]
+    for o in ops:
+        args = o.get("args") if isinstance(o.get("args"), dict) else {}
+        method = str(args.get("method") or ("POST" if o.get("op") == "login" else "GET")).upper()
+        path = args.get("path") or args.get("subject") or o.get("op") or "request"
+        resp = o.get("response") or {}
+        status = resp.get("status")
+        head = f"Request `{_code(method)} {_code(str(path))}`"
+        if status is not None:
+            head += f" → `{_code(str(status))}`"
+        out += [head, ""]
+        if resp.get("snippet"):
+            out += _fence(str(resp["snippet"]))
+            out.append("")
+    for c in crefs:
+        loc = str(c.get("file") or "") + (f":{c['line']}" if c.get("line") else "")
+        out += [f"Code `{_code(loc)}`", ""]
+        if c.get("snippet"):
+            out += _fence(str(c["snippet"]))
+            out.append("")
+    return out
+
+
+def _finding_section(index: int, f: dict) -> list[str]:
+    sev = str(f.get("severity") or "unrated").capitalize()
+    lines = [f"### {index}. [{sev}] {_inline(f.get('title') or 'Untitled finding')}", ""]
+    meta_bits = []
+    if f.get("category"):
+        meta_bits.append(f"**Category:** {_inline(f['category'])}")
+    if f.get("cwe"):
+        meta_bits.append(f"**Weakness:** {_inline(f['cwe'])}")
+    if f.get("confidence"):
+        meta_bits.append(f"**Confidence:** {_inline(f['confidence'])}")
+    if meta_bits:
+        lines += [" · ".join(meta_bits), ""]
+    ep = f.get("endpoint") or {}
+    if ep.get("url") or ep.get("path"):
+        lines += [f"**Affected endpoint:** `{_code(ep.get('method', 'GET'))} {_code(ep.get('url') or ep.get('path'))}`", ""]
+    if f.get("impact"):
+        lines += ["**Impact**", "", _text(f["impact"]), ""]
+    if f.get("description"):
+        lines += ["**Detail**", "", _text(f["description"]), ""]
+    steps = f.get("steps") or []
+    if steps:
+        lines += ["**Reproduction**", ""]
+        lines += [f"{i + 1}. `{_code(s)}`" for i, s in enumerate(steps)]
+        lines.append("")
+    lines += _evidence_block(f)
+    if f.get("remediation"):
+        lines += ["**Remediation**", "", _text(f["remediation"]), ""]
+    src = f.get("source") or {}
+    if src.get("file"):
+        loc = str(src["file"]) + (f":{src['line']}" if src.get("line") else "")
+        lines += [f"**Source:** `{_code(loc)}`", ""]
+    return lines
+
+
+def _posture_section(prescan: dict) -> list[str]:
+    """Render the pre-scan's coverage + posture observations. These are factual
+    OBSERVATIONS of the public surface (what was checked, what is weak, what is
+    sound) -- deliberately not severity-rated findings: anything that is a real
+    exploitable vulnerability is confirmed and assessed by the agents above."""
+    if not prescan:
+        return []
+    out = ["## Surface posture & coverage", "",
+           "An automated pre-scan characterised the target's public surface. The items "
+           "below are observations of security posture, not confirmed vulnerabilities.", ""]
+
+    coverage = [c for c in (prescan.get("coverage") or []) if isinstance(c, str)]
+    if coverage:
+        out += ["### Checks performed", ""]
+        out += [f"- {_inline(_COVERAGE_LABELS.get(c, c))}" for c in coverage]
+        out.append("")
+
+    target = prescan.get("target") or {}
+    fp_bits = []
+    if target.get("server"):
+        fp_bits.append(f"Server: `{_code(target['server'])}`")
+    if target.get("x_powered_by"):
+        fp_bits.append(f"X-Powered-By: `{_code(target['x_powered_by'])}`")
+    if isinstance(target.get("fingerprints"), list) and target["fingerprints"]:
+        named = ", ".join(
+            _inline(f"{p.get('product')} {p.get('version')}".strip())
+            for p in target["fingerprints"] if isinstance(p, dict)
+        )
+        if named:
+            fp_bits.append(f"Detected: {named}")
+    if fp_bits:
+        out += ["### Technology", "", *[f"- {b}" for b in fp_bits], ""]
+
+    signals = [s for s in (prescan.get("signals") or []) if isinstance(s, dict)]
+    if signals:
+        out += ["### Observations", "",
+                "| Area | Observation | Confidence | Confirm at |", "| --- | --- | --- | --- |"]
+        for s in signals:
+            area = _cell(s.get("area") or s.get("category") or "—")
+            title = _cell(s.get("title") or s.get("detail") or "")
+            conf = _cell(s.get("confidence") or "—")
+            tier = _cell(s.get("tier_to_confirm") or "—")
+            out.append(f"| {area} | {title} | {conf} | {tier} |")
+        out.append("")
+
+    positives = prescan.get("posture", {}).get("hygiene_positives") or []
+    positives = [p for p in positives if isinstance(p, (str, dict))]
+    if positives:
+        out += ["### Verified sound", ""]
+        for p in positives:
+            out.append(f"- {_inline(p.get('title') if isinstance(p, dict) else p)}")
+        out.append("")
+    return out
+
+
+def _appendix(findings: list[dict]) -> list[str]:
+    """A compact evidence index: each finding mapped to the cited evidence (env call ids)
+    and code locations that back it. Non-empty whenever findings cite anything."""
+    rows: list[str] = []
+    for f in findings:
+        repro = f.get("reproduction") or {}
+        ids = [str(o.get("evidence_id")) for o in (repro.get("ops") or [])
+               if isinstance(o, dict) and o.get("evidence_id") is not None]
+        refs = list(f.get("evidenceRefs") or [])
+        if not ids and not refs:
+            continue
+        cited = "; ".join(filter(None, [
+            ("evidence " + ", ".join(ids)) if ids else "",
+            ("code " + ", ".join(_inline(r) for r in refs)) if refs else "",
+        ]))
+        rows.append(f"| {_cell(f.get('title') or 'Finding')} | {_cell(cited)} |")
+    if not rows:
+        return []
+    return ["## Evidence index", "",
+            "Every confirmed finding and the evidence it cites (full request/response bodies "
+            "and source are reachable per-finding above, and via the MCP interface by id).", "",
+            "| Finding | Cited evidence |", "| --- | --- |", *rows, ""]
+
+
+def build_report(*, run_meta: dict, findings: list[dict], prescan: dict | None, narrative: str) -> str:
+    """Assemble the full Markdown report. `findings` are finding-payload dicts."""
+    findings = sort_findings(findings)
+    target = _inline(run_meta.get("target") or "the target application")
+    lines: list[str] = [f"# Security assessment — {target}", ""]
+
+    meta_line = []
+    if run_meta.get("scanProfile"):
+        meta_line.append(f"**Scan:** {str(run_meta['scanProfile']).upper()}")
+    if run_meta.get("startedAt"):
+        meta_line.append(f"**Date:** {run_meta['startedAt']}")
+    if run_meta.get("durationMin") is not None:
+        meta_line.append(f"**Duration:** {run_meta['durationMin']:.0f} min")
+    if run_meta.get("runId"):
+        meta_line.append(f"**Run:** `{_code(run_meta['runId'])}`")
+    if meta_line:
+        lines += [" · ".join(meta_line), ""]
+
+    lines += ["## Executive summary", "", _text(narrative).strip() or "_No summary available._", ""]
+
+    lines += ["## Findings at a glance", ""]
+    lines += _rollup_table(findings)
+    lines.append("")
+
+    lines += ["## Scope & methodology", ""]
+    if run_meta.get("hosts"):
+        lines.append(f"- **In scope:** {', '.join(_inline(h) for h in run_meta['hosts'])}")
+    lines.append(f"- **Access:** {_inline(run_meta.get('actionTier') or 'passive (read-only)')}")
+    idents = run_meta.get("identities") or []
+    lines.append(f"- **Authenticated as:** {', '.join(_inline(i) for i in idents) if idents else 'unauthenticated (external attacker)'}")
+    if run_meta.get("scanProfile"):
+        lines.append(f"- **Depth:** {str(run_meta['scanProfile']).upper()} scan profile")
+    lines.append("")
+
+    if findings:
+        lines += ["## Confirmed findings", ""]
+        for i, f in enumerate(findings, 1):
+            lines += _finding_section(i, f)
+    else:
+        lines += ["## Confirmed findings", "",
+                  "No confirmed vulnerabilities were found in scope during this assessment. "
+                  "See the surface posture below for what was checked.", ""]
+
+    lines += _posture_section(prescan or {})
+    lines += _appendix(findings)
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _fallback_summary(findings: list[dict], prescan: dict | None) -> str:
+    counts = severity_counts(findings)
+    present = [f"{counts[s]} {s}" for s in SEVERITY_ORDER if counts[s]]
+    if present:
+        head = f"The assessment confirmed {sum(counts.values())} finding(s): {', '.join(present)}."
+    else:
+        head = "The assessment confirmed no vulnerabilities in scope."
+    top = next((f for f in sort_findings(findings) if f.get("title")), None)
+    if top:
+        head += f" The most severe is \"{_inline(top['title'])}\" ({str(top.get('severity') or 'unrated')})."
+    if prescan and (prescan.get("signals")):
+        head += (f" An automated pre-scan also recorded {len(prescan['signals'])} surface-posture "
+                 "observation(s); see below.")
+    return head
+
+
+def llm_summary(findings: list[dict], prescan: dict | None, run_meta: dict,
+                key: str | None, model: str | None,
+                call: Callable[[str, str, list[dict]], str] | None = None,
+                log: Callable[[str], None] | None = None) -> str | None:
+    """Attempt the LLM-authored executive summary. Returns the narrative, or None if the
+    prerequisites are missing or the call fails (logging the reason via `log`) so the
+    caller can retry with another model before using the deterministic fallback."""
+    if not (key and model and call):
+        return None
+    compact = [{
+        "title": f.get("title"), "severity": f.get("severity"),
+        "category": f.get("category"), "impact": f.get("impact"),
+        "endpoint": (f.get("endpoint") or {}).get("url") or (f.get("endpoint") or {}).get("path"),
+    } for f in sort_findings(findings)]
+    posture = [
+        {"area": s.get("area"), "title": s.get("title")}
+        for s in (prescan.get("signals") if prescan else []) or [] if isinstance(s, dict)
+    ][:20]
+    payload = {
+        "target": run_meta.get("target"),
+        "scan_profile": run_meta.get("scanProfile"),
+        "confirmed_findings": compact,
+        "posture_observations": posture,
+    }
+    messages = [
+        {"role": "system", "content": (
+            "You write the executive summary of a web application security assessment for a "
+            "technical decision-maker. Use ONLY the findings and observations provided; do not "
+            "invent, infer, or speculate about anything not listed. Write four short, factual "
+            "paragraphs as flowing prose (no markdown headers or bullet lists):\n"
+            "1. Overall risk posture — one or two sentences on how exposed the application is and why.\n"
+            "2. The most significant confirmed issues, grouped by theme where they relate (e.g. "
+            "several access-control gaps), naming what each lets an attacker do and how they chain "
+            "into greater impact together.\n"
+            "3. What this means for the business — the data or functions actually at risk.\n"
+            "4. A prioritised remediation roadmap — what to fix first and why, then the next tier.\n"
+            "Reference specific findings by their real titles. If there are no confirmed findings, "
+            "say so plainly and summarise what was verified instead.")},
+        {"role": "user", "content": json.dumps(payload, ensure_ascii=False)},
+    ]
+    try:
+        text = (call(key, model, messages) or "").strip()
+        if not text and log:
+            log(f"executive summary via {model}: empty response")
+        return text or None
+    except Exception as exc:  # noqa: BLE001 — the report must render even if the call fails
+        if log:
+            log(f"executive summary via {model} failed: {exc}")
+        return None
+
+
+def executive_summary(findings: list[dict], prescan: dict | None, run_meta: dict,
+                      key: str | None, model: str | None,
+                      call: Callable[[str, str, list[dict]], str] | None = None) -> str:
+    """The LLM-authored summary if available, else the deterministic fallback. Thin wrapper
+    over llm_summary for callers that want a single model and no retry (and for tests)."""
+    return llm_summary(findings, prescan, run_meta, key, model, call) or _fallback_summary(findings, prescan)

package/runners/skills/api/idor-enumeration/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: idor-enumeration
+description: Find IDOR / broken object-level authorization on id-keyed API endpoints by reading objects that belong to other users or tenants.
+when-to-use: an endpoint path or response contains a numeric or guessable id (e.g. /api/orders/1001, ?user_id=, /invoices/{id}), or a resource is keyed by an identifier.
+surface: web
+severity: high
+---
+
+# IDOR / broken object-level authorization
+
+A read-only playbook for the `http` op. Goal: demonstrate that an object keyed by
+an identifier can be read by a party who should not be authorized for it.
+
+## 1. Find object-keyed endpoints
+From the site map, APIs, and JS bundles, collect endpoints shaped like
+`/api/<resource>/<id>`, `?id=`, `?user_id=`, `/<resource>/{uuid}`. Source-map and
+JS mining (`http` with `grep`) often reveals the full API shape.
+
+## 2. Establish a baseline
+Read one object anonymously (or as a low-privilege identity if one exists):
+`http {"path":"/api/orders/1001"}`. Note what fields come back and whose data it is
+(owner email, tenant id, account number).
+
+## 3. Enumerate neighbors
+Request adjacent identifiers that should belong to OTHER principals:
+`http {"path":"/api/orders/1002"}`, `/1003`, and so on. For UUIDs, use ids you
+discovered elsewhere (in listings, JS, other responses) rather than guessing.
+A 200 returning another principal's data with no auth, or with your low-priv
+identity, is the IDOR.
+
+## 4. Distinguish real IDOR from correct behavior
+It is only a finding if the object is one the requester SHOULD NOT reach:
+- different owner/tenant than the (anonymous or low-priv) requester, and
+- no authorization error (not 401/403), and
+- the data is sensitive or scoped (orders, invoices, profiles, PII).
+Public, intentionally-shared objects are NOT findings.
+
+## Evidence & severity
+Cite two requests: the baseline and the cross-object read, plus the field that
+proves different ownership (e.g. a different `owner`/`email`). Severity high, or
+critical if it exposes PII/financial data at scale (sequential ids). Read only —
+never modify or delete an enumerated object.

package/runners/skills/exploit/authz-differential/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: authz-differential
+description: Prove a broken-access-control impact (IDOR/BOLA, tenant crossing, privilege escalation) by differentially comparing responses across identities or ids, so the boundary break is demonstrated, not asserted.
+when-to-use: a candidate access-control weakness needs PROOF — the same resource is reachable by parties who should have different access, or an id-keyed object may cross an owner/tenant boundary, and you want a reproducible comparison rather than a single suggestive response.
+surface: web
+severity: high
+tier: safe-active
+---
+
+# Differential authorization proof (exploiter)
+
+A non-destructive playbook for the `diff` op (safe-active). Where the passive
+`idor-enumeration` skill *finds* id-keyed endpoints with `http`, this skill *proves*
+the authorization boundary is broken by comparing responses side by side. The
+`diff` op returns FACTUAL signals (`status_varies`, `length_varies`,
+`content_varies`, `distinct_bodies`) — it renders no verdict; you reason over them.
+
+## 1. State the authorization claim
+Name, in one line, the boundary you believe is broken and who should be on each
+side: e.g. "order 1001 belongs to account A; an anonymous caller (or account B)
+must not read it." The claim is what the differential will confirm or refute.
+
+## 2. Build the differential
+Pick the comparison that isolates the boundary — vary ONE thing (the principal, or
+the object id), hold the rest constant:
+- **Cross-owner / tenant (BOLA):** fetch the SAME endpoint for ids owned by
+  different principals.
+  `diff {"requests":[{"path":"/api/orders/1001"},{"path":"/api/orders/1002"}]}`
+- **Authenticated vs anonymous:** fetch one resource as a named identity and again
+  with no identity.
+  `diff {"requests":[{"path":"/api/orders/1001","identity":"user_a"},{"path":"/api/orders/1001"}]}`
+- **Low-priv vs high-priv surface:** fetch an admin/privileged path as each
+  identity to show a role boundary is not enforced.
+
+Each sub-request is shaped like `http` args; a `"label"` is optional but makes the
+result readable.
+
+## 3. Read the signals, decide the boundary
+- `content_varies: true` with `distinct_bodies == 2` across two *different-owner*
+  reads, both `status 200`, no auth required → each party reads the other's
+  record: the object boundary is broken (IDOR/BOLA).
+- A protected resource returning the SAME body to a named identity and to anonymous
+  → authentication is not enforced on it.
+- `content_varies: false` / `distinct_bodies == 1` across supposedly-distinct
+  principals → the boundary HOLDS, or the resource is public by design — NOT a
+  finding. (The benign twin: `/api/catalog` fetched twice returns one body.)
+
+## 4. Distinguish a real break from correct/public behavior
+It is only an impact if the data is one the requester SHOULD NOT reach: a different
+owner/tenant, sensitive/scoped data (orders, invoices, profiles, PII), and no
+authorization error (not 401/403). A public, intentionally-shared resource that
+simply answers everyone is not a finding, however much it "varies."
+
+## 5. Prove without harm
+Demonstrate the read; never exercise it destructively. Read the record you should
+not be able to read — do not modify, delete, or create. If a mutating step would
+be needed to go further, stop: that boundary is deliberate.
+
+## Evidence & severity
+Cite the `diff` evidence id(s) and the exact distinguishing field that proves
+different ownership (e.g. a differing `owner`/`email`/`tenant`). Severity high, or
+critical when sequential/guessable ids expose PII or financial data at scale.

package/runners/skills/exploit/business-logic/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: business-logic
+description: Find and prove business-logic flaws — the app enforces the wrong invariant, so tampering with a trusted parameter, step order, or quantity yields an outcome the rules should forbid.
+when-to-use: a request carries a value the server should decide itself (price, total, discount, role, account id, quantity, status), or a multi-step workflow (cart→pay→ship, invite→accept, apply→approve) could be reordered, replayed, or skipped.
+surface: web
+severity: high
+tier: safe-active
+---
+
+# Business-logic abuse (parameter tampering, workflow, mass assignment)
+
+A non-destructive playbook for the `http` and `diff` ops. This is the most
+LLM-differentiated class: no scanner signature finds it — you must reason about what
+the operator INTENDED and where the app trusts the client for something it should
+decide. Prove the broken invariant by demonstrating the outcome; do not complete a
+genuinely fraudulent or destructive transaction.
+
+## 1. State the invariant the app should enforce
+In one line: what must always hold? "The price charged is the catalog price, never
+the client's." "Only an admin may set role=admin." "A coupon applies at most once."
+"You can only read your own account." The finding is a violation of THIS.
+
+## 2. Find where the client is trusted
+Look for request fields that encode a server-side decision: `price`, `total`,
+`amount`, `discount`, `role`, `is_admin`, `account_id`, `owner`, `status`,
+`quantity`, `step`. Baseline the honest request and note which of these the response
+echoes back as if authoritative.
+
+## 3. Tamper one thing and compare — use diff
+Change exactly the trusted field, hold the rest constant, and compare:
+`diff {"requests":[
+  {"path":"/api/checkout?item=1&price=19.99"},
+  {"path":"/api/checkout?item=1&price=0.01"}]}`.
+`content_varies` with the charge following your input (0.01) is the flaw: the server
+honored a value it should have decided. For workflows, diff the result of the normal
+order vs the reordered/replayed/skipped order.
+
+## 4. Distinguish a real flaw from correct behavior
+If the server re-derives the value and ignores your input (`content_varies: false`,
+the charge stays at the catalog price), the invariant holds — NOT a finding. Beware
+values that are merely display echoes with no effect; confirm the tampered value
+actually changes the authoritative outcome.
+
+## 5. Prove without harm
+Demonstrate the broken invariant with the smallest read/echo that shows it (the
+response reflects the under-charge, the escalated role, the reused coupon). Do NOT
+finalize a real fraudulent purchase, grant yourself durable admin, or mutate state —
+if proving it further requires a write, stop and report the demonstrated boundary.
+
+## Evidence & severity
+Cite the honest vs. tampered requests (or the diff evidence id) and name the
+invariant broken and the resulting impact (underpayment, privilege gain, boundary
+cross). Severity by impact: high for money/privilege, up to critical at scale.

package/runners/skills/exploit/client-side-exploitation/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: client-side-exploitation
+description: Prove interaction-only client-side bugs by DRIVING the page in a real headless browser — fill a field, click, submit a form — to trigger stored/DOM XSS that only fires on interaction, exercise a client-side state change, or complete a multi-step flow, then read the resulting DOM. The exploit-tier step beyond a passive render.
+when-to-use: a safe-active `render` (load-and-observe) showed a sink or a form/button that only acts on user interaction (a comment box that reflects into innerHTML on submit, a handler that runs on click), a bug you cannot reach by just loading a URL, and the engagement is at the exploit tier.
+surface: web
+severity: high
+tier: exploit
+---
+
+# Client-side exploitation (driving the browser)
+
+The exploit-tier counterpart to `render`. A passive render loads a page and reads what
+its JavaScript produced; this DRIVES the page — `render` with `actions` (fill, click,
+press, submit) — to reach bugs that only trigger on interaction, then returns the
+resulting DOM, console, and fetched URLs. Same op, same scope/origin rules; the
+`actions` capability unlocks only at the exploit tier with destructiveActions.
+
+Interaction causes real client-side effects (and can submit forms that change server
+state). Keep the action sequence minimal and benign, and prove execution, not just
+that you clicked.
+
+## 1. Find the interaction sink first
+From a passive render or the DOM, identify the element and the handler: a field whose
+value is written into `innerHTML`/`document.write` on a button click, a form that
+reflects its input on submit, a control that mutates client state. If a payload in the
+URL fragment already fires (no interaction needed), that is the passive
+`client-side-rendering` case — use that; this skill is for sinks that need a click.
+
+## 2. Drive the minimal sequence
+Fill the field with your payload, then trigger the handler:
+`render {"path":"/form","actions":[{"type":"fill","selector":"#comment","value":"<img
+src=x onerror=\"document.title='XSS_FIRED'\">"},{"type":"click","selector":"#go"}]}`.
+Use a payload whose execution is unambiguous and observable — set `document.title`, add
+a uniquely-identifiable node — not `alert()` (nothing reads it). Keep to the few actions
+the proof needs.
+
+## 3. Prove execution from the result
+The finding is the payload EXECUTING after interaction: the title/marker your payload
+set is present in the returned DOM/`title`, the injected node is live in the DOM, or a
+handler console error shows it ran. A payload that appears as inert, escaped text in the
+DOM did NOT execute — the sink is safe.
+
+## 4. Confirm the input caused it (precision)
+Run the same actions against a benign input (or the properly-escaped twin, if one
+exists): if the marker does NOT appear there, your input — not the page — caused it.
+A page that renders your payload with `textContent` (escaped) is NOT vulnerable; do not
+claim it. Clicking a button that does nothing observable is not a finding.
+
+## 5. If actions submit to the server
+A `submit` can change server state (it is a real form post). Treat that like any
+state-change exploit: prefer a reversible/throwaway submission, confirm the effect, and
+clean up. Do not mass-submit or repeat destructive posts to "confirm".
+
+## Scope & safety
+`render` (with or without actions) only reaches the origin and hosts under the verified
+root domain, and carries a login session as a cookie to the origin only. One proving
+interaction per finding; keep the action list short.
+
+## Evidence & severity
+Cite the path, the exact action sequence (selectors + payload), and the rendered DOM /
+title / console line that shows execution — plus the benign/escaped comparison. An
+interaction-triggered XSS that runs in a victim's authenticated session is high
+(session/account compromise). No proven execution, no finding.

package/runners/skills/exploit/client-side-rendering/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: client-side-rendering
+description: See the surface that only exists after JavaScript runs — render a page in a real headless browser to find DOM-based XSS (a payload that executes only once client JS processes it, invisible to a raw HTTP fetch) and to enumerate the routes and APIs a client-rendered app (SPA) loads at runtime.
+when-to-use: the raw http body of a page is a near-empty shell (a React/Vue/Angular app, lots of script, little markup), you suspect a sink that reads location/hash/postMessage into the DOM, or you need to discover the endpoints a client-rendered app calls that never appear in the static HTML.
+surface: web
+severity: high
+tier: safe-active
+---
+
+# Client-side rendering (DOM XSS & SPA surface)
+
+A non-destructive playbook for the `render` op (with `http` for the raw comparison).
+Modern apps ship a shell and build the page in the browser, so the `http` body shows
+almost nothing — the real attack surface appears only after JavaScript runs. `render`
+loads the page in a real browser and returns the rendered DOM, console messages, and
+the URLs the page fetched.
+
+`render` is LOAD-AND-OBSERVE ONLY. It navigates and reads; it does not click, submit,
+or drive the page. Interacting with the page is exploit-tier — do not try to simulate
+it here.
+
+## 1. Confirm it's worth rendering
+If `http` on a page returns a tiny shell dominated by `<script>` with little content,
+or you see a client-side sink (code reading `location.hash`, `location.search`,
+`document.referrer`, `postMessage`, or `name` into `innerHTML`/`document.write`),
+render it.
+
+## 2. Find DOM-based XSS
+Put the payload in the part of the URL the sink reads — usually the fragment, which
+never reaches the server: `render {"path":"/app#<img src=x onerror=...>"}`. A
+reflected-XSS payload won't help here; the sink is client-side. Prove execution from
+the rendered result: the injected node present in the returned DOM, a console error
+from the handler, or a title/marker your payload set. Compare with a benign input to
+confirm the input — not the page — caused it.
+
+## 3. Enumerate client-rendered surface
+The returned `requests` are the URLs the page fetched as it built itself — APIs,
+config, feature-flag and route endpoints that never appear in the static HTML. Treat
+each as a new target for `http`/`diff` (auth, IDOR, oversharing). This is often how
+you find the real API behind an SPA.
+
+## 4. Render as a session
+To test authenticated client-side state, `login` first, then
+`render {"path":"/dashboard","identity":"<session>"}` — the session cookie is carried
+into the browser (origin only). Compare anonymous vs. authenticated renders.
+
+## 5. Distinguish a real DOM-XSS from nothing
+Only a finding if your input actually executes or injects live markup in the rendered
+DOM. Input that appears escaped or as inert text is NOT DOM-XSS — the sink is safe;
+do not claim it. A console error alone, with no injected execution, is not proof.
+
+## Evidence & severity
+Cite the rendered URL (with the payload), and the rendered DOM / console line that
+shows execution — or, for surface enumeration, the fetched URLs. DOM-based XSS is
+high (account/session compromise in the victim's browser); a newly-enumerated
+unauthenticated API that overshares is as severe as the data it exposes. Render and
+read only; never drive the page to perform actions.