Witness Schema v1 Contract

Version: stellaops.witness.v1
Status: Active (implemented)
Sprint: SPRINT_3700_0001_0001_witness_foundation

Overview

Audience: engineers producing, consuming, or verifying Stella Ops reachability witnesses (Scanner, Attestor, CLI, and Evidence Locker integrators).

A witness is a cryptographically-signed proof of a reachability path from an entrypoint to a vulnerable sink. Witnesses provide:

1. Auditability - Proof that a path was found at scan time
2. Offline verification - Verify claims without re-running analysis
3. Provenance - Links to the source graph and analysis context
4. Transparency - Can be published to transparency logs

Two representations

This contract describes two related-but-distinct on-disk shapes. Do not confuse them:

1. Wire / DSSE payload schema (stellaops.witness.v1) — the canonical signed payload produced and consumed by the Scanner. This is the authoritative runtime shape. Modelled by StellaOps.Scanner.Reachability.Witnesses.PathWitness (snake_case JSON). This is the signed payload inside a persisted witness record, not the record or verification response wrapper.
2. In-toto predicate JSON Schema (stellaops-path-witness.v1.schema.json) — a separate draft JSON Schema used by the Attestor for predicate validation. It uses a UUID witness_id, a separate witness_hash, a provenance block, a nested path.{entrypoint,sink,steps,hop_count} structure, and cas://-style evidence_uris. These fields are NOT present in the wire schema.

Scanner’s record API returns WitnessResponseDto: a camelCase wrapper containing the persisted record GUID witnessId, witnessHash, scan/run and signature metadata, the nested payload, and nullable dsseEnvelope. Lists return { witnesses, totalCount }; verification returns the separate WitnessVerificationResponseDto with status, error and verification metadata. The nested payload’s witness_id is not the persisted record GUID. CLI JSON for Scanner records retains these wrappers; list output additionally marks the public reachability verdict unknown because the record does not supply one. These response contracts are defined in src/Scanner/StellaOps.Scanner.WebService/Endpoints/WitnessEndpoints.cs and shown in the scoped owner reference.

The same field-shape divergence is reflected in storage: the scanner.witnesses table (see Storage) persists predicate-style columns (witness_hash, witness_type, graph_hash, scan_id, run_id, entrypoint_fqn, sink_cve, created_at) in addition to the full wire payload in payload_json.

Sections below are labelled with which representation they describe.

Schema Definition — wire / DSSE payload (stellaops.witness.v1)

Source of truth: src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Witnesses/PathWitness.cs and WitnessSchema.cs. This is the shape that is DSSE-signed, stored in scanner.witnesses.payload_json, and exposed as the nested payload in Scanner record API and CLI responses. This payload uses snake_case JSON; the outer record wrapper uses camelCase.

{
  "witness_schema": "stellaops.witness.v1",
  "witness_id": "wit:sha256:abcd1234...",
  "artifact": {
    "sbom_digest": "sha256:...",
    "component_purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1"
  },
  "vuln": {
    "id": "CVE-2021-44228",
    "source": "NVD",
    "affected_range": "<2.15.0"
  },
  "entrypoint": {
    "kind": "http",
    "name": "GET /api/users/{id}",
    "symbol_id": "com.example.MyController.handleRequest"
  },
  "path": [
    {
      "symbol": "MyController.handleRequest",
      "symbol_id": "com.example.MyController.handleRequest",
      "file": "src/main/java/com/example/MyController.java",
      "line": 45,
      "column": null
    },
    {
      "symbol": "LoggingService.logMessage",
      "symbol_id": "com.example.LoggingService.logMessage",
      "file": "src/main/java/com/example/LoggingService.java",
      "line": 23
    },
    {
      "symbol": "Logger.log",
      "symbol_id": "org.apache.log4j.Logger.log",
      "file": null,
      "line": null
    }
  ],
  "sink": {
    "symbol": "Logger.log",
    "symbol_id": "org.apache.log4j.Logger.log",
    "sink_type": "deserialization"
  },
  "gates": [
    {
      "type": "AuthRequired",
      "guard_symbol": "com.example.MyController.requireAuth",
      "confidence": 0.92,
      "detail": "Requires authenticated user"
    }
  ],
  "evidence": {
    "callgraph_digest": "blake3:...",
    "surface_digest": "sha256:...",
    "analysis_config_digest": "sha256:...",
    "build_id": "gnu-build-id:..."
  },
  "observed_at": "2025-12-18T12:00:00Z",
  "path_hash": "path:sha256:...",
  "node_hashes": ["sha256:...", "sha256:..."],
  "evidence_uris": ["evidence:callgraph:blake3:...", "evidence:sbom:sha256:..."],
  "predicate_type": "https://stella.ops/predicates/path-witness/v1",
  "observation_type": 0,
  "claim_id": null,
  "observations": null,
  "symbolization": null
}

Field Definitions — wire schema

Root Fields

There is no witness_hash, witness_type, provenance, created_at, or hop_count field in the wire schema. Those fields belong to the in-toto predicate / storage row only (see below).

artifact

vuln

entrypoint

Path Step (path[])

The wire PathStep has no index, call_site, or edge_type field — those exist only in the in-toto predicate’s pathStep definition.

sink

Gates (gates[])

Optional array of detected guards/mitigating controls along the path.

evidence

In-toto predicate JSON Schema (separate artifact)

Source of truth: src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-path-witness.v1.schema.json ($id https://stella.ops/schemas/predicates/path-witness/v1).

This draft-2020-12 JSON Schema is used by the Attestor for predicate validation and has a different shape than the wire payload. It is the origin of the historical example previously shown in this document. Its required fields are witness_id, witness_hash, provenance, path.

{
  "witness_id": "uuid",
  "witness_hash": "sha256:abcd1234...  (pattern ^(blake3|sha256):[a-f0-9]{64}$)",
  "witness_type": "reachability_path  (enum: reachability_path | gate_proof; default reachability_path)",
  "provenance": {
    "graph_hash": "sha256:efgh5678...  (required)",
    "scan_id": "uuid",
    "run_id": "uuid",
    "analyzer_version": "1.0.0  (required)",
    "analysis_timestamp": "2025-12-18T11:59:00Z  (required)"
  },
  "path": {
    "entrypoint": { "fqn": "...", "kind": "http_handler", "location": {"file": "...", "line": 42}, "node_hash": "sha256:..." },
    "sink": { "fqn": "...", "cve": "CVE-2021-44228", "package": "pkg:maven/...", "node_hash": "sha256:..." },
    "steps": [
      { "index": 0, "fqn": "...", "call_site": "...:45", "edge_type": "call", "node_hash": "sha256:..." }
    ],
    "hop_count": 3,
    "path_hash": "sha256:...",
    "node_hashes": ["sha256:..."]
  },
  "gates": [
    { "type": "auth_required", "location": "MyController.java:40", "description": "Requires authenticated user" }
  ],
  "evidence": {
    "graph_fragment_hash": "sha256:ijkl9012...",
    "path_hash": "sha256:mnop3456..."
  },
  "evidence_uris": {
    "graph": "cas://sha256:...",
    "sbom": "cas://sha256:...",
    "attestation": "cas://sha256:...",
    "rekor": "https://rekor.sigstore.dev/..."
  }
}

Predicate enum domains (from the JSON Schema):

Hash patterns in the predicate schema accept either blake3: or sha256: prefixes (^(blake3\|sha256):[a-f0-9]{64}$), except path.path_hash, node_hashes, and *.node_hash which are ^sha256:[a-f0-9]{64}$ only.

Witness ID (content addressing)

The wire witness_id is a content address, not a UUID. It is computed by PathWitnessBuilder.ComputeWitnessId over a fixed subset of fields:

1. Build a canonical projection containing exactly: witness_schema, artifact, vuln, entrypoint, path, sink, evidence (snake_case, no indentation, Web defaults). Note this projection excludes gates, observed_at, path_hash, node_hashes, evidence_uris, predicate_type, and the runtime fields.
2. Hash the UTF-8 bytes via ICryptoHash.ComputePrefixedHashForPurpose(json, HashPurpose.Content). The default compliance profile maps HashPurpose.Content to SHA-256 (prefix sha256:); the FIPS profile is also SHA-256.
3. Prefix the result with wit: (WitnessSchema.WitnessIdPrefix).

Result format: wit:sha256:<64-hex>.

var canonical = new {
    witness.WitnessSchema, witness.Artifact, witness.Vuln,
    witness.Entrypoint, witness.Path, witness.Sink, witness.Evidence
};
var json = JsonSerializer.SerializeToUtf8Bytes(canonical, jsonOptions);
var hash = _cryptoHash.ComputePrefixedHashForPurpose(json, HashPurpose.Content); // "sha256:<hex>"
var witnessId = $"{WitnessSchema.WitnessIdPrefix}{hash}";                         // "wit:sha256:<hex>"

The separate witness_hash value (predicate / storage column) follows the predicate schema pattern ^(blake3|sha256):[a-f0-9]{64}$ and is a hash of the canonical witness payload. It is distinct from witness_id. There is no BLAKE3-over-the-whole-witness-excluding-created_at recipe in the implementation. The Scanner producer (see Producer) computes it over the complete canonical payload bytes, the DSSE payload WitnessDsseSigner signs, with the content hash of the active crypto profile (sha256: by default). Because that payload includes observed_at, two runs that build the same witness (same witness_id) at different times store different witness_hash values.

DSSE Constants

Sprint: SPRINT_3700_0001_0001 (WIT-007C)

The following constants are used for DSSE envelope creation and verification:

Note: the legacy short form stella.ops/pathWitness@v1 and the URL variant https://stella.ops/pathWitness/v1 were deleted 2026-09-02 (P8-14, S2.11) - WitnessSchema.PredicateType now equals the canonical URI, matching what PathWitnessBuilder has always emitted. The DSSE payloadType written by WitnessDsseSigner is WitnessSchema.DssePayloadType (application/vnd.stellaops.witness.v1+json), not an in-toto predicate type. WitnessSchema.JsonSchemaUri (https://stellaops.org/schemas/witness-v1.json) is the wire-schema URI and is distinct from the in-toto predicate schema $id https://stella.ops/schemas/predicates/path-witness/v1.

Witness Types

Defined as WitnessSchema.WitnessTypeReachabilityPath / WitnessTypeGateProof. These values populate the storage witness_type column and the in-toto predicate witness_type enum. The wire PathWitness record itself has no witness_type field — it always represents a reachability path.

Canonical Predicate Type and Aliases

Sprint: SPRINT_20260112_004_SCANNER_path_witness_nodehash
Sprint: SPRINT_20260112_008_DOCS_path_witness_contracts (PW-DOC-001)

The canonical predicate type for path witnesses is:

https://stella.ops/predicates/path-witness/v1

The alias forms (stella.ops/pathWitness@v1 legacy short form, https://stella.ops/pathWitness/v1 URL variant) were deleted 2026-09-02 (SPRINT_20260824_010 P8-14, S2.11): producers always emitted the canonical form, so the alias acceptance had no producer. Consumers accept the canonical type only.

Node Hash Recipe

Canonical node hash recipe for deterministic static/runtime evidence joining.

Recipe

NodeHash = SHA256(normalize(PURL) + ":" + normalize(SYMBOL_FQN))

Output format: sha256:<64-hex-chars>

PURL Normalization Rules

1. Lowercase scheme (pkg:)
2. Lowercase type (e.g., NPM -> npm)
3. Preserve namespace/name case (some ecosystems are case-sensitive)
4. Sort qualifiers alphabetically by key
5. Remove trailing slashes
6. Normalize empty version to unversioned

Symbol FQN Normalization Rules

1. Trim whitespace
2. Normalize multiple dots (..) to single dot
3. Normalize signature whitespace: (type,type) -> (type, type)
4. Empty signatures become ()
5. Collapse the module-level placeholder ._. to .

Caveats (matching the current NodeHashRecipe code, not just its XML comments): rules 5/6 above are partial. NormalizePurl lowercases the scheme and type and sorts qualifiers, but does not substitute an empty version with unversioned (despite the doc-comment). NormalizeSymbolFqn collapses the literal ._. placeholder rather than stripping bare _ type placeholders.

Example

Input:
  PURL: pkg:npm/lodash@4.17.21
  Symbol: lodash.merge(object, object)

Normalized Input:
  "pkg:npm/lodash@4.17.21:lodash.merge(object, object)"

Output:
  sha256:a1b2c3d4e5f6... (64 hex chars)

Implementation

See src/__Libraries/StellaOps.Reachability.Core/NodeHashRecipe.cs (NodeHashRecipe.ComputeHash / NormalizePurl / NormalizeSymbolFqn). The normalization rules above describe this canonical recipe.

Divergence warning: PathWitnessBuilder does not call NodeHashRecipe. Its private ComputeNodeHash uses a simplified normalization — it lowercases the entire PURL (purl.Trim().ToLowerInvariant()) and does not sort qualifiers or expand empty versions — then hashes SHA256(normalizedPurl + ":" + symbolFqn.Trim()). The two recipes can therefore produce different node hashes for the same input. The canonical NodeHashRecipe is the intended long-term recipe; the builder’s inline variant is the value actually emitted in PathWitness.node_hashes today.

Path Hash Recipe

Canonical path hash recipe for deterministic path fingerprinting.

Recipe

PathHash = SHA256(nodeHash1 + ">" + nodeHash2 + ">" + ... + nodeHashN)

The > separator represents directed edges in the path.

Top-K Selection

For efficiency, witnesses include a top-K subset of node hashes:

1. Take first K/2 nodes (entry points)
2. Take last K/2 nodes (exit/vulnerable points)
3. Deduplicate while preserving order
4. Default K = 10

PathFingerprint Fields

The PathFingerprint record (PathHashRecipe.CreateFingerprint) carries:

PathFingerprint is an in-memory record only; it is not embedded as a path_fingerprint object in the witness JSON. The witness instead carries the flat path_hash and node_hashes fields.

Implementation

See src/__Libraries/StellaOps.Reachability.Core/PathHashRecipe.cs (PathHashRecipe.ComputeHash / ComputeWithTopK / CreateFingerprint).

Divergence warning: the >-separated recipe above is the canonical PathHashRecipe, but the path_hash actually emitted on a PathWitness is produced by PathWitnessBuilder’s private ComputeCombinedPathHash, which uses a different recipe: "path:sha256:" + SHA256(hexPart1 + ":" + hexPart2 + ... ) — i.e. a path:sha256: prefix and a : separator over the hex parts of each node hash (not the > directed-edge separator, and not the bare sha256: prefix). The builder also computes node hashes over all path steps for the path hash, while exposing only the deduplicated top-K (sorted, K=10) in node_hashes.

Evidence URI Fields

There are two distinct evidence-URI conventions; do not mix them.

Wire schema — evidence_uris (flat string array)

In the wire payload, evidence_uris is an array of strings built by PathWitnessBuilder.BuildEvidenceUris. Each entry uses the evidence:<kind>:<value> scheme and is emitted only when the corresponding request field is present:

{
  "evidence_uris": [
    "evidence:callgraph:blake3:abc123...",
    "evidence:sbom:sha256:def456..."
  ]
}

In-toto predicate schema — evidence_uris (object with cas://)

The predicate JSON Schema (stellaops-path-witness.v1.schema.json) instead defines evidence_uris as an object whose graph/sbom/attestation values match ^cas://sha256:[a-f0-9]{64}$ and whose rekor value is a free-form URI:

{
  "evidence_uris": {
    "graph": "cas://sha256:abc123...",
    "sbom": "cas://sha256:def456...",
    "attestation": "cas://sha256:ghi789...",
    "rekor": "https://rekor.sigstore.dev/api/v1/log/entries/abc123def456"
  }
}

There are no graph_uri / sbom_uri / attestation_uri / rekor_uri scalar fields anywhere in the implementation.

stella:// evidence URIs (separate builder)

StellaOps.Reachability.Core.EvidenceUriBuilder produces a third, unrelated URI scheme used for ReachGraph/runtime-fact references — stella://reachgraph/<digest>, stella://signals/runtime/<tenant>/<digest>, stella://cvemap/<cve>, stella://attestation/<digest>, stella://hybrid/<digest> — not cas:// and not the witness evidence: scheme.

Runtime Symbolization Tuple

Runtime witnesses — those whose observation_type is Runtime (1) or Confirmed (2), i.e. anything other than Static (0), or that carry a non-empty observations array — must include a deterministic symbolization tuple. This is enforced by PathWitness.ValidateDeterministicSymbolization, which WitnessDsseSigner calls before signing and during verification (a runtime witness with a missing or invalid symbolization tuple fails both signing and verification):

{
  "symbolization": {
    "build_id": "gnu-build-id:...",
    "debug_artifact_uri": "cas://symbols/by-build-id/.../artifact.debug",
    "symbol_table_uri": "cas://symbols/by-build-id/.../symtab.json",
    "symbolizer": {
      "name": "llvm-symbolizer",
      "version": "18.1.7",
      "digest": "sha256:..."
    },
    "libc_variant": "glibc",
    "sysroot_digest": "sha256:..."
  }
}

Validation rules:

1. build_id, symbolizer.name, symbolizer.version, symbolizer.digest, libc_variant, and sysroot_digest are required.
2. At least one of debug_artifact_uri or symbol_table_uri must be present.
3. Missing runtime symbolization inputs must fail witness signing/verification validation.
4. Runtime observation arrays must be canonicalized before witness hashing/signing (stable sort by timestamp and deterministic tiebreakers) so equivalent inputs produce byte-identical DSSE payloads.

Runtime Witness Artifact Triplet (MWD-004)

Source of truth: src/EvidenceLocker/__Libraries/StellaOps.EvidenceLocker.Export/Models/BundleManifest.cs (ArtifactEntry, RuntimeWitnessIndexKey, RuntimeWitnessArtifactRoles, BundlePaths, BundleMediaTypes).

Runtime witnesses exported through Evidence Locker use a deterministic three-file profile, stored under the bundle’s runtime-witnesses/ directory (BundlePaths.RuntimeWitnessesDirectory) and indexed via the manifest’s runtimeWitnesses array:

1. trace.json - canonical witness payload (media type application/vnd.stellaops.witness.v1+json)
2. trace.dsse.json - DSSE envelope over trace.json (media type application/vnd.dsse.envelope+json)
3. trace.sigstore.json - Sigstore bundle for offline replay (media type application/vnd.dev.sigstore.bundle.v0.3+json)

Each manifest ArtifactEntry links to:

• witnessId
• witnessRole — one of trace, dsse, sigstore_bundle (RuntimeWitnessArtifactRoles)
• witnessIndex — the deterministic replay lookup keys (RuntimeWitnessIndexKey):
  • buildId
  • kernelRelease
  • probeId
  • policyRunId
• linkedArtifacts — paths of the sibling triplet files

(Field names above are the JSON property names; C# uses PascalCase, e.g. WitnessRole.)

Offline verification must use only bundle-contained artifacts; no network lookups are required for triplet integrity checks.

Cross-Distro Replay Matrix Verification (MWD-005)

Deterministic replay verification must include a minimum matrix of:

1. Three kernel releases.
2. Both glibc and musl libc variants.
3. Fixed witness artifacts replayed across matrix rows with byte-identical replay-frame output.

QA evidence for MWD-005 was intended to be captured at:

• docs/qa/feature-checks/runs/signals/ebpf-micro-witness-determinism/run-001/tier2-replay-matrix-tests.log
• docs/qa/feature-checks/runs/signals/ebpf-micro-witness-determinism/run-001/tier2-replay-matrix-summary.json

Status — evidence pending. Neither file exists in the repository yet, and the ebpf-micro-witness-determinism/run-001/ directory is absent. The feature is documented at docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md and docs/product/ebpf-micro-witness-determinism.md, but the cited replay-matrix run artifacts have not yet been produced. Treat the matrix requirement as a roadmap target until the evidence lands.

DSSE Signing

Witnesses are signed by WitnessDsseSigner.SignWitness using DSSE (Dead Simple Signing Envelope). The payload is the witness serialized via CanonJson.Canonicalize with snake_case naming, no indentation, and null-omission (DefaultIgnoreCondition.WhenWritingNull). The signature is produced over the DSSE PAE by the shared EnvelopeSignatureService and stored base64 (standard, via Convert.ToBase64String):

{
  "payloadType": "application/vnd.stellaops.witness.v1+json",
  "payload": "<base64-encoded canonical witness JSON>",
  "signatures": [
    {
      "keyid": "<signing key id>",
      "sig": "<base64-encoded signature>"
    }
  ]
}

Verification

WitnessDsseSigner.VerifyWitness performs, in order:

1. Check payloadType equals application/vnd.stellaops.witness.v1+json (else reject).
2. Deserialize the payload into PathWitness.
3. Check witness_schema equals stellaops.witness.v1 (else reject as unsupported schema).
4. Run ValidateDeterministicSymbolization() — runtime/confirmed witnesses must carry a valid symbolization tuple.
5. Locate the signature whose keyid matches the supplied public key, then verify it via EnvelopeSignatureService.VerifyDsse.

Verification does not recompute witness_hash or witness_id; it validates payload type, schema version, symbolization, and the signature. Transparency-log inclusion is out of scope of the signer/verifier and is not performed here.

Storage

Source of truth: src/Scanner/__Libraries/StellaOps.Scanner.Persistence/Migrations/001_scanner_consolidated_baseline.sql (table), 013_tenant_qualify_witnesses.sql (tenant column, per-tenant uniqueness and lookup indexes) and 014_witness_scan_id_text.sql (the scan id as the Scanner scan id text), applied by Scanner Web on startup. All three are idempotent.

Witnesses are stored in the scanner.witnesses table. Note this row uses the predicate-style fields (witness_hash, witness_type, graph_hash, created_at) alongside the full wire payload:

Indexes: ix_witnesses_tenant_scan_id and ix_witnesses_tenant_sink_cve (both partial, on tenant_id then the lookup column and created_at DESC), ix_witnesses_tenant_graph_hash, ix_witnesses_entrypoint (partial), ix_witnesses_created_at (DESC), and a GIN index ix_witnesses_payload_gin on payload_json.

Tenant boundary. Every repository statement (PostgresWitnessRepository) names the tenant: reads by id, hash, scan, CVE or graph hash return only that tenant’s witnesses, and signing updates and verification records apply only to a witness the tenant owns. Two tenants that scan the same bytes may each hold a witness with the same witness_hash. Migration 013 attributes rows written before it from the exact scanner.scan_runtime_state tenant of their scan, then the sole tenant observed in Scanner history (or default when none is observed), and aborts rather than guess when several tenants are observed.

A companion audit table scanner.witness_verifications records each verification attempt (verification_id, witness_id FK, verified_at, verified_by, verification_status, verification_error, verifier_key_id).

Producer

Source of truth: src/Scanner/StellaOps.Scanner.Worker/Processing/Reachability/ReachabilityWitnessRecorder.cs, ReachabilityWitnessStageExecutor.cs and ScanReachabilityEvidenceJobProcessor.cs (same folder).

The Scanner worker writes scanner.witnesses; no other service and no API route does.

• When. The scan’s reachability-evidence stage runs the reachability evidence job for every CVE and component with a sink mapping, and the job builds one PathWitness per entrypoint-to-sink path it finds (ReachabilityEvidenceJobResult.Witnesses; the public verdict object references the same witnesses by witness_id and path_hash). The publish-evidence stage then stores them. The on-demand scan-level job (the scan’s compute-reachability route) stores the witnesses of its completed child jobs the same way. A job that finds no path builds no witness, so a scan without reachability evidence stores no row.
• Tenant and scan. The tenant is the one Scanner records for the scan in scanner.scan_runtime_state, the tenant the scan read routes authorize against; job lease metadata is not consulted. scan_id is the scan’s own id. A scan without a recorded tenant stores no witness and the worker logs a warning; no tenant is guessed or defaulted.
• Row. payload_json holds the canonical wire payload (the bytes WitnessDsseSigner signs), witness_hash the content hash over those bytes (see Witness ID), witness_type reachability_path, graph_hash the payload’s evidence.callgraph_digest, entrypoint_fqn the entrypoint name, sink_cve the vulnerability id and created_at the witness observed_at. Rows are stored unsigned (dsse_envelope NULL): the scan path holds no witness signing key, and the verify route reports such a witness as unsigned.
• Idempotency. Recording is idempotent per tenant and scan: a witness whose witness_id the scan already holds is not stored again, so a re-run of the same scan adds only witnesses it has not recorded and removes none.
• Failure. A storage failure fails the publish-evidence stage (the scan is retried or failed like any other evidence write) or, for the on-demand job, marks that job failed with the reason; it is never reported as success.
• Limit. Under a fixed worker clock (Determinism.FixedClock), two scans of the same image build byte-identical witnesses; the per-tenant hash uniqueness then keeps the row of the first scan, and the later scan does not list it under its own scan id.
• Limit: re-runs under one scan id. Recording never removes a row, and run_id stays NULL. The scan id is derived from the submission (tenant, reference, digest, force flag, client request id and metadata), and a forced resubmission of an existing scan id runs that scan again under the same id. When the new run builds a different set of witnesses (for example a tag-only reference whose tag now names other bytes, or a run that no longer finds a path), the earlier run’s witnesses stay listed under the same scanId next to the new ones, while the scan’s evidence projection and public verdict show only the latest run. The payload’s artifact.sbom_digest and observed_at tell the runs apart.

API Endpoints

Source of truth: src/Scanner/StellaOps.Scanner.WebService/Endpoints/WitnessEndpoints.cs, mounted under the API base path /api/v1 (ScannerWebServiceOptions.Api.BasePath). All endpoints require the scanner.scans.read authorization policy (ScannerPolicies.ScansRead) and are scoped to the caller’s tenant.

Every route resolves the tenant from the validated stellaops:tenant claim (a global-admin principal may select a tenant with the canonical X-StellaOps-TenantId header). A request without a tenant claim returns HTTP 400 Invalid tenant with detail tenant_missing; no default tenant is assumed. A witness id, witness hash, scanId, cve or graphHash of another tenant answers like an unknown one: the list is empty and the single-witness and verify routes return 404, and no verification row is recorded.

The list endpoint returns an empty list when none of scanId / cve / graphHash is supplied (it deliberately avoids a full-table scan). The path parameter is the DB-row UUID witnessId, and the list query parameter is scanId (not scan). There is no create operation in this witness endpoint group — witnesses are produced by the Scanner pipeline, not created over the API (see Producer). scanId is the Scanner scan id (scanner.scan_runtime_state.scan_id, 40 lower-case hex characters for a submitted scan, the id the scan routes take), not a UUID; it is compared trimmed and case-sensitively, and a blank value returns HTTP 400 Invalid scan identifier.

Authorization

The witness endpoints reuse the Scanner read policy scanner.scans.read. There are no witness-specific scopes in the canonical scope catalog (src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs), which defines Scanner scopes such as scanner:read, scanner:scan, scanner:export, and scanner:write. The scanner.scans.read policy/scope name is a Scanner-local constant (ScannerPolicies.ScansRead / ScannerAuthorityScopes.ScansRead) and is not present in the canonical StellaOpsScopes catalog.

CLI

The record/CLI boundary described here was source-checked against 26de00a315978e56c11b562fa2f1df0a85c17310 on 2026-10-14. Re-verify with pwsh tools/scripts/test-targeted-xunit.ps1 -Project src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj -Class '*WitnessOwnerContractTests' -BuildProjectReferences -MaxThreads 1.

stella reachability witness-ops wraps Scanner’s persisted-record API through WitnessCommandGroup.cs and CommandHandlers.Witness.cs. Its list command requires exactly one of --scan, --vuln or --graph-hash. Scan IDs are opaque text; show and verify take the persisted record GUID. Supported requests use canonical scanner:read and the existing CLI tenant resolver.

Verdict/tier, reachable-only, probe-type and paging options are unsupported and return non-success before requests. Verification is online through the owner, records verification history, and returns success only for a coherent owner valid result. Offline/public-key modes and the discoverable export command return exit 9 before requests, key access or output-file creation. No JSON, DSSE or SARIF download is produced. Source tests do not authorize a live verification request.

The separate top-level stella witness group operates on binary micro-witness files and is not this API wrapper. See the Scanner witness-record guide for supported output, identity and refusal behavior.

Related Documents

• Rich Graph Contract
• DSSE Specification
• BLAKE3 Hash Function