ShakerScan Functionality Reference — DAST + AI + Connected Devices

Status: Canonical exhaustive functional reference for the whole product. This is the "what can ShakerScan actually do" map across DAST, attack-surface management, AI security, evidence, governance, automation, UI, CLI, API, and agent-facing surfaces. The human-readable sections explain the behavior; the generated inventory in §17 enumerates every current public route, registry command, CLI flag, wrapper command, Make target, release gate, runtime configuration key, UI page, skill, agent, adapter, scanner module, and durable table. Reconciled: 2026-08-29 Audience: users, operators, AI coding agents, and engineers who need one place that explains the product's functionality end to end.

Source of truth. This document describes shipped behavior, grounded in the code at the time of writing. As with the sibling architecture docs, the code, DB schema, and tests remain authoritative — file paths drift, so this reference prefers named files/symbols over line numbers. Verify before depending on a detail. For implementation-depth and roadmap material, follow the cross-links in §18.

---

Table of contents

1. What ShakerScan is
2. System architecture
3. DAST — one Scan, policy, and budgets
4. DAST — immutable action plans and continuation
5. DAST — discovery and reconnaissance
6. DAST — vulnerability checks
7. DAST — authentication support
8. DAST — scoring, attack chains, coverage, and reports
9. Scaling DAST: parallel scanning and Continuous ASM
10. Attack-surface management: discovery, CT monitoring, schedules

• Connected-device posture

11. AI red teaming
12. Cross-cutting: findings, exposure graph, workers, queue
13. REST API reference (by area)
14. Configuration and integrated tools
15. Safety model
16. UI, CLI, skills, and agent surfaces
17. Generated capability inventory
18. Where to go deeper

---

1. What ShakerScan is

ShakerScan is an open-source security scanner for web applications, APIs, AI systems, and network-connected devices. It runs locally as a Docker stack with a web UI, a REST API, a PostgreSQL database, a Redis job queue, and a scalable pool of scan workers. It is designed to be driven either directly (CLI / UI / REST) or through an AI coding agent (Claude Code, Codex, OpenCode) using plain-English requests.

It covers two complementary pillars:

• DAST — actively probes a running website or API for real vulnerabilities the way an attacker would: injection (XSS, SQLi), broken access control (BOLA/IDOR), exposed secrets and files, misconfigured TLS/headers/CORS, SSRF/LFI/RCE, weak auth/session/JWT, and more — then grades what it finds and correlates findings into attack chains.
• AI red teaming — attacks AI features the same way: chatbots, RAG endpoints, agents, and MCP tools are probed for prompt injection, sensitive-data disclosure, unsafe tool use, approval bypass, and RAG/MCP boundary failures. A separate Model Intake capability statically vets model artifacts before deployment.

The runtime boundary is simpler than the feature catalog: Scan is the one deterministic DAST workflow; Hunt is the one adaptive AI-directed investigation workflow. Hunt may choose among server-advertised semantic capabilities, but ShakerScan—not model output—owns target scope, approval, credential custody, budgets, placement, execution, evidence, recovery, and proof promotion.

Both pillars write into one shared findings store and one exposure graph, so DAST and AI results are triaged, filtered, and reported through the same workflow.

Connected-device posture is a deliberately separate plane: it inventories network services, applies device service policies, checks discovered SSH, and hands HTTP(S) interfaces on any port to bounded device-owned Web/API children without creating Web targets or changing ordinary DAST metrics.

---

2. System architecture

UI / CLI / agent
        │  one Scan request: target + policy + budget + opaque references
        ▼
API admission
        │  freezes target, scope, approvals, inputs, execution-plan digest
        ▼
immutable root action plan ── bounded continuation amendment after discovery
        │
        ▼
shared action orchestrator
        ├── local worker backend
        ├── outbound-only broker backend
        └── partitioned parallel child authority
        │
        ▼
semantic capability adapters ── receipts / observations / budget settlement
        │
        ▼
offline deterministic finalizer ── findings / coverage / grade reliability

Components

• API server (api/api.py): admits the canonical request, freezes target and input authority, compiles and persists the content-addressed action plan, and serves the full product REST surface. Its six background asyncio loops maintain schedules, ASM, retention, and Model Intake workflows.
  • stale_scan_checker — fails scans stuck beyond MAX_SCAN_DURATION.
  • schedule_runner — fires due recurring schedules and recomputes their next run.
  • asm_dispatcher — for each ASM-enabled target, picks one safe next action (recon vs. test batch vs. wait) within freshness/rate/window budgets.
  • research_autopilot_runner — advances bounded compatibility research episodes.
  • scan_artifact_retention_runner — enforces configured scan-artifact retention.
  • model_intake_automatic_review_runner — advances durable automatic Model Intake reviews.
• Canonical Scan runtime (api/scan/): the action compiler, allocator, durable action store, shared orchestrator, local/broker execution backends, continuation amendment, private manifest transport, and pure finalizer. This is the V2 execution authority.
• Workers (api/worker.py, api/broker_worker.py): lease only admitted jobs/actions by leasing Redis Stream messages. They resolve secrets late, revalidate scope and approval immediately before privileged work, reserve typed budget, execute one registered capability adapter, and settle a content-safe receipt.
• Compatibility scanner (scanner/scanner.py, scanner/scanner_tools/): supplies migrated detector implementations behind registered adapters. Its historical phase waterfall and mode flags are not V2 orchestration authority and must not be used to add a new Scan engine.
• PostgreSQL (db/init.sql): durable storage for scans, findings, targets, schedules, AI targets/credentials/principals, scan campaigns, the ASM endpoint inventory, attempt ledger, and discovery runs. Findings are de-duplicated at the DB with UNIQUE(target_id, fingerprint), which makes concurrent writes from many workers against one target race-safe.
• Redis: delivery and coordination, never durable Scan authority. Canonical plan, action, receipt, observation, and budget state remains in PostgreSQL/object storage and survives redelivery.
• Session manager (api/session_manager.py): headless Playwright browser sessions for interactive AI security testing.
• Gungnir worker (api/gungnir_worker.py): Certificate Transparency log monitor.

Worker scaling. Placement changes where an immutable action executes, not what it means. Local, broker, and parallel execution consume the same action schema, capability registry, budget ledger, proof contracts, and finalizer. A broker worker does not receive PostgreSQL or Redis credentials.

---

3. DAST — one Scan, policy, and budgets

V2 has exactly one deterministic engine: scan. Three independent inputs shape a run:

• Policy grants permission: passive-only versus active testing, state-changing HTTP, network or subdomain discovery, and family include/exclude constraints.
• Budget profile selects hard ceilings: fast (30 minutes), balanced (60 minutes), thorough (180 minutes), or opt-in deep (360 minutes).
• Opaque references select exact-target credential profiles and request-collection selections.

Cookie profiles admitted for web.browser_crawl seed the primary cookie jar in a fresh, owner-only Chromium profile. Bearer profiles may additionally declare a nonsecret browser_storage_key; when present, the worker seeds that localStorage key at the exact target origin. Bootstrap navigation is fulfilled locally, the token never enters process arguments or public receipts, and the ephemeral profile is deleted after Katana exits. Other bearer profiles continue to authenticate HTTP-aware capabilities without guessing an application-specific browser storage convention.

The typed budget covers duration, HTTP requests, state-changing requests, endpoints, hosts, browser actions, TCP attempts, tool wall time, and workers. A custom value may only lower the selected profile. max_state_changing_requests=0 is an explicit deny ceiling. Every action reserves its multi-dimensional hold before execution and reconciles consumed, released, or uncertain authority afterward; unused profile capacity remains visibly unallocated.

The server-generated GET /scan/contracts manifest is the public vocabulary for the UI and CLI. The complete REST shape is frozen in docs/generated/public-openapi-manifest.json: every OpenAPI operation ID, request/response schema digest, and component-schema digest is checked on API changes. scripts/generate_public_api_contract.py also generates the six release-critical UI client surfaces (Scan, Hunt, credentials, request collections, evidence, and Model Intake) from that same live OpenAPI document. GET /hunts/contract remains the runtime Hunt policy/budget discovery endpoint. The canonical action compiler currently implements recon, nuclei, xss, sqli, and bola. An unsupported registry family is rejected rather than accepted as a successful no-op. Explicit XSS, SQLi, or BOLA inclusion requires active permission; BOLA additionally requires two distinct credential profiles whose scopes allow authz.verify.

Historical compatibility records

Historical quick, standard, deep, full, aggressive, and smart names remain readable for audit and report continuity, but no public route or client accepts them as new authority. New UI, API, CLI, skills, schedules, and agent flows use scan with explicit policy and budget fields.

---

4. DAST — immutable action plans and continuation

Admission creates a content-addressed scan-action-plan/v1 DAG. Every action records its semantic capability, dependencies, target/input digests, requested budget, placement requirements, output schema, and required/supporting classification. Capability arguments cannot carry secret fields, shell commands, or planner-supplied argv.

The root plan closes deterministic prerequisites in this order:

1. restore or establish any selected authenticated session;
2. run bounded HTTP/DNS/TLS baseline actions;
3. probe, crawl, discover content, and optionally discover subdomains/services;
4. consume exact saved request selections through safe or confirmed-active replay capabilities;
5. run the reviewed passive template pack;
6. run policy-enabled deterministic XSS, SQLi, template, and cross-principal verifiers;
7. finalize from persisted receipts and observations without target network authority.

Discovery can reveal work that did not exist at admission. V2 handles that through one bounded two-phase continuation, not a mutable plan: the root plan pre-commits a continuation allocation ceiling; discovery produces content-addressed endpoint/candidate/request/template manifests; the server appends a second digest-bound plan revision whose parent digest, family set, target, credentials, collections, approvals, and total budget cannot expand. Duplicate authority and more than 512 total actions fail closed.

The durable amendment chain stores root, parent, continuation, discovery-result, allocation, work- manifest, and revision digests. Completed terminal actions are reused after a restart. Cancellation remains distinct and never launches continuation. Safe partial receipts remain available after a timeout, while uncertain reservations stay visibly uncertain rather than being silently released.

---

5. DAST — discovery and reconnaissance

The canonical graph uses web.probe, web.crawl, web.content_discover, subdomains.discover, ports.discover, and service.fingerprint. All targets receive the bounded web probe; the recon family controls additional crawl/content breadth, and network/subdomain actions require their separate policy permission. Output is normalized into one content-addressed endpoint manifest.

Declared surface (web.spec_ingest): besides the conventional OpenAPI/Swagger locations, the same action fetches robots.txt and llms.txt from the origin root. Disallow/Allow rules and Markdown links become discovered_route observations, origin-bound (another host's link is never declared), with a wildcard rule contributing only the literal prefix it is anchored on and Disallow: / contributing nothing. A path written in prose keeps its query string, since observed parameters are what candidate generation is built from. A 200 that is really the application's single-page shell is refused as hint_document_is_markup rather than mined. A declared path is a claim, never a confirmed route: it enters the endpoint manifest and is probed like any other.

Measured absence (web.content_discover): a few high-entropy paths that cannot exist are probed inside the same exact request reservation as the wordlist, and their responses are the negative control. A hit whose response is an origin-only rewrite identical to at least two independent control paths (same status, request path/query/fragment carried through unchanged — a fact the producer records before redaction, because redaction is not injective) is dropped and counted as indistinguishable_from_absent:N. Anything the observations cannot distinguish from a real route is retained as uncertain and reported as unverified_redirect_observations:N; a run that carried no control claims nothing.

Family presets and the active default. policy.preset selects the family set: passive (recon, reviewed passive templates), standard_active (passive plus XSS and SQLi) or custom (exactly include_families). A submission that allows active testing and names no preset resolves to standard_active; one that does not allow it resolves to passive. Permission and work are reported separately: the scan page's Testing tile names the active families that ran, or warns that active testing was allowed but no active family was selected.

DNS posture over a limited forwarder. dns.inspect asks the system resolver first. When a query times out and the bound host is a public name on public addresses, the same query is retried over DNS-over-HTTPS (SHAKERSCAN_DNS_DOH_RESOLVERS, comma-separated https:// URLs, default Cloudflare then Google; empty disables it). Set it in the project .env: both Compose files pass it to the api, worker and agent-tool-worker services, and the broker worker file passes it to its worker, with ${VAR-default} so an explicit blank stays blank. Internal names and private addresses never leave the network as a resolver query. An HTTP 200 is not a DNS answer: a reply is accepted only when its rcode is NOERROR or NXDOMAIN, it is not truncated, its question is the one asked, and every answer record belongs to the asked name or a CNAME target the answer introduces; anything else is refused, the next resolver is tried, and a run with no valid answer keeps the primary timeout as its stated reason. Recovered answers are marked resolver: doh in the record metadata and listed under doh_fallback_queries.

Discovery reservations scale with the profile. Each producer keeps the share of the ceiling it always took, but the cap that share may reach now rises with the granted budget instead of staying at the constant sized for the smallest profile; the tools derive their rate from the reservation, so a larger grant buys a longer look, not a louder one. dns.inspect bounds its fan-out and asks the six conventional DKIM selectors alongside SPF/DMARC/CAA/DNSKEY/MTA-STS/TLS-RPT; absence from those names is not proof that the domain does not sign mail.

The compatibility scanner_tools/ directory supplies migrated adapter implementations and richer observations behind those registered capabilities. Its module inventory does not imply that every module is enabled in every V2 plan. Available discovery/recon implementations include:

DNS & domain (discovery.py, dns_enhanced.py): A/AAAA/MX/TXT/NS/SOA/CAA records; SPF/DMARC/DKIM enumeration; DNSSEC validation; zone-transfer attempts; virtual-host enumeration.

TLS & certificates (tls_scanner.py): certificate subject/issuer/expiry/key-size/chain analysis, OCSP stapling, cipher-suite enumeration, and TLS version detection — using sslyze, testssl.sh, and nmap in combination.

HTTP fingerprinting: server/framework detection, security-header analysis (HSTS, CSP, X-Frame- Options, Referrer-Policy, COOP/CORP), and HTTP/2 / HTTP/3 detection. CSP is graded with parsed directives.

Web application discovery:

• Crawling — katana recursive crawl + httpx probing (discovery.py).
• Browser crawl — headless Playwright multi-page crawl with HAR/network capture and API capture (http_scanner.py); SPA hash-route crawling (hash_routes.py).
• Content discovery — ffuf directory/file fuzzing against bundled and custom wordlists.
• Parameter discovery — query/body parameter inference from observed requests.
• JS bundle analysis — extracts hidden endpoints and routes from JavaScript bundles.
• API discovery — HTTP OPTIONS method discovery, gRPC reflection (grpc_discovery.py), GraphQL introspection (graphql_schema_recovery.py), and JSON link following (HATEOAS/pagination).
• HAR-driven prioritization — har_discovery.py / active_prioritization.py rank real network-captured endpoints first.

WAF detection: response-pattern fingerprinting of the protecting WAF product.

Port scanning (nmap.py): bounded TCP discovery and service/version detection under explicit network permission and the plan's TCP/host/tool-time ceilings.

Subdomain enumeration: subfinder (passive), gungnir (CT logs), and crt.sh — see §10.

Historical and source-assisted discovery: OpenAPI/Swagger schema discovery uses prioritized, bounded concurrent probes under one global deadline and reuses the result across later active phases; explicit schemas can also be exercised through Schemathesis. Wayback/Common Crawl/GAU helpers; JavaScript and browser-derived API bases; GraphQL schema recovery; gRPC reflection; virtual hosts; custom endpoint files, focus/avoid rules, and agent-produced custom_endpoints/custom_list seeds.

Threat intelligence and external posture: opt-in DNSBL, AbuseIPDB, and VirusTotal IP reputation; typosquatting/lookalike-domain generation and resolution; WHOIS/RDAP domain age, expiry, and registrar analysis; certificate-transparency posture; ASN/hosting-provider/prefix/geography/multihoming facts; HIBP/GitHub-oriented breach and credential-leak checks; and third-party resource/vendor risk.

Known endpoints and exact request selections can seed discovery. Saved selections remain target- bound and content-addressed; discovery_only contributes safe route facts without replay, safe_reads executes only read-only requests, and confirmed_active requires active permission, state-changing authority, and a target-bound approval receipt (the target's standing authorization suffices). Arbitrary custom payload/shell input is not part of the canonical Scan contract.

---

6. DAST — vulnerability checks

V2 exposes only checks backed by a registered semantic capability and deterministic output/evidence contract. The current Scan family surface is intentionally narrower than the historical module inventory: passive reviewed templates plus bounded XSS, SQLi, and two-principal BOLA verification. The modules below describe available detector implementations; modules not yet wired to the canonical action graph remain compatibility/internal implementation surface, not advertised Scan coverage.

Active injection

• XSS (active_checks.py, dom_xss_analyzer.py): dalfox-based reflected/DOM detection plus a custom context-aware tester that detects reflection context (in-script, in-attribute, event handler, HTML body, SVG/CSS/JSON/URL-path) and selects context-specific payloads; canary-based reflection detection; browser proof for GET reflections and HTML-like POST/PUT/PATCH response reflections; hash-route testing; static DOM-XSS source-to-sink analysis over JS files.
• SQLi (active_checks.py): sqlmap-based testing that is DBMS-aware (SQLite, MySQL, PostgreSQL, MSSQL, Oracle) — it fingerprints the database, then chooses DBMS-specific payloads, techniques, and optional data-extraction chaining. Supports out-of-band (blind) detection via oob_callback_url.
• Other injection (injection_extra_checks.py): SSI/ESI, prototype pollution, CSV/formula injection, RFI, LDAP/XPath, XXE/XML injection.
• SSRF / command injection / LFI / RCE: high-risk active families, gated behind non-safe exploit level and parameterized endpoints; SSRF includes cloud-metadata and Gopher payloads (gopher_payloads.py) with OOB verification.

Access control

• BOLA / IDOR (bola_comparison.py, access_control_checks.py): dual-user testing — replay the same endpoint as user1 and user2, normalize volatile fields (timestamps, UUIDs, nonces), and detect cross-user data exposure with concrete PII matching. Also forced browsing, path traversal, privilege escalation, and unauthenticated-access detection.

Web/API security (Phase 4)

File upload bypass (file_upload_tests.py), open redirect, host-header injection, CSRF token presence/reuse/randomness, HTTP method tampering, content-type switching, WebSocket auth/message handling (websocket_security.py), OAuth flow tests (oauth_tests.py), and a generic API-security sweep (api_security.py).

Auth/session/crypto

Weak JWT/session/cookie checks, default-credential testing (credential_check.py), and deserialization tests (deserialization_tests.py) for Java/PHP/Python unsafe deserialization.

Business logic

Race conditions (race_condition_tests.py) for checkout, coupons, balance, votes, and invitations.

Template & infra

Nuclei template checks (nuclei.py, with a reviewed read-only passive pack); infrastructure-leak checks (infrastructure_checks.py) for CI/CD config, cloud buckets, registries, k8s/terraform artifacts; critical checks (critical_checks.py) for default creds, directory listing, and verbose error pages.

Opt-in infrastructure families also cover SSH authentication posture; SMTP STARTTLS, banner, MX, and safe open-relay checks; VPN, RDP/VNC, IoT, industrial-protocol, and database-service exposure; IP/ASN and domain intelligence; third-party vendor resources; webhook signature bypass; package-manager and backup artifacts; container registries; and Kubernetes/Terraform/cloud-storage exposure.

OpenAPI schemas can be supplied explicitly or discovered and exercised through Schemathesis. The scanner records schema/test errors as evidence rather than treating process exit as proof.

Canonical focus uses policy.include_families / policy.exclude_families. The old xss: true and sqli: true booleans are compatibility inputs only and must not be added to new UI, CLI, skill, or agent flows.

For OWASP-mapped coverage and intentional gaps, see docs/owasp-coverage-matrix.md.

---

7. DAST — authentication support

Authentication is resolved late per action. A credential is never globally inherited by every tool: the worker checks the profile's semantic allowed_capabilities against the exact capability about to execute. Static identities can authorize capabilities such as http.request, web.crawl, templates.scan, collections.replay_safe, xss.verify, sqli.verify, or authz.verify. Interactive form/OAuth profiles must additionally authorize auth.session.establish.

Canonical Scan submission accepts up to two credential_profile_ids, bound to the exact Web/API target. Profiles hold authorization headers, bearer tokens, API-key headers, cookies, custom headers, basic auth, or interactive form/OAuth material in the encrypted credential store. Basic auth, form login, and OAuth password profiles accept a username-only or secret-only identity when that unusual target flow requires it; at least one half is required. This is storage flexibility, not proof that a specific Scan capability can authenticate with incomplete material. primary/service selects the first identity and secondary selects the differential identity. scan.execute is accepted only as a deprecated compatibility scope; new profiles should use semantic capability names. Query-parameter credentials are not admitted to generic Scan because they require exact request-replay authority.

Hunt can inspect public client artifacts without expanding every HTTP response placed in planner context. artifact.inspect returns one target-pinned, redacted byte window (16 KiB maximum), while javascript.analyze privately reads at most 256 KiB and returns bounded routes, source-map references, client sink signals, Supabase origins, and decoded JWT metadata. JWT values never leave the worker result boundary; a classified token remains evidence, not credential authority.

Worker-private form login, OAuth client credentials, and OAuth password exchange are supported. Sealed private session checkpoints preserve resumability without plaintext secrets at rest. Session headers remain bound to the profile version, action, target, and lane; a resumed action must re-establish or restore that exact authority.

Principal and benchmark receipts distinguish configured contexts, redacted identity fingerprints, server-observed accepted authentication, family attempts, and cross-principal proof. A verified BOLA result requires distinct accepted principals and a deterministic owner/attacker differential; two configured or merely attempted lanes do not satisfy that gate.

Workflow: create a test account → create an encrypted, target-bound profile → obtain a target-bound approval receipt → pass only credential_profile_ids to /scans. The worker validates the frozen profile version and resolves it in memory immediately before execution. Reusable secret values do not enter canonical Scan requests, rows, logs, or queue payloads. Legacy Scan write paths are removed; historical compatibility records remain readable for audit purposes.

---

8. DAST — scoring, attack chains, coverage, and reports

scan.finalize is an offline-only semantic capability. It receives zero target-traffic authority and builds the report exclusively from the immutable plan/revision chain, terminal action results, receipts, observation manifests, and private-work manifest references. The same evidence bundle can be rebuilt with scanner.sh report-rebuild while outbound sockets are disabled; mismatched plan, result, revision, or observation digests fail closed. File output uses an atomic same-directory write, refuses to overwrite by default, and requires an explicit --force replacement.

Scoring & grading (api/scan/scoring.py, policy risk_and_assurance/v8): the report carries two independent axes which must not be blended. risk_score (0–100, higher is better) and risk_grade (A–F) describe the material risk observed by deterministic evidence, including only HTTP posture that was actually observed from an application response. assurance_score (0–100) and assurance_band (none, weak, limited, adequate, strong) describe completed required work, selected-family and candidate coverage, verification attempts, authenticated contexts, placement, and examination breadth. AI notes and suspected candidates cannot promote a finding to verified.

The compatibility score and grade mirror the risk axis. An unreliable grade gains *, while grade_reliable=false, coverage.grade_reliability.reasons, and assurance_gaps carry the exact qualification. risk_assessment_state=not_examined / application_observed=false is explicit when the run received an HTTP response but did not observe the application (such as a 401 challenge). In that state a numerical risk projection is not a clean bill of health. Historical reports retain their stored scoring policy; score_projection.recomputed_for_display remains false rather than silently rewriting old evidence. The scan also returns:

• risk_score, risk_grade, risk_assessment_state, and grade_reliable
• assurance_score, assurance_band, assurance_components, and assurance_gaps
• compatibility score / grade
• findings: array with severities critical / high / medium / low / info
• result: the rich object below

Finding processing: deduplication (deduplication_engine.py), false-positive validation (finding_validator.py), correlation (finding_correlator.py), and a verification ladder (verification_engine.py, verification_phase.py, proof_of_exploit.py) that produces reproducible evidence for high-severity findings.

Attack-chain analysis (attack_chains.py): correlates findings into exploitable chains with business impact. The nine implemented chain types (CHAIN_TEMPLATES) are xss_to_account_takeover, sqli_to_privilege_escalation, ssrf_to_cloud_breach, idor_to_data_breach, lfi_to_credential_theft, cors_to_data_theft, weak_jwt_to_impersonation, xxe_to_data_exfil, and deserialization_to_rce. Partial chains can be surfaced with include_partial_attack_chains: true.

Coverage tracking: /scans/{id}/actions, /capabilities, and /coverage expose the plan digest, revision/continuation digests, stage timeline, per-action placement/status/reason, observation count, required versus optional gaps, and allocated/reserved/consumed/released/uncertain/unallocated budget. Legacy detector coverage fields may remain in historical results, but they are not the V2 execution authority.

Compliance mapping (compliance_mapper.py): OWASP Top 10, CWE, PCI DSS, SOC 2, HIPAA, GDPR, CIS Controls, control evidence requirements, business impact, remediation priority, and a GRC evidence matrix. These are evidence mappings, not certification claims.

Rich result object (result.*): http.csp_evaluation, http.security_headers, tls.certificate, tls.ocsp, dns, discovery.tech.items, discovery.browser_api_endpoints, discovery.browser_crawl, discovery.waf_detection, attack_chains, canonical action execution, and — when AI is enabled — ai_correlations and ai_logs.summary.cross_finding_correlations. SARIF 2.1 output, fingerprinted baselines, known-finding suppression, and severity-count quality gates are available through the scanner CLI; the UI offers PDF export.

---

9. Scaling DAST: parallel scanning and Continuous ASM

These two subsystems share the same durable primitives (endpoint inventory, work allocator, attempt ledger). They are two views over the same facts: "run full coverage now" vs. "keep this target covered over time."

Parallel scanning

Parallelism partitions immutable action authority; it does not invoke a second orchestration engine. The parent first commits a canonical discovery/root plan, then partitions content-addressed endpoint, candidate, template, credential, and exact-request manifests into child action plans. Every child is bound to the parent execution-plan/target/plan digests and receives only its assigned request IDs and aggregate budget share. The parent aggregate reservation is authoritative, so children cannot each spend the full profile ceiling.

The same shared orchestrator executes local, broker, and parallel actions. Outbound-only broker workers receive lease-scoped sealed private inputs and have no PostgreSQL/Redis credentials. Secrets are decrypted only by the executing child after target, profile version, approval, capability, and lease validation. Redelivery reuses terminal actions; duplicate completion is fenced by lease and result digests.

Placement and partition choices remain policy data:

The parent is the user-visible Scan. Child/discovery rows are internal unless explicitly requested. Any missing, failed, cancelled, or uncertain required child makes the merged coverage incomplete and the grade unreliable. The report retains per-action backend/worker/attempt/receipt provenance and never claims that undiscovered endpoints were tested.

Current execution design: docs/dast-asm-architecture.md.

Continuous ASM

Continuous ASM keeps a persistent endpoint inventory per target (target_endpoints) and improves coverage over time within safe budgets and allowed windows (api/asm_inventory.py, the asm_dispatcher loop, and the exploit_batch worker job).

• Endpoint identity includes auth state, HTTP method, normalized path, and parameter location/shape, so the same path under anonymous/user1/user2 is tracked as distinct coverage obligations.
• The dispatcher reserves per-root-domain rate budget in Redis before queueing, claims rows with FOR UPDATE SKIP LOCKED under durable leases, and never stacks load on a target.
• Coverage derives from a normalized attempt ledger (asm_endpoint_attempts): an endpoint is only marked tested when scanner telemetry proves it was attempted/completed. Timeouts/partial results do not count unattempted endpoints as covered.
• For AI/agent workflows, prefer POST /targets/{id}/asm/improve, which chooses recon vs. test batch vs. wait from current gaps. Focused families: sqli, xss, credential-gated auth (requires a primary auth context), and gated bola (requires exploit_depth: true plus primary and second-user auth). Planned families (ssrf, lfi, rce, business_logic) are registered but rejected for ASM execution until their scanner integrations ship.
• GET /targets/{id}/asm/activity is the read-only operator summary for one target: recent hidden ASM recon/test jobs, the scheduler decision, campaign timeline events, active ASM scans, and a bounded target-scoped hypothesis situation report. The embedded hypothesis report surfaces proof leads and missing preconditions next to coverage state, but it does not queue work, create findings, or change proof state.

Current execution design: docs/dast-asm-architecture.md.

Multi-node boundary: the first owned-fleet trust foundation is implemented: durable node identity, hashed usage-bounded join tokens (single-use by default), HTTPS enrollment, authenticated heartbeat, one-time overlay connection bundles, and credential rotation/revocation. A digest-pinned worker/agent-only Compose runtime and pull-based local node-agent now apply versioned worker-count/drain desired state without an inbound listener or remote Docker API. The opt-in fleet Compose profile adds a CA-verified HTTPS listener on the private data address, preserves the real overlay socket peer with Linux host networking, and disables duplicate background controllers in that edge process. Linux host automation now implements persistent fleet init, aggregated read-only fleet preflight, tag-to-digest image resolution, automatic pre-conversion backup, bounded/revocable fleet join-token, automatic/manual peer reconciliation, automatic restricted public HTTPS for broker fleets with pinned Caddy, certificate renewal and secret-bound proxy trust, minimal public health, protected-route/rollback verification, bounded enrollment attempts, and worker-only join with HTTPS preflight and WireGuard handshake diagnostics. The installed worker image is derived automatically; --worker-image selects a custom build. Fleet is host-aware and opt-in: standalone installs hide Fleet navigation, remote capacity, and remote placement; direct macOS visits explain the Linux requirement, while uninitialized Linux visits show setup guidance. GET /health and GET /workers expose the same non-secret capability state. The enabled Fleet UI also flags WireGuard nodes awaiting their first connection. Leased delivery and fencing, central artifact transfer, placement, capacity-weighted scaling, rolling lifecycle, outbound-only HTTPS broker transport, and fleet-wide admission/request controls are implemented. Exact-node broker execution and central persistence have been exercised on two local-build VPS nodes; the remaining release-topology gate is the complete digest-pinned physical acceptance and fault matrix. Follow the operator guide; the design authority is docs/multi-node-architecture.md.

---

10. Attack-surface management: discovery, CT monitoring, schedules

Subdomain discovery (POST /discovery, process_discovery_job): enumerates subdomains for a root domain via Gungnir, Subfinder, and crt.sh, then upserts discovered hosts as targets.

Certificate Transparency monitoring (Gungnir) (api/gungnir_worker.py): a long-running worker that watches CT logs in real time, discovering new certificates for monitored domains. New subdomains are auto-added as targets (discovery_source = gungnir-monitor); if the root domain has ASM enabled, discovered surface inherits the ASM policy. Controlled via ./scanner.sh gungnir start|stop|status and /gungnir/* endpoints.

Schedules (schedule_runner, /schedules): recurring daily/weekly actions with timezone and jitter support. New schedules support normal scans and bounded asm_improve coverage waves. Legacy evidence_retention_sweep records remain readable for migration but are automatically disabled and cannot be created or resumed. Interactive deletion requires a fresh immutable preview and an exact-action, target-matching approval created through the interactive flow. Schedule listings include derived schedule_health when recent scan results show repeated failures or timeout/heartbeat failures for the same active target/type pair, and the Dashboard Action Center links operators to the affected schedule plus the latest failed scan.

Connected-device posture

Connected-device security is isolated from Web DAST targets. The /devices product surface stores TVs, cameras, printers, routers, NAS systems, conference equipment, and other network-connected assets in dedicated device, interface, and service tables. device_posture work uses its own queue, worker capacity, and build-health registry, so it cannot change ordinary Web DAST worker freshness, target counts, scan lists, ASM state, or dashboard posture.

Every profile uses Naabu for TCP discovery and Nmap only for confirmed-open TCP fingerprinting plus the declared curated UDP set. inventory scans priority/device-hint ports followed by Naabu's top 100; posture and thorough divide all 65,535 TCP ports into bounded Naabu CONNECT ranges. Connect concurrency is derived from the probe rate and timeout, each failed range receives one bounded retry, and partial open-port evidence is preserved. There is no all-port Nmap fallback. Cancellation and device-health checks run between ranges, and progress is persisted per range. Reachability prioritizes previously observed, operator-hinted, policy-defined, and credential-bound TCP ports, then applies compact common, device-class-specific, and major-TV-manufacturer port sets (Vizio, LG, Samsung, TCL, and Hisense). If that bounded check is silent, only an already all-TCP posture or thorough scan expands discovery; the same result becomes the main inventory, so the range is never scanned twice and silence alone never proves online status. Each Naabu range has an independent receipt, so partial all-port discovery cannot be reported complete. A completed TCP scope proves reachable-open-port coverage from the scanner's vantage without claiming silent ports were distinguished as closed versus filtered. UDP open|filtered/no-response results are kept as inconclusive observations and excluded from service policy and scoring until a protocol response confirms them open. Nmap service/version/CPE output, addresses, hostnames, MAC/vendor evidence, and bounded OS hints are retained. The scanner recognizes HTTP and TLS on discovered TCP ports rather than assuming 80/443, then optionally runs hidden, request-aware quick, standard, or deep Web/API children with capped origins, time, URLs, and requests. Operators can upload encrypted Postman Collection/environment, HAR 1.2, OpenAPI 3.x, or Swagger 2.0 JSON, review a redacted request inventory, and bind selected collections to a scan. Safe requests can be replayed normally; POST/PUT/PATCH/DELETE require authenticated-active safety plus explicit confirmation. Imported Postman scripts, HAR responses, and external OpenAPI references never execute, and every socket remains pinned to a discovered origin on the device. Child findings retain device/origin/request provenance and never create Web targets. Before those children, ShakerScan parses same-device SSDP/UPnP descriptors and runs a versioned, bounded application catalog for Roku, Vizio, Samsung, LG, Philips, Cast/DIAL, Panasonic, and Sony interfaces. Confirmed cleartext APIs, unauthenticated privacy-sensitive reads, software disclosure, TLS trust failures, cookie/CORS defects, and authenticated-versus-anonymous response equivalence are reported as device findings. Untrusted device TLS remains scannable, but credentials and imported secrets are withheld unless the operator grants a separate authenticated-active override.

SSH checks run on the discovered port and collect auth methods, host-key evidence, negotiated algorithms, and weak-crypto signals without credential guessing. An operator may bind one encrypted, device-scoped SSH password/private-key profile for one authentication attempt with no command execution. Discovered web origins may likewise use an encrypted authorization-header, cookie, or form-login profile. Credential values are decrypted only in the dedicated worker, never persisted in scan options/results, and never shown to the AI planner. Ordered service policies support allow, deny, review, and fail-closed required-control rules. Built-in generic, media, camera, printer, and network-appliance baselines can be copied or replaced with custom allowlists. review findings produce needs_review; deny/failed-require findings block. A complete report states TCP/UDP scope and truncation; older device findings are cleared only after complete all-TCP and complete web-origin coverage. Bluetooth/BLE and other radio protocols remain a future capability-labeled sensor extension rather than an implied Docker-worker capability. See connected-device-security.md.

Device coverage depth and action safety are independent. observe_only, safe_remote, and authenticated_active are the executable profiles. The never-implemented lab_invasive profile was removed; a request naming it is rejected with a pointer to authenticated_active. Device reports carry device-safety/v1 receipts plus a stable device-evidence/v1 node/edge/observation graph. A device-target POST /hunts run lets the current coding agent inspect device state, inspect redacted user-bound request collections, compare scans, recall prior hypotheses, query effective policy, use size-capped SHA-256-pinned offline advisory candidates and protocol playbooks, queue bounded deterministic scans, and query normalized evidence. Its context pack treats network data as untrusted, its target and safety profile are immutable, and its tool/turn/scan/daily-device/fragility budgets are server-enforced and recorded in a durable action ledger. A health circuit breaker freezes new traffic while leaving read-only evidence tools available. Its debrief persists typed, non-authoritative candidates with canonical device loci and registered verifier contracts. A server-owned candidate verifier, not model prose, owns promotion; the initial service-exposure path requires a fresh protocol observation, a persisted deny policy, a healthy safety receipt, and a satisfied Proof Contract v2 before creating a finding.

The selected device-scan view polls a structured, secret-free activity stream showing meaningful reachability, discovery, fingerprint, protocol, Web/API request, finding, and safety events instead of exposing raw command output.

For a narrow hypothesis, POST /devices/{device_id}/verify-service and the agent's verify_service_state tool queue a device_probe on the same dedicated worker. The executor resolves and pins the registered locator once, invokes rate-limited Nmap against exactly one declared TCP or UDP port, checks health before and after, and returns a typed satisfied, refuted, or inconclusive invariant. Filtered, silent, malformed, timed-out, or missing-port output is never accepted as proof that a service is absent. Probe rows remain separate from Web DAST targets, findings, scores, device inventory, and ordinary DAST metrics.

Each connected device has an immutable UUID and a mutable current locator. Operators can use POST /devices/{device_id}/locator or the device detail page's Change address action after a DHCP change; the API requires same-device confirmation, rejects changes during active device traffic or an AI investigation, and appends the transition to device_locator_history. Existing policies, credentials, findings, scans, and agent memory remain bound to the device UUID, while each scan keeps the exact locator used at submission.

Core protocol adapters send bounded exact-target unicast SSDP and mDNS discovery probes, normalize UPnP and DNS-SD metadata, refuse to follow cross-host descriptor locations, and promote UDP open|filtered state only after a valid application response.

---

11. AI red teaming

The AI side has five capabilities:

1. Hunt — the shared adaptive investigation runtime for Web, API, network, and device targets. The current coding-agent session owns strategy; the server advertises semantic capabilities and enforces every call's scope, approval, risk, typed budget, placement, credentials, evidence, and deterministic proof contract. Device Hunt is a target-kind/policy-filtered use of this runtime, not a target-specific planning engine. Historical Deep Hunt/device-agent URLs redirect to Hunt.
2. AI Gate — probe-driven runtime testing of chat, RAG, agent, MCP, and widget surfaces.
3. Model Intake — static artifact and supply-chain vetting before deployment.
4. Interactive session compatibility API — bounded browser/session testing retained for Command Arsenal and the compatibility skill; no standalone 2.0 UI.
5. AI-assisted analysis — correlation, explanation, and retest planning for DAST findings.

Design principle. AI may help judge, correlate, and explain, but verified security decisions must be backed by deterministic, cryptographic, parser-backed, protocol-backed, or replay-backed evidence. Findings carry proof quality explicitly (see AI proof and evidence states below); AI is never the sole authority for verified status or severity promotion. Operator workflows are in AI_TEST_WORKFLOWS.md, and future hardening belongs only in the maintained architecture and evaluation documents.

AI capability status quick read

These implemented components were last reconciled against code on 2026-08-29. AI Gate remains a preview product surface for 2.0.0. Model Intake is release-gated for deterministic static review, artifact and report generation, and its opt-in AMD64 Linux/KVM Firecracker tier; unsupported formats, incomplete evidence, missing required tools, and unavailable runtime qualification fail closed. The AI Gate policy/exception and deterministic-judge seams marked Planned in E2E_TEST_PLAN.md are not yet release-gated. "Partial" means the capability runs but the listed caveat applies — treat the caveat as load-bearing, not cosmetic.

AI proof and evidence states

Today a finding exposes a three-state proof level — verified (deterministic proof), suspected, or unverified (api/api.py), with proof_state exploited / likely_vulnerable at the scanner — and deterministic proof blocks any AI downgrade. The target is one taxonomy unified across DAST and AI (deterministic_verified, cryptographically_verified, claimed_present, ai_judged_likely, inconclusive, blocked, false_positive) so that claimed metadata and AI-judged results can never render as verified. Future proof-state changes belong in the proof contracts and focused architecture/decision records.

11.1 AI Gate

AI Gate tests AI application surfaces by sending crafted probes and grading the responses.

Target types (api/ai_gate_scan.py, adapters under api/ai_gate/targets/):

REST/JSON adapters use a request_template containing {{prompt}} (and optionally {{session_id}} / {{previous_response}}), extract the model's answer via a JSONPath response_path (e.g. $.answer), and support json or sse streaming modes plus a headers_template for auth.

Probe packs (api/ai_gate/probe_registry.py):

Vulnerability classes probed: prompt injection, sensitive/secret disclosure, system-prompt leakage, improper output handling, excessive agency, unbounded consumption, encoding-bypass; agent families like approval bypass, tool-result injection, secret exfiltration, cross-account/cross-tenant actions, identity/approval-token replay; MCP families like untrusted-server trust, tool-metadata change, OAuth audience confusion, PKCE downgrade; and RAG families like retrieval-ACL bypass, citation fabrication, poisoned/deleted-document recall, and canary leakage.

Profiles (smoke / trace / standard / deep) scale the probe set and the max conversation turns; environments (preview / staging / development / production) gate which probes run — production blocks probes flagged unsafe for production, and production scans require confirm_production: true.

Detection — two layers:

1. Deterministic detectors run first (api/ai_gate_scan.py): regex/keyword markers for token and secret patterns (AWS/GitHub/Slack keys, private keys, JWTs, DB connection strings), prompt-leakage markers, approval-bypass markers, metadata-injection markers, agent/tool markers, MCP/OAuth markers, and RAG markers.
2. Semantic AI judging (scanner/scanner_tools/ai_classifier.py), when an AI provider is configured: judges probe transcripts and populates ai_verdict, ai_confidence, ai_rationale, and ai_recommendations. Sensitive headers/bodies are redacted before being sent to the judge; a circuit breaker and retry/backoff protect against provider failures. A verdict policy (scanner/ai_verdict_policy.py) governs trust thresholds — high-confidence false positives can be downgraded, but never when deterministic proof of exploitation exists.

AI control-evidence baseline (api/ai_control_requirements.py): from a target's metadata_json, AI Gate builds a control-evidence pack (asset owner, risk tier, data classification; RAG ACL/ingestion/tenant-isolation controls; agent tool scopes, delegated identity, token-audience validation, approval/dry-run/transaction limits, sandboxing, audit logs, anomaly detection, kill switch; governance mappings to NIST AI RMF / ISO 27001 / OWASP LLM). With enforce_ai_control_baseline: true, missing required controls become findings. The AI Gate score and the deploy decision combine deterministic findings, AI verdicts, and control evidence.

Principals (/ai/targets/{id}/principals): multiple named identities (roles attacker/victim/ admin/service/observer) with separate credentials, enabling cross-user/cross-tenant RAG and agent tests.

Transcripts & reporting: GET /ai/scans/{id}/transcript returns probe transcripts; AI findings carry probe family/technique/OWASP refs, classifier output, and raw evidence. Post-scan AI red-team reports are available via /scans/{id}/ai-redteam-report and a CI/CD deployment-decision endpoint.

11.2 Model Intake

Model Intake (scanner/scanner_tools/model_intake.py) is a provider-neutral model admission pipeline. It resolves and completely acquires immutable subjects, creates content-addressed quarantine objects and repository manifests, runs generated static evidence, optionally invokes a separate no-egress semantic sandbox and content-free embedding/data-plane evaluation, and emits a signed, revocable decision package. It never imports publisher model code in the API or worker process. An operator-configured, digest-pinned runtime adapter can perform exact-subject load/inference and deterministic known-answer cases inside the hardened sandbox tier. A disposable microVM with independent telemetry is still required for the highest-risk custom-code approval tier.

Signature/provenance (R1, shipped 2026-06-24). Model Intake performs real detached-signature verification (Ed25519 / RSA-PSS / ECDSA via the cryptography lib) over the artifact or its digest when a public key + signature are supplied (signature_public_key/_url, signature_value/ signature_url); require_cryptographic_signature_verification makes a metadata-only claim fail. Metadata booleans such as sigstore_verified: true are treated as claims, never as cryptographic proof. Offline DSSE/in-toto subject verification is supported. A policy requiring transparency evidence fails closed unless an independently trusted transparency verifier/bundle is available.

Checks include:

• Unsafe serialization — flags pickle-like formats (.pkl, .pickle, .joblib, .pt, .pth, .ckpt, .bin, .mar) vs. safer ones (.safetensors, .onnx, .tflite, .gguf); scans for pickle opcode markers and suspicious loader markers (os.system, subprocess, eval/exec, pickle.loads, network downloaders, base64 decode).
• Archive payload analysis — recursively inspects ZIP and TAR families without extraction, enforcing entry/depth/expanded-size/ratio bounds and rejecting traversal, links, devices, collisions, nested unsafe serialization, and executables.
• Provenance & integrity — checksum (sha256) verification; signature/attestation presence; claimed signature/provenance metadata; cryptographic detached-signature verification (Ed25519/RSA-PSS/ECDSA via the cryptography lib, over the artifact or its digest); Hugging Face reference normalization.
• Generated evidence — normalized fail-closed adapters for model/pickle scanners, Python AST, secrets, malware, CycloneDX SBOM/SCA, native binaries, licenses, plus explicit tool/rules/version/coverage status.
• Packaged core adapter bundle — rebuilt worker images install hash-locked ModelScan 0.8.8, Semgrep 1.172.0, Fickling 0.1.12, Trivy 0.73.0, OSV Scanner 2.5.0, and a hash-bound offline pip-audit 2.10.1 result. The image build fails unless the deterministic functional receipt matches the safe, review, and malicious fixtures expected for the applicable adapters. GET /model-intake/scanners/readiness exposes versions, applicability, rules/database identity, and the last functional receipt.
• Advisory-data cadence — the dedicated Model Intake worker attempts a bounded Trivy database refresh at startup when registry egress is available and retains the image's baked database on failure or in offline environments. Generated static evidence and every frozen evidence manifest record trivy_db_updated_at, so operators can judge database age instead of inferring freshness from the image build date.
• Typed non-scanner providers — GET /model-intake/providers/readiness separately reports sandbox execution, embedding evaluation, embedded/OPA policy, and core report providers. OPA remains explicitly NOT_IMPLEMENTED; an installed or configured label does not imply an enforcing decision contract.
• Model/application evaluation — computes retrieval quality, vector integrity, poisoning, ACL/tenant and sensitive-data leakage, stability, capacity, graph boundaries, deletion receipts, cache context, and index/model digest compatibility without persisting source text or benchmark vectors.
• Admission lifecycle — signs the complete decision, registers it durably, enforces exact subjects at verification, and supports expiry, supersession, reassessment triggers, revocation, and audit history. The core verifier accepts only an exact signed allow; HTTP verification also requires an active matching registry record. Mutation endpoints require operator authentication, and global operations require explicit confirmation plus a change receipt. External deployment systems must integrate the verification boundary.

Saved trust anchors can be created, updated/deactivated, selected by policy, and previewed before a scan. POST /model-intake/resolve normalizes HTTP, Hugging Face, S3, GCS, Azure, OCI, and MLflow references. OCI/MLflow use an operator gateway or signed HTTPS export bound to the exact provider subject and expected digest, so provider credentials never enter scanner output. Completed scans expose a content-free evidence export and durable admission lifecycle APIs.

Model repositories and artifacts are Model Intake subjects, not web targets. They are therefore excluded from the default /targets, /targets/grouped, /domains, dashboard web-target totals, and target-dedupe surfaces. Existing internal target links remain readable for report and rescan compatibility, and Exposure continues to show them explicitly as model_artifact assets. The automatic HTML report identifies the pinned source/revision and digests, explains the controller stop reason and next action, shows a scanner coverage matrix, and lists the bounded content-free repository manifest plus per-scanner file coverage.

Result shape: model_intake.checks.*, aibom, supply_chain, summary (with the decision), and artifact. Findings are stored with tool = model_intake and filter independently through source_type=model_intake; they are excluded from source_type=dast. Sensitive URL params and metadata keys are redacted.

11.3 Interactive session compatibility API

api/session_manager.py plus /session/* endpoints remain available to agents and Command Arsenal for bounded manual browser work. There is no standalone 2.0 UI and new adaptive investigation should normally use Hunt. A compatibility client can start a session and drive actions (navigate, click, fill, register, login, submit, wait, extract), maintain separate per-user contexts (e.g. user1/user2), capture screenshots, and test endpoints for cross-user access (test-endpoint with as_user). Endpoint tests that name a user require that user to exist and be authenticated in the session; authz replay automation also requires at least two authenticated principals before it can make a cross-principal claim. Evidence-backed findings can be saved via POST /session/{id}/findings (the compatibility source value is ai_session; the user-facing source label is Interactive). This is the engine behind the /ai-security-session compatibility skill. These findings remain unverified until deterministic proof establishes impact; see the live /session* OpenAPI contract.

11.4 AI-assisted analysis of DAST findings

When an AI provider is configured (AI_URL / AI_API_KEY / AI_MODEL), ShakerScan adds cross-finding correlation and an overall risk assessment to DAST reports, and can run AI-driven retest verification of findings (AI_VERIFY_*). The AI retest tier generates an exploitation plan and replays it (optionally via a browser), and can downgrade false positives — but deterministic proof of exploitation blocks any downgrade.

11.5 AI Operations Router

POST /ai/ops/route maps natural-language DAST/ASM requests to concrete API calls with dry-run defaults. It recognizes the deterministic Scan plus dated legacy-name compatibility translations, "run parallel coverage", "keep this target covered" (enable ASM with a safe preset), "what is still untested?" (ASM gaps), "spend more budget on APIs", and focused SQLi/XSS/BOLA requests. Active, state-changing, or budget-increasing intents stay dry-run unless execute=true and the explicit confirmations are all present. Standard installs enable the server execution gate; AI_OPS_ROUTER_EXECUTE_ENABLED=false disables all gated execution globally. BOLA additionally requires primary + second-user auth context. Ambiguous language never upgrades a Safe/Balanced plan to Lab. The UI binds execution confirmation to the exact prompt and target that produced the visible preview; editing either input invalidates the preview and clears its confirmations.

11.6 Hunt

Hunt is the canonical AI-driven investigation workflow for web, API, network, and device targets. The current Codex, Claude, or OpenCode session plans through POST /hunts, /query, and the server-returned capability manifest; ShakerScan alone executes actions. Active or credentialed capabilities require a live, target-bound approval that is revalidated per call. A target authorized once (POST /targets/{id}/authorization, standing, revocable) supplies that approval automatically for active, network, mutation, OOB, identity-header and direct-origin authority; credential use keeps an explicit credential-tier receipt.

GET /hunt/skills publishes metadata for 31 server-shipped web-testing methodologies. Complete methodology bodies remain server-side. A Hunt normally starts with no selection, then POST /hunts/{id}/skills/suggestions returns at most three compact recommendations from the objective, target metadata, and bounded observed-stack signals. The planner loads exactly one at the Hunt-specific /read endpoint before /bind; it can later unbind or record evidenced use. Binding validates existing prerequisites but never grants, removes, or resizes authority. Versioned lifecycle events are stored outside the planner context and included in the Hunt record export.

The planner can issue read probes on explicit target-bound origins, compare managed principal contexts when they are configured, query stored knowledge, record candidates, and invoke bounded active capabilities. It cannot issue arbitrary state-changing HTTP. Capability calls, requests, active actions, wall time, ports, hosts, browser actions, device fragility, and candidate counts are bounded. A direct HTTP call consumes one request; external scanners reserve their fail-closed maximum wire request allowance before execution, and cannot run when that reservation does not fit. Receipts report reserved traffic, exact settled traffic when the scanner exposes it, and observed-minimum traffic otherwise. Scanner subprocesses run on the worker plane, which independently rebuilds fixed argv and revalidates the target host; the API never spawns them. The external coding agent owns its model context: ShakerScan cannot meter an external coding agent's tokens, and makes no token-budget claim for that planner. It meters every executable capability.

service.nse_check exposes Nmap's scripting engine inside Hunt only for the reviewed ssl-enum-ciphers, http-security-headers, http-methods, and http-trace scripts. It requires network-discovery authority and a standing active authorization, accepts at most four bound TCP ports and three script IDs per call, and never accepts script arguments, categories, paths, or raw Nmap flags. HTTP script traffic is charged at a conservative fixed allowance because NSE does not report a reliable request count. Results contain bounded signals and a digest of the script output, without raw target content; they are observations and cannot verify a finding. Broader CVE scripts need separate review of their request and device-fragility behavior before being added to the server-owned allowlist.

A final debrief persists evidence-backed claims only as durable, non-authoritative investigation candidates outside the findings table. Candidate lifecycle is linked to the server verification record and typed evidence. A finding is materialized only after a supported family reaches Verified through server-run deterministic proof. Legacy unverified autonomous_agent rows are migrated into the candidate ledger and retired. The /research/* controller remains available for specialized guided verification and is not a Hunt launcher. Legacy /agent/hunt/* and /device-agent/* writes return 410 Gone by default; reads and cancellation remain temporarily available with deprecation headers.

Candidates can be created, corrected with PATCH, expired with DELETE, and submitted to a registered deterministic verifier. A budget-exhausted run still accepts a final debrief without erasing its exhaustion reason. GET /hunts supports target/search/status/kind/budget filters, sorting, and pagination; GET /hunts/{id}/record exports the bounded explicit decision trace and debrief, never hidden chain-of-thought.

HuntStartContract is the sole Hunt policy and budget authority. The server publishes the same dimension/profile schema used to generate UI types at GET /hunts/contract. Zero is valid for risk dimensions: disabled mutation, network discovery, out-of-band interaction, and non-device fragility are persisted as hard zero ceilings, and an explicit positive override that contradicts policy is rejected. Duration, capability calls, HTTP traffic, candidates, and verification counts remain strictly positive runtime ceilings.

Web target identity is host-level: scheme and port variants share one target record and durable security history, while each scan and hunt retains the exact concrete origin it executes against. The target APIs return origins ordered by recent DAST use. Hunt binds the target and its known origins at creation; capability calls cannot replace that destination. Model Intake subjects retain exact artifact/revision identity in the Model Intake evidence model; they do not appear in the normal web-target inventory.

Targets also expose a validated cohort (production, staging, lab, demo, calibration, internal, or unclassified on update). Cohorts drive grouped target views, the Exposure lens, and the dashboard's default operational scope; they do not alter DAST scoring or finding proof.

Natural-language routing treats an unqualified “scan” as the deterministic Scan, historical mode names as display-only history, “Deep Hunt” as Hunt, “verify this finding” as deterministic retest/verification, and manual browser work as Interactive Testing. See product-model.md.

11.7 Test scenario catalog and Honey demo

GET /ai/test-scenarios returns ready-made templates — notably secure-rag-agent (canonical Honey RAG/agent/MCP endpoints with full control metadata) and model-intake-pipeline (safe/unsafe-pickle/ missing-signature/missing-approval model presets). Probe/test-case metadata is exportable to promptfoo, pyrit, and garak formats (/ai/test-cases/export). See docs/AI_TEST_WORKFLOWS.md.

11.8 AI surface inventory, histories, replay, and evidence

/ai/surfaces/* persists normalized AI surfaces and attempt facts independently of findings. AI-target and AI-scan campaign-history endpoints expose longitudinal decision, coverage, blocked, errored, and readiness-trend context; target history also has an export endpoint. Scan replay can rerun all probes or bounded slices selected by probe ID/family/error/skipped state while preserving the original target context and safety gates. Transcript reads support redacted default output and audited sensitive access only when the server policy allows it.

---

12. Cross-cutting: findings, exposure graph, workers, queue

Findings lifecycle: every proof-promoted DAST, connected-device, Hunt, Interactive, AI Gate, ASM, manual, and model-intake result lands in one findings table, de-duplicated by (target_id, fingerprint). Findings have a status (active / resolved / false_positive / accepted_risk), CVSS, CWE/OWASP tags, evidence, optional AI verdict fields, and verification history. The UI exposes DAST, Hunt, Interactive, AI Gate, Model Intake, ASM, and Manual filters. The API source_type filter accepts the canonical deep_hunt value plus compatibility values: dast, ai, ai_gate, ai_session, autonomous, deep_hunt, model_intake, asm, manual. Scanner findings driven by a hunt are included in deep_hunt and excluded from dast, so one row does not present two competing sources. model_intake and the AI sources also filter separately from dast (R8). Findings support filtering, sorting, bulk status triage from the list selection dock (POST /findings/bulk), previewed cleanup, manual creation, and per-finding retest.

Findings freshness is separate from status. Status answers whether someone triaged a finding; first_seen_at / last_seen_at answer when a scan actually observed it, and a scan that does not observe a finding never advances last_seen_at. The Findings page opens on Current (observed within the last 14 days), says how many older findings that leaves out, and offers Not seen recently and All; the card shows when the finding was last and first seen, whether it returned after being resolved (resurfaced_count), and the latest retest verdict. "Not seen recently" is deliberately not "fixed": absence from a later scan may only mean that scan never reached the route. Web findings are never auto-resolved on non-observation — only connected-device findings are, and only after a run that proved complete coverage — and a false_positive retest verdict does not change status unless auto_fp_on_retest is enabled, so a human stays in the loop. The API exposes the same partition through seen_within_days and its complement not_seen_within_days, so paging and totals are computed server-side.

Evidence objects: finding evidence is indexed by hash, storage URI, retention class, scan/finding links, and redaction profile. Large evidence can live in local content-addressed storage or an opt-in S3/MinIO-compatible backend; evidence reads verify SHA-256 before returning remote or local content. Retention sweeps are target-scoped and dry-run by default. A preview persists the exact candidate snapshot, criteria, storage effects, policy hash, and expiry in PostgreSQL and cannot be altered at execution time. The preview TTL defaults to 600 seconds; EVIDENCE_RETENTION_PREVIEW_TTL_SECONDS is clamped to 60-3600 seconds.

Deletion requires a target-scoped, one-use dangerous approval whose action_name is exactly evidence.retention_sweep and whose canonical action context is exactly preview_id, preview_hash, and target_id from that preview. The approval must expire no later than the preview. The execution body contains only dry_run:false, preview_id, and approval_receipt_id; resubmitted target, age, class, limit, or storage-deletion criteria are rejected.

Execution locks and revalidates the immutable rows, storage-reference effects, and finding/scan ownership, then commits durable executing intent and per-object pending markers before external blob deletion. A retry with the same preview and approval resumes unfinished work, treats an already-missing content-addressed blob as completed, and finalizes the persisted intent. Once the preview is consumed, the same retry returns the stored result idempotently instead of repeating side effects. Legal hold and evidence attached to active findings are never candidates. Local or remote blob failures preserve their database rows, and drift or a reused/mismatched approval fails closed.

Evidence instances and exports: proof instances bind a concrete route/object/payload/principal pair to evidence objects, tool receipts, campaign actions, proof state, and retention policy. APIs list/record instances, export content-free manifests or bounded bundles, verify object hashes on read, and record export events. Retention classes are short, standard, audit, legal_hold, and sensitive; legal hold is never swept.

HTTP transaction archive: GET /scans/{id}/http-transactions and GET /hunts/{id}/http-transactions export instrumented calls as ShakerScan transaction JSON or HAR 1.2, aggregating descendant scan shards for a user-visible parent. JSON is redacted by default. HAR is deliberately raw replay evidence and may contain credentials and bodies; raw non-HAR JSON also requires SHAKERSCAN_HTTP_ARCHIVE_ALLOW_RAW plus the operator credential. The export's fidelity and archive stats distinguish complete, partial, unavailable, failed, and dropped capture; absence of an archived row is not proof that no request occurred. Operator-authenticated DELETE routes purge the archive and unreferenced blobs without requiring raw export to be enabled.

Mission campaigns and action ledger: campaigns are durable operating wrappers over Continuous ASM, authenticated DAST, API authorization, AI red-team, Model Intake, benchmark, and retest work. Campaign actions retain plan/command/scope/approval/evidence/hypothesis/tool-receipt links and explicit execution state. The cross-product /timeline merges actions, scans, evidence, exports, refuter reviews, and upcoming schedules. Campaign list/detail reads compute current finding impact across every linked action in one live rollup. The displayed critical/high blocker count is explicitly a default-policy estimate, not the authoritative per-scan deployment decision.

Batch scan submission: POST /scans/batch accepts 1-50 targets, de-duplicates them, and returns accepted jobs plus per-target failures. Partial queueing is explicit (status: partial) rather than being reported as all-or-nothing success.

Hypothesis lifecycle: source/spec hints, operation plans, benchmark artifacts, scanner signals, and application-graph producer/object/consumer facts can create source-only hypotheses. Hypotheses support dedupe, optimistic versions, leased claims, endorsements/refutations, signals, next-test planning, situation reports, and campaign linkage. Only exact existing deterministic finding proof can reconcile a hypothesis into the canonical finding path.

Refuter reviews: durable support/question/weaken/refute signals challenge weak or high-impact claims. Summary, queue, execution, and verdict derivation APIs delegate to existing gated replay or retest primitives. Signal-only, failed, error, and AI-only results cannot create proof-backed verdicts.

Scope, approval, context, and decision contracts: scope previews create bounded receipts; approval/denial receipts bind confirmations and expiry to that scope. Operation plans, command results, agent context packs, agent decision traces, tool receipts, evidence instances, and campaign actions are versioned/redacted audit records. Local-agent planning remains dry-run and parser- validated; it has no raw-shell command or direct finding authority.

Exposure graph (/exposure/*): a derived graph across domains, targets, APIs, auth roles, vendors, AI surfaces, MCP tools, model artifacts, scans, and findings, with asset-centric breakdowns (by owner/tier/classification), change deltas over time, and attack-path views. Backs the UI /exposure page.

Dashboard & queue: /dashboard (active/critical counts, average score, running scans), /queue/stats, and /queue/clear.

Verification & retest: deterministic provers exist for xss, sqli, ssrf, path_traversal, open_redirect, cors, command_injection, ssti, xxe, jwt, idor, bola, and exposed_file; others can be replayed by the AI tier. Retests are slot-limited (RETEST_MAX_PARALLEL) with a watchdog and auto-retest-on-scan-complete policy.

---

13. REST API reference (by area)

Base URL http://localhost:8080. Most structured POST/PATCH operations accept JSON, while some control and discovery operations use query parameters or no body. FastAPI also serves the live schema at /openapi.json. The curated groups below explain product areas; §17 is the exhaustive generated method/path catalog. (See api/api.py for handlers. The agent-facing how-to with request bodies is in AGENTS.md.)

Health & settings: GET / · GET /health · GET|PUT /settings/ai · POST /settings/ai/test · GET|PUT /settings/scan-execution · GET|PUT /settings/automation

Multi-node fleet: POST|DELETE /fleet/join-tokens[/{token_id}] · POST /fleet/nodes/join · GET /fleet/nodes · POST /fleet/scale · GET|PATCH /fleet/nodes/{id}/state · GET /fleet/nodes/{id}/activity · GET /fleet/nodes/{id}/events · POST /fleet/nodes/{id}/heartbeat · POST /fleet/nodes/{id}/connection-bundle · POST /fleet/nodes/{id}/credentials/rotate · POST /fleet/nodes/{id}/revoke · /fleet/broker/*. Join tokens and node credentials are returned once and stored only as hashes. Enrollment returns the public fleet CA alongside one-time node identity material. Fleet operator reads and lifecycle operations require either an actual loopback socket peer or the high-entropy bearer generated by fleet init; a loopback host-port publish does not authenticate Docker-network peers. Non-loopback operator traffic requires HTTPS except for ShakerScan's narrow token-authenticated HTTP exception when the persisted bind exactly matches the host's currently verified Tailscale IPv4. Enrollment and secret delivery require HTTPS, and connection bundles also require the actual socket peer to be inside the configured overlay CIDR. Node state pulls and heartbeats likewise reject plaintext transport so node bearer credentials are never sent over HTTP. The worker-only Compose WireGuard worker runtime requires a digest-pinned image and starts no UI, API, Redis, or Postgres. Its pull-based agent uses owner-only local state, reconciles only node-labeled workers on the local Docker engine, and reports applied state/capacity/errors. scanner.sh fleet init, fleet join-token, fleet reconcile, and scanner.sh join provide the Linux host workflow with owner-only state, explicit system/private CA trust, CA-verified overlay proof, one-time bundle persistence, and pinned-image startup. Broker nodes receive no Redis, PostgreSQL, or object-store credentials and use outbound HTTPS only. On an initialized Linux control plane, the Fleet UI manages capacity, drift, drain/resume, image rollout, lifecycle events, and revocation. It stays hidden on standalone installs. shakerscan fleet accept is implemented; development broker execution has passed on two local-build VPS nodes, while the frozen, digest-pinned physical release run and fault matrix remain pending.

Command Arsenal: GET /arsenal/commands · GET /arsenal/contracts · POST|GET /arsenal/plans · POST|GET /arsenal/context-packs · POST /arsenal/context-packs/from-target · POST|GET /arsenal/decision-traces · GET /arsenal/command-results · POST /arsenal/scope/preview · POST /arsenal/approvals · GET /arsenal/tools · GET|POST /arsenal/refuter-reviews · GET /arsenal/refuter-reviews/summary · POST /arsenal/refuter-reviews/queue-from-summary · POST /arsenal/refuter-reviews/{id}/execute · POST /arsenal/refuter-reviews/{id}/derive-verdict · POST /arsenal/hypotheses/source-ingest · POST /arsenal/hypotheses/from-plan · POST /arsenal/hypotheses/{id}/reconcile-proof · GET /agents/local · POST /agents/local/test · POST /agents/local/plan. Source/spec hints and saved dry-run plan actions can be recorded as source-only hypotheses; they never create findings or queue scans. Worker finalization also routes uncertain medium-or-higher scanner findings into scanner_signal hypotheses with deterministic finding.retest next actions; verified findings stay on the finding/proof path instead of duplicating into the lead queue. The /settings/arsenal UI includes a Source Hint Ingest panel for bounded source/spec/route facts. Refuter verdict derivation is gated and derives only from a linked or explicit verification row; failed/error/AI-driven results remain signal-only. Authz replay promotion requires an authenticated cross-principal differential, treats login/forbidden soft-200 bodies and redirect denials as non-violations, and validates approval receipts against the campaign action's actual target before a manual BOLA finding can be created. Hypothesis proof reconciliation is separately approval-gated and can only link an existing exploited canonical finding with exact campaign-action, target, family, and route dimensions; it never creates or verifies a finding from lead context.

Bounded Research Agent: GET /research/readiness · POST|GET /research/episodes · GET /research/episodes/{id} · POST /research/episodes/{id}/decisions · POST /research/episodes/{id}/observe · POST /research/episodes/{id}/settle · POST /research/episodes/{id}/cancel. An episode is a target-bound state machine over immutable, redacted ObservationPack rows and exactly-one-action DecisionEpisode rows. Decisions are bound to the current observation ID/hash, cannot carry receipts or credentials, must declare an expected signal and falsifier, and consume bounded step/action/time/request/model-token budgets. The campaign and episode APIs supply server-owned target-hunt, exact-finding, and ASM-gap missions, deduplicate concurrent one-click launches, and reserve a final synthesis step. The UI launches these missions from Finding Detail, Continuous ASM, and registered web assets in Exposure as well as from the main Autonomous Hunt page. Linked scans and finding retests must settle before exactly one result-bearing observation is attached. No-progress duplicate actions are rejected until a state-changing action occurs, and provider failures meter model usage before retry. Scan/ASM request values are conservative reservation units rather than exact HTTP counts. Shadow mode records decisions without dispatch. Read-only mode dispatches only the target-scoped inspection allowlist. Gated mode can additionally dispatch asm.improve, asm.recon, asm.test, finding.retest, scan.focused_family, experiment.http_diff, and experiment.workflow through the existing Arsenal gateway when a matching scope/approval receipt and the global execution flag are present. Target IDs/URLs and receipts are injected by the server. Research campaigns persist one of three planner modes. agent is the clean-install default: the current Codex/Claude/OpenCode session reads the immutable observation and submits one bounded decision without a stored provider. configured_ai uses AI settings and durable server autopilot. local_codex uses the host-side ./scanner.sh research <episode-id> [max-decisions] with an isolated ephemeral Codex process and fails fast when server autopilot is enabled for the episode, preventing two planners from racing the same immutable observation. Pause server autopilot before invoking the local runner. The command prints a compact decision/episode receipt and UI path instead of the full observation pack. A planner cannot mint proof or findings. A trusted server-side workflow replay may create or refresh a finding only after deterministic family proof and the promotion gate pass. Cancellation terminates the episode, cancels linked queued retests and pending/running scans where possible, and reports already-running retests as continuing rather than pretending they stopped.

experiment.http_diff is the first typed adaptive experiment actuator. It accepts two to four anonymous control/mutation/verification requests using relative same-origin paths, JSON or form bodies, bounded query/header mutations, and named scalar extraction from non-sensitive JSON paths or response headers. Later steps may reference extracted resource values as ${name}; every rendered request is revalidated before dispatch. It forbids model-supplied credential/host headers and redirects. Autonomous planner proposals are limited to GET, HEAD, and OPTIONS; experiment.http_diff cannot receive cleanup-safe write authority because it has no restoration contract. The manual typed-experiment surface retains the broader runtime method contract. Variable references and extract names are preflighted across the complete experiment, so undeclared, forward, duplicate, or over-budget variables fail before any request is sent. Query and form values are constrained to bounded scalars. Responses are closed after a capped streaming prefix, extracted values are persisted as hash/length metadata, and failed steps are marked non-comparable instead of producing synthetic deltas. The result records status/body/JSON-shape, selected JSON/header, timing, and before/after comparisons in a tool receipt plus an unverified evidence instance. The research budget reserves four requests before dispatch. Experiment signals cannot directly create or verify findings; a family-specific deterministic verifier must establish proof.

experiment.workflow extends the actuator with two to twelve typed HTTP/browser steps and server-resolved principal slots (anonymous, user1, user2, admin, or tenant:<id>). It supports before/mutation/after/action/cleanup/rollback checkpoints, same-origin navigation, click, fill, submit, bounded wait, scalar extraction, and shared ${name} resources. Credential profiles are decrypted only in API memory and are never accepted in planner parameters. Cross-principal workflows require distinct profile IDs and distinct verified account fingerprints before any target or browser request. Results contain content-free principal/profile/role/tenant identity receipts, bounded mixed HTTP/browser observations, comparisons, assertions, and restoration outcomes. A caller-supplied workflow UUID allows cooperative cancellation through POST /experiments/workflows/{id}/cancel; cancellation is checked between steps and browser contexts always close in a finally block. Credential-tier Hunt may receive PUT, PATCH, and DELETE steps only through the typed workflow contract, with later cleanup/rollback and restoration assertions. The server independently re-executes a promotable workflow, derives family predicates from observed results, and may create or refresh a canonical finding only when deterministic family proof and promotion gates pass. Create-based mass-assignment workflows may leave explicitly labeled test objects when the discovered target has no delete route; this bounded exception is limited to server-materialized create/read-back proof and is surfaced in the run outcome.

MCP — read-only Arsenal inspection plus target-bound Hunt V2: ./scanner.sh mcp starts a stdio adapter. Arsenal inspection exposes targets, ASM gaps, findings, content-free evidence manifests, the mission timeline, saved dry-run plans, and tool status through POST /arsenal/execute; it revalidates the live catalog and never represents state-changing Arsenal commands. Hunt tools load GET /hunts/contract, generate the canonical start schema, expose progressive methodology suggest/read/bind/unbind/usage operations, and wrap start/get/query/capability/candidate-create/ candidate-update/candidate-delete/verify/finish/cancel. Candidate edits are Hunt-scoped and cannot alter deterministic proof state; deletion retains an immutable audit record. Capability calls require the live Hunt manifest, validate its published input schema, and use a caller-provided or returned generated idempotency key. Target binding, approvals, budgets, receipts, evidence, and deterministic proof remain server-enforced. See docs/mcp.md.

Scans (DAST): POST /scans · POST /scans/batch · GET /scans · GET /scans/{id} · GET /scans/{id}/result · GET /scans/{id}/logs · POST /scans/{id}/cancel · GET /scans/{id}/deployment-decision · GET /scans/{id}/ai-redteam-report · GET|DELETE /scans/{id}/http-transactions

Findings: GET /findings · GET /findings/{id} · PATCH /findings/{id} · DELETE /findings/{id} (list filters include severity, status, source_type, target_id, scan_id, root_domain, search, seen_within_days, not_seen_within_days, first_seen_within_days, resolved_within_days, verification_verdict, verified_only) · POST /findings/bulk · POST /findings/cleanup · POST /findings/manual · POST /findings/{id}/retest · POST /findings/retest · GET /retests/{id} · GET /retests/finding/{id}

Targets & domains: GET /targets · GET /targets/grouped · GET /domains · POST /targets · GET /targets/{id} · PATCH /targets/{id} · DELETE /targets/{id} · POST /targets/{id}/scan

Connected devices: GET /devices/readiness · GET|POST /devices · GET|PATCH|DELETE /devices/{id} · POST /devices/{id}/scan · POST /devices/{id}/verify-service · GET /device-scans · GET|POST /devices/{id}/credentials · POST /devices/{id}/credentials/{profile_id}/rotate · DELETE /devices/{id}/credentials/{profile_id} · POST /devices/{id}/credentials/{profile_id}/acknowledge-lockout · GET|POST /device-policies · PATCH /device-policies/{id}

Hunt: GET /hunts/contract · GET /hunt/skills · GET /hunt/skills/{skill_id} · POST|GET /hunts · GET /hunts/{hunt_id} · GET /hunts/{hunt_id}/record · POST /hunts/{hunt_id}/skills/suggestions · POST /hunts/{hunt_id}/skills/{skill_id}/read|bind|usage · DELETE /hunts/{hunt_id}/skills/{skill_id} · POST /hunts/{hunt_id}/query · POST /hunts/{hunt_id}/capabilities/{capability_name} · POST /hunts/{hunt_id}/candidates · PATCH|DELETE /hunts/{hunt_id}/candidates/{candidate_id} · POST /hunts/{hunt_id}/candidates/{candidate_id}/verify · POST /hunts/{hunt_id}/finish|cancel|resume · GET|DELETE /hunts/{hunt_id}/http-transactions

Every Hunt capability call carries a client-generated opaque idempotency_key. Repeating the same key with the same semantic input returns the original durable action; reusing it for a different capability or input fails closed.

All release-critical public V2 writes also accept the optional Idempotency-Key header published in OpenAPI. The server binds its SHA-256 digest to the exact method, concrete path, and request-body digest, stores no request body or raw key, and replays only an already-public successful JSON response. This makes installed Scan, Hunt start, credential create/rotate, and collection mutations safe to retry after a lost response. A key reused with different input returns 409; an in-flight duplicate returns a bounded idempotency_request_in_progress response instead of executing twice.

Legacy device SSH, header, cookie, and form profiles are backfilled to same-ID generic profiles. Their older encrypted JSON envelopes are canonicalized without returning or logging plaintext; new and compatibility mutations remain transactional in both stores until device execution stops reading the legacy table. SSH profiles receive only the SSH-plan capability, while device Web profiles receive bounded replay/probe capabilities.

Continuous ASM: GET /asm/check-families · GET /targets/{id}/asm/endpoints · GET /targets/{id}/asm/coverage · POST /targets/{id}/asm/test · POST /targets/{id}/asm/recon · POST /targets/{id}/asm/prune · POST /targets/{id}/asm/improve · GET|PUT /targets/{id}/asm/policy · GET /targets/{id}/asm/diff · GET /targets/{id}/asm/gaps · GET /targets/{id}/asm/activity

AI Gate: GET /ai/test-scenarios · GET /ai/test-cases · GET /ai/test-cases/export · GET /ai/learning-guide · POST /ai/demo/run · GET /ai/inventory · GET|POST /ai/targets · PATCH|DELETE /ai/targets/{id} · POST /ai/targets/{id}/scan · POST /ai/targets/{id}/test · POST /ai/targets/{id}/mcp/live-readiness · GET /ai/targets/{id}/runtime-risk · GET|POST /ai/targets/{id}/principals · PATCH|DELETE /ai/targets/{id}/principals/{pid} · GET|DELETE /ai/scans/{id}/transcript · POST /ai/findings/{id}/retest · POST /ai/surfaces/sync · GET /ai/surfaces · GET /ai/surfaces/{id}/attempts

Model Intake: POST /model-intake/resolve · POST /model-intake/scan · POST /model-intake/targets/{id}/rescan · GET|POST /model-intake/trust-anchors · PATCH|DELETE /model-intake/trust-anchors/{id} · GET /model-intake/scans/{id}/evidence-export · GET /model-intake/capabilities · POST /model-intake/admission/verify · GET /model-intake/admissions · GET /model-intake/admissions/{id} · POST /model-intake/admissions/{id}/revoke · POST /model-intake/reassessment/events · POST /model-intake/retention/cleanup

Governance (deployment gate): GET|POST /policy-profiles · PATCH|DELETE /policy-profiles/{id} · GET|POST /finding-exceptions · PATCH|DELETE /finding-exceptions/{id} · POST /finding-exceptions/lifecycle/sweep

Evidence and mission control: GET|POST /evidence/instances · GET /evidence/{id} · GET /evidence/export-manifest · GET /evidence/export-bundle · POST /evidence/retention/sweep · GET /timeline · GET|POST /arsenal/campaigns · GET /arsenal/campaigns/{id} · POST /arsenal/campaigns/{id}/actions · GET|POST /arsenal/tool-receipts

AI Ops Router: POST /ai/ops/route

Interactive sessions: POST /session/start · GET /session/{id} · POST /session/{id}/screenshot · GET /session/{id}/screenshot.png · POST /session/{id}/action · POST /session/{id}/test-endpoint · POST /session/{id}/findings · DELETE /session/{id} · GET /sessions

Generic credential profiles: GET|POST /credential-profiles · GET|PATCH|DELETE /credential-profiles/{profile_id} · POST /credential-profiles/{profile_id}/rotate. These exact-target Web, API, network, and device profiles use immutable encrypted versions, metadata-only responses, capability bounds, expiry, and primary/secondary/service/SSH slots. Scan and Hunt queue only opaque IDs; workers revalidate the target-bound approval and decrypt the admitted version immediately before execution. A bearer profile may expose a nonsecret browser_storage_key for authenticated SPA crawling; cookie values and bearer tokens remain worker-private, are placed only in an ephemeral browser profile, and are never returned or passed on the scanner command line.

Legacy target credentials and principals: GET|POST /targets/{id}/credential-profiles · PATCH|DELETE /targets/{id}/credential-profiles/{profile_id} · POST /targets/{id}/credential-profiles/{profile_id}/rotate · GET|POST /targets/{id}/principals · PATCH|DELETE /targets/{id}/principals/{principal_id} · GET|POST /targets/{id}/principal-matrix. This compatibility surface remains metadata-only and write-only for secrets. Existing rows are backfilled under the schema migration lock and every create, rotation, principal-slot change, and deactivation is transactionally mirrored to the generic immutable store. Generic rename, rotation, expiry, and deactivation changes are mirrored back while legacy execution remains enabled. Ciphertext is never returned or logged. An ID/target/auth-kind collision fails closed instead of overwriting a generic identity. These routes will be removed after remaining legacy callers migrate.

Discovery & exposure: POST|GET /discovery · GET /discovery/{id} · GET /dashboard · GET /exposure/graph · GET /exposure/nodes · GET /exposure/assets · GET /exposure/changes · GET /exposure/attack-paths

Schedules: GET|POST /schedules · GET|PATCH|DELETE /schedules/{id}

Workers, queue, gungnir, results: GET|POST /workers · GET /queue/stats · DELETE /queue/clear · GET /gungnir/status · POST /gungnir/start · POST /gungnir/stop · GET /results · GET /results/{folder}/latest

---

14. Configuration and integrated tools

Key environment variables (.env):

• AI analysis: AI_URL, AI_API_KEY, AI_MODEL, AI_FALLBACK_MODEL.
• AI retest verification: AI_VERIFY_ENABLED, AI_VERIFY_URL, AI_VERIFY_API_KEY, AI_VERIFY_MODEL, AI_VERIFY_USE_BROWSER, AI_VERIFY_MAX_PER_SCAN, AI_VERIFY_MIN_SEVERITY.
• AI Ops Router execution gate: AI_OPS_ROUTER_EXECUTE_ENABLED (default on; set false for a global kill switch).
• Evidence-retention preview lifetime: EVIDENCE_RETENTION_PREVIEW_TTL_SECONDS (default 600 seconds, clamped to 60-3600 seconds).
• AI Gate transcripts: AI_GATE_TRANSCRIPT_RETENTION_DAYS (retention label, default 30); AI_TRANSCRIPT_ALLOW_SENSITIVE (default off — when on, GET /ai/scans/{id}/transcript?include_sensitive=true returns raw, audit-logged bodies; otherwise responses are redacted at response time).
• Credential encryption-at-rest: AI_CREDENTIAL_ENC_KEY may supply the stable Fernet key. When it is unset, the runtime creates and persists an owner-only shared key under RESULTS_DIR. Every new secret write must produce an enc:fernet: value or fails closed. Plaintext is accepted only when reading a legacy row long enough to migrate it; it is never a supported new-write mode.
• Allocation fallback: COVERAGE_ALLOCATION_DEFAULT. Shard ceilings: SHAKERSCAN_MAX_SHARDS, SHAKERSCAN_COVERAGE_MAX_SHARDS, PARALLEL_SHARD_MAX_PER_PARENT, etc.
• Custom dictionaries: SHAKERSCAN_CUSTOM_WORDLIST, SHAKERSCAN_CUSTOM_<CAT>_PAYLOADS.
• Deployment/binding: SHAKERSCAN_BIND_HOST (UI/API), SHAKERSCAN_DATA_BIND_HOST (Redis/Postgres; loopback by default), SHAKERSCAN_PUBLIC_HOST, SHAKERSCAN_REMOTE.
• Data-store authentication: REDIS_PASSWORD, POSTGRES_PASSWORD (shakerscan start generates strong owner-only values when missing/weak and migrates the historical standalone Postgres default; Compose has no well-known password fallback).
• Owned-fleet bootstrap: FLEET_OVERLAY_CIDR, FLEET_CONTROL_PLANE_OVERLAY_URL, FLEET_WIREGUARD_PUBLIC_KEY, FLEET_WIREGUARD_ENDPOINT, digest-pinned FLEET_WORKER_IMAGE_DIGEST, generated FLEET_OPERATOR_TOKEN, and one-time FLEET_CONNECTION_BUNDLE_JSON. Insecure enrollment is disabled by default and its explicit test escape hatch works only from loopback.

Integrated external tools: httpx (HTTP probing), katana (crawling), nuclei (templates), ffuf/meg/dirb/gobuster (content discovery), dalfox/XSStrike (XSS), sqlmap/commix (injection), subfinder/Gungnir/dnsrecon (domain discovery), tlsx/SSLyze/testssl.sh/OpenSSL (TLS), nmap/masscan/netcat (ports and services), nikto, hydra/medusa, whois, Shodan client support, and Playwright (browser). The authoritative execution-facing adapter catalog is generated in §17; an installed binary is not automatically a runnable ShakerScan adapter. Subprocess execution is concurrency-limited with per-tool timeouts and a global deadline.

---

15. Safety model

• Authorization: only scan targets you own or are explicitly authorized to test. A Scan sends state-changing or exploit-style probes only when its explicit policy and target-bound approval permit them; a resource ceiling never grants active authority. AI Gate production scans and ASM BOLA likewise require explicit confirmation.
• Bounded automation: passive recon and ASM new-surface tracking can be safe-on by default; active exploitation uses small safe batches and requires an explicit Lab/deep policy for deep exploit mode. Rate tokens are reserved before active work is queued.
• Coverage honesty: an endpoint is only counted tested when scanner telemetry proves it was attempted/completed; timeouts/partials never inflate coverage.
• Local binding: laptop mode binds to 127.0.0.1; remote mode binds to a Tailscale IP. Exposing on 0.0.0.0 is only safe behind a firewall/VPN/reverse proxy.
• AI redaction and credential handling: sensitive headers/bodies and secret-bearing URL params/metadata are redacted before any content is sent to an AI provider, via the shared redact_sensitive() helper (R2a). AI-target and target-profile credential secrets are encrypted at rest with a configured or auto-generated persistent key (R2b); unavailable stable encryption fails new writes closed, and transcript responses are redacted at response time by default (R3). Normal DAST worker launches pass auth material through a short-lived 0600 auth-config file rather than raw scanner subprocess argv, and scan-time AI provider keys are supplied through the child environment instead of --ai-api-key.

---

16. UI, CLI, skills, and agent surfaces

Web UI routes

API-only or partially UI-backed workflows

Not every public operation should have a dedicated screen. The following remain intentionally available primarily to CI, agents, integrations, or advanced operators: raw result/result-folder reads; direct evidence-instance/tool-receipt recording; MCP read-only Arsenal inspection and target-bound Hunt V2; generic Arsenal execution; local-agent output parsing; host-side Codex episode driving; and bulk finding retest/update/manual creation. §17 lists every operation so this boundary is visible rather than accidental.

Several workflows that were previously API-only now have UI surfaces: the cross-product mission timeline (/timeline), read-only mission campaign list/detail (/campaigns), evidence browsing plus content-free manifest/bundle export and approval-gated retention sweeps (/evidence), the durable AI surface inventory (inside /ai-gate), hypothesis claim/signal/plan-campaign and the from-plan/from-benchmark generators (inside /settings/arsenal), the natural-language AI Operations Router (POST /ai/ops/route, API only), and the one-click operational actions batch scan (/scan/new), target dedupe (/targets), queue emergency clear (/), and ASM inventory prune (/asm).

Scanner CLI

scanner.sh scan is the canonical client. It submits scan-start/v2, loads the server contract, accepts budget/policy/family/credential/collection/placement/advanced-ceiling inputs, supports automation-safe --json, and never accepts raw reusable secrets. It prints the Scan ID and UI link and exits without polling. The old scan-full, scan-smart, and scan --type ... write paths are removed. Historical records remain readable through the audit surfaces; they cannot create plans or queue work.

scanner/scanner.py and its large flag inventory are compatibility/internal detector implementation surface. They remain generated in §17 so maintainers can audit migration risk, but users and agents must not treat those flags as separate V2 engines or trusted capability input.

The remaining scanner.sh commands operate service lifecycle, status/doctor, scaling, logs, builds, offline report rebuild, agent/MCP launch, Fleet, Model Intake runner, Gungnir, environment inspection, backup, and containers. §17 inventories the canonical wrapper commands.

Skills, slash commands, and specialized agents

• ai-security-session: drives authorized interactive Playwright testing with explicit evidence and finding-save boundaries.
• shakerscan: routes general scans, targets, findings, Continuous ASM, AI Gate, Model Intake, operations, and bounded research while enforcing authorization and asynchronous handoff rules.
• js-analyze: converts bundles and browser evidence into routes, APIs, libraries, secret leads, custom_endpoints, and content-discovery seeds.
• content-discovery: builds generic and app-specific route/file/API lists and scanner/ffuf inputs.
• research-agent: compatibility skill for older prompts; it routes new investigations to canonical Hunt and keeps specialized guided experiments bounded.
• device-hunt: drives one authorized connected-device investigation through immutable scope, context, memory, fragility, health, and deterministic-evidence boundaries.
• device-triage: explains and compares existing connected-device evidence without sending traffic.
• review-skills: audits skills, commands, and subagents for broken references, unsafe prompts, and missing gates or output contracts.

The slash-command layer provides canonical Scan, Hunt, AI Gate, interactive session, finding list/ save, subdomain, worker, status, JS analysis, content discovery, bounded research, and skill-review workflows. Historical smart/full command files are compatibility shims that translate to explicit Scan policy/budget input and carry the same 2026-12-31 sunset. Three specialized Claude subagents back JS analysis, content discovery, and skill review. The product also catalogs Codex, Claude Code, OpenCode, and Hermes local-agent capabilities. The Codex research runner can submit one schema-constrained decision at a time, but only the API policy controller can dispatch an accepted Arsenal action; local-agent output never grants execution or finding authority.

---

17. Generated capability inventory

This appendix is generated directly from code and repository manifests. It is intentionally verbose: it is the exhaustive backstop behind the human-readable product map above.

Saved browser login and read-only QA

browser.login_check is a shared credential-gated Scan/Hunt action using an operator-saved encrypted workflow. Select it with Scan browser_login_profile_ids or Hunt's managed principal and browser.login_check capability. It performs one login and fixed protected-page assertions, retains no exported browser state, and does not grant permission to other actions. See browser login QA for the profile contract, invocation, limits and acceptance gates.

<!-- BEGIN GENERATED CAPABILITY INVENTORY -->

Generated source inventory. Run python3 scripts/generate_capability_inventory.py after changing any inventoried surface. CI uses --check; do not edit this block manually.

Inventory Summary

Public REST Operations

Check-Family Registry

Command Arsenal

Tool And Local-Agent Adapters

Internal Compatibility Scanner Flags

These parser flags inventory the private compatibility scanner surface. They are not the public Scan contract, must not receive secrets directly from V2 clients, and cannot grant execution authority. Public clients use GET /scan/contracts plus /scans policy, budget, opaque profile, and collection-reference fields.

Wrapper Commands, Make Targets, And Release Gates

Runtime Environment-Key Inventory

Only key names and declaring sources are documented; secret values are never read or emitted.

UI Pages

Skills, Slash Commands, And Subagents

Internal Compatibility Scanner Module Inventory

Implementation modules below are inventory only. The immutable action graph and canonical capability registry define execution authority; module presence does not advertise a public Scan feature or a second orchestration engine.

access_control_checks.py, active_checks.py, active_enrichment_policy.py, active_prioritization.py, adaptive_throttle.py, ai_classifier.py, api_auth.py, api_security.py, approval_checks.py, asn_discovery.py, attack_chains.py, attempt_telemetry.py, auth_session.py, authz_replay_routing.py, benchmark_summary.py, bola_comparison.py, bounded_exec.py, brand_protection.py, breach_check.py, browser_profile.py, build_fingerprint.py, cancellation.py, client_side.py, common.py, completion_status.py, compliance_mapper.py, coverage_tracker.py, credential_check.py, critical_checks.py, ct_monitor.py, data_exposure.py, deduplication_engine.py, deserialization_tests.py, device_advisories.py, device_application.py, device_control_plane.py, device_evidence.py, device_postman.py, device_posture.py, device_probe.py, device_protocols.py, device_reachability.py, device_request_formats.py, device_safety.py, device_shell.py, device_web.py, discovery.py, discovery_policy.py, dns_enhanced.py, dom_xss_analyzer.py, domain_intel.py, exposure_markers.py, file_upload_tests.py, finding_correlator.py, finding_validator.py, focused_scope.py, form_login.py, github_recon.py, google_dorking.py, gopher_payloads.py, graphql_schema_recovery.py, grpc_discovery.py, gungnir.py, har_discovery.py, hash_routes.py, health_check.py, http_archive_capture.py, http_scanner.py, hunter_summary.py, infrastructure_checks.py, injection_extra_checks.py, ip_reputation.py, logging_checks.py, model_intake.py, model_intake_acquisition.py, model_intake_adapter_self_test.py, model_intake_admission.py, model_intake_archives.py, model_intake_attestation.py, model_intake_evaluation.py, model_intake_licenses.py, model_intake_providers.py, model_intake_registry.py, model_intake_retention.py, model_intake_runtime.py, model_intake_safetensors_runtime.py, model_intake_safetensors_selftest.py, model_intake_sandbox.py, model_intake_scanners.py, network_services.py, nmap.py, nuclei.py, oauth_auth.py, oauth_tests.py, phase4_checks.py, proof_of_exploit.py, race_condition_tests.py, remediation_kb.py, report_gating.py, request_collections.py, request_meter.py, request_replay.py, resource_propagation.py, sarif_output.py, scan_delta.py, signal_types.py, smtp_scanner.py, ssh_scanner.py, subdomain_discovery.py, subfinder.py, tech_discovery.py, tls_scanner.py, url_redaction.py, v2_fingerprint_hardening.py, v2_request_replay_hardening.py, vendor_risk.py, verification_engine.py, verification_phase.py, wayback_discovery.py, webhook_checks.py, websocket_security.py, xss_evidence.py

Durable Storage Inventory

<!-- END GENERATED CAPABILITY INVENTORY -->

---

18. Where to go deeper

Reminder: where any doc and the code disagree, the code, DB schema, and tests win. This reference is a map, not the territory.