Scanner Endpoint Registration Matrix

Last updated: 2026-08-29 (Q-25 removes Scanner’s duplicate generic offline-kit HTTP map; Sprint 20260722_017 SCN-2E added the DC-15 digest detail route; the remaining inventory is based on Sprint 20260714_002, tasks SVC-4/SVC-6).

This file is the Scanner WebService source-of-truth for endpoint registration intent and authorization posture.

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 active bounded owner seam; it does not accept generic carrier imports. MapOfflineKitEndpoints is therefore not an active or deferred Scanner endpoint map and must not be reintroduced. The same source cut removes the route-only MapObservabilityEndpoints because its sole backing store, OfflineKitMetricsStore, retires with the duplicate import plane; /metrics is not an active Scanner route. Scanner’s other instrumentation remains.

Captured openapi_* snapshots describe their capture-time route surface and are not current source authority. They remain unchanged until their owning regeneration/capture step; use Program.cs and this matrix for the current registration set.

Active endpoint maps (registered in Program.cs)

Webhook tenant contract (name routes)

• 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 using canonical and compatibility claim/header paths with conflict detection.
• Unknown queries are tenant-scoped by data access predicates (tenant_id::text = @tenantId) in the Scanner WebService query service.
• 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.
• SmartDiff routes (/api/v1/smart-diff/**) now resolve tenant context and pass it explicitly to material-change and VEX-candidate stores.
• SmartDiff persistence/retrieval paths are tenant-parameterized (material_risk_changes, vex_candidates), so candidate ID collisions across tenants resolve as deterministic not-found.
• 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 (not registered by design)