shadowcat 2.0.0__py3-none-any.whl

backend/tools/http_tool.py

@@ -0,0 +1,351 @@
+"""HTTP request tool — the Enterprise-mode workhorse.
+
+This is the *only* way the agent touches the network in Enterprise mode, and it
+enforces two of the engine's hard guarantees:
+
+  1. The agent NEVER sees or handles raw credentials. To act as a user the
+     agent sets ``identity`` (e.g. ``"userA"``, ``"userB"``, ``"anon"``); the
+     system looks up that identity's secret headers/cookies and injects them.
+     Any credential header the model tries to set itself is stripped. Injected
+     credentials are never echoed back in the result.
+
+  2. The agent NEVER holds raw evidence. The full request/response exchange —
+     including the injected credentials — is written to the :class:`EvidenceStore`
+     server-side; the model gets back only a ``request_id`` and a compact,
+     credential-free summary. It must refer to the exchange by ``request_id``.
+
+The tool itself is deliberately mechanical: it does what it is told and records
+what happened. Scope enforcement (which host/range is authorized) is applied at
+the orchestrator's shared execution boundary via ``SafetyPolicy`` — not here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from backend.verification.evidence_store import EvidenceStore
+
+# Credential-bearing headers the model is forbidden from setting. Credentials
+# are injected by the system per identity; if the model supplies any of these
+# they are dropped before the request is built.
+_CREDENTIAL_HEADERS = frozenset({"authorization", "cookie", "proxy-authorization"})
+
+# Response headers worth surfacing to the model. Deliberately excludes
+# ``set-cookie`` — a server-issued session token is a credential the model must
+# not handle. The full header set (set-cookie included) lives in evidence.
+_SUMMARY_RESPONSE_HEADERS = frozenset(
+    {
+        "content-type",
+        "content-length",
+        "location",
+        "www-authenticate",
+        "content-disposition",
+        "server",
+        "x-powered-by",
+    }
+)
+
+# Browser-like default headers. Makes the scanner look like a real browser and
+# bypasses User-Agent / Accept-header-based WAF blocklists. The model's supplied
+# headers and identity headers always override these defaults.
+_BROWSER_DEFAULTS: dict[str, str] = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/124.0.0.0 Safari/537.36"
+    ),
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+    "Accept-Encoding": "gzip, deflate, br",
+}
+
+# The model reasons over a bounded body preview; the full body is in evidence.
+# Kept deliberately tight: this preview is re-sent in the conversation history on
+# every subsequent turn, so on a non-cached model its size is paid O(turns²) over
+# a long ReAct loop. ~900 chars still surfaces error signatures, reflected input,
+# JSON shape, and the head of any data dump — enough to form a hypothesis and cite
+# the request_id; the canonical full body lives in the evidence store.
+_SUMMARY_BODY_MAX = 900
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+@dataclass
+class Identity:
+    """A seeded actor. ``headers`` and ``cookies`` are secrets the model never sees."""
+
+    name: str
+    headers: dict[str, str] = field(default_factory=dict)
+    cookies: dict[str, str] = field(default_factory=dict)
+
+
+class IdentityStore:
+    """Maps an identity name to its secret session material.
+
+    Seeded out-of-band by the run configuration. ``anon`` (no credentials)
+    always exists so the agent can gather unauthenticated negative controls.
+    """
+
+    def __init__(self, identities: list[Identity] | None = None) -> None:
+        self._identities: dict[str, Identity] = {}
+        self.register(Identity("anon"))
+        for identity in identities or []:
+            self.register(identity)
+
+    def register(self, identity: Identity) -> None:
+        self._identities[identity.name] = identity
+
+    def resolve(self, name: str) -> Identity | None:
+        return self._identities.get(name)
+
+    def names(self) -> list[str]:
+        return sorted(self._identities)
+
+
+class HttpRequestTool:
+    """Send an HTTP request as a seeded identity and capture it as evidence."""
+
+    name = "http_request"
+
+    def __init__(
+        self,
+        evidence_store: EvidenceStore,
+        identities: IdentityStore,
+        *,
+        client: httpx.AsyncClient | None = None,
+        default_timeout: float = _DEFAULT_TIMEOUT,
+        default_follow_redirects: bool = False,
+        rate_limit_ms: int = 0,
+    ) -> None:
+        self._evidence = evidence_store
+        self._identities = identities
+        self._client = client
+        self._owns_client = client is None
+        self._default_timeout = default_timeout
+        self._default_follow_redirects = default_follow_redirects
+        self._rate_limit_ms = rate_limit_ms
+
+    # ------------------------------------------------------------------
+    # Tool advertisement
+    # ------------------------------------------------------------------
+
+    def schema(self) -> dict[str, Any]:
+        """OpenAI-style function schema advertised to the model.
+
+        Note there is no header parameter for credentials: the model picks an
+        ``identity`` and the system injects the session. ``rationale`` is
+        required so every action carries its (non-evidentiary) reasoning.
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Send a single HTTP request to the authorized target through a "
+                    "managed session and record the full exchange as evidence. To "
+                    "act as a user, set `identity` (e.g. 'userA', 'userB', 'anon'); "
+                    "the system injects that identity's session — you never handle "
+                    "credentials. Returns a `request_id` plus a compact summary; "
+                    "refer to the exchange ONLY by its request_id."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "rationale": {
+                            "type": "string",
+                            "description": "Concise, factual reason for this request "
+                            "(hypothesis / step). Shown to operators; NOT evidence.",
+                        },
+                        "method": {
+                            "type": "string",
+                            "enum": ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+                        },
+                        "url": {"type": "string", "description": "Absolute URL within scope."},
+                        "identity": {
+                            "type": "string",
+                            "description": "Seeded identity whose session to use "
+                            "(e.g. 'userA', 'userB', 'anon'). Defaults to 'anon'.",
+                        },
+                        "headers": {
+                            "type": "object",
+                            "additionalProperties": {"type": "string"},
+                            "description": "Extra non-credential request headers. "
+                            "Authorization/Cookie are managed by `identity` and "
+                            "will be ignored if set here.",
+                        },
+                        "body": {
+                            "type": "string",
+                            "description": "Raw request body (for POST/PUT/PATCH).",
+                        },
+                    },
+                    "required": ["rationale", "method", "url", "identity"],
+                },
+            },
+        }
+
+    # ------------------------------------------------------------------
+    # Execution
+    # ------------------------------------------------------------------
+
+    def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            # verify=False mirrors the existing pentest HTTP runtime: targets in
+            # an engagement frequently use self-signed certs.
+            self._client = httpx.AsyncClient(verify=False, timeout=self._default_timeout)
+            self._owns_client = True
+        return self._client
+
+    async def run(self, **kwargs: Any) -> dict[str, Any]:
+        """Execute one request and return ONLY a request_id + credential-free summary."""
+        method = str(kwargs.get("method") or "GET").upper()
+        url = kwargs.get("url") or ""
+        identity_name = kwargs.get("identity") or "anon"
+        body = kwargs.get("body")
+        # Redirects are NOT auto-followed at the model's request: a 3xx Location
+        # can point outside the authorized scope, and the scope guard only checks
+        # the initial URL — auto-following would be an SSRF bypass (e.g. a target
+        # 302 -> http://169.254.169.254/...). The Location is surfaced in the
+        # summary; to pursue it the agent issues an explicit follow-up request,
+        # which IS scope-checked at the orchestrator boundary.
+        follow_redirects = self._default_follow_redirects
+        llm_headers: dict[str, str] = dict(kwargs.get("headers") or {})
+
+        if not url:
+            return {"error": "missing_parameter", "detail": "url is required"}
+
+        # Politeness delay with ±20% jitter — reduces synchronized bursts
+        # across concurrent workers and looks more like organic traffic to WAFs.
+        if self._rate_limit_ms > 0:
+            jitter = random.uniform(0.8, 1.2)
+            await asyncio.sleep(self._rate_limit_ms / 1000 * jitter)
+
+        identity = self._identities.resolve(identity_name)
+        if identity is None:
+            # Never reveal credentials; just say which identities exist.
+            return {
+                "error": "unknown_identity",
+                "identity": identity_name,
+                "known_identities": self._identities.names(),
+            }
+
+        # Strip any credential headers the model tried to set, then build the
+        # final header set: browser defaults (lowest priority) → model-supplied
+        # non-credential headers → identity's secret headers (highest priority,
+        # so the managed session can never be overridden).
+        safe_headers = {
+            k: v for k, v in llm_headers.items() if k.lower() not in _CREDENTIAL_HEADERS
+        }
+        sent_headers = {**_BROWSER_DEFAULTS, **safe_headers, **identity.headers}
+        # Inject the identity's cookies as an explicit Cookie header rather than
+        # via the per-request ``cookies=`` kwarg (deprecated, and ambiguous about
+        # jar persistence). Building the header keeps each request's session
+        # deterministic — one identity's cookies can't bleed into another's call.
+        # TODO: for production, give each identity its own AsyncClient so the
+        # response cookie jar is isolated per identity too.
+        if identity.cookies:
+            sent_headers["Cookie"] = "; ".join(f"{k}={v}" for k, v in identity.cookies.items())
+
+        # Server-side request record (includes injected credentials — never
+        # returned to the model, only persisted as evidence).
+        request_record: dict[str, Any] = {
+            "method": method,
+            "url": url,
+            "identity": identity_name,
+            "headers": sent_headers,
+            "cookies": dict(identity.cookies),
+            "body": body,
+            "follow_redirects": follow_redirects,
+        }
+
+        client = self._ensure_client()
+        t0 = time.perf_counter()
+        try:
+            resp = await client.request(
+                method,
+                url,
+                headers=sent_headers,
+                content=body.encode() if isinstance(body, str) else body,
+                follow_redirects=follow_redirects,
+            )
+        except httpx.RequestError as exc:
+            # A transport failure is still evidence (DNS, timeout, refused).
+            elapsed_ms = int((time.perf_counter() - t0) * 1000)
+            response_record = {
+                "error": exc.__class__.__name__,
+                "detail": str(exc),
+                "elapsed_ms": elapsed_ms,
+            }
+            request_id = self._evidence.put(request_record, response_record)
+            return {
+                "request_id": request_id,
+                "identity": identity_name,
+                "request": {"method": method, "url": url},
+                "error": exc.__class__.__name__,
+                "detail": str(exc),
+                "elapsed_ms": elapsed_ms,
+            }
+
+        elapsed_ms = int((time.perf_counter() - t0) * 1000)
+        body_text = resp.text
+        full_len = len(resp.content)
+
+        # Full response record (server-side evidence — every header, full body).
+        response_record = {
+            "status": resp.status_code,
+            "headers": dict(resp.headers),
+            "body": body_text,
+            "body_length": full_len,
+            "elapsed_ms": elapsed_ms,
+            "redirect_chain": [str(r.url) for r in resp.history] or None,
+        }
+        request_id = self._evidence.put(request_record, response_record)
+
+        return self._summary(
+            request_id, method, url, identity_name, resp, body_text, full_len, elapsed_ms
+        )
+
+    def _summary(
+        self,
+        request_id: str,
+        method: str,
+        url: str,
+        identity_name: str,
+        resp: httpx.Response,
+        body_text: str,
+        full_len: int,
+        elapsed_ms: int,
+    ) -> dict[str, Any]:
+        """Compact, credential-free view for the model.
+
+        Echoes only ``method`` + ``url`` from the request (never the injected
+        headers/cookies) and a bounded body preview. The model reasons over
+        this; the canonical evidence is in the store under ``request_id``.
+        """
+        preview = body_text[:_SUMMARY_BODY_MAX]
+        summary_headers = {
+            k: v for k, v in resp.headers.items() if k.lower() in _SUMMARY_RESPONSE_HEADERS
+        }
+        return {
+            "request_id": request_id,
+            "identity": identity_name,
+            "request": {"method": method, "url": url},
+            "status": resp.status_code,
+            "response_headers": summary_headers,
+            "body_length": full_len,
+            "body_preview": preview,
+            "body_truncated": full_len > len(preview.encode()),
+            "redirected": bool(resp.history),
+            "elapsed_ms": elapsed_ms,
+        }
+
+    async def aclose(self) -> None:
+        """Close the HTTP client if this tool created it."""
+        if self._client is not None and self._owns_client:
+            await self._client.aclose()
+            self._client = None

backend/tools/nuclei_tool.py

@@ -0,0 +1,20 @@
+"""Nuclei template-scan tool.
+
+Skeleton only.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class NucleiTool:
+    """Run nuclei templates against an in-scope target."""
+
+    name = "nuclei"
+
+    def schema(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def run(self, **kwargs: Any) -> Any:
+        raise NotImplementedError

backend/tools/report_tool.py

@@ -0,0 +1,145 @@
+"""``report_finding`` tool — the only way the agent records a candidate finding.
+
+Two hard guarantees, enforced here rather than trusted to the prompt:
+
+  1. **Strict shape.** The submission is validated against :class:`FindingReport`
+     (``extra="forbid"``, no verdict fields). The agent cannot add fields, and
+     it cannot declare a finding "confirmed"/"vulnerable" — that vocabulary
+     simply does not exist in the schema.
+
+  2. **Grounded evidence.** Every ``request_id`` the finding cites must refer to
+     a real exchange in the :class:`EvidenceStore`. If any cited id is unknown,
+     the report is rejected and the agent is told to make the request first.
+     This makes fabricated or hallucinated evidence impossible to report.
+
+The tool records a *candidate* (status ``pending_verification``). It never
+renders a verdict — the deterministic oracle does that downstream.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError
+
+from backend.schemas.api import FindingReport
+from backend.verification.evidence_store import EvidenceStore
+
+
+class ReportFindingTool:
+    """Validate, ground, and record a candidate finding."""
+
+    name = "report_finding"
+
+    def __init__(self, evidence_store: EvidenceStore) -> None:
+        self._evidence = evidence_store
+        self._findings: list[tuple[str, FindingReport]] = []
+        self._counter = 0
+
+    def schema(self) -> dict[str, Any]:
+        """OpenAI-style function schema mirroring :class:`FindingReport`.
+
+        The advertised schema guides the model; :class:`FindingReport` enforces
+        it strictly on the way in. Note the absence of any verdict field.
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": (
+                    "Report a CANDIDATE access-control finding for deterministic "
+                    "verification. You do NOT decide whether it is vulnerable — a "
+                    "separate oracle renders the verdict. Every request_id you cite "
+                    "MUST come from an http_request you actually made."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "title": {
+                            "type": "string",
+                            "description": "Short title, e.g. 'IDOR on GET /api/orders/{id}'.",
+                        },
+                        "hypothesis": {
+                            "type": "string",
+                            "description": "The specific access-control hypothesis tested.",
+                        },
+                        "vuln_class": {
+                            "type": "object",
+                            "properties": {
+                                "cwe": {"type": "string", "description": "e.g. 'CWE-639'."},
+                                "owasp": {"type": "string", "description": "e.g. 'A01:2021'."},
+                            },
+                            "required": ["cwe"],
+                        },
+                        "evidence": {
+                            "type": "object",
+                            "properties": {
+                                "baseline": {
+                                    "type": "string",
+                                    "description": "request_id: identity A reading A's OWN object.",
+                                },
+                                "cross_access": {
+                                    "type": "string",
+                                    "description": "request_id: identity A requesting B's object.",
+                                },
+                                "controls": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                    "description": "request_ids of negative controls.",
+                                },
+                            },
+                            "required": ["baseline", "cross_access"],
+                        },
+                        "rationale": {
+                            "type": "string",
+                            "description": "Concise factual reasoning. NOT a verdict.",
+                        },
+                    },
+                    "required": ["title", "hypothesis", "vuln_class", "evidence"],
+                },
+            },
+        }
+
+    async def run(self, **kwargs: Any) -> dict[str, Any]:
+        """Validate the submission, verify its citations, and record a candidate."""
+        # 1. Strict shape — reject invented fields and any verdict vocabulary.
+        try:
+            report = FindingReport.model_validate(kwargs)
+        except ValidationError as exc:
+            return {
+                "error": "invalid_finding",
+                "detail": exc.errors(include_url=False, include_context=False),
+                "note": "Fix the fields and resubmit. You cannot add fields or declare a verdict.",
+            }
+
+        # 2. Grounding — every cited request_id must be real evidence.
+        cited = report.cited_request_ids()
+        missing = [rid for rid in cited if not self._evidence.has(rid)]
+        if missing:
+            return {
+                "error": "unknown_request_id",
+                "missing": missing,
+                "note": (
+                    "Each request_id must come from an http_request you actually made. "
+                    "Make the request first, then cite the request_id it returned."
+                ),
+            }
+
+        # 3. Record as a candidate — pending verification, NOT a verdict.
+        self._counter += 1
+        finding_id = f"f{self._counter}"
+        self._findings.append((finding_id, report))
+        return {
+            "finding_id": finding_id,
+            "status": "pending_verification",
+            "cited_request_ids": cited,
+            "note": (
+                "Recorded as a candidate. A deterministic oracle will render the "
+                "verdict — you have not confirmed anything."
+            ),
+        }
+
+    @property
+    def findings(self) -> list[tuple[str, FindingReport]]:
+        """Recorded candidate findings, in submission order."""
+        return list(self._findings)

backend/tools/shell_tools.py

@@ -0,0 +1,23 @@
+"""Raw shell tool(s) for CTF mode.
+
+Capability-isolated to CTF: this tool is never registered in Enterprise mode,
+so the LLM never sees it and the executor can never dispatch it there.
+
+Skeleton only.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ShellTool:
+    """Execute an arbitrary shell command (CTF mode only)."""
+
+    name = "shell"
+
+    def schema(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def run(self, **kwargs: Any) -> Any:
+        raise NotImplementedError

backend/verification/__init__.py

@@ -0,0 +1 @@
+"""Deterministic verification: evidence storage and the IDOR oracle (the judge)."""

backend/verification/evidence_store.py

@@ -0,0 +1,125 @@
+"""Append-only store of raw request/response pairs, keyed by ``request_id``.
+
+This is the single source of truth for what actually happened on the wire. The
+agent never holds raw evidence: every ``http_request`` exchange is recorded here
+in full and the agent gets back only a ``request_id`` plus a compact summary.
+The agent then refers to evidence ONLY by ``request_id`` — when reporting a
+finding, when reasoning — so it is structurally incapable of inventing or
+paraphrasing request/response content.
+
+Consumers of the *full* exchange are server-side, never the LLM:
+  * the deterministic IDOR oracle, which compares exchanges to render a verdict;
+  * the ``GET /api/scans/{id}/evidence/{req_id}`` endpoint, which renders the
+    raw request/response side by side for a human operator.
+
+Because the stored request includes the credentials the system injected for an
+identity, the store is a server-side artifact and is never serialized back to
+the model.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from backend.db.repository import ScanRepository
+
+
+@dataclass(frozen=True)
+class HttpExchange:
+    """One fully-recorded HTTP request/response, addressable by ``request_id``."""
+
+    request_id: str
+    request: dict[str, Any]
+    response: dict[str, Any]
+    ts: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+    def as_dict(self) -> dict[str, Any]:
+        """Full server-side view (request + response). Not for the LLM."""
+        return {
+            "request_id": self.request_id,
+            "ts": self.ts,
+            "request": self.request,
+            "response": self.response,
+        }
+
+
+class EvidenceStore:
+    """Per-scan store of HTTP exchanges, addressable by ``request_id``.
+
+    IDs are sequential and human-readable (``r1``, ``r2``, …) so they read
+    cleanly in findings and the Task Tree. The store is append-only — an
+    exchange, once recorded, is never mutated.
+    """
+
+    def __init__(self, scan_id: str, repo: ScanRepository | None = None) -> None:
+        self.scan_id = scan_id
+        self._exchanges: dict[str, HttpExchange] = {}
+        self._counter = 0
+        # Durable backing store (optional). When set, ``put`` records each
+        # exchange in a write-behind buffer that ``flush`` drains to the DB.
+        self._repo = repo
+        self._unflushed: list[HttpExchange] = []
+
+    def put(self, request: dict[str, Any], response: dict[str, Any]) -> str:
+        """Persist a full exchange and return its freshly minted ``request_id``.
+
+        Runs synchronously with no ``await`` inside, so it is atomic with
+        respect to the event loop even when tool calls fan out concurrently —
+        no two exchanges can collide on an ID. When a repository is configured
+        the exchange is also queued for write-behind persistence (drained by
+        :meth:`flush`); the in-memory cache stays the authoritative, synchronous
+        view that grounding (:meth:`has`) and the oracle (:meth:`get`) read from.
+        """
+        self._counter += 1
+        request_id = f"r{self._counter}"
+        exchange = HttpExchange(
+            request_id=request_id,
+            request=request,
+            response=response,
+        )
+        self._exchanges[request_id] = exchange
+        if self._repo is not None:
+            self._unflushed.append(exchange)
+        return request_id
+
+    def get(self, request_id: str) -> dict[str, Any] | None:
+        """Fetch the full stored exchange by ``request_id``; ``None`` if unknown.
+
+        Reads the in-memory cache only — synchronous and authoritative for the
+        life of the run. For a cross-process read (e.g. the evidence endpoint
+        after a restart) use :meth:`aget`, which falls back to the database.
+        """
+        exchange = self._exchanges.get(request_id)
+        return exchange.as_dict() if exchange is not None else None
+
+    async def aget(self, request_id: str) -> dict[str, Any] | None:
+        """Async fetch: the in-memory cache first, then the database if configured."""
+        cached = self.get(request_id)
+        if cached is not None or self._repo is None:
+            return cached
+        return await self._repo.get_exchange(self.scan_id, request_id)
+
+    def has(self, request_id: str) -> bool:
+        """Whether ``request_id`` refers to a real, recorded exchange.
+
+        The grounding check: ``report_finding`` uses this to reject any finding
+        that cites a ``request_id`` the agent did not actually produce.
+        """
+        return request_id in self._exchanges
+
+    async def flush(self) -> None:
+        """Drain buffered exchanges to the database (no-op without a repository).
+
+        Swaps the buffer out before awaiting so concurrent :meth:`put` calls
+        accumulate into the next batch rather than racing this one.
+        """
+        if self._repo is None or not self._unflushed:
+            return
+        batch, self._unflushed = self._unflushed, []
+        await self._repo.add_exchanges(self.scan_id, batch)
+
+    def __len__(self) -> int:
+        return len(self._exchanges)