Scanner Endpoint Registration Matrix

Verified against commit 942a18727c (2026-09-26). Re-verify with: grep -nE "^(app|apiGroup)\.Map" src/Scanner/StellaOps.Scanner.WebService/Program.cs and grep -rnE "RequireAuthorization|AllowAnonymous" src/Scanner/StellaOps.Scanner.WebService/Endpoints/.

This file is the Scanner WebService source-of-truth for endpoint registration intent and authorization posture. Program.cs is the authority; policy names below are the ScannerPolicies constants (src/Scanner/StellaOps.Scanner.WebService/Security/ScannerPolicies.cs), and the scopes each policy accepts are bound in Program.cs (see architecture.md section 10). Routes under apiGroup are relative to scanner:api:basePath (default /api/v1); every apiGroup route passes through ScannerCapacityPauseFilter.

Q-25 assigns canonical HTTP import/status/manifest/validate, carrier quarantine/CAS, lifecycle and import-ledger ownership to OfflineKit at /api/offlinekit/v1. Scanner accepts the exact Scanner artifact-BOM part through its bounded owner seam; MapOfflineKitEndpoints and the route-only MapObservabilityEndpoints are not Scanner endpoint maps and must not be reintroduced. /metrics is not an active Scanner route.

Captured openapi_* snapshots describe their capture-time route surface and are not current source authority; the live document is GET /openapi/v1.json (anonymous, app.MapOpenApi()).

Host-level routes (outside the API base path)

API-group maps (registered in Program.cs)

Webhook tenant contract (name routes)

All webhook routes are quarantined: RejectQuarantinedScanTrigger answers 501 source_scan_not_available before any dispatch (source-triggered scanning has no production IScanJobQueue; see src/Scanner/AGENTS.md). The tenant rules below describe the preserved, unwired receiver contract.

• Name-based webhook routes are:
• POST /api/v1/webhooks/docker/{sourceName}
• POST /api/v1/webhooks/github/{sourceName}
• POST /api/v1/webhooks/gitlab/{sourceName}
• POST /api/v1/webhooks/harbor/{sourceName}
• Tenant context is required for name-based routes (claim or X-StellaOps-TenantId/compatibility alias). Missing tenant returns 400 with tenant_missing; claim/header mismatch returns 400 with tenant_conflict.
• Source lookup is tenant-scoped via GetByNameAsync(tenantId, sourceName), so same-name sources in different tenants cannot cross-dispatch.
• POST /api/v1/webhooks/{sourceId} accepts optional tenant context; if present and it does not match source ownership, the endpoint returns 404.

Triage tenant contract

• Triage and finding-evidence routes resolve tenant context via ScannerRequestContextResolver.
• Resolution uses the validated tenant claim through the shared StellaOpsTenantResolver; there is no default-tenant fallback. The canonical tenant-switch header is honored only for authenticated global-admin principals, and legacy tenant headers are not tenancy sources.
• Missing or conflicting validated tenancy returns a deterministic request error rather than selecting a fallback tenant.
• Triage-facing contracts now require tenant input (ITriageStatusService, ITriageQueryService, IFindingQueryService, IGatingReasonService, IUnifiedEvidenceService, IReplayCommandService, IFindingRationaleService) and enforce tenant-filtered data access.
• Triage persistence is tenant partitioned (triage_scan.tenant_id, triage_finding.tenant_id), and the active-case uniqueness key includes tenant_id to avoid cross-tenant collisions.
• Cross-tenant finding lookups are treated as deterministic not-found responses (404) on triage/finding endpoints.
• /api/v1/triage/inbox?artifactDigest=... is the canonical identity bridge: artifactDigest filters all matching tenant rows and paths[].findingIds[] returns bare UUIDs consumed unchanged by /findings/{findingId}/evidence. Findings-service matcher tokens are not Scanner Triage aliases.
• Existing findings may return partial unified evidence as 200 with typed availability.missing[]; missing and cross-tenant findings return a non-echoing 404 scanner.triage.finding_not_found with producer and recovery metadata.

Unknowns tenant contract

• Unknowns routes resolve tenant context via ScannerRequestContextResolver, a facade over the shared claims-only StellaOpsTenantResolver (the stellaops:tenant claim; a global admin may select a tenant with X-StellaOps-TenantId); a request without a tenant fails with 400 (tenant_missing).
• Unknown queries are tenant-scoped by a UUID predicate (tenant_id = @tenantId) in the Scanner WebService query service. scanner.unknowns.tenant_id is UUID; the request tenant is converted with ScannerTenantScope.Resolve, the same identity Scanner’s repositories store in their UUID tenant columns (a canonical UUID passes through; a slug maps to a deterministic name-based UUID). The earlier tenant_id::text = @tenantId text comparison against the slug never matched (SPRINT_20261017_006 PCD-847 item a). No production path writes scanner.unknowns (verified 2026-10-18), so the routes return empty results until a producer exists.
• Missing records across tenant boundaries resolve as deterministic 404 for detail/evidence/history endpoints.

Reachability + SmartDiff tenant contract (SCAN-TEN-11)

• Reachability drift routes (/api/v1/scans/{scanId}/drift, /api/v1/drift/{driftId}/sinks) now resolve tenant context via ScannerRequestContextResolver before repository access.
• Drift persistence/retrieval paths are tenant-parameterized end-to-end (call_graph_snapshots, code_changes, reachability_drift_results, drifted_sinks) instead of using a fixed tenant scope. Both drift routes are read-only: the drift GET computes a drift for a supplied baseScanId without storing it (SPRINT_20261017_006 PCD-847 item d). The stored results they read are written by the Worker’s reachability-drift stage for scans submitted with reachability.drift.base_scan_id (PCD-874).
• SmartDiff routes (/api/v1/smart-diff/**) now resolve tenant context and pass it explicitly to the material-change store.
• SmartDiff persistence/retrieval paths are tenant-parameterized (material_risk_changes). The VEX-candidate store over vex_candidates and its routes were withdrawn by PCD-222.
• Remaining reachability/SmartDiff storage adapters used by these flows are tenant-parameterized as well (risk_state_snapshots, reachability_results), removing fixed-tenant constants from Postgres adapter implementations.

Source-runs + secret-exception tenant contract (SCAN-TEN-13)

• Source run routes (/api/v1/sources/{sourceId}/runs, /api/v1/sources/{sourceId}/runs/{runId}) now pass resolved tenant context into ISbomSourceRunRepository and SQL predicates (tenant_id = @tenantId) for scanner.sbom_source_runs.
• Secret exception routes (/api/v1/secrets/config/exceptions/{tenantId}/{exceptionId}) now use tenant-scoped repository methods for get/update/delete against secret_exception_pattern rather than ID-only lookups.
• The generic webhook route (POST /api/v1/webhooks/{sourceId}) remains compatibility-tolerant for missing tenant context, but enforces ownership match when tenant context is present.

Deferred endpoint maps (present in source, not registered)

The Scanner-side /api/v1/registries/* group and the fabricated /api/v1/security/* adapter were removed; Platform owns both surfaces.