work

docs/modules/cli/guides/commands/sbom.md

@@ -0,0 +1,25 @@
+# stella sbom — Command Guide
+
+## Commands
+- `stella sbom generate --image <ref> [--output sbom.spdx.json] [--offline]`
+- `stella sbom compose --fragment <path> --output composition.json --offline`
+- `stella sbom verify --file <sbom> --signature <sig> --key <keyfile>`
+
+## Flags (common)
+- `--offline`: no network pulls; use local cache/OCI archive.
+- `--format`: `spdx-json` (default) or `cyclonedx-json`.
+- `--attest`: emit DSSE attestation alongside SBOM.
+- `--hash`: include layer/file hashes (deterministic ordering).
+
+## Inputs/outputs
+- Inputs: container image, directory, or fragments.
+- Outputs: deterministic SPDX/CycloneDX JSON, optional DSSE + checksums.
+- Exit codes per `output-and-exit-codes.md`; verification failure uses exit code 3 or 4 depending on cause.
+
+## Determinism rules
+- Stable ordering of packages/files; timestamps UTC.
+- Hashes hex-lowercase; no host-specific paths.
+
+## Offline/air-gap notes
+- With `--offline`, image sources must already be cached (tar/OCI archive); command fails with exit code 5 if it would fetch remotely.
+- Verification uses local trust roots; no remote key fetch.