51 lines
2.5 KiB
Markdown
51 lines
2.5 KiB
Markdown
# 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`.
|