up

docs/cli/sbomer.md

@@ -0,0 +1,40 @@
+# stella sbomer (DOCS-CLI-DET-01)
+
+Offline-first usage of `stella sbomer` verbs with deterministic outputs.
+
+## Prerequisites
+- Install CLI from offline bundle; ensure `local-nugets/` is available.
+- Export images/charts locally; no network access required during commands.
+
+## Commands
+- `stella sbomer layer <image>`
+  - Emits deterministic SBOM per layer; options: `--format cyclonedx|spdx`, `--output <path>`, `--deterministic` (default true).
+- `stella sbomer compose <manifest>`
+  - Merges layer SBOMs with stable ordering; rejects missing hashes.
+- `stella sbomer drift <baseline> <current>`
+  - Computes drift; returns machine-readable diff with stable ordering.
+- `stella sbomer verify <sbom> --hash <sha256>`
+  - Validates hash/signature if provided; offline only.
+
+## Determinism rules
+- Use fixed sort keys (component name, version, purl) when composing.
+- All timestamps forced to `1970-01-01T00:00:00Z` unless `--timestamp` supplied.
+- GUID/UUID generation disabled; use content hashes as IDs.
+- Outputs written in UTF-8 with LF line endings; no BOM.
+
+## Examples
+```bash
+# generate layer SBOM
+stella sbomer layer ghcr.io/acme/app:1.2.3 --format cyclonedx --output app.cdx.json
+
+# compose
+stella sbomer compose app.cdx.json lib.cdx.json --output combined.cdx.json
+
+# drift
+stella sbomer drift baseline.cdx.json combined.cdx.json --output drift.json
+```
+
+## Offline tips
+- Preload registries; set `STELLA_SBOMER_OFFLINE=true` to prevent remote pulls.
+- Configure cache dir via `STELLA_CACHE_DIR` for reproducible paths.
+- For air-gapped logs, use `--log-format json` and capture to file for later analysis.