Signals API — Reachability Contract

Status: Working contract (aligns with src/Signals/StellaOps.Signals/Program.cs).

This document is the as-wired contract for the Stella Ops Signals service: it enumerates exactly the HTTP routes the Signals host registers in the request pipeline, the scopes each requires, and the routes that are defined in the assembly but not served. It is the authoritative companion to the Signals API reference, which presents the same surface in a more narrative form — when the two disagree, prefer this contract and the source it cites.

All routes are registered in Program.cs (minimal-API endpoints), CompatibilityApiV1Endpoints.cs, and ScmWebhookEndpoints.cs. URLs are lowercased (AddRouting(LowercaseUrls = true)).

Auth, scopes, sealed mode

• Scopes: signals:read, signals:write, signals:admin (endpoint-specific; see below). These map to SignalsPolicies.Read / .Write / .Admin in src/Signals/StellaOps.Signals/Routing/SignalsPolicies.cs, and to StellaOpsScopes.SignalsRead / SignalsWrite / SignalsAdmin in the canonical scope catalog. The compatibility endpoints under /api/v1/signals additionally accept orch:read (StellaOpsScopes.OrchRead) as an alternative to signals:read.
• Per-request authorization model: the /signals/** and /api/v1/signals endpoints do not use ASP.NET authorization filters/policies on the route. Instead each handler calls Program.TryAuthorize (single scope) or Program.TryAuthorizeAny (any-of scopes). An authenticated principal that lacks the required scope receives 403; an unauthenticated request receives 401 (unless the dev fallback applies — see below).
• Dev fallback: when Authority auth is disabled (Signals:Authority:Enabled=false) the service uses the Anonymous authentication handler and the handlers honour the Signals:Authority:AllowAnonymousFallback flag. When fallback is allowed, requests must include X-Scopes: <space-separated scopes> (example: X-Scopes: signals:write). AllowAnonymousFallback=true is rejected at startup outside the local-harness environment by SignalsRuntimeConfigurationValidator.
• Sealed mode (air-gap): controlled by Signals:AirGap:SealedMode (SignalsSealedModeMonitor). When enforcement is enabled and evidence is not compliant, most endpoints return 503 with { "error": "sealed-mode evidence invalid", "reason": "<detail>" }. Enforcement is a no-op when EnforcementEnabled is false.

Endpoints

Discovery, health & status

• GET /openapi/v1.json (anonymous) — OpenAPI 3.1 discovery document used by the gateway aggregator fan-out.
• GET /healthz (anonymous) — health check.
• GET /readyz (anonymous) — 503 with { "status": "sealed-mode-blocked", "reason": ... } when sealed-mode enforcement blocks readiness; 503 (no body) when not yet ready; otherwise 200 with { "status": "ready" }.
• GET /buildinfo (anonymous) — image-provenance/build-info endpoint mapped via BuildInfoEndpointExtensions.MapBuildInfoEndpoint (fallback module name signals), for the operator verify aggregator.
• GET /signals/ping (scope: signals:read, response: 204 No Content).
• GET /signals/status (scope: signals:read) — returns { service, version, sealedMode: { enforced, compliant, reason } }.

Callgraph ingestion & retrieval

• POST /signals/callgraphs (scope: signals:write)
  • Body: CallgraphIngestRequest. Required fields: language, component, version, artifactContentType, artifactFileName, artifactContentBase64. Optional: metadata, schemaVersion, analyzer.
  • Response: 202 Accepted with CallgraphIngestResponse (callgraphId, artifactPath, artifactHash, casUri, graphHash, manifestCasUri, schemaVersion, nodeCount, edgeCount, rootCount) and Location: /signals/callgraphs/{callgraphId}.
  • Graph hash is computed deterministically from normalized nodes/edges/roots; see graphHash in the response.
  • Validation failures return 400 (CallgraphIngestionValidationException, CallgraphParserNotFoundException, FormatException) or 422 (CallgraphParserValidationException).
• GET /signals/callgraphs/{callgraphId} (scope: signals:read) — 404 when not found.
• GET /signals/callgraphs/{callgraphId}/manifest (scope: signals:read) — returns the manifest file (application/json); 404 when the callgraph or manifest is missing.

Sample request: docs/api/signals/samples/callgraph-sample.json

Runtime facts ingestion

• POST /signals/runtime-facts (scope: signals:write)
  • Body: RuntimeFactsIngestRequest with subject, callgraphId, events[] (RuntimeFactEvent), and optional metadata.
  • Response: 202 Accepted with RuntimeFactsIngestResponse (factId, subjectKey, callgraphId, runtimeFactCount, totalHitCount, storedAt) and Location: /signals/runtime-facts/{subjectKey}.
• POST /signals/runtime-facts/ndjson (scope: signals:write)
  • Query parameters (RuntimeFactsStreamMetadata): callgraphId (required), plus optional scanId, imageDigest, component, version, purl.
  • Body: NDJSON of RuntimeFactEvent objects; Content-Encoding: gzip supported. An empty stream returns 400.
• POST /signals/runtime-facts/synthetic (scope: signals:write)
  • Generates a small deterministic sample set of runtime events for a callgraph to unblock testing.
  • Local-harness only: this route is registered only when SignalsRuntimeConfigurationValidator.IsSignalsLocalHarness is true (Development / TestingLocalHarness). It returns 404 in normal deployments.

Runtime observations ingestion (internal agent)

• POST /api/v1/runtime/observations (anonymous — see note)
  • Sprint 20260512_020 RO-RUN-003 unified runtime-evidence ingest, consumed by the deployment-observation agent over internal backend networking (trust at the network edge, not OAuth). The route is mapped AllowAnonymous() and does not require a signals:* scope.
  • Requires durable PostgreSQL persistence. When Signals runs without a configured Postgres connection string, the route is still mapped but returns 503 { "error": "runtime observation ingest requires durable PostgreSQL persistence." }.
  • Body: RuntimeObservationIngestRequest (tenantId GUID, agentId GUID, imageDigest sha256:..., containerName required; plus releaseId, hostId, containerId, containerName, imageRef, captureMode, capturedAt, containerLabels, processList, portBindings, metadata, userStack, kernelStack, stackCaptureMode). Missing/invalid tenantId/agentId/ imageDigest/containerName return 400.
  • Response: 202 Accepted with { factId, releaseId, imageDigest } and Location: /api/v1/runtime/observations/{factId}.

Unknowns ingestion, retrieval & query

• POST /signals/unknowns (scope: signals:write)
  • Body: UnknownsIngestRequest (subject, callgraphId, unknowns[] of UnknownSymbolEntry).
  • Response: 202 Accepted with UnknownsIngestResponse (subjectKey, unknownsCount) and Location: /signals/unknowns/{subjectKey}.
• GET /signals/unknowns/{subjectKey} (scope: signals:read) — returns the unknown entries for a subject; 404 when none.
• GET /signals/unknowns (scope: signals:read)
  • Query parameters: optional band (parsed against the UnknownsBand enum), limit (default 100, clamped 1–1000), offset (default 0).
  • Response: 200 with { items, count, limit, offset, band }.
• GET /signals/unknowns/{id}/explain (scope: signals:read)
  • Response: 200 with { id, subjectKey, band, score, normalizationTrace, flags, nextScheduledRescan, rescanAttempts, createdAt, updatedAt }; 404 when the id is unknown.

Reachability scoring & facts

• POST /signals/reachability/recompute (scope: signals:admin)
  • Body: ReachabilityRecomputeRequest (callgraphId, subject, entryPoints[], targets[], optional runtimeHits[], optional blockedEdges[] of ReachabilityBlockedEdge { from, to }, optional metadata).
  • Response: 200 OK with { id, callgraphId, subject, entryPoints, states, computedAt }. Validation failures return 400 (ReachabilityScoringValidationException); unknown callgraph returns 404 (ReachabilityCallgraphNotFoundException).
• GET /signals/facts/{subjectKey} (scope: signals:read)
  • Response: ReachabilityFactDocument (per-target states, score, riskScore, unknownsCount, unknownsPressure, optional uncertainty, optional runtimeFacts snapshot and runtimeFactsBatchUri/runtimeFactsBatchHash, optional edgeBundles, hasQuarantinedEdges); 404 when not found.

Sample fact: docs/api/signals/samples/facts-sample.json

Execution evidence

• POST /signals/execution-evidence (scope: signals:write)
  • Body: ExecutionEvidenceRequest (artifactId and environmentId required).
  • Response: 202 Accepted with the built evidence and Location: /signals/execution-evidence/{artifactId}/{environmentId}. Returns 400 when ids are missing, 422 when there are insufficient trace events or the pipeline is disabled, and 200 with { status: "rate_limited", ... } when rate-limited.

Beacon attestation

• POST /signals/beacons (scope: signals:write)
  • Body: BeaconIngestRequest (events[] — at least one required, else 400).
  • Response: 202 Accepted with the ingest response and Location: /signals/beacons.
• GET /signals/beacons/rate/{artifactId}/{environmentId} (scope: signals:read)
  • Response: 200 with the verification rate; 404 when no beacon data exists for the artifact/environment pair.

Reachability union bundle ingestion (CAS layout)

• POST /signals/reachability/union (scope: signals:write)
  • Body: application/zip bundle containing nodes.ndjson, edges.ndjson, meta.json. A non-application/zip Content-Type returns 400.
  • Optional header: X-Analysis-Id (defaults to a new GUID N format if omitted).
  • Response: 202 Accepted with ReachabilityUnionIngestResponse (analysisId, casRoot, files[] of { path, sha256, records }) and Location: /signals/reachability/union/{analysisId}/meta.
• GET /signals/reachability/union/{analysisId}/meta (scope: signals:read) — returns meta.json (application/json); 404 when missing.
• GET /signals/reachability/union/{analysisId}/files/{fileName} (scope: signals:read) — returns the requested file (application/json for *.json, otherwise application/x-ndjson); 404 when missing.

Compatibility surface (/api/v1/signals)

These return a fixed, in-memory deterministic sample dataset (operator/console compatibility) and accept either signals:read or orch:read.

• GET /api/v1/signals (scope: signals:read or orch:read)
  • Query parameters: optional type, status, provider, limit (default 50, clamped 1–200), cursor (numeric offset).
  • Response: 200 with { items, total, cursor }.
• GET /api/v1/signals/stats (scope: signals:read or orch:read)
  • Response: 200 with aggregate counts (total, byType, byStatus, byProvider, lastHourCount, successRate, avgProcessingMs).

SCM / CI webhooks

Anonymous endpoints (AllowAnonymous()); authentication is per-provider signature/token validation rather than Authority scopes. All are subject to sealed-mode enforcement.

• POST /webhooks/github — validates X-Hub-Signature-256 HMAC; reads X-GitHub-Event, X-GitHub-Delivery, optional X-Integration-Id/X-Tenant-Id.
• POST /webhooks/gitlab — validates X-Gitlab-Token; reads X-Gitlab-Event, X-Gitlab-Event-UUID.
• POST /webhooks/gitea — validates X-Hub-Signature-256 (falls back to X-Hub-Signature); reads X-Gitea-Event, X-Gitea-Delivery.

Responses: 202 Accepted with { eventId, eventType, provider, repository, triggersDispatched, scanTriggersCount, sbomTriggersCount } on success; 200 with a message when the event is ignored; 400/401 on validation failures.

Defined but not currently mapped

The following attribute-routed controllers exist in the Signals assembly but are not served by the Signals host as shipped: Program.cs never calls AddControllers() / MapControllers(), so these routes are not registered and return 404. They are documented here as forward/internal surface only — do not treat them as live API:

• RuntimeAgentController / RuntimeFactsController (route base api/v1/agents): POST /api/v1/agents/register, POST /api/v1/agents/{agentId}/heartbeat, GET /api/v1/agents/{agentId}, GET /api/v1/agents, DELETE /api/v1/agents/{agentId}, POST /api/v1/agents/{agentId}/commands, PATCH /api/v1/agents/{agentId}/posture, POST /api/v1/agents/{agentId}/facts.
• HotSymbolsController (route base api/v1/signals): GET /api/v1/signals/hot-symbols, GET /api/v1/signals/hot-symbols/top, GET /api/v1/signals/hot-symbols/stats, GET /api/v1/signals/hot-symbols/correlated.