shadowcat 2.0.0__py3-none-any.whl

backend/schemas/api.py

@@ -0,0 +1,423 @@
+"""Shared request / response / event models for the Enterprise API.
+
+These Pydantic models are the single source of truth for the wire contract:
+FastAPI generates ``/openapi.json`` from them so the frontend can codegen a
+fully typed TS client with zero hand-syncing.
+
+The run envelope (``scan_id``, ``mode``, ``status``, timing, ``summary``) is
+identical across modes; mode-specific shapes live inside ``findings`` / ``extra``
+so the frontend branches on ``mode`` once, never on field types.
+
+Skeleton only — fields sketch the contract from ``ENTERPRISE_ARCH.md``; refine
+as the orchestrator and modes are implemented.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ScanMode(str, Enum):
+    """Operating mode requested for a scan. Resolved to an ``AgentMode`` via the registry."""
+
+    CTF = "ctf"
+    ENTERPRISE = "enterprise"
+    GENERAL = "general"
+
+
+class RunStatus(str, Enum):
+    """Lifecycle status shared across modes (mirrors the ``run.status`` SSE event)."""
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    VERIFYING = "verifying"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+
+
+class IdentityConfig(BaseModel):
+    """Credentials for one seeded identity (userA / userB / custom).
+
+    The agent only ever names an identity (e.g. ``"userA"``); the server injects
+    these credentials server-side. The model never sees or handles secrets.
+
+    Credential priority (first that yields cookies wins):
+      1. ``cookie`` / ``cookies`` — paste a raw session string directly.
+      2. ``username`` + ``password`` — server POSTs to ``login_url`` (or
+         auto-discovers common login paths) and extracts ``Set-Cookie``.
+    """
+
+    name: str = Field(..., description="Identity label used in http_request calls (e.g. 'userA').")
+    cookie: str | None = Field(
+        None,
+        description="Raw Cookie header value (e.g. 'session=abc123; user_id=1'). "
+        "Parsed into individual cookies and merged with the `cookies` dict.",
+    )
+    headers: dict[str, str] = Field(
+        default_factory=dict,
+        description="Extra request headers injected for this identity (e.g. Authorization).",
+    )
+    cookies: dict[str, str] = Field(
+        default_factory=dict,
+        description="Explicit cookie key/value pairs (supplement or override `cookie`).",
+    )
+    username: str | None = Field(
+        None,
+        description="Login username / e-mail for auto-login. Requires `password`.",
+    )
+    password: str | None = Field(
+        None,
+        description="Login password for auto-login. Requires `username`.",
+    )
+    login_url: str | None = Field(
+        None,
+        description="Explicit login endpoint URL. When omitted the server probes "
+        "common paths (/login, /api/login, /auth/login, …) under the scan target.",
+    )
+    csrf_field: str | None = Field(
+        None,
+        description="Name of the CSRF token hidden input on the login form (e.g. '_token', "
+        "'csrfmiddlewaretoken'). When set the server fetches the login page first, extracts "
+        "the token, and includes it in the login POST. When omitted, common names are tried.",
+    )
+
+
+class ScanConfig(BaseModel):
+    """Per-run tuning knobs — controls how deep and how fast the scan runs.
+
+    Sensible defaults allow small targets to work without any configuration;
+    increase ``max_turns`` / ``max_requests`` / ``max_crawl_pages`` for large
+    sites such as universities or enterprise portals.
+    """
+
+    crawl_first: bool = Field(
+        True,
+        description="Run the automated spider before the AI agent to build an attack "
+        "surface map. The agent receives a structured summary and focuses on testing.",
+    )
+    max_turns: int = Field(
+        0,
+        ge=0,
+        le=400,
+        description="Max LLM ReAct turns. 0 = unlimited: runs until the agent finishes "
+        "on its own, the target goes unreachable, or you press Stop (Stop still "
+        "verifies and produces a report). Set 1-400 to cap it.",
+    )
+    max_requests: int = Field(
+        300,
+        ge=10,
+        le=2000,
+        description="Total HTTP request budget shared between the spider and the agent.",
+    )
+    rate_limit_ms: int = Field(
+        300,
+        ge=0,
+        le=10000,
+        description="Milliseconds to wait between outgoing HTTP requests (politeness delay). "
+        "Increase to avoid triggering WAFs on production sites.",
+    )
+    max_depth: int = Field(
+        3,
+        ge=1,
+        le=6,
+        description="How many link-hops deep the spider follows from the start URL.",
+    )
+    max_crawl_pages: int = Field(
+        150,
+        ge=10,
+        le=1000,
+        description="Maximum pages the spider visits before handing off to the agent.",
+    )
+    spider_workers: int = Field(
+        10,
+        ge=1,
+        le=50,
+        description="Number of concurrent spider worker coroutines. More workers "
+        "improve throughput on slow targets without changing the per-second rate.",
+    )
+    enable_js_analysis: bool = Field(
+        True,
+        description="After the HTML crawl, fetch linked .js files and scan for API "
+        "endpoint paths not visible in HTML (fetch/axios calls, route definitions).",
+    )
+    render_js: bool = Field(
+        False,
+        description="Render the target's root page in a real headless browser "
+        "(Playwright) so JavaScript-rendered SPAs are crawled properly and the API "
+        "endpoints they call are captured. Requires Playwright + a browser to be "
+        "installed; falls back to the plain HTTP crawl if unavailable.",
+    )
+    enable_subdomains: bool = Field(
+        False,
+        description="Enumerate and HTTP-confirm subdomains of the target domain before "
+        "crawling, then add live subdomains to the authorized scope.",
+    )
+    enable_waf_detection: bool = Field(
+        True,
+        description="Send a known-bad probe to fingerprint any WAF before the main "
+        "scan so the agent knows what evasion variants may be needed.",
+    )
+    prune_every_n_turns: int = Field(
+        8,
+        ge=0,
+        le=200,
+        description="Compress old conversation turns every N LLM completions to keep "
+        "context bounded. On a non-cached model the whole history is re-billed every "
+        "turn, so frequent pruning is the main cost lever. Set 0 to disable pruning.",
+    )
+    prune_keep_recent: int = Field(
+        5,
+        ge=2,
+        le=40,
+        description="How many of the most recent agent turns to keep verbatim when "
+        "pruning. Older turns collapse into a one-line summary (with reported finding "
+        "ids preserved). Lower = cheaper, higher = more short-term context.",
+    )
+    max_completion_tokens: int | None = Field(
+        1536,
+        ge=256,
+        le=8192,
+        description="Cap on output tokens per LLM turn. A single tool call + rationale "
+        "is small, so this bounds runaway generations without hurting normal steps. "
+        "Set null to leave the provider default uncapped.",
+    )
+
+
+class ScanRequest(BaseModel):
+    """Body of ``POST /api/scans``."""
+
+    mode: ScanMode
+    target: str = Field(..., min_length=1, description="Authorized target URL or host.")
+    instruction: str | None = Field(None, description="Optional operator hint / focus.")
+    scope: list[str] = Field(
+        default_factory=list,
+        description="Authorized host / CIDR / URL allowlist for this run.",
+    )
+    model: str | None = Field(
+        None,
+        description="LLM model slug to drive this run (e.g. 'anthropic/claude-sonnet-4-5'). "
+        "Falls back to the server's MODEL env var, then a built-in default.",
+    )
+    openrouter_api_key: str | None = Field(
+        None,
+        description="Caller-supplied API key. Works with OpenRouter (sk-or-...) and PSU Blue "
+        "(sk-user-...). When set, overrides the server's OPENROUTER_API_KEY for this run only.",
+    )
+    api_base_url: str | None = Field(
+        None,
+        description="Custom OpenAI-compatible base URL for this run "
+        "(e.g. 'https://ai.psu.blue/v1'). Auto-detected from key prefix when omitted.",
+    )
+    identities: list[IdentityConfig] = Field(
+        default_factory=list,
+        description="Seeded user sessions for IDOR testing. Provide at least 'userA' and "
+        "'userB' with their session cookies so the agent can test cross-user access.",
+    )
+    victim_markers: list[str] = Field(
+        default_factory=list,
+        description="Strings that uniquely identify the victim identity's private data "
+        "(e.g. userB's email, account number, order id). The IDOR oracle confirms a finding "
+        "only when one of these appears in a cross-access response and is absent from the "
+        "attacker's own baseline — without them a successful cross-access stays 'inconclusive'. "
+        "Required for deterministic IDOR/BOLA verification.",
+    )
+    config: ScanConfig = Field(
+        default_factory=ScanConfig,
+        description="Scan depth and rate-limiting configuration.",
+    )
+
+
+class ScanCreatedResponse(BaseModel):
+    """``202`` response from ``POST /api/scans``."""
+
+    scan_id: str
+    status: RunStatus = RunStatus.QUEUED
+
+
+class RunResult(BaseModel):
+    """Mode-polymorphic final result inside a common envelope.
+
+    Returned by ``AgentMode.finalize``. Keep the envelope identical across
+    modes; let each mode populate ``findings`` / ``extra`` with its own shape.
+    """
+
+    scan_id: str
+    mode: ScanMode
+    status: RunStatus
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    summary: dict[str, Any] = Field(default_factory=dict)
+    findings: list[dict[str, Any]] = Field(default_factory=list)
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class ScanStatusResponse(BaseModel):
+    """``GET /api/scans/{id}`` — status plus a poll-able result snapshot."""
+
+    scan_id: str
+    mode: ScanMode
+    status: RunStatus
+    result: RunResult | None = None
+
+
+class SSEEvent(BaseModel):
+    """One Server-Sent Event envelope, discriminated by ``type``.
+
+    Same shape for both modes so the frontend has exactly one parser and can
+    build the Task Tree directly from ``node_id`` / ``parent_id``. The
+    monotonic ``id`` lets the browser resume via ``Last-Event-ID``.
+    """
+
+    id: int
+    scan_id: str
+    ts: datetime
+    type: str
+    node_id: str | None = None
+    parent_id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Finding report (agent-supplied) — strictly an evidence bundle, never a verdict
+# ---------------------------------------------------------------------------
+#
+# This is the schema the agent MUST use to report a candidate finding. It is
+# deliberately constrained:
+#   * ``extra="forbid"`` rejects any field the agent invents.
+#   * There is NO status / severity / "confirmed" / "is_vulnerable" field — the
+#     agent is structurally incapable of declaring a verdict. The deterministic
+#     oracle assigns those downstream.
+#   * Evidence is carried only as ``request_id`` strings; the agent cannot paste
+#     request/response content here, so it cannot fabricate evidence.
+
+
+class VulnClass(BaseModel):
+    """Vulnerability classification for a candidate finding."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    cwe: str = Field(..., description="CWE identifier, e.g. 'CWE-639'.")
+    owasp: str | None = Field(None, description="OWASP category, e.g. 'A01:2021'.")
+
+
+class FindingEvidence(BaseModel):
+    """Evidence for a finding — ``request_id`` references only, never content."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    baseline: str = Field(
+        ..., description="request_id: identity A reading A's OWN object (legitimate behavior)."
+    )
+    cross_access: str = Field(
+        ..., description="request_id: identity A requesting identity B's object."
+    )
+    controls: list[str] = Field(
+        default_factory=list,
+        description="request_ids of negative controls (e.g. unauthenticated, non-existent reference).",
+    )
+
+
+class FindingReport(BaseModel):
+    """Agent-supplied candidate finding. An evidence bundle, not a verdict."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    title: str = Field(..., description="Short finding title, e.g. 'IDOR on GET /api/orders/{id}'.")
+    hypothesis: str = Field(..., description="The specific access-control hypothesis tested.")
+    vuln_class: VulnClass
+    evidence: FindingEvidence
+    rationale: str | None = Field(
+        None, description="Concise factual reasoning. Shown to operators; NOT a verdict."
+    )
+
+    def cited_request_ids(self) -> list[str]:
+        """Every ``request_id`` referenced, in (baseline, cross_access, controls) order."""
+        return [self.evidence.baseline, self.evidence.cross_access, *self.evidence.controls]
+
+
+# ---------------------------------------------------------------------------
+# General DAST finding (OWASP Top 10 — any vulnerability class)
+# ---------------------------------------------------------------------------
+
+
+class GeneralFindingEvidence(BaseModel):
+    """Evidence for a general-purpose DAST finding.
+
+    Simpler than IDOR evidence — a single probe request is the minimum; an
+    optional baseline makes the comparison machine-verifiable.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    probe: str = Field(
+        ...,
+        description="request_id of the test request that elicited the anomalous response.",
+    )
+    baseline: str | None = Field(
+        None,
+        description="request_id of a benign baseline request (same endpoint, safe input).",
+    )
+    controls: list[str] = Field(
+        default_factory=list,
+        description="request_ids of additional variant requests (e.g. different payloads).",
+    )
+
+
+class GeneralFindingReport(BaseModel):
+    """Agent-supplied candidate finding for General DAST mode."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    title: str = Field(..., description="Short title, e.g. 'Reflected XSS on GET /search?q='.")
+    hypothesis: str = Field(..., description="The specific vulnerability hypothesis tested.")
+    vuln_class: VulnClass
+    evidence: GeneralFindingEvidence
+    payload: str | None = Field(
+        None,
+        description="The test payload used (e.g. the SQLi string or XSS vector).",
+    )
+    rationale: str | None = Field(None, description="Concise factual reasoning. NOT a verdict.")
+
+    def cited_request_ids(self) -> list[str]:
+        ids = [self.evidence.probe]
+        if self.evidence.baseline:
+            ids.append(self.evidence.baseline)
+        ids.extend(self.evidence.controls)
+        return ids
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator run state (in-memory, not part of the wire contract)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RunState:
+    """Mutable per-run state threaded through the orchestrator loop.
+
+    Passed to the ``AgentMode`` hooks (``is_complete`` / ``on_tool_result`` /
+    ``finalize``). Held in memory for the life of a run.
+    """
+
+    scan_id: str
+    mode: ScanMode
+    target: str
+    status: RunStatus = RunStatus.QUEUED
+    turn: int = 0
+    actions_used: int = 0
+    transcript: list[dict[str, Any]] = field(default_factory=list)
+    scratch: dict[str, Any] = field(default_factory=dict)
+    # Cooperative stop flag: set by the cancel endpoint; the orchestrator checks it
+    # at each turn boundary and stops *gracefully* (verify + report), not hard-killed.
+    cancelled: bool = False

backend/tools/__init__.py

@@ -0,0 +1,62 @@
+"""Tool framework: per-mode tool registries and individual tool implementations.
+
+A ``ToolRegistry`` is built per mode (see ``AgentMode.tool_registry``) so a
+mode's capabilities are fixed *by construction*: a tool absent from the
+registry is absent both from what the LLM sees and from what the executor can
+dispatch. The dangerous mode's capabilities physically cannot leak into the
+strict mode.
+
+Skeleton only.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Tool(Protocol):
+    """A single dispatchable capability exposed to the LLM."""
+
+    name: str
+
+    def schema(self) -> dict[str, Any]:
+        """OpenAI-style function schema advertised to the model."""
+        ...
+
+    async def run(self, **kwargs: Any) -> Any:
+        """Execute the tool and return its result."""
+        ...
+
+
+class ToolRegistry:
+    """The set of tools that EXIST for a given mode.
+
+    Tools are added per mode; lookups for an unregistered name return ``None``
+    so the executor can refuse to dispatch a capability the mode never granted.
+    """
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        """Add a tool to the registry (last registration of a name wins)."""
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        """Look up a tool by name; ``None`` if not registered for this mode."""
+        return self._tools.get(name)
+
+    def schemas(self) -> list[dict[str, Any]]:
+        """Return the function schemas for every registered tool."""
+        return [tool.schema() for tool in self._tools.values()]
+
+    def names(self) -> list[str]:
+        """Names of all registered tools."""
+        return list(self._tools)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._tools
+
+    def __len__(self) -> int:
+        return len(self._tools)