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

package/runners/prod_env.py

@@ -0,0 +1,1686 @@
+#!/usr/bin/env python3
+"""Product env adapter: basic-harness (teams+directions) -> a Blackglass assessment target.
+
+This is the in-PRODUCT sibling of security-eval/benches/apps_env.py. Where apps_env
+reads a local lab's private/lab.json, this adapter reads the control-plane's RunSpec
+(input-spec.json) for scope + identities and resolves each identity's credential from
+the out-of-band BLACKGLASS_SECRETS_JSON env var (never from disk). It exposes the
+target's HTTP surface to the prober as named identities, scope-bound to the RunSpec's
+allowedHosts.
+
+SAFETY: this adapter is READ-ONLY. Blackglass has no disposable-target provisioning,
+so a real assessment hits the customer's registered origin directly; the beta posture
+(matching the multiagent runner) is non-destructive, staging-only. Mutating methods
+(POST/PUT/PATCH/DELETE) are refused whenever policy.destructiveActions is false (which
+the control plane hard-forces). This limits what the agent DOES, not what it REPORTS:
+it still probes and reports read-oversharing greedily.
+
+Usage (set by basic_harness_run.py as the harness's -env command):
+    python3 prod_env.py --spec <session>/input-spec.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import hmac
+import ipaddress
+import json
+import os
+import re
+import secrets
+import socket
+import struct
+import sys
+import time
+import urllib.error
+import urllib.request
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urlencode, urljoin, urlparse
+
+import recon   # sibling module: WAF-independent EASM ops (dns/crt/tls/storage/...)
+import skills  # sibling module: on-demand playbook library (list_skills/get_skill)
+
+MAX_OUTPUT = 20000
+MAX_READ = 5_000_000        # cap a response body read to bound memory (huge/hostile responses)
+HTTP_TIMEOUT = 25           # under the core's fixed 30s env guillotine (env.go), leaving margin
+MAX_GREP_MATCHES = 50       # snippets returned when grepping a body (e.g. secret mining)
+RECON_ENABLED = os.environ.get("BASIC_HARNESS_RECON", "1") != "0"
+# Out-of-band interaction collaborator: a server the agent can mint unique callback
+# URLs on and poll for hits. A hit proves a blind server-side request (SSRF/XXE).
+# In the lab this points at the fixture's /mock/oob; in production at a real
+# Blackglass-operated collaborator. Unset => the oob_* ops are unavailable.
+OOB_COLLABORATOR_BASE = os.environ.get("OOB_COLLABORATOR_BASE", "").rstrip("/")
+# Headless-browser render service: an external endpoint that loads a URL in a REAL
+# browser (running its JavaScript) and returns the rendered DOM, console, and the
+# requests the page made. The adapter stays dependency-free -- it just POSTs
+# {url, cookie?, wait?} and parses the JSON back; the operator backs this URL with a
+# Chrome/Playwright/CDP service. Unset => the `render` op is unavailable (like OOB).
+BROWSER_RENDER_URL = os.environ.get("BROWSER_RENDER_URL", "").rstrip("/")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Return the 3xx response unfollowed so the agent can see Location (open-redirect,
+    auth-flow analysis) instead of transparently landing on the redirect target."""
+
+    def redirect_request(self, *a, **k):
+        return None
+
+
+class _ScopedRedirect(urllib.request.HTTPRedirectHandler):
+    """Follow a redirect only when its target is in scope; otherwise return the 3xx unfollowed,
+    exactly as allow_redirects:false would. A target that answers with a redirect to an
+    out-of-scope host (another local port, the metadata address, any other host) must not pull
+    the scan onto it: the agent sees the Location, but the runner never fetches it. This is the
+    backstop behind the per-request scope check, which only guards the FIRST hop."""
+
+    def __init__(self, target):
+        super().__init__()
+        self._target = target
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if not self._target.url_in_scope(newurl):
+            return None
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+READONLY_METHODS = {"GET", "HEAD", "OPTIONS"}
+
+
+def _clip(text: str, limit: int = MAX_OUTPUT) -> str:
+    if len(text) <= limit:
+        return text
+    head = limit * 3 // 4
+    tail = limit - head
+    return f"{text[:head]}\n...{len(text) - limit} chars clipped...\n{text[-tail:]}"
+
+
+def _host(origin: str) -> str:
+    return urlparse(origin).netloc
+
+
+def _authority(url_or_host: str, default_scheme: str = "http") -> str:
+    """Effective host:port, with the default port filled from the scheme (http->80, https->443),
+    lowercased. So http://h and http://h:80 compare equal, while http://h (80), https://h (443)
+    and ftp://h (21) do not. A bare host[:port] is read under default_scheme."""
+    raw = url_or_host if "//" in url_or_host else f"{default_scheme}://{url_or_host}"
+    p = urlparse(raw)
+    host = (p.hostname or "").lower()
+    try:
+        port = p.port
+    except ValueError:
+        port = None
+    if port is None:
+        port = {"https": 443, "ftp": 21}.get(p.scheme, 80)
+    return f"{host}:{port}"
+
+
+def _is_registrable_domain(host: str) -> bool:
+    """True only for a real multi-label DNS name. A loopback/IP literal or a bare local
+    hostname like "localhost" has no registrable root, so the subdomain scope carve-out must
+    not apply to it -- otherwise scanning 127.0.0.1 would put *.0.1 in scope, and localhost
+    would admit *.localhost."""
+    h = (host or "").strip().lower()
+    if h.startswith("["):          # [bracketed] IPv6, maybe with :port
+        h = h[1:].split("]", 1)[0]
+    elif h.count(":") == 1:        # host:port (a lone colon; an IPv6 literal has several)
+        h = h.split(":", 1)[0]
+    h = h.strip(".")
+    if not h or "." not in h:
+        return False
+    try:
+        ipaddress.ip_address(h)
+        return False               # an IPv4/IPv6 literal is not a registrable domain
+    except ValueError:
+        return True
+
+
+class Target:
+    """The assessment target described by a RunSpec + resolved secrets."""
+
+    def __init__(self, spec: dict, secrets: list[dict]):
+        scope = spec.get("scope") or {}
+        allowed = [h for h in (scope.get("allowedHosts") or []) if h]
+        origins = [o for o in ((spec.get("target") or {}).get("origins") or []) if o]
+        if not origins and not allowed:
+            raise SystemExit("RunSpec has no target.origins or scope.allowedHosts")
+        # Prefer an explicit origin; fall back to the first allowed host as https.
+        self.origin = (origins[0] if origins else f"https://{allowed[0]}").rstrip("/")
+        base_host = _host(self.origin) or (allowed[0] if allowed else "")
+        self.base_host = base_host
+        # Hosts the prober may reach: the allowlist, plus the origin's own host.
+        self.allowed_hosts = set(allowed) | ({base_host} if base_host else set())
+        # The verified registrable root (scope carve-out for recon + host pivots):
+        # the prober may probe any host UNDER this root, discovered via recon. Prefer
+        # an explicit scope.rootDomain (known from asset verification, and correct for
+        # multi-label TLDs like co.uk); otherwise derive it from the origin host.
+        # Subdomain carve-out (recon host-pivots): only a real DNS domain has a registrable
+        # root. For a loopback/IP or bare local hostname -- the local-runner target -- there is
+        # none, so scope stays exactly the origin host + explicit allowlist, and a redirect or
+        # a recon "subdomain" can't pull the scan to another host. `scope.exact` (set by the
+        # local-scan CLI) disables the carve-out outright -- even for a multi-label local name
+        # like service.team.internal -- so scope is exactly allowed_hosts and nothing else.
+        explicit_root = (scope.get("rootDomain") or "").strip().lower()
+        self.exact = bool(scope.get("exact"))
+        if self.exact:
+            self.root_domain = ""
+        else:
+            self.root_domain = explicit_root or (recon.registrable(base_host) if _is_registrable_domain(base_host) else "")
+        # Exact scope: the complete set of reachable authorities (scheme-normalized host:port) --
+        # the origin plus any explicit allowed host. A request or redirect must match one exactly,
+        # so a sibling host, a scheme/port switch (http->https/ftp), or a Host override can't pivot.
+        default_scheme = urlparse(self.origin).scheme or "http"
+        self.allowed_authorities = {_authority(self.origin)} | {_authority(h, default_scheme) for h in self.allowed_hosts}
+        self.excluded_paths = [p for p in (scope.get("excludedPaths") or []) if p]
+        # destructiveActions is hard-forced false by the control plane; honor it.
+        self.read_only = not bool((spec.get("policy") or {}).get("destructiveActions", False))
+        # The action tier bounds how far the agent may go (mirrors the harness's
+        # -action-tier). "passive" = discovery/read-only (the default, and the
+        # behaviour before this field existed); "safe-active" unlocks non-destructive
+        # active-inference ops (e.g. diff); "exploit" is mutating. Unknown/empty
+        # resolves to passive (fail-closed), so a typo never silently unlocks more.
+        self.action_tier = str((spec.get("policy") or {}).get("actionTier") or "passive")
+        # Dynamically-established sessions (name -> Cookie header), populated by the
+        # `login` op and reused by `http`/`diff` via identity:<name>. Empty until a
+        # login succeeds; a static spec identity still resolves as before.
+        self.sessions: dict[str, str] = {}
+        # Test accounts signed in automatically (sign_in): extra headers a session carries
+        # (a bearer token returned in the body), and why an account couldn't sign in, so a
+        # wrong password isn't retried on every request (and can't lock the account out).
+        self.session_headers: dict[str, dict[str, str]] = {}
+        self.sign_in_failed: dict[str, str] = {}
+        # Loot store + chain graph (safe-active): credentials/ids/endpoints the agent
+        # RECOVERS (loot, id -> {kind,value,source,note}) and the edges between
+        # findings (one enabling the next). Stashed loot is replayed on later
+        # requests via http/diff loot:<id>; edges feed the kill-chain report.
+        self.loot: dict[str, dict] = {}
+        self.edges: list[dict] = []
+        self._loot_seq = 0
+
+        # Preliminary-scan profile (default-OFF feature). When BLACKGLASS_PROFILE is
+        # enabled and BLACKGLASS_PROFILE_PATH points at a profile.json (produced by the
+        # deterministic profile.py pre-pass), it is loaded here and surfaced as a compact
+        # headline in describe() + a `profile` op. With the feature off, self.profile is
+        # None and nothing below it fires, so the adapter is byte-identical to before.
+        # The profile is SIGNALS to confirm, never findings (see docs/preliminary-scan-plan.md).
+        self.profile = None
+        if _profile_enabled():
+            ppath = os.environ.get("BLACKGLASS_PROFILE_PATH", "").strip()
+            if ppath:
+                try:
+                    data = json.loads(Path(ppath).read_text())
+                    if isinstance(data, dict):
+                        self.profile = data
+                except Exception:  # noqa: BLE001 - a bad/absent profile just disables the feature
+                    self.profile = None
+
+        # The control plane emits ResolvedSecret.id == identity.id (server.ts launch),
+        # so match on the identity id first, then fall back to secretRef.
+        by_id = {s.get("id"): s for s in secrets if isinstance(s, dict)}
+        self.identities: dict[str, dict] = {}
+        for ident in spec.get("identities") or []:
+            iid = ident.get("id")
+            if not iid:
+                continue
+            secret = by_id.get(iid) or by_id.get(ident.get("secretRef"))
+            self.identities[iid] = {
+                "id": iid,
+                "kind": ident.get("kind"),
+                "how": ident.get("how"),
+                "secret": secret,  # {id, kind, value} or None
+            }
+        # The adapter signs every password account in once at scan start and hands the
+        # sessions to each environment process out-of-band (never on disk), so the agents
+        # share one session instead of each signing in.
+        for iid, shared in load_shared_sessions().items():
+            if iid not in self.identities or not isinstance(shared, dict):
+                continue
+            if shared.get("error"):
+                self.sign_in_failed[iid] = str(shared["error"])
+                continue
+            if shared.get("cookie"):
+                self.sessions[iid] = str(shared["cookie"])
+            if isinstance(shared.get("headers"), dict):
+                self.session_headers[iid] = {str(k): str(v) for k, v in shared["headers"].items()}
+
+    def host_in_scope(self, host: str) -> bool:
+        """A host the prober may fetch: an explicit allowlisted host, the origin,
+        or any host under the verified root domain (recon-discovered subdomains)."""
+        host = (host or "").lower()
+        return host in self.allowed_hosts or recon.in_domain_scope(host, self.root_domain)
+
+    def url_in_scope(self, url: str) -> bool:
+        """Whether the runner may fetch this URL. Always: an http(s) scheme (so a redirect can't
+        switch to ftp://, file://, ...). Exact mode: the exact scheme-normalized host:port, so a
+        default-port target can't be pivoted to :443/:21 and a sibling host is refused. Otherwise
+        the host-level scope (host_in_scope)."""
+        p = urlparse(url)
+        if p.scheme not in ("http", "https"):
+            return False
+        if self.exact:
+            return _authority(url) in self.allowed_authorities
+        return self.host_in_scope(_host(url))
+
+    def tier_at_least(self, tier: str) -> bool:
+        """Whether the run's action tier permits ops at `tier` or above. Gates
+        which ops describe() advertises; mirrors the harness's tierAtLeast."""
+        return _tier_rank(self.action_tier) >= _tier_rank(tier)
+
+    def header_for(self, identity: str):
+        ident = self.identities.get(identity)
+        if ident is None:
+            return None, f"unknown identity {identity!r}; available: {', '.join(self.identities) or '(none)'}"
+        secret = ident.get("secret")
+        if not secret or not secret.get("value"):
+            return None, f"identity {identity!r} has no resolved credential (anonymous only)"
+        value = str(secret["value"])
+        kind = (secret.get("kind") or ident.get("kind") or "header").lower()
+        if kind == "password":
+            # A password account is not a header credential — the JSON broker blob must
+            # never be sent as one. Sign in with the `login` op instead.
+            return None, f"identity {identity!r} is a password account — sign in with the `login` op (do not attach it as a header)"
+        if kind == "cookie" and ":" not in value.split(";", 1)[0]:
+            return ("Cookie", value), None
+        if ":" in value:  # a full header line, e.g. "Authorization: Basic ..."
+            name, _, val = value.partition(":")
+            return (name.strip(), val.strip()), None
+        return None, f"identity {identity!r} credential is not a usable header/cookie"
+
+
+_TIER_RANK = {"passive": 0, "safe-active": 1, "exploit": 2}
+MAX_DIFF_REQUESTS = 12       # bound the fan-out of one diff op (rate-awareness)
+
+
+def _tier_rank(tier: str) -> int:
+    """Rank a tier; anything unrecognized is passive (0), fail-closed."""
+    return _TIER_RANK.get(str(tier or "").strip(), 0)
+
+
+def _profile_enabled() -> bool:
+    """The single gate for the preliminary-scan profile feature (default OFF). Read at
+    Target construction so the feature can be toggled per run without re-importing."""
+    return os.environ.get("BLACKGLASS_PROFILE", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _skill_allowed(t: Target, skill_tier: str) -> bool:
+    """Whether a skill declaring `skill_tier` may be surfaced on this run. A skill
+    with no declared tier is passive discovery methodology, always available (the
+    existing skills). An explicit known tier gates the skill to runs at or above
+    it. An unrecognized non-empty tier string is fail-CLOSED (hidden) so a typo in
+    a skill's frontmatter never leaks an offensive playbook into a lower-tier run.
+    Note the fail direction is opposite to _tier_rank (which fail-closes the RUN's
+    tier to passive): here an unknown SKILL tier must be the most restrictive."""
+    skill_tier = str(skill_tier or "").strip()
+    if not skill_tier:
+        return True
+    if skill_tier not in _TIER_RANK:
+        return False
+    return _tier_rank(t.action_tier) >= _TIER_RANK[skill_tier]
+
+
+def _skill_gate(t: Target):
+    """The predicate skills.* uses to filter by the run's action tier."""
+    return lambda skill_tier: _skill_allowed(t, skill_tier)
+
+
+def _http(t: Target, args: dict) -> dict:
+    method = str(args.get("method", "GET")).upper()
+    path = args.get("path")
+    if not isinstance(path, str) or not path.startswith("/"):
+        return {"ok": False, "error": "http needs a 'path' starting with '/' (relative to the target origin)"}
+    if method not in READONLY_METHODS:
+        # A mutating request is the EXPLOIT-tier primitive. Two independent keys must
+        # both be turned or it is refused (fail-closed): the run must be at the exploit
+        # tier AND destructiveActions must be authorized (read_only False, which the
+        # control plane can hard-force off). `login` is the one non-exploit POST, and it
+        # does not route through here. This is strictly tighter than before (which let
+        # destructiveActions alone unlock mutation at any tier).
+        if not t.tier_at_least("exploit"):
+            return {"ok": False, "error": (
+                f"method {method} mutates target state and is an EXPLOIT-tier action; this run is "
+                f"'{t.action_tier}'. Probe access-control exposure with GET/HEAD only (use `login` to "
+                "authenticate); do not create, modify, or delete data.")}
+        if t.read_only:
+            return {"ok": False, "error": (
+                f"method {method} is refused: destructiveActions is not authorized for this run. A "
+                "mutating exploit needs BOTH the exploit tier AND destructiveActions enabled.")}
+    for ex in t.excluded_paths:
+        if path.startswith(ex):
+            return {"ok": False, "error": f"path {path} is out of scope (excluded)"}
+
+    # Optional host override: pivot to a recon-discovered host UNDER the verified
+    # root domain, using the same evidence-generating op. Defaults to the origin.
+    host_arg = args.get("host")
+    if host_arg:
+        host_arg = str(host_arg).lower()
+        if not t.host_in_scope(host_arg):
+            return {"ok": False, "error": (
+                f"host {host_arg} is out of scope: reachable hosts are the target origin "
+                f"and any host under the verified root domain {t.root_domain}")}
+        origin = f"https://{host_arg}"
+    else:
+        origin = t.origin
+
+    url = origin + path
+    if not t.url_in_scope(url):
+        return {"ok": False, "error": f"request left scope; reachable: the target origin and hosts under {t.root_domain}" if not t.exact else "request left scope; this scan is pinned to its exact target host:port"}
+
+    # Present a mainstream browser signature by default. Many real targets sit behind a
+    # WAF/CDN (e.g. Cloudflare) that outright bans the stock urllib client signature
+    # (error 1010 "browser_signature_banned"), which starves the assessment before it
+    # starts. The agent can still override any header per request via `headers`.
+    headers = {
+        "User-Agent": ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                       "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"),
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.9",
+    }
+    extra = args.get("headers")
+    if isinstance(extra, dict):
+        for k, v in extra.items():
+            headers[str(k)] = str(v)
+    # Under exact scope, drop any caller-supplied Host header: on a name-based reverse proxy a
+    # Host override reaches a sibling virtual host on the same address despite the host:port
+    # being in scope. Pin Host to the target (urllib sets it from the URL).
+    if t.exact:
+        for hk in [k for k in list(headers) if k.lower() == "host"]:
+            del headers[hk]
+
+    identity = args.get("identity") or args.get("as")
+    actor = "anonymous"
+    if identity:
+        # Never send an identity's credential to a host other than the one it was
+        # issued for: a cookie/token for the origin must not leak to a pivoted
+        # recon-discovered subdomain. Probe those anonymously.
+        if _host(url) != t.base_host:
+            return {"ok": False, "error": (
+                f"credentials are only injected for the primary origin host ({t.base_host}); "
+                f"omit identity to probe {_host(url)} anonymously")}
+        sid = str(identity)
+        creds, err = identity_headers(t, sid, renew=bool(args.get("_renew")))
+        if err:
+            return {"ok": False, "error": err}
+        headers.update(creds)
+        actor = sid
+
+    # A recovered credential (loot) stashed earlier, replayed by reference. Like an
+    # identity, it is only ever sent to the primary origin host -- a credential
+    # recovered from the origin must not leak to a pivoted recon-discovered host.
+    loot_ref = args.get("loot")
+    if loot_ref:
+        if _host(url) != t.base_host:
+            return {"ok": False, "error": (
+                f"recovered credentials (loot) are only replayed to the primary origin host "
+                f"({t.base_host}); omit loot to probe {_host(url)} anonymously")}
+        item = t.loot.get(str(loot_ref))
+        if not item:
+            return {"ok": False, "error": f"unknown loot {loot_ref!r}; stash it first with the loot op (action:'stash'), or list what you have"}
+        hk, hv = _loot_header(item)
+        if hk is None:
+            return {"ok": False, "error": hv}
+        headers[hk] = hv
+        if actor == "anonymous":
+            actor = f"loot:{loot_ref}"
+
+    data = None
+    body = args.get("body")
+    if body is not None:
+        if isinstance(body, (dict, list)):
+            data = json.dumps(body).encode("utf-8")
+            headers.setdefault("Content-Type", "application/json")
+        else:
+            data = str(body).encode("utf-8")
+
+    # By default follow redirects, but only to in-scope hosts (_ScopedRedirect): an off-scope
+    # redirect is returned to the agent as a 3xx, never fetched. Set allow_redirects:false to
+    # see any 3xx + Location unfollowed (open-redirect / auth-flow analysis).
+    follow = args.get("allow_redirects", True)
+    opener = urllib.request.build_opener(_ScopedRedirect(t) if follow else _NoRedirect).open
+    req = urllib.request.Request(url, data=data, method=method, headers=headers)
+    final_url = url
+    try:
+        with opener(req, timeout=HTTP_TIMEOUT) as resp:
+            raw = resp.read(MAX_READ)
+            status, resp_headers = resp.status, dict(resp.headers.items())
+            final_url = resp.geturl() or url
+    except urllib.error.HTTPError as e:
+        raw = e.read(MAX_READ) if hasattr(e, "read") else b""
+        status = e.code
+        resp_headers = dict(e.headers.items()) if e.headers else {}
+    except Exception as e:  # noqa: BLE001 - surface to the agent, don't crash the adapter
+        return {"ok": False, "error": f"request failed: {e}"}
+
+    # A test account's session expired (a 401, or the app sent the request back to the
+    # sign-in page): sign in again and repeat the request once.
+    if identity and not args.get("_renew") and is_password_account(t.identities.get(str(identity))):
+        login_path = sign_in_path(t.identities.get(str(identity))).split("?", 1)[0]
+        landed = urlparse(urljoin(url, resp_headers.get("Location") or resp_headers.get("location") or final_url)).path
+        if path.split("?", 1)[0] != login_path and (status == 401 or landed == login_path):
+            return _http(t, {**args, "_renew": True})
+
+    text = raw.decode("utf-8", "replace")
+    # Keep headers that carry evidence for the checklist surfaces: content/redirect/auth,
+    # tech fingerprint (server/x-powered-by/via), CORS posture, and the presence or
+    # absence of security headers (a missing CSP/HSTS is itself a finding).
+    keep_exact = {"content-type", "content-length", "location", "www-authenticate",
+                  "server", "x-powered-by", "via", "x-aspnet-version",
+                  "access-control-allow-origin", "access-control-allow-credentials",
+                  "access-control-allow-methods", "set-cookie",
+                  "content-security-policy", "strict-transport-security",
+                  "x-frame-options", "x-content-type-options", "referrer-policy"}
+    keep = {k: v for k, v in resp_headers.items() if k.lower() in keep_exact}
+    out = {"ok": True, "actor": actor, "method": method, "path": path,
+           "status": status, "bytes": len(raw), "headers": keep}
+    # Opt-in FULL header set (default off, so the curated `headers` output is unchanged):
+    # the profile pre-pass and header-hygiene analysis need every header, not the subset.
+    if args.get("raw_headers"):
+        out["raw_headers"] = resp_headers
+    if host_arg:
+        out["host"] = host_arg
+
+    # Optional server-side grep over the FULL body: for secret mining in large JS
+    # bundles / source maps where the clipped body would drop the middle. Returns
+    # snippets around each regex match instead of the (clipped) whole body.
+    grep = args.get("grep")
+    if grep:
+        try:
+            rx = re.compile(str(grep))
+        except re.error as e:
+            return {"ok": False, "error": f"bad grep regex {grep!r}: {e}"}
+        snippets = []
+        for m in rx.finditer(text):
+            lo, hi = max(0, m.start() - 100), min(len(text), m.end() + 100)
+            snippets.append(text[lo:hi])
+            if len(snippets) >= MAX_GREP_MATCHES:
+                break
+        out["grep"] = str(grep)
+        out["match_count"] = len(snippets)
+        out["matches"] = snippets
+    else:
+        out["body"] = _clip(text)
+    return out
+
+
+def _diff(t: Target, args: dict) -> dict:
+    """Differential oracle (safe-active): run 2+ requests and report how their
+    responses differ. The precision primitive -- it turns "this endpoint might
+    leak per-user data" into a reproducible comparison (e.g. two owners' records
+    differ in content under no auth => IDOR; a true/false payload pair differs in
+    length => a boolean oracle). Each sub-request goes through the SAME read-only
+    http path (method gate, scope, identity, redirect handling), so diff can never
+    do more than http can. It returns FACTUAL signals, not a verdict -- the agent
+    reasons over them. Comparison uses the (clipped) body plus the full byte length,
+    so a difference only past the clip is caught by length, not content."""
+    if not t.tier_at_least("safe-active"):
+        return {"ok": False, "error": "diff requires the safe-active action tier"}
+    reqs = args.get("requests")
+    if not isinstance(reqs, list) or len(reqs) < 2:
+        return {"ok": False, "error": "diff needs 'requests': a list of 2 or more request objects (each shaped like http args)"}
+    if len(reqs) > MAX_DIFF_REQUESTS:
+        return {"ok": False, "error": f"diff takes at most {MAX_DIFF_REQUESTS} requests at once"}
+    results, bodies = [], []
+    for r in reqs:
+        if not isinstance(r, dict):
+            return {"ok": False, "error": "each request must be an object shaped like http args"}
+        r = dict(r)
+        label = r.pop("label", None)
+        # Accept BOTH shapes the model emits: flat http args ({"path": "/x"}) and the
+        # env envelope ({"op": "http", "args": {"path": "/x"}}). Models reach for the
+        # envelope out of habit, so unwrap it rather than fail the sub-request.
+        inner = r.get("args")
+        if isinstance(inner, dict):
+            r = dict(inner)
+        else:
+            r.pop("op", None)  # a stray top-level "op" is not an http argument
+        r.pop("grep", None)  # diff needs the body itself to compare, not grep snippets
+        res = _http(t, r)
+        if not res.get("ok"):
+            results.append({"ok": False, "label": label, "path": r.get("path"), "error": res.get("error")})
+            bodies.append(None)
+            continue
+        results.append({"ok": True, "label": label, "actor": res.get("actor"), "method": res.get("method"),
+                        "path": res.get("path"), "host": res.get("host"), "status": res.get("status"), "bytes": res.get("bytes")})
+        bodies.append(res.get("body"))
+    oks = [x for x in results if x.get("ok")]
+    statuses = sorted({x["status"] for x in oks})
+    lengths = sorted({x["bytes"] for x in oks})
+    distinct_bodies = len({b for b in bodies if b is not None})
+    return {"ok": True, "tier": t.action_tier, "count": len(results), "results": results,
+            "signals": {
+                "status_varies": len(statuses) > 1,
+                "length_varies": len(lengths) > 1,
+                "content_varies": distinct_bodies > 1,
+                "distinct_bodies": distinct_bodies,
+                "statuses": statuses,
+                "lengths": lengths,
+            }}
+
+
+def _oob_mint(t: Target, args: dict) -> dict:
+    """Mint a unique out-of-band callback URL + token (safe-active). The agent
+    plants the URL where the target might fetch it (an SSRF url param, a webhook,
+    an XXE entity); a server-side request to it is logged for oob_poll. This is the
+    proof primitive for BLIND vulns -- no callback, no critical."""
+    if not t.tier_at_least("safe-active"):
+        return {"ok": False, "error": "oob_mint requires the safe-active action tier"}
+    if not OOB_COLLABORATOR_BASE:
+        return {"ok": False, "error": "no OOB collaborator configured (OOB_COLLABORATOR_BASE unset); blind-callback proofs are unavailable on this run"}
+    token = secrets.token_hex(8)
+    return {"ok": True, "token": token, "url": f"{OOB_COLLABORATOR_BASE}/{token}",
+            "hint": "plant this url where the target may fetch it (SSRF url=, webhook, redirect, XXE), then oob_poll the token to prove a blind callback"}
+
+
+def _oob_poll(t: Target, args: dict) -> dict:
+    """Check whether a minted callback was hit out-of-band. interaction:true proves
+    the target made a server-side request to the collaborator (blind SSRF/XXE);
+    zero hits is NOT proof (the payload may simply not have fired)."""
+    if not t.tier_at_least("safe-active"):
+        return {"ok": False, "error": "oob_poll requires the safe-active action tier"}
+    if not OOB_COLLABORATOR_BASE:
+        return {"ok": False, "error": "no OOB collaborator configured (OOB_COLLABORATOR_BASE unset)"}
+    token = str(args.get("token", "")).strip()
+    if not token:
+        return {"ok": False, "error": "oob_poll needs a 'token' from oob_mint"}
+    try:
+        with urllib.request.urlopen(f"{OOB_COLLABORATOR_BASE}/{token}/hits", timeout=HTTP_TIMEOUT) as r:
+            data = json.loads(r.read(MAX_READ).decode("utf-8", "replace"))
+    except Exception as e:  # noqa: BLE001 - surface to the agent
+        return {"ok": False, "error": f"oob_poll failed: {e}"}
+    hits = int(data.get("hits", 0)) if isinstance(data, dict) else 0
+    return {"ok": True, "token": token, "hits": hits, "interaction": hits > 0,
+            "note": ("a hit proves the target made an out-of-band request to your collaborator "
+                     "(blind SSRF/XXE confirmed)" if hits > 0 else "no callback yet; this is not proof of a blind vuln")}
+
+
+# ─── Password-identity broker ─────────────────────────────────────────────────
+# A 'password' identity carries a JSON blob {username, password, totp?(base32 seed)}
+# resolved out-of-band. The adapter signs in with it and generates the TOTP code at
+# login time; the model never sees these values — it drives `login` by identity name
+# and may shape the request body with {{username}}/{{password}}/{{totp}} placeholders.
+_CSRF_NAME = re.compile(r"csrf|xsrf|_token|authenticity_token|csrfmiddlewaretoken|__RequestVerificationToken", re.I)
+_INPUT_TAG = re.compile(r"<input\b[^>]*>", re.I)
+_ATTR = re.compile(r'([\w:-]+)\s*=\s*"([^"]*)"')
+
+
+def _totp_now(seed: str, *, digits: int = 6, period: int = 30) -> str | None:
+    """RFC 6238 TOTP from a base32 seed (stdlib only). None on a malformed seed."""
+    cleaned = re.sub(r"\s+", "", seed or "").upper()
+    if not cleaned:
+        return None
+    try:
+        key = base64.b32decode(cleaned + "=" * (-len(cleaned) % 8))
+    except Exception:  # noqa: BLE001 - a bad seed just disables TOTP
+        return None
+    digest = hmac.new(key, struct.pack(">Q", int(time.time() // period)), hashlib.sha1).digest()
+    offset = digest[-1] & 0x0F
+    code = (struct.unpack(">I", digest[offset:offset + 4])[0] & 0x7FFFFFFF) % (10 ** digits)
+    return str(code).zfill(digits)
+
+
+def _fill_secret_placeholders(value, mapping: dict):
+    """Substitute {{key}} tokens in a body (string / dict / list) with secret values."""
+    if isinstance(value, str):
+        for k, v in mapping.items():
+            value = value.replace("{{" + k + "}}", v)
+        return value
+    if isinstance(value, dict):
+        return {k: _fill_secret_placeholders(v, mapping) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_fill_secret_placeholders(v, mapping) for v in value]
+    return value
+
+
+def _scrape_hidden_tokens(html: str) -> dict:
+    """Best-effort: pull hidden CSRF-looking inputs (name->value) from a login page."""
+    out: dict[str, str] = {}
+    for tag in _INPUT_TAG.findall(html or ""):
+        attrs = {k.lower(): v for k, v in _ATTR.findall(tag)}
+        name, val = attrs.get("name"), attrs.get("value")
+        if name and val and _CSRF_NAME.search(name):
+            out[name] = val
+    return out
+
+# ─── Automatic sign-in for test accounts ──────────────────────────────────────
+# A 'password' test account signs itself in: the adapter opens the saved sign-in page, fills
+# its form (username, password, any hidden CSRF token, a fresh authenticator code), or posts
+# JSON when the page is a sign-in API, and keeps the session that comes back: its cookies, or
+# a token returned in the body. Agents then act as the account with identity:"<id>" on
+# http/diff/render, like a cookie account, and never see the credentials. A session that
+# expires (a 401, or a redirect back to the sign-in page) is renewed once. Allowed at every
+# tier: posting the customer's own credentials to their own sign-in page is exactly what
+# adding the account asked for.
+_BROWSER_UA = ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+               "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36")
+_USER_FIELD = re.compile(r"user|email|login|account|identifier|name|phone", re.I)
+_OTP_FIELD = re.compile(r"otp|totp|mfa|2fa|one.?time|verif\w*.?code|auth\w*.?code|^code$", re.I)
+_TOKEN_KEYS = ("access_token", "accessToken", "token", "jwt", "id_token", "idToken",
+               "auth_token", "authToken", "sessionToken", "session_token")
+MAX_SIGN_IN_HOPS = 5
+
+
+class _Forms(HTMLParser):
+    """The page's forms with their inputs (enough to fill a sign-in form)."""
+
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.forms: list[dict] = []
+        self._open: dict | None = None
+        self.loose: list[dict] = []  # inputs outside any <form> (script-driven pages)
+
+    def handle_starttag(self, tag, attrs):
+        a = {k.lower(): (v or "") for k, v in attrs}
+        if tag == "form":
+            self._open = {"action": a.get("action", ""), "method": (a.get("method") or "post").lower(), "inputs": []}
+            self.forms.append(self._open)
+        elif tag in ("input", "button") and a.get("name"):
+            field = {"name": a["name"], "type": (a.get("type") or ("submit" if tag == "button" else "text")).lower(),
+                     "value": a.get("value", ""), "checked": "checked" in a,
+                     "autocomplete": a.get("autocomplete", "").lower()}
+            (self._open["inputs"] if self._open is not None else self.loose).append(field)
+
+    def handle_endtag(self, tag):
+        if tag == "form":
+            self._open = None
+
+
+def _page_forms(html: str) -> _Forms:
+    parser = _Forms()
+    try:
+        parser.feed(html or "")
+    except Exception:  # noqa: BLE001 - a malformed page just yields fewer forms
+        pass
+    return parser
+
+
+def _has_password_field(html: str) -> bool:
+    forms = _page_forms(html)
+    return any(f["type"] == "password" for form in forms.forms for f in form["inputs"]) or \
+        any(f["type"] == "password" for f in forms.loose)
+
+
+def _jar_update(jar: dict[str, str], headers) -> None:
+    for raw in (headers.get_all("Set-Cookie") or []) if headers else []:
+        pair, _, attrs = raw.partition(";")
+        name, sep, value = pair.partition("=")
+        name = name.strip()
+        if not sep or not name:
+            continue
+        if re.search(r"max-age\s*=\s*0\b", attrs, re.I) or re.search(r"expires\s*=\s*thu,\s*01[ -]jan[ -]1970", attrs, re.I):
+            jar.pop(name, None)  # the app cleared it
+        else:
+            jar[name] = value.strip()
+
+
+def _jar_header(jar: dict[str, str]) -> str:
+    return "; ".join(f"{k}={v}" for k, v in jar.items())
+
+
+def _send(t: "Target", url: str, jar: dict[str, str], method: str = "GET", data: bytes | None = None,
+          headers: dict | None = None):
+    """One request, redirects unfollowed (a sign-in's cookies often ride the 3xx). Updates
+    the cookie jar; returns (status, headers, body text)."""
+    if urlparse(url).scheme not in ("http", "https"):
+        raise ValueError(f"refused a non-http(s) URL during sign-in: {url}")
+    h = {"User-Agent": _BROWSER_UA, "Accept": "text/html,application/json;q=0.9,*/*;q=0.8"}
+    h.update(headers or {})
+    if jar:
+        h["Cookie"] = _jar_header(jar)
+    req = urllib.request.Request(url, data=data, method=method, headers=h)
+    try:
+        with urllib.request.build_opener(_NoRedirect).open(req, timeout=HTTP_TIMEOUT) as resp:
+            status, resp_headers, raw = resp.status, resp.headers, resp.read(MAX_READ)
+    except urllib.error.HTTPError as e:
+        status, resp_headers = e.code, e.headers
+        raw = e.read(MAX_READ) if hasattr(e, "read") else b""
+    _jar_update(jar, resp_headers)
+    return status, resp_headers, raw.decode("utf-8", "replace")
+
+
+def _follow(t: Target, url: str, jar: dict[str, str], first: tuple | None = None):
+    """Follow redirects on the target's own host, keeping cookies. Returns
+    (status, headers, body, final url); a redirect to another site raises ValueError."""
+    status, headers, body = first if first else _send(t, url, jar)
+    for _ in range(MAX_SIGN_IN_HOPS):
+        if status not in (301, 302, 303, 307, 308) or not headers or not headers.get("Location"):
+            break
+        url = urljoin(url, headers["Location"])
+        if _host(url) != t.base_host:
+            raise ValueError(f"the sign-in redirects to {_host(url)} (single sign-on), which isn't supported yet")
+        if not t.url_in_scope(url):
+            raise ValueError(f"the sign-in redirects out of scope ({url})")
+        status, headers, body = _send(t, url, jar)
+    return status, headers, body, url
+
+
+def _token_from(body: str) -> str | None:
+    try:
+        data = json.loads(body)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    scopes = [data] + ([data.get(k) for k in ("data", "result", "session", "auth")] if isinstance(data, dict) else [])
+    for scope in scopes:
+        if isinstance(scope, dict):
+            for key in _TOKEN_KEYS:
+                value = scope.get(key)
+                if isinstance(value, str) and len(value) >= 16 and " " not in value:
+                    return value
+    return None
+
+
+def _fill(form: dict, creds: dict[str, str]) -> dict[str, str]:
+    """A sign-in form's fields: the credentials where they go, everything else as the page set it."""
+    fields: dict[str, str] = {}
+    user_field = None
+    passwords = 0
+    for f in form["inputs"]:
+        name, kind = f["name"], f["type"]
+        if kind == "password":
+            passwords += 1
+            if passwords == 1:
+                fields[name] = creds["password"]
+        elif kind in ("submit", "button", "image", "reset", "file"):
+            continue
+        elif kind in ("checkbox", "radio"):
+            if f["checked"]:
+                fields[name] = f["value"] or "on"
+        elif kind == "hidden":
+            fields[name] = f["value"]
+        elif creds.get("totp") and (_OTP_FIELD.search(name) or f["autocomplete"] == "one-time-code"):
+            fields[name] = creds["totp"]
+        elif user_field is None and (kind == "email" or f["autocomplete"] in ("username", "email")
+                                     or _USER_FIELD.search(name)):
+            user_field = name
+            fields[name] = creds["username"]
+        else:
+            fields[name] = f["value"]
+    if user_field is None and creds.get("username"):
+        # No field looked like a username: use the first plain text field.
+        for f in form["inputs"]:
+            if f["type"] in ("text", "email", "tel", "") and (f["name"] not in fields or not fields[f["name"]]):
+                fields[f["name"]] = creds["username"]
+                break
+    return fields
+
+
+def sign_in_path(ident: dict | None) -> str:
+    """The saved sign-in page, as a path on the target origin. It's stored as a full URL, but
+    the scan reaches the app at its own origin, so only the path is used."""
+    try:
+        blob = json.loads(str(((ident or {}).get("secret") or {}).get("value") or "{}"))
+    except (json.JSONDecodeError, ValueError):
+        blob = {}
+    login = str(blob.get("login") or "").strip()
+    if not login:
+        return "/login"
+    parsed = urlparse(login)
+    path = (parsed.path or "/") + (f"?{parsed.query}" if parsed.query else "")
+    return path if path.startswith("/") else "/" + path
+
+
+def is_password_account(ident: dict | None) -> bool:
+    secret = (ident or {}).get("secret") or {}
+    return str(secret.get("kind") or (ident or {}).get("kind") or "").lower() == "password"
+
+
+def sign_in(t: Target, iid: str) -> dict:
+    """Sign a password test account in and keep its session on the target. Never returns or
+    logs the credentials. {ok, authenticated, status, via?, note|error}."""
+    ident = t.identities.get(iid)
+    if not is_password_account(ident):
+        return {"ok": False, "authenticated": False, "error": f"{iid!r} isn't a username-and-password test account"}
+    try:
+        blob = json.loads(str(ident["secret"].get("value") or "{}"))
+    except (json.JSONDecodeError, ValueError, AttributeError, TypeError):
+        blob = {}
+    creds = {"username": str(blob.get("username") or ""), "password": str(blob.get("password") or "")}
+
+    def failed(error: str, status=None) -> dict:
+        t.sign_in_failed[iid] = error
+        t.sessions.pop(iid, None)
+        t.session_headers.pop(iid, None)
+        return {"ok": True, "authenticated": False, "status": status, "error": error}
+
+    if not creds["username"] or not creds["password"]:
+        return failed("no username or password is saved for this test account")
+    if blob.get("totp"):
+        code = _totp_now(str(blob["totp"]))
+        if code is None:
+            return failed("the saved authenticator secret is invalid")
+        creds["totp"] = code
+    url = t.origin + sign_in_path(ident)
+    jar: dict[str, str] = {}
+    try:
+        _status, _h, page, page_url = _follow(t, url, jar)
+        before = dict(jar)
+        forms = _page_forms(page)
+        form = next((f for f in forms.forms if any(i["type"] == "password" for i in f["inputs"])), None)
+        if form is None and any(i["type"] == "password" for i in forms.loose):
+            form = {"action": "", "method": "post", "inputs": forms.loose}
+        if form is not None:
+            via = "form"
+            action = urljoin(page_url, form["action"] or page_url)
+            if _host(action) != t.base_host:
+                return failed(f"the sign-in form posts to {_host(action)}, another site (single sign-on), "
+                              "which isn't supported yet")
+            fields = _fill(form, creds)
+            if form["method"] == "get":
+                action = action.split("?", 1)[0] + "?" + urlencode(fields)
+                first = _send(t, action, jar, "GET", headers={"Referer": page_url})
+            else:
+                first = _send(t, action, jar, "POST", urlencode(fields).encode(),
+                              {"Content-Type": "application/x-www-form-urlencoded", "Referer": page_url})
+        else:
+            # No sign-in form on the page: treat the saved address as a sign-in API.
+            via = "api"
+            action = url
+            key = "email" if "@" in creds["username"] else "username"
+            body = {key: creds["username"], "password": creds["password"]}
+            if creds.get("totp"):
+                body["otp"] = creds["totp"]
+            first = _send(t, action, jar, "POST", json.dumps(body).encode(),
+                          {"Content-Type": "application/json", "Accept": "application/json"})
+        posted = first[0]
+        token = _token_from(first[2])
+        _status, _h, landed, landed_url = _follow(t, action, jar, first)
+        # A second step that asks only for an authenticator code.
+        if creds.get("totp") and not token and not _has_password_field(landed):
+            step = next((f for f in _page_forms(landed).forms
+                         if any(_OTP_FIELD.search(i["name"]) or i["autocomplete"] == "one-time-code"
+                                for i in f["inputs"] if i["type"] not in ("hidden", "submit", "button"))), None)
+            if step is not None:
+                step_action = urljoin(landed_url, step["action"] or landed_url)
+                if _host(step_action) == t.base_host:
+                    first = _send(t, step_action, jar, "POST", urlencode(_fill(step, creds)).encode(),
+                                  {"Content-Type": "application/x-www-form-urlencoded", "Referer": landed_url})
+                    posted = first[0]
+                    _status, _h, landed, landed_url = _follow(t, step_action, jar, first)
+    except ValueError as e:
+        return failed(str(e))
+    except Exception as e:  # noqa: BLE001 - an unreachable app or a timeout: report it, don't crash
+        return failed(f"the sign-in page couldn't be reached: {e}")
+
+    changed = {k for k, v in jar.items() if before.get(k) != v}
+    if posted >= 500 and not token:
+        return failed(f"the app answered the sign-in with a server error (HTTP {posted})", posted)
+    if posted in (400, 401, 403, 404, 405, 409, 422, 429) and not token:
+        return failed(f"the sign-in was refused (HTTP {posted}): check the username and password", posted)
+    if not token and _has_password_field(landed):
+        return failed("the sign-in page came back: the username or password is wrong, or the page needs "
+                      "an extra step such as a CAPTCHA", posted)
+    if not token and not changed:
+        return failed("the sign-in went through, but the app returned no session (no cookie and no token)", posted)
+    t.sign_in_failed.pop(iid, None)
+    t.sessions[iid] = _jar_header(jar)
+    if token:
+        t.session_headers[iid] = {"Authorization": f"Bearer {token}"}
+    else:
+        t.session_headers.pop(iid, None)
+    note = f"signed in through the sign-in {'form' if via == 'form' else 'API'}" + (" with a token" if token else "")
+    return {"ok": True, "authenticated": True, "status": posted, "via": via, "note": note}
+
+
+def identity_headers(t: Target, sid: str, *, renew: bool = False) -> tuple[dict | None, str | None]:
+    """The headers that make a request come from a test account or a `login` session. A
+    password account signs in on first use, and again when `renew` (its session expired)."""
+    ident = t.identities.get(sid)
+    if is_password_account(ident):
+        if renew or not (t.sessions.get(sid) or t.session_headers.get(sid)):
+            if sid in t.sign_in_failed and not renew:
+                return None, f"test account {sid!r} could not sign in: {t.sign_in_failed[sid]}"
+            result = sign_in(t, sid)
+            if not result.get("authenticated"):
+                return None, f"test account {sid!r} could not sign in: {result.get('error') or result.get('note')}"
+        headers = dict(t.session_headers.get(sid) or {})
+        if t.sessions.get(sid):
+            headers["Cookie"] = t.sessions[sid]
+        return headers, None
+    if sid in t.sessions:
+        return {"Cookie": t.sessions[sid]}, None  # a session established with the `login` op
+    hdr, err = t.header_for(sid)
+    if err:
+        return None, err
+    return {hdr[0]: hdr[1]}, None
+
+
+def load_shared_sessions() -> dict:
+    raw = os.environ.get("BLACKGLASS_SESSIONS_JSON")
+    if not raw:
+        return {}
+    try:
+        val = json.loads(raw)
+        return val if isinstance(val, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+def _login(t: Target, args: dict) -> dict:
+    """Establish a session (safe-active). The one POST carve-out from the GET-only
+    posture: authentication is non-destructive, so at safe-active the agent may POST
+    credentials to a login endpoint, and the adapter captures the resulting session
+    cookie under a name to reuse via http/diff (identity:<name>). Credentials come
+    from a named identity's injected secret (the agent never sees it) or an explicit
+    body. Only the primary origin host is targeted, like any credential."""
+    identity = args.get("identity") or args.get("as")
+    account = is_password_account(t.identities.get(str(identity))) if identity else False
+    if account and not isinstance(args.get("body"), dict):
+        # A configured test account: sign it in from its saved sign-in page (allowed at any
+        # tier). It's then used with http/diff/render identity:"<id>".
+        result = sign_in(t, str(identity))
+        if result.get("authenticated"):
+            # For the agent; `note` is what the dashboard shows as the account's status.
+            result["use"] = f"act as it with http identity:'{identity}'"
+        return result
+    if not account and not t.tier_at_least("safe-active"):
+        return {"ok": False, "error": "login with an explicit body requires the safe-active action tier; "
+                                      "test accounts sign in automatically -- pass identity:'<id>' to http"}
+    path = args.get("path")
+    if not isinstance(path, str) or not path.startswith("/"):
+        return {"ok": False, "error": "login needs a 'path' (the login endpoint, starting with '/')"}
+    for ex in t.excluded_paths:
+        if path.startswith(ex):
+            return {"ok": False, "error": f"path {path} is out of scope (excluded)"}
+    url = t.origin + path
+    if _host(url) != t.base_host:
+        return {"ok": False, "error": f"login only authenticates against the primary origin host ({t.base_host})"}
+    name = str(args.get("session") or (identity if account else "session")).strip() or "session"
+    headers = {"User-Agent": _BROWSER_UA}
+    extra = args.get("headers")
+    if isinstance(extra, dict):
+        for k, v in extra.items():
+            headers[str(k)] = str(v)
+    fill: dict[str, str] = {}   # secret substitutions for a password identity
+    scraped: dict[str, str] = {}
+    if identity:
+        ident = t.identities.get(str(identity))
+        secret = (ident or {}).get("secret") or {}
+        if (secret.get("kind") or (ident or {}).get("kind")) == "password":
+            # Password broker: fill username/password/TOTP server-side; the model never
+            # sees them. It supplies field NAMES (body) and placeholders; we supply values.
+            try:
+                blob = json.loads(str(secret.get("value") or "{}"))
+            except Exception:  # noqa: BLE001
+                return {"ok": False, "error": f"identity {identity!r} has a malformed password credential"}
+            fill["username"] = str(blob.get("username") or "")
+            fill["password"] = str(blob.get("password") or "")
+            if blob.get("totp"):
+                code = _totp_now(str(blob["totp"]))
+                if code is None:
+                    return {"ok": False, "error": f"identity {identity!r} has an invalid TOTP secret"}
+                fill["totp"] = fill["otp"] = code
+            # CSRF two-step (best-effort, on by default): GET the login page to capture a
+            # session cookie and any hidden CSRF token, then carry them into the POST.
+            if args.get("prefetch", True):
+                try:
+                    pre = urllib.request.Request(url, headers={"User-Agent": headers["User-Agent"]})
+                    with urllib.request.build_opener(_NoRedirect).open(pre, timeout=HTTP_TIMEOUT) as pr:
+                        pre_html = pr.read(MAX_READ).decode("utf-8", "replace")
+                        pre_cookies = pr.headers.get_all("Set-Cookie") or []
+                    if pre_cookies:
+                        headers["Cookie"] = "; ".join(c.split(";", 1)[0] for c in pre_cookies)
+                    scraped = _scrape_hidden_tokens(pre_html)
+                except Exception:  # noqa: BLE001 - prefetch is best-effort; the POST still runs
+                    scraped = {}
+        else:  # cookie/header identity: inject its credential as a header, as before
+            hdr, err = t.header_for(str(identity))
+            if err:
+                return {"ok": False, "error": err}
+            headers[hdr[0]] = hdr[1]
+    data = None
+    body = args.get("body")
+    if fill and not isinstance(body, dict):
+        # No body shape supplied: default to common field names.
+        body = {"username": fill["username"], "password": fill["password"]}
+        if "totp" in fill:
+            body["otp"] = fill["totp"]
+    if isinstance(body, dict):
+        if fill:
+            body = _fill_secret_placeholders(body, fill)
+            for _fname, _fval in scraped.items():  # own vars — must not shadow `name` (the session key)
+                body.setdefault(_fname, _fval)  # include a scraped CSRF token unless already set
+        if headers.get("Content-Type", "").lower().startswith("application/json"):
+            data = json.dumps(body).encode("utf-8")
+        else:
+            data = urlencode(body).encode("utf-8")
+            headers.setdefault("Content-Type", "application/x-www-form-urlencoded")
+    elif body is not None:
+        data = str(body).encode("utf-8")
+    method = str(args.get("method", "POST")).upper()
+    # Do not follow redirects: a login's Set-Cookie often rides the 3xx itself.
+    opener = urllib.request.build_opener(_NoRedirect).open
+    req = urllib.request.Request(url, data=data, method=method, headers=headers)
+    try:
+        with opener(req, timeout=HTTP_TIMEOUT) as resp:
+            status, resp_headers = resp.status, resp.headers
+            resp.read(MAX_READ)
+    except urllib.error.HTTPError as e:
+        status = e.code
+        resp_headers = e.headers
+    except Exception as e:  # noqa: BLE001 - surface to the agent
+        return {"ok": False, "error": f"login request failed: {e}"}
+    set_cookies = resp_headers.get_all("Set-Cookie") if resp_headers else None
+    cookie = "; ".join(c.split(";", 1)[0] for c in set_cookies) if set_cookies else ""
+    if cookie:
+        t.sessions[name] = cookie
+    return {"ok": True, "session": name, "status": status, "authenticated": bool(cookie),
+            "note": (f"session '{name}' established; reuse it with http identity:'{name}'" if cookie
+                     else "no Set-Cookie returned -- wrong credentials, or the session is token-based (read it from the response and send it via headers)")}
+
+
+MAX_PROBE_PORTS = 16         # bound the fan-out of one probe (rate-awareness, like diff)
+PROBE_READ_DEFAULT = 2048
+PROBE_READ_MAX = 8192
+PROBE_TIMEOUT_DEFAULT = 4.0
+PROBE_TIMEOUT_MAX = 10.0
+SEND_MAX_BYTES = 65536       # bound one raw-send payload (exploit tier)
+MAX_RENDER_ACTIONS = 20      # bound the browser actions driven in one render (exploit tier)
+
+
+def _bare_host(h: str) -> str:
+    """The hostname without a :port suffix (leaving IPv6 literals alone)."""
+    h = (h or "").lower()
+    if h.count(":") == 1:
+        head, _, tail = h.partition(":")
+        if tail.isdigit():
+            return head
+    return h
+
+
+def _probe_one(host: str, port: int, timeout: float, read_bytes: int) -> dict:
+    """TCP-connect to one port and read whatever banner the service volunteers on
+    connect. Sends nothing -- a pure, non-destructive banner grab."""
+    try:
+        conn = socket.create_connection((host, port), timeout=timeout)
+    except OSError as e:
+        return {"port": port, "open": False, "error": str(e)}
+    try:
+        conn.settimeout(timeout)
+        try:
+            data = conn.recv(read_bytes)
+        except (socket.timeout, OSError):
+            data = b""
+    finally:
+        try:
+            conn.close()
+        except OSError:
+            pass
+    out = {"port": port, "open": True, "bytes": len(data), "banner": _clip(data.decode("utf-8", "replace"), 2000)}
+    # A binary handshake (e.g. MySQL) has little printable text; add a hex preview.
+    if data and any(c < 9 or 13 < c < 32 for c in data):
+        out["banner_hex"] = data[:64].hex()
+    return out
+
+
+def _probe(t: Target, args: dict) -> dict:
+    """Raw service probe (safe-active): reach NON-HTTP services the web surface
+    hides. TCP-connect to a port (or a bounded list) and read the connect-banner --
+    SSH/SMTP/FTP/MySQL greet with version strings; HTTP/Redis stay silent (still
+    detected open). Scope-bound to in-scope HOSTS (any port). It CONNECTS AND READS
+    only -- it sends nothing, so it cannot change a service's state; active protocol
+    interaction (sending commands) is exploit-tier. Reports facts (open/closed,
+    banner), not a verdict; the agent reasons about the version/service."""
+    if not t.tier_at_least("safe-active"):
+        return {"ok": False, "error": "probe requires the safe-active action tier"}
+    proto = str(args.get("proto") or "tcp").lower()
+    if proto != "tcp":
+        return {"ok": False, "error": "only proto 'tcp' is supported (connect + banner read); sending protocol commands is exploit-tier"}
+    host = _bare_host(str(args.get("host") or _bare_host(t.base_host)))
+    if not host:
+        return {"ok": False, "error": "probe needs a 'host' (defaults to the origin host)"}
+    allowed_bares = {_bare_host(h) for h in t.allowed_hosts}
+    if not (host in allowed_bares or recon.in_domain_scope(host, t.root_domain)):
+        return {"ok": False, "error": (
+            f"host {host} is out of scope: probe the target host or a host under the "
+            f"verified root domain {t.root_domain}")}
+    ports = args.get("ports")
+    if ports is None:
+        p = args.get("port")
+        if p is None:
+            return {"ok": False, "error": "probe needs a 'port' (int) or 'ports' (a list of ints)"}
+        ports = [p]
+    if not isinstance(ports, list):
+        return {"ok": False, "error": "'ports' must be a list of integers"}
+    try:
+        ports = [int(x) for x in ports]
+    except (TypeError, ValueError):
+        return {"ok": False, "error": "ports must be integers"}
+    if not ports:
+        return {"ok": False, "error": "no ports given"}
+    if len(ports) > MAX_PROBE_PORTS:
+        return {"ok": False, "error": f"probe takes at most {MAX_PROBE_PORTS} ports at once"}
+    for pp in ports:
+        if not 1 <= pp <= 65535:
+            return {"ok": False, "error": f"port {pp} is out of range (1-65535)"}
+    try:
+        read_bytes = max(1, min(int(args.get("read_bytes", PROBE_READ_DEFAULT)), PROBE_READ_MAX))
+    except (TypeError, ValueError):
+        read_bytes = PROBE_READ_DEFAULT
+    try:
+        timeout = max(0.1, min(float(args.get("timeout", PROBE_TIMEOUT_DEFAULT)), PROBE_TIMEOUT_MAX))
+    except (TypeError, ValueError):
+        timeout = PROBE_TIMEOUT_DEFAULT
+    results = [_probe_one(host, pp, timeout, read_bytes) for pp in ports]
+    return {"ok": True, "host": host, "proto": "tcp",
+            "open_ports": [r["port"] for r in results if r.get("open")], "results": results}
+
+
+def _raw_send(t: Target, args: dict) -> dict:
+    """Raw service exploitation (EXPLOIT tier): TCP-connect to a NON-HTTP service,
+    SEND caller-supplied bytes, then read the reply -- the exploit-tier counterpart of
+    `probe` (which only reads the connect banner, sending nothing). This is how you
+    drive an exposed line protocol to prove impact: an unauthenticated Redis accepting
+    INFO/CONFIG, a memcached answering `stats`, an open SMTP relay. Two-key gated
+    (exploit tier AND destructiveActions) and scope-bound exactly like probe."""
+    if not t.tier_at_least("exploit"):
+        return {"ok": False, "error": (
+            f"send transmits data to a service and is an EXPLOIT-tier op; this run is '{t.action_tier}'. "
+            "Use `probe` to read a service banner non-destructively (it sends nothing).")}
+    if t.read_only:
+        return {"ok": False, "error": (
+            "send is refused: destructiveActions is not authorized. Transmitting protocol commands needs "
+            "BOTH the exploit tier AND destructiveActions enabled.")}
+    proto = str(args.get("proto") or "tcp").lower()
+    if proto != "tcp":
+        return {"ok": False, "error": "only proto 'tcp' is supported"}
+    host = _bare_host(str(args.get("host") or _bare_host(t.base_host)))
+    if not host:
+        return {"ok": False, "error": "send needs a 'host' (defaults to the origin host)"}
+    allowed_bares = {_bare_host(h) for h in t.allowed_hosts}
+    if not (host in allowed_bares or recon.in_domain_scope(host, t.root_domain)):
+        return {"ok": False, "error": (
+            f"host {host} is out of scope: send only to the target host or a host under the "
+            f"verified root domain {t.root_domain}")}
+    port = args.get("port")
+    if port is None:
+        return {"ok": False, "error": "send needs a 'port' (int)"}
+    try:
+        port = int(port)
+    except (TypeError, ValueError):
+        return {"ok": False, "error": "port must be an integer"}
+    if not 1 <= port <= 65535:
+        return {"ok": False, "error": f"port {port} is out of range (1-65535)"}
+    # Payload: binary via "hex", or text via "data" (lone \n normalized to CRLF for
+    # line protocols unless crlf:false). One of the two is required.
+    if args.get("hex") is not None:
+        try:
+            payload = bytes.fromhex(re.sub(r"\s+", "", str(args["hex"])))
+        except ValueError as e:
+            return {"ok": False, "error": f"bad hex payload: {e}"}
+    else:
+        data = args.get("data")
+        if data is None:
+            return {"ok": False, "error": "send needs 'data' (text to transmit) or 'hex' (binary bytes)"}
+        text = str(data)
+        if args.get("crlf", True):
+            text = re.sub(r"(?<!\r)\n", "\r\n", text)
+        payload = text.encode("utf-8", "replace")
+    if len(payload) > SEND_MAX_BYTES:
+        return {"ok": False, "error": f"payload too large ({len(payload)} bytes; max {SEND_MAX_BYTES})"}
+    try:
+        read_bytes = max(1, min(int(args.get("read_bytes", PROBE_READ_DEFAULT)), PROBE_READ_MAX))
+    except (TypeError, ValueError):
+        read_bytes = PROBE_READ_DEFAULT
+    try:
+        timeout = max(0.1, min(float(args.get("timeout", PROBE_TIMEOUT_DEFAULT)), PROBE_TIMEOUT_MAX))
+    except (TypeError, ValueError):
+        timeout = PROBE_TIMEOUT_DEFAULT
+    try:
+        conn = socket.create_connection((host, port), timeout=timeout)
+    except OSError as e:
+        return {"ok": False, "error": f"connect failed: {e}", "host": host, "port": port}
+    try:
+        conn.settimeout(timeout)
+        conn.sendall(payload)
+        chunks, total = [], 0
+        try:
+            while total < read_bytes:
+                b = conn.recv(min(4096, read_bytes - total))
+                if not b:
+                    break
+                chunks.append(b)
+                total += len(b)
+        except (socket.timeout, OSError):
+            pass
+    finally:
+        try:
+            conn.close()
+        except OSError:
+            pass
+    data_in = b"".join(chunks)
+    out = {"ok": True, "host": host, "port": port, "sent_bytes": len(payload),
+           "recv_bytes": len(data_in), "response": _clip(data_in.decode("utf-8", "replace"), 4000)}
+    if data_in and any(c < 9 or 13 < c < 32 for c in data_in):
+        out["response_hex"] = data_in[:128].hex()
+    return out
+
+
+def _loot_header(item: dict):
+    """Turn a stashed credential into the (header, value) to inject. The agent
+    declares the kind; the shape follows it so the common recovered-credential
+    cases just work: a cookie string, an explicit 'Name: value' header line, or
+    (the default) a bearer token."""
+    value = str(item.get("value") or "")
+    if not value:
+        return None, f"loot {item.get('id')!r} has no value to replay"
+    kind = str(item.get("kind") or "").lower()
+    if kind == "cookie":
+        return "Cookie", value
+    if ":" in value and kind in ("", "header"):
+        name, _, val = value.partition(":")
+        return name.strip(), val.strip()
+    return "Authorization", f"Bearer {value}"
+
+
+def _loot(t: Target, args: dict) -> dict:
+    """Loot store + chain graph (safe-active). Structured, cross-step memory for
+    what the assessment RECOVERS and how one finding ENABLES the next. It is the
+    third credential source beside static identities (injected, never seen) and
+    login-captured sessions -- this one for values the agent recovered itself (a
+    key in a JS bundle, a token from an IDOR, a cookie from a response). `stash`
+    stores a recovered credential/id/endpoint and returns an id to replay with
+    http/diff loot:<id>; `link` records a chain edge so the coordinator can report
+    the full kill-chain with evidence at each hop; `list` returns both. The agent
+    decides what is loot and what the edges are -- this only stores them."""
+    if not t.tier_at_least("safe-active"):
+        return {"ok": False, "error": "loot requires the safe-active action tier"}
+    action = str(args.get("action") or "").strip().lower()
+    if action == "stash":
+        value = args.get("value")
+        t._loot_seq += 1
+        lid = f"loot-{t._loot_seq}"
+        item = {"id": lid, "kind": str(args.get("kind") or "credential"),
+                "value": None if value is None else str(value),
+                "source": args.get("source"), "note": args.get("note")}
+        t.loot[lid] = item
+        return {"ok": True, "id": lid, "kind": item["kind"],
+                "hint": f"replay a recovered credential on a later request with http \"loot\":\"{lid}\"; "
+                        "record what it unlocks with loot action:'link'"}
+    if action == "link":
+        frm, to = args.get("from"), args.get("to")
+        if not frm or not to:
+            return {"ok": False, "error": "link needs 'from' and 'to' (loot/finding ids or short labels) to record a chain edge"}
+        edge = {"from": str(frm), "to": str(to), "note": args.get("note")}
+        t.edges.append(edge)
+        return {"ok": True, "edges": len(t.edges), "edge": edge}
+    if action in ("list", ""):
+        return {"ok": True, "loot": list(t.loot.values()), "edges": t.edges}
+    return {"ok": False, "error": f"unknown loot action {action!r}; use 'stash' | 'list' | 'link'"}
+
+
+def _render(t: Target, args: dict) -> dict:
+    """Headless-browser render (safe-active). Loads a page in a REAL browser so its
+    JavaScript runs, then returns the rendered DOM, console messages, and the URLs
+    the page fetched -- the surface the raw `http` body cannot show (a near-empty
+    SPA shell, a DOM-based XSS that fires only after JS, client-rendered routes).
+    LOAD-AND-OBSERVE ONLY: it navigates and reads; it does not click, submit, or
+    otherwise drive the page (that is exploit-tier). Scope- and origin-bound exactly
+    like `http`. The browser is an external service (BROWSER_RENDER_URL); the adapter
+    only posts to it, so the runner carries no browser dependency."""
+    if not t.tier_at_least("safe-active"):
+        return {"ok": False, "error": "render requires the safe-active action tier"}
+    if not BROWSER_RENDER_URL:
+        return {"ok": False, "error": "no headless browser configured (BROWSER_RENDER_URL unset); client-side rendering is unavailable on this run"}
+    path = args.get("path")
+    if not isinstance(path, str) or not path.startswith("/"):
+        return {"ok": False, "error": "render needs a 'path' starting with '/' (a DOM-XSS payload goes in the fragment, e.g. /app#<payload>)"}
+    for ex in t.excluded_paths:
+        if path.startswith(ex):
+            return {"ok": False, "error": f"path {path} is out of scope (excluded)"}
+    host_arg = args.get("host")
+    if host_arg:
+        host_arg = str(host_arg).lower()
+        if not t.host_in_scope(host_arg):
+            return {"ok": False, "error": f"host {host_arg} is out of scope (reachable: the origin and hosts under {t.root_domain})"}
+        origin = f"https://{host_arg}"
+    else:
+        origin = t.origin
+    url = origin + path
+    if not t.host_in_scope(_host(url)):
+        return {"ok": False, "error": f"request left scope; reachable: the origin and hosts under {t.root_domain}"}
+
+    # A browser carries credentials as cookies. Resolve an identity/session to a
+    # Cookie for the ORIGIN only (never a pivoted host), as http does.
+    cookie = ""
+    cred = args.get("identity") or args.get("as")
+    if cred:
+        if _host(url) != t.base_host:
+            return {"ok": False, "error": f"credentials are only sent to the primary origin host ({t.base_host}); omit identity to render {_host(url)} anonymously"}
+        sid = str(cred)
+        creds, err = identity_headers(t, sid)
+        if err:
+            return {"ok": False, "error": err}
+        cookie = creds.get("Cookie", "")
+        if not cookie:
+            return {"ok": False, "error": f"identity {sid!r} carries no cookie session; render carries cookie sessions only -- use http for it"}
+    try:
+        timeout_ms = min(max(int(args.get("timeout_ms", 8000)), 500), 20000)
+    except (TypeError, ValueError):
+        timeout_ms = 8000
+    payload = {"url": url, "wait": ("networkidle" if args.get("wait") == "networkidle" else "load"),
+               "timeout_ms": timeout_ms}
+    if cookie:
+        payload["cookie"] = cookie
+    # Browser INTERACTION (exploit tier): actions that DRIVE the page (click/fill/
+    # submit/press) rather than just load it. Loading + observing is the safe-active
+    # posture; interacting is two-key gated (exploit tier AND destructiveActions), the
+    # same line the render skill draws. Without actions, render stays load-and-observe.
+    actions = args.get("actions")
+    if actions:
+        if not t.tier_at_least("exploit"):
+            return {"ok": False, "error": (
+                "driving the page (actions: click/fill/submit) is an EXPLOIT-tier capability; at this "
+                "tier render is load-and-observe only -- navigate and read, do not interact.")}
+        if t.read_only:
+            return {"ok": False, "error": (
+                "render actions are refused: destructiveActions is not authorized. Interacting with the "
+                "page needs BOTH the exploit tier AND destructiveActions enabled.")}
+        if not isinstance(actions, list) or not all(isinstance(x, dict) for x in actions):
+            return {"ok": False, "error": "'actions' must be a list of {\"type\", \"selector\"?, \"value\"?} objects"}
+        if len(actions) > MAX_RENDER_ACTIONS:
+            return {"ok": False, "error": f"at most {MAX_RENDER_ACTIONS} actions per render"}
+        payload["actions"] = actions
+    try:
+        req = urllib.request.Request(BROWSER_RENDER_URL, data=json.dumps(payload).encode(),
+                                     method="POST", headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=HTTP_TIMEOUT) as resp:
+            body = json.loads(resp.read(MAX_READ).decode("utf-8", "replace"))
+    except Exception as e:  # noqa: BLE001 - surface to the agent
+        return {"ok": False, "error": f"render failed: {e}"}
+    if not isinstance(body, dict) or not body.get("ok"):
+        err = body.get("error") if isinstance(body, dict) else body
+        return {"ok": False, "error": f"render service reported an error: {err}"}
+    return {"ok": True, "url": url, "final_url": body.get("final_url"), "title": body.get("title"),
+            "status": body.get("status"), "console": (body.get("console") or [])[:50],
+            "requests": (body.get("requests") or [])[:100], "dom": _clip(str(body.get("dom") or ""))}
+
+
+def describe(t: Target) -> dict:
+    return {
+        "ok": True,
+        "description": (
+            f"A running web application reachable ONLY at {t.origin}. You are performing a broad "
+            "security assessment of its reachable HTTP surface: data exposure, access-control / "
+            "auth-boundary violations, secrets in JS bundles & source maps, unauthenticated APIs & "
+            "GraphQL introspection, IDOR, exposed paths (.git/.env/backups/debug/swagger), verbose "
+            "errors, and CORS / security-header misconfig. Use the `http` op to send requests; pass a "
+            "named identity to act AS that account (the adapter injects its credentials and signs "
+            "username-and-password accounts in for you, so you never see the raw secret), or omit it to probe "
+            "ANONYMOUSLY -- the anonymous surface matters "
+            "even when no identities exist. Report each demonstrated issue citing the exact request "
+            "and the response that proves it. "
+            + ("THIS IS A READ-ONLY, NON-DESTRUCTIVE assessment: GET/HEAD only -- do not create, modify, "
+               "or delete data (mutating requests are refused). "
+               if t.read_only or not t.tier_at_least("exploit") else
+               "This is an EXPLOIT-tier engagement: you MAY send mutating requests (POST/PUT/PATCH/DELETE "
+               "with a body) to PROVE real impact. Prove every change with a before/after read showing the "
+               "state actually moved, prefer the smallest reversible blast radius (write a throwaway marker "
+               "rather than destroy real data, and undo it), and never send a mutation to any host but the "
+               "primary origin. ")
+            + (f"Beyond the origin you may also enumerate and probe the VERIFIED root domain {t.root_domain} "
+               "and its subdomains: use the recon ops (dns/crt/tls/storage/registries) to discover hosts, "
+               "buckets, and public artifacts -- these hit external data sources, NOT the protected origin, so "
+               "a WAF/CDN does not block them -- then pivot `http` (with a \"host\" arg, anonymous) to any host "
+               f"under {t.root_domain}. "
+               if RECON_ENABLED else "No host other than the target origin is reachable. ")
+            + "Report each demonstrated issue with the exact request and the proving response."
+            + (" The `diff` op is available: run several requests and compare their responses to PROVE "
+               "access-control and blind-inference findings (e.g. two owners reading each other's records, "
+               "or a true/false payload pair) instead of merely asserting them." if t.tier_at_least("safe-active") else "")
+            + (" For BLIND findings, oob_mint gives a unique callback URL and oob_poll reports whether the "
+               "target fetched it out-of-band -- the proof for blind SSRF/XXE (no callback, no critical)."
+               if t.tier_at_least("safe-active") and OOB_COLLABORATOR_BASE else "")
+            + (" You may also `login` (the one permitted POST, for authentication only) to establish a "
+               "session and then act as it, to test authenticated and cross-account access-control."
+               if t.tier_at_least("safe-active") else "")
+            + (" Use the `loot` op to stash any credential/id/endpoint you RECOVER and replay it on later "
+               "requests (http \"loot\":\"<id>\"), and to record chain edges (one finding enabling the next) "
+               "so a multi-step kill-chain is reported end to end." if t.tier_at_least("safe-active") else "")
+            + (" The `probe` op reaches NON-HTTP services: TCP-connect to a port and read the banner it "
+               "volunteers (e.g. an SSH/MySQL version), to find exposed services and vulnerable versions "
+               "the web surface hides." if t.tier_at_least("safe-active") else "")
+            + (" A real headless browser is available via `render`: load a page so its JavaScript runs, then "
+               "inspect the rendered DOM / console / fetched URLs -- for DOM-based XSS and client-rendered (SPA) "
+               "surface the raw http body cannot show." if t.tier_at_least("safe-active") and BROWSER_RENDER_URL else "")
+            + (" The `send` op reaches NON-HTTP services at the exploit tier: TCP-connect and transmit protocol "
+               "bytes, then read the reply (the counterpart of probe, which only reads the banner) -- to drive an "
+               "exposed line protocol (Redis/memcached/SMTP) and prove it accepts your commands."
+               if t.tier_at_least("exploit") and not t.read_only else "")
+            + (" At the exploit tier `render` also DRIVES the page: pass \"actions\" (fill/click/submit) to prove "
+               "interaction-only bugs a mere load cannot reach (stored/DOM XSS behind a form, client-side state "
+               "changes), then read the resulting DOM."
+               if t.tier_at_least("exploit") and not t.read_only and BROWSER_RENDER_URL else "")
+            + _profile_blurb(t)
+            + _skills_blurb(t)
+        ),
+        "ops": ops_for(t),
+    }
+
+
+def _profile_blurb(t: Target) -> str:
+    """A compact, anti-anchoring headline for the preliminary profile, injected into the
+    brief when the feature is on and a profile loaded. It frames the profile as a baseline
+    of SIGNALS to confirm and go beyond -- never findings -- and points at the `profile`
+    op for the detail. Empty string when no profile (so describe() is unchanged when off)."""
+    p = getattr(t, "profile", None)
+    if not p:
+        return ""
+    tgt = p.get("target") or {}
+    fp = tgt.get("x_powered_by") or tgt.get("server") or "unknown stack"
+    n = len(p.get("signals") or [])
+    return ("\n\nPRELIMINARY PROFILE (a deterministic pre-pass already swept the rote surface "
+            "before you): treat everything in it as SIGNALS/observations to CONFIRM, never as "
+            "findings, and GO BEYOND it -- it does not cover logic, authz, or chained bugs, and a "
+            f"swept check is not a safe area. Stack: {fp}. {n} candidate signal(s) + security-posture "
+            "facts are available via the `profile` op; build on them, don't just re-run them.")
+
+
+def _skills_blurb(t: Target) -> str:
+    gate = _skill_gate(t)
+    if not skills.available(gate):
+        return ""
+    idx = skills.render_index(gate)
+    return ("\n\nDEEP PLAYBOOKS (get_skill op): detailed methodologies for specific surfaces. When "
+            "your task matches a playbook's trigger below, you MUST FIRST call get_skill with its "
+            "name and follow it before probing that surface:\n" + idx) if idx else ""
+
+
+def ops_for(t: Target) -> dict:
+    mutating = t.tier_at_least("exploit") and not t.read_only
+    ops = {
+        "http": ('{"identity"?: string, "method"?: '
+                 + ('"GET"|"HEAD"|"OPTIONS"|"POST"|"PUT"|"PATCH"|"DELETE"' if mutating else '"GET"|"HEAD"|"OPTIONS"')
+                 + ', "path": "/...", "host"?: string, "body"?: object|string, '
+                 '"headers"?: object, "grep"?: regex, "allow_redirects"?: bool} send a request. Omit identity '
+                 'for anonymous. "host" pivots to a recon-discovered host UNDER the verified root domain '
+                 f'{t.root_domain} (anonymous only; defaults to the origin). "grep" returns regex-matched snippets '
+                 'over the FULL body (use for secret mining in large JS/source-map files). "allow_redirects":false '
+                 'returns a 3xx + Location unfollowed (open-redirect / auth-flow checks).'
+                 + (' At this EXPLOIT tier you may send a MUTATING method with a "body" (a dict is sent as JSON) to '
+                    'change state and PROVE impact; confirm every change with a follow-up read, and keep the blast '
+                    'radius minimal and reversible.' if mutating else '')),
+        "list_identities": "{} list the named identities you can act as, with their roles (no secrets).",
+    }
+    if t.tier_at_least("safe-active"):
+        # Active-inference ops, unlocked above the passive tier. They do no more
+        # than http can (read-only, scope-bound) but drive it systematically.
+        ops["diff"] = ('{"requests": [ {<http args>, "label"?: string}, ... ]} run 2+ requests (each shaped '
+                       'like http args) and report how the responses differ: per-request status/bytes plus signals '
+                       '(status_varies / length_varies / content_varies / distinct_bodies). The differential oracle '
+                       'for proving access-control and blind-inference findings -- e.g. fetch the same record as two '
+                       'owners to show one reads the other’s data, or send a true/false payload pair to detect a '
+                       'boolean oracle. Returns facts, not a verdict; you interpret the signals.')
+        if OOB_COLLABORATOR_BASE:
+            ops["oob_mint"] = ('{} mint a unique out-of-band callback URL + token. Plant the URL where the '
+                               'target might fetch it (SSRF url=, webhook, open redirect, XXE entity); a '
+                               'server-side request to it is logged.')
+            ops["oob_poll"] = ('{"token": "..."} check whether a minted callback was hit. interaction:true '
+                               'proves a blind server-side request (SSRF/XXE); no hit is not proof. The rule: '
+                               'no OOB callback, no SSRF critical.')
+        ops["login"] = ('{"path": "/login", "body"?: {..}, "identity"?: string, "session"?: name, "headers"?: object} '
+                        'authenticate (the one allowed POST) and capture the session under "session" (default '
+                        '"session"); then act as it with http/diff identity:"<session>". Test accounts '
+                        '(list_identities) need none of this: pass identity:"<id>" to http/diff/render and they sign '
+                        'in automatically. Use login for credentials you RECOVERED, with an explicit body; for an '
+                        'unusual sign-in form you may give a test account a body whose field VALUES are the '
+                        'placeholders {{username}}/{{password}}/{{totp}} (the adapter fills the real values). '
+                        'authenticated:false means no cookie came back.')
+        ops["loot"] = ('{"action": "stash"|"list"|"link", ...} record and reuse what you RECOVER. '
+                       'stash {"kind","value","source"?,"note"?} stores a recovered credential/id/endpoint and '
+                       'returns an id; replay a stashed credential on a later request with http "loot":"<id>" '
+                       '(injected only for the origin, like an identity -- "kind":"cookie"|"bearer"|"header" '
+                       'picks how). link {"from","to","note"?} records a chain edge (finding A enabled B) for '
+                       'the kill-chain report. list returns the stashed loot and recorded edges.')
+        ops["probe"] = ('{"host"?: string, "port": int | "ports": [int,...], "timeout"?: sec, "read_bytes"?: n} '
+                        'TCP-connect to a NON-HTTP service and read the banner it volunteers on connect '
+                        '(SSH/SMTP/FTP/MySQL greet with versions; HTTP/Redis stay silent but are still detected '
+                        f'open). Scope-bound to the target host and hosts under the root domain {t.root_domain}, '
+                        'any port. Reports open/closed + banner per port. Connect-and-read only -- it sends '
+                        'nothing and cannot change service state (sending protocol commands is exploit-tier).')
+        if mutating:
+            ops["send"] = ('{"host"?: string, "port": int, "data"?: string, "hex"?: string, "crlf"?: bool, '
+                           '"read_bytes"?: n, "timeout"?: sec} the EXPLOIT-tier counterpart of probe: TCP-connect '
+                           'and TRANSMIT bytes to a non-HTTP service, then read the reply. Drive an exposed line '
+                           'protocol to prove impact -- e.g. send "INFO\\r\\n" to an unauthenticated Redis, or '
+                           '"stats" to memcached. Give "data" (text; a lone \\n becomes CRLF unless crlf:false) or '
+                           '"hex" (binary bytes). Scope-bound to the origin host like probe; keep commands '
+                           'reversible where you can and prove the service accepted them.')
+        if BROWSER_RENDER_URL:
+            ops["render"] = ('{"path": "/...", "identity"?: session, "host"?: string, "wait"?: "load"|"networkidle", '
+                             '"timeout_ms"?: n' + (', "actions"?: [{"type":"click"|"fill"|"press"|"submit"|"wait", '
+                             '"selector"?: css, "value"?: string}, ...]' if mutating else '') + '} load the page in a '
+                             'REAL headless browser (runs its JavaScript) and return the rendered DOM, console '
+                             'messages, and the URLs the page fetched. Use it where the raw http body is a near-empty '
+                             'SPA shell: to find DOM-based XSS (put the payload in the fragment, e.g. "/app#<payload>", '
+                             'and look for it executed in the DOM/console) and to enumerate client-rendered routes/APIs '
+                             '(the fetched URLs). Scope- and origin-bound like http.'
+                             + (' At this EXPLOIT tier you may DRIVE the page with "actions" (fill a field, click, '
+                                'submit a form) to prove interaction-only bugs -- stored/DOM XSS behind a form, a '
+                                'client-side state change -- then read the resulting DOM; keep actions minimal.'
+                                if mutating else ' Load-and-observe only -- no clicking or submitting (interacting is '
+                                'exploit-tier).'))
+    if getattr(t, "profile", None):
+        ops["profile"] = ("{} the deterministic preliminary-scan profile: fingerprint + "
+                          "security-posture FACTS + candidate SIGNALS (observations to CONFIRM, "
+                          "NOT findings). Reason about it and go BEYOND it; a swept check is not a "
+                          "safe area, and the profile never covers logic/authz/chained bugs.")
+    if RECON_ENABLED:
+        # WAF-independent EASM ops: these query fixed external data sources about the
+        # verified root domain/org, never the protected origin, so a CDN/WAF can't
+        # block them. Discover hosts here, then pivot `http` to them.
+        ops.update(recon.describe_ops(t.root_domain))
+    if skills.available(_skill_gate(t)):
+        # On-demand deep playbooks (progressive disclosure): the index is in the
+        # brief; load a full procedure with get_skill when a direction matches.
+        # Advertised whenever any tier-permitted skill exists; get_skill itself
+        # still refuses a skill above the run's tier.
+        ops.update(skills.describe_ops())
+    if "login" not in ops and any(is_password_account(i) for i in t.identities.values()):
+        ops["login"] = ('{"identity": string} sign a username-and-password test account in again. Rarely '
+                        'needed: passing identity:"<id>" to http/diff/render signs it in automatically and '
+                        'renews an expired session.')
+    return ops
+
+
+def list_identities(t: Target) -> dict:
+    out = []
+    for i in t.identities.values():
+        secret = i.get("secret") or {}
+        kind = (secret.get("kind") or i.get("kind") or "").lower()
+        entry = {
+            "id": i["id"],
+            "role": i.get("how") or "",
+            "authenticated": bool(i.get("secret")),
+            "kind": kind or None,
+            "use": f"pass identity:'{i['id']}' to http/diff/render",
+        }
+        if kind == "password":
+            # Signed in automatically on first use; the session is renewed when it expires.
+            entry["sign_in"] = "automatic"
+            entry["signed_in"] = bool(t.sessions.get(i["id"]) or t.session_headers.get(i["id"]))
+            if i["id"] in t.sign_in_failed:
+                entry["sign_in_error"] = t.sign_in_failed[i["id"]]
+        out.append(entry)
+    return {"ok": True, "identities": out}
+
+
+def handle(t: Target, req: dict) -> dict:
+    op = req.get("op")
+    args = req.get("args") or {}
+    if not isinstance(args, dict):
+        return {"ok": False, "error": "args must be an object"}
+    if op == "describe":
+        return describe(t)
+    if op == "http":
+        return _http(t, args)
+    if op == "diff":
+        return _diff(t, args)
+    if op == "oob_mint":
+        return _oob_mint(t, args)
+    if op == "oob_poll":
+        return _oob_poll(t, args)
+    if op == "login":
+        return _login(t, args)
+    if op == "loot":
+        return _loot(t, args)
+    if op == "probe":
+        return _probe(t, args)
+    if op == "send":
+        return _raw_send(t, args)
+    if op == "render":
+        return _render(t, args)
+    if op == "list_identities":
+        return list_identities(t)
+    if op == "profile":
+        if getattr(t, "profile", None):
+            return {"ok": True, "profile": t.profile}
+        return {"ok": False, "error": "no preliminary-scan profile is available on this run"}
+    if RECON_ENABLED:
+        result = recon.handle(op, args, t.root_domain)
+        if result is not None:
+            return result
+    skill_result = skills.handle(op, args, _skill_gate(t))
+    if skill_result is not None:
+        return skill_result
+    return {"ok": False, "error": f"unknown op {op!r}; ops: {', '.join(['describe'] + list(ops_for(t)))}"}
+
+
+def load_secrets() -> list[dict]:
+    raw = os.environ.get("BLACKGLASS_SECRETS_JSON")
+    if not raw:
+        return []
+    try:
+        val = json.loads(raw)
+        return val if isinstance(val, list) else []
+    except json.JSONDecodeError:
+        return []
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--spec", required=True, help="path to the RunSpec input-spec.json")
+    a = ap.parse_args()
+    spec = json.loads(Path(a.spec).read_text())
+    target = Target(spec, load_secrets())
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+            if not isinstance(req, dict):
+                raise ValueError("request must be a JSON object")
+        except (json.JSONDecodeError, ValueError) as e:
+            sys.stdout.write(json.dumps({"ok": False, "error": f"bad request: {e}"}) + "\n")
+            sys.stdout.flush()
+            continue
+        try:
+            resp = handle(target, req)
+            out = json.dumps(resp)
+        except Exception as e:  # noqa: BLE001 - never let one op crash the env process
+            out = json.dumps({"ok": False, "error": f"env error handling op {req.get('op')!r}: {e}"})
+        sys.stdout.write(out + "\n")
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())