git.stella-ops.org/docs/artifacts/bom-index

StellaOps BOM Index (bom-index@1)

The BOM index is a deterministic, offline-friendly sidecar that accelerates queries for layer-to-component membership and entrypoint usage. It is emitted alongside CycloneDX SBOMs and consumed by Scheduler/Notify services.

File Layout

Binary little-endian encoding, organised as the following sections:

1. Header

   • magic (byte[7]): ASCII "BOMIDX1" identifier.
   • version (uint16): current value 1.
   • flags (uint16): bit 0 set when entrypoint usage bitmaps are present.
   • imageDigestLength (uint16) + UTF-8 digest string (e.g. sha256:...).
   • generatedAt (int64): microseconds since Unix epoch.
   • layerCount (uint32), componentCount (uint32), entrypointCount (uint32).

2. Layer Table

   • For each layer: length (uint16) + UTF-8 layer digest (canonical order, base image → top layer).

3. Component Table

   • For each component: length (uint16) + UTF-8 identity (CycloneDX purl when available, otherwise canonical key).

4. Component ↦ Layer Bitmaps

   • For each component (matching table order):
     • bitmapLength (uint32).
     • Roaring bitmap payload (Collections.Special.RoaringBitmap.Serialize) encoding layer indexes that introduce or retain the component.

5. Entrypoint Table (optional; present when flags & 0x1 == 1)

   • For each unique entrypoint/launcher string: length (uint16) + UTF-8 value (sorted ordinally).

6. Component ↦ Entrypoint Bitmaps (optional)

   • For each component: roaring bitmap whose set bits reference entrypoint indexes used by EntryTrace. Empty bitmap (length == 0) indicates the component is not part of any resolved entrypoint closure.

Determinism Guarantees

• Layer, component, and entrypoint tables are strictly ordered (base → top layer, lexicographically for components and entrypoints).
• Roaring bitmaps are optimised prior to serialisation and always produced from sorted indexes.
• Header timestamp is normalised to microsecond precision using UTC.

Sample

sample-index.bin is generated from the integration fixture used in unit tests. It contains:

• 2 layers: sha256:layer1, sha256:layer2.
• 3 components: pkg:npm/a, pkg:npm/b, pkg:npm/c.
• Entrypoint bitmaps for /app/start.sh and /app/init.sh.

The sample can be decoded with the BomIndexBuilder unit tests or any RoaringBitmap implementation compatible with Collections.Special.RoaringBitmap.