Signal Contract Mapping: Advisory ↔ StellaOps

This document is the durable cross-walk between the reference advisory’s wire-level Signal contracts (10 / 12 / 14 / 16 / 18) and their concrete StellaOps implementations. It is written for architects and integrators who need to confirm that StellaOps fulfils each advisory signal, and to find the StellaOps entity, contract, or endpoint that does so.

Altitude note. This is an architectural mapping, not an API reference. It records which StellaOps construct fulfils each advisory signal and why the mapping holds — it deliberately does not restate every DTO field, enum member, or endpoint signature. For exact shapes, follow the src/ pointers; the code is the source of truth and this doc is reconciled against it in passes.

Overview

This document maps the reference advisory’s Signal-based message contracts (10/12/14/16/18) onto the StellaOps implementation. StellaOps uses domain-specific entity names instead of generic “Signal-X” labels; the table below is the durable cross-walk, and each section explains the equivalence.

Key Insight: StellaOps implements the same architectural patterns as the advisory but names entities after business concepts (Triage, Risk, Evidence, Decision) rather than wire-level signal numbers. This buys type safety, relational integrity, and domain clarity while preserving conceptual alignment.

Quick Reference Table

Advisory SignalStellaOps equivalentOwning module(s)Key types
Signal-10 (SBOM Intake)CallgraphIngestRequest, ISbomIngestionServiceScanner, SignalsCallgraphIngestRequest, ISbomIngestionService
Signal-12 (Evidence/Attestation)in-toto Statement + DSSEAttestor, SignerInTotoStatement, DsseEnvelope, PredicateTypes
Signal-14 (Triage Fact)TriageFinding + satellite entitiesScanner.TriageTriageFinding, TriageReachabilityResult, TriageRiskResult, TriageEffectiveVex
Signal-16 (Diff Delta)TriageSnapshot, MaterialRiskChange, DriftCauseScanner.SmartDiff, ReachabilityDriftMaterialRiskChangeDetector, ReachabilityDriftDetector, TriageSnapshot
Signal-18 (Decision)TriageDecision + DSSE signaturesScanner.TriageTriageDecision, TriageEvidenceArtifact

Signal-10: SBOM Intake

Advisory Specification

The advisory’s Signal-10 carries a CycloneDX 1.7 BOM, a subject (image + digest), a source, a scanProfile, and createdAt. Purpose: initial SBOM ingestion with subject identification.

StellaOps Implementation

Data flow:

[Scanner] → SbomIngestionService → [CycloneDxComposer/SpdxComposer]
                                        ↓
                                   PostgreSQL (scanner.sboms)
                                        ↓
                                   Event: "sbom.ingested"
                                        ↓
                                   [Downstream processors]

API surface (shape only — see route registrations for exact paths/verbs):

Equivalence: BOM content (CycloneDX 1.7), subject digest (ArtifactDigest, SHA-256), source/profile (Metadata + SbomIngestionOptions), and ingestion timestamp are all represented.

Signal-12: Evidence/Attestation (in-toto Statement)

Advisory Specification

Signal-12 is a DSSE-wrapped in-toto statement: subject.digest, statement type, predicateType, predicate, materials, tool, runId, and start/finish timestamps. Purpose: signed evidence envelopes.

StellaOps Implementation

Data flow:

[Component] → ProofChainSigner → [Build in-toto Statement]
                                       ↓
                                  Canonical JSON serialization
                                       ↓
                                  DSSE PAE construction
                                       ↓
                                  CryptoDsseSigner (KMS/Keyless)
                                       ↓
                                  DsseEnvelope (signed)
                                       ↓
                                  PostgreSQL (attestor.envelopes)
                                       ↓
                                  Optional: Rekor transparency log

Sample attestations: src/Attestor/StellaOps.Attestor.Types/samples/ (build-provenance.v1.json, vex-attestation.v1.json, scan-results.v1.json).

Equivalence: subject digests, in-toto statement type, predicate type + body, tool/run/timestamp metadata (carried inside the predicate), and full DSSE wrapping are all present.

Signal-14: Triage Fact

Advisory Specification

Signal-14 is the per-CVE triage fact: subject (purl), cve, stable findingId, location, reachability (status + call-stack ref), epss, cvss (version/vector/score), vexStatus, notes, and evidenceRefs.

StellaOps Implementation

The advisory’s single flat fact is normalised into a core entity plus four satellite entities (1:1 or 1:N), giving relational integrity and independent recompute/caching per component. All live under src/Scanner/__Libraries/StellaOps.Scanner.Triage/Entities/.

Database schema (table shape): scanner.triage_findings (core), with scanner.triage_reachability_results, scanner.triage_risk_results, scanner.triage_effective_vex (each 1:1) and scanner.triage_evidence_artifacts (1:N).

Equivalence: every advisory field maps onto a column or satellite entity — subject (AssetId+Purl), CveId, stable FindingId, location/evidence (TriageEvidenceArtifact), reachability, EPSS, CVSS, VEX status, notes (lattice explanation), and evidence refs.

Signal-16: Diff Delta

Advisory Specification

Signal-16 is the minimal delta between two SBOM snapshots: subject, fromVersion/toVersion, a changed set (packages/files/symbols/vulns), and explainableReasons (reason code + params + evidence refs).

StellaOps Implementation

API surface (shape only): smart-diff exposes per-scan change and SARIF 2.1.0 views plus a per-image VEX-candidate view under /smart-diff/…. See route registrations for exact paths.

Database schema (table shape): scanner.triage_snapshots, scanner.risk_state_snapshots, scanner.material_risk_changes, scanner.call_graph_snapshots.

Equivalence: subject, from/to version, changed packages (DiffJson), changed symbols (drift detection), changed vulns (material risk changes), explainable reasons (DriftCause.Kind), and evidence refs are all represented.

Signal-18: Decision

Advisory Specification

Signal-18 is a policy decision: subject, decisionId, severity, priority, rationale[], actions[], and dsseSignatures[].

StellaOps Implementation

The decision splits across two entities: the act of deciding (TriageDecision) and the scoring that severity/priority/actions derive from (TriageRiskResult).

Database schema (table shape): scanner.triage_decisions (+ scanner.triage_risk_results for severity/priority).

API surface (shape only): create / revoke / list-by-finding under /triage/decisions and /triage/findings/{findingId}/decisions. See route registrations for exact paths/verbs.

Equivalence: subject (via FindingId), DecisionId, severity (Lane), priority (RiskScore), rationale (Reason + lattice explanation), actions (Verdict), and DSSE signatures are all represented.

Idempotency Key Handling

Advisory Pattern

idemKey = hash(subjectDigest || type || runId || cve || windowStart)

StellaOps Implementation

StellaOps achieves the same dedup guarantee through two mechanisms rather than one global hash:

Equivalence: subject digest (in scanId/AssetId), type (EventKind), run id (correlation/trace + attempt), CVE (in the finding id), and window (scan/job timing) are all folded into the dedup keys.

Evidence Reference Mechanisms

Advisory Pattern

evidenceRefs[i] = dsse://sha256:<payloadHash>

DSSE payloads stored as blobs, indexed by payloadHash and subjectDigest.

StellaOps Implementation

StellaOps uses content-addressable storage with two reference schemes:

These are surfaced on:

Storage:

Equivalence: hash-addressed storage (SHA-256/BLAKE3), DSSE references, cas:// URIs, S3-compatible blob store, and subject indexing (via FindingId) all map onto the advisory pattern.

API Endpoint Mapping

The advisory’s flat endpoints map onto namespaced StellaOps routes. Paths below are the shape of the surface; treat the OpenAPI spec (src/Api/StellaOps.Api.OpenApi/stella.yaml) and the route registrations as authoritative for exact verbs and paths.

SignalAdvisory EndpointStellaOps surface (shape)
Signal-10POST /sbom/intake/api/scanner/sboms/…, /api/signals/callgraph/…
Signal-12POST /attestationsimplicit via signing services; /api/attestor/envelopes/{hash}
Signal-14GET /triage/facts/{findingId}/api/scanner/triage/findings/{findingId} (+ /evidence)
Signal-16GET /diff/{from}/{to}/api/smart-diff/scans/{scanId}/changes, /api/smart-diff/images/{digest}/candidates
Signal-18POST /decisions/api/triage/decisions, /api/triage/findings/{findingId}/decisions

Component Architecture Alignment

Advisory Architecture

[ Sbomer ] → Signal-10 → [ Router ]
[ Attestor ] → Signal-12 → [ Router ]
[ Scanner.Worker ] → Signal-14 → [ Triage Store ]
[ Reachability.Engine ] → updates Signal-14
[ Smart-Diff ] → Signal-16 → [ Router ]
[ Deterministic-Scorer ] → Signal-18 → [ Router/Notify ]

StellaOps Architecture

[ Scanner.Emit ] → SbomIngestionService → PostgreSQL (scanner.sboms)
[ Attestor.ProofChain ] → DsseEnvelopeSigner → PostgreSQL (attestor.envelopes)
[ Scanner.Triage ] → TriageFinding + related entities → PostgreSQL (scanner.triage_*)
[ ReachabilityAnalyzer ] → PathWitnessBuilder → TriageReachabilityResult
[ SmartDiff + ReachabilityDrift ] → MaterialRiskChangeDetector → TriageSnapshot
[ Policy.Scoring engines ] → ScoreExplanationService → TriageRiskResult + TriageDecision
[ Router.Gateway ] → TransportDispatchMiddleware → Inter-service routing
[ TimelineIndexer ] → TimelineEventEnvelope → Event ordering & storage

Mapping:

Summary

Alignment Status: Fully aligned (conceptually).

StellaOps uses domain-specific entity names instead of generic “Signal-X” labels, but every advisory signal concept has an implemented equivalent:

Why the StellaOps shape: strong entity types over generic JSON blobs, PostgreSQL referential integrity, indexed lookups, business-concept naming, and additive extensibility.

References

StellaOps Code Files

API Contract

Advisory References

StellaOps Documentation