52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
# Portable Audit Pack CLI Runbook
|
|
|
|
Status: Target behavior for implementation sprint handoff (2026-02-10).
|
|
|
|
## Objective
|
|
Define expected parity between generation and verification CLI flows for portable audit packs in connected and air-gapped environments.
|
|
|
|
## Export workflow (target)
|
|
```bash
|
|
stella auditpack export \
|
|
--artifact myorg/myapp@sha256:<digest> \
|
|
--bom sbom.json \
|
|
--vex vex/*.json \
|
|
--out artifact-audit-pack.tzst \
|
|
--profile portable-v1 \
|
|
--rekor-tiles fetch \
|
|
--sign-key ed25519:stella-bom-signer@2026Q1
|
|
```
|
|
|
|
Expected behavior:
|
|
- Emits manifest conforming to `portable-audit-pack-manifest.v1.schema.json`.
|
|
- Produces deterministic archive metadata and ordered contents.
|
|
- Emits stable machine-readable summary ordered by file path.
|
|
|
|
## Verify workflow (target)
|
|
```bash
|
|
stella auditpack verify artifact-audit-pack.tzst --offline --profile portable-v1
|
|
```
|
|
|
|
Required checks:
|
|
- Manifest signature verification.
|
|
- File digest and size verification.
|
|
- DSSE payload digest binding verification.
|
|
- Rekor inclusion/root verification from bundled material.
|
|
- Optional Parquet fingerprint verification when present.
|
|
|
|
## Output contract
|
|
- Human output grouped in fixed order: manifest -> file digests -> DSSE -> Rekor -> optional index.
|
|
- JSON output fields sorted lexicographically for deterministic diffing.
|
|
- Non-zero exit and stable error codes on first failure.
|
|
|
|
## Air-gap operator sequence
|
|
1. Transfer bundle to offline verifier host.
|
|
2. Run `stella auditpack verify ... --offline`.
|
|
3. Archive verification output with audit evidence.
|
|
4. Record profile version and verifier key IDs in release record.
|
|
|
|
## Documentation dependency
|
|
- Keep this runbook aligned with:
|
|
- `portable-audit-pack-contract.md`
|
|
- `portable-audit-pack-rekor-offline.md`
|
|
- `portable-audit-pack-test-matrix.md` |