Scanner SBOM and Attestation Hot Lookup Profile

Version: 0.2.0 Status: Active Last Updated: 2026-06-05

Purpose

Define a Stella-compatible persistence profile for fast SBOM/attestation lookup queries in PostgreSQL without moving full replay/audit payloads out of CAS/object storage.

Scope

This profile covers:

This profile does not replace:

Current Baseline (confirmed)

Advisory Fit Assessment

Aligned with current direction:

Gap requiring implementation:

Target Contract

1) Authoritative storage split

2) Hot lookup table

Create a new append-only projection table:

CREATE TABLE scanner.artifact_boms (
  build_id TEXT NOT NULL,
  canonical_bom_sha256 TEXT NOT NULL,
  payload_digest TEXT NOT NULL,
  inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),

  raw_bom_ref TEXT,
  canonical_bom_ref TEXT,
  dsse_envelope_ref TEXT,
  merged_vex_ref TEXT,

  canonical_bom JSONB,
  merged_vex JSONB,
  attestations JSONB,

  evidence_score INTEGER NOT NULL DEFAULT 0,
  rekor_tile_id TEXT,

  PRIMARY KEY (build_id, inserted_at)
) PARTITION BY RANGE (inserted_at);

Partition policy:

3) Index profile

Required:

CREATE INDEX IF NOT EXISTS ix_artifact_boms_payload_digest
  ON scanner.artifact_boms (payload_digest, inserted_at DESC);

CREATE INDEX IF NOT EXISTS ix_artifact_boms_canonical_sha
  ON scanner.artifact_boms (canonical_bom_sha256);

CREATE INDEX IF NOT EXISTS ix_artifact_boms_inserted_at
  ON scanner.artifact_boms (inserted_at DESC);

CREATE INDEX IF NOT EXISTS ix_artifact_boms_canonical_gin
  ON scanner.artifact_boms USING GIN (canonical_bom jsonb_path_ops);

CREATE INDEX IF NOT EXISTS ix_artifact_boms_merged_vex_gin
  ON scanner.artifact_boms USING GIN (merged_vex jsonb_path_ops);

Optional partial index for pending triage:

CREATE INDEX IF NOT EXISTS ix_artifact_boms_pending_vex
  ON scanner.artifact_boms USING GIN (merged_vex jsonb_path_ops)
  WHERE jsonb_path_exists(merged_vex, '$[*] ? (@.state == "unknown" || @.state == "triage_pending")');

Uniqueness guard (optional):

CREATE UNIQUE INDEX IF NOT EXISTS uq_artifact_boms_monthly_dedupe
  ON scanner.artifact_boms (canonical_bom_sha256, payload_digest, date_trunc('month', inserted_at));

Query Contracts

Latest by payload digest

SELECT build_id, inserted_at, evidence_score
FROM scanner.artifact_boms
WHERE payload_digest = $1
ORDER BY inserted_at DESC
LIMIT 1;

Component presence by PURL

SELECT build_id, inserted_at
FROM scanner.artifact_boms
WHERE canonical_bom @? '$.components[*] ? (@.purl == $purl)'
ORDER BY inserted_at DESC
LIMIT 50;

Pending triage extraction

SELECT build_id, inserted_at,
       jsonb_path_query_array(merged_vex, '$[*] ? (@.state == "unknown" || @.state == "triage_pending")') AS pending
FROM scanner.artifact_boms
WHERE jsonb_path_exists(merged_vex, '$[*] ? (@.state == "unknown" || @.state == "triage_pending")')
ORDER BY inserted_at DESC
LIMIT 100;

Implemented API Surface (Scanner WebService)

Base path: /api/v1/sbom/hot-lookup

Pagination constraints:

Ingestion Contract

Operations

Operational runbook and jobs:

Mirror Seed Contract

scanner.artifact_boms is included in the stellaops-mirror-seed-v1 archive as an allowlisted projection table. Seed export/import preserves:

Import creates any missing monthly artifact_boms_YYYY_MM partitions for the archived inserted_at values before merging rows. This makes a clean local or air-gapped install regain SBOM readiness and hot lookup state without replaying registry scans first.

The seed is not the authoritative SBOM archive. It does not carry raw SBOM blobs, private signing material, registry credentials, request headers, Rekor tiles, or object-store/CAS payloads.

Security and Determinism Notes