stella audit-pack — Command Guide

Audience: Compliance engineers and auditors who package, transfer, and independently verify scan evidence. Scope: Exporting, verifying, inspecting, and deterministically replaying audit packs — including air-gapped workflows.

Overview

The stella audit-pack commands export, verify, inspect, and replay audit packs for compliance and verification workflows. An audit pack bundles a scan’s run manifest, verdict, evidence, SBOMs, attestations, VEX documents, and the feed/policy snapshot needed to reproduce the verdict — so an auditor can replay the scan offline and confirm the result is byte-for-byte identical.

Commands

Export

Export an audit pack from a scan result.

stella audit-pack export --scan-id <id> --output audit-pack.tar.gz

# With signing
stella audit-pack export --scan-id <id> --sign --key signing-key.pem --output audit-pack.tar.gz

# Minimize size
stella audit-pack export --scan-id <id> --minimize --output audit-pack.tar.gz

Options:

--scan-id <id> - Scan ID to export
--output <path> - Output file path (tar.gz)
--sign - Sign the audit pack
--key <path> - Signing key path (required if --sign)
--minimize - Minimize bundle size (only required feeds/policies)
--name <name> - Custom pack name

Example:

stella audit-pack export \
  --scan-id abc123 \
  --sign \
  --key ~/.stella/keys/signing-key.pem \
  --output compliance-pack-2025-12.tar.gz

Verify

Verify audit pack integrity and signatures.

stella audit-pack verify audit-pack.tar.gz

# Skip signature verification
stella audit-pack verify --no-verify-signatures audit-pack.tar.gz

Options:

--no-verify-signatures - Skip signature verification
--json - Output results as JSON

Output:

✅ Audit Pack Verification
  Pack ID: abc-123-def-456
  Created: 2025-12-22T00:00:00Z
  Files: 42 (all digests valid)
  Signature: Valid (verified with trust root 'prod-ca')

Info

Display information about an audit pack.

stella audit-pack info audit-pack.tar.gz

# JSON output
stella audit-pack info --json audit-pack.tar.gz

Output:

Audit Pack Information
  Pack ID:       abc-123-def-456
  Name:          compliance-pack-2025-12
  Created:       2025-12-22T00:00:00Z
  Schema:        1.0.0

  Contents:
    Run Manifest:  included
    Verdict:       included
    Evidence:      included
    SBOMs:         2 (CycloneDX, SPDX)
    Attestations:  3
    VEX Docs:      1
    Trust Roots:   2

  Bundle:
    Feeds:         4 (NVD, GHSA, Debian, Alpine)
    Policies:      2 (default, strict)
    Size:          42.5 MB

Replay

Replay scan from audit pack and compare results.

stella audit-pack replay audit-pack.tar.gz --output replay-result.json

# Show differences
stella audit-pack replay audit-pack.tar.gz --show-diff

Options:

--output <path> - Write replay results to file
--show-diff - Display verdict differences
--json - JSON output format

Output:

✅ Replay Complete
  Original Verdict Digest:  abc123...
  Replayed Verdict Digest:  abc123...
  Match:                    Identical
  Duration:                 1.2s

  Verdict Comparison:
    ✅ All findings match
    ✅ All severities match
    ✅ VEX statements identical

Verify and Replay (Combined)

Verify integrity and replay in one command.

stella audit-pack verify-and-replay audit-pack.tar.gz

This combines verify and replay for a complete verification workflow.

Output:

Step 1/2: Verifying audit pack...
✅ Integrity verified
✅ Signatures valid

Step 2/2: Replaying scan...
✅ Replay complete
✅ Verdicts match

Overall Status: PASSED

Exit Codes

Code	Meaning
0	Success
1	Verification failed
2	Replay failed
3	Verdicts don’t match
10	Invalid arguments

Environment Variables

STELLAOPS_AUDIT_PACK_VERIFY_SIGS - Default signature verification (true/false)
STELLAOPS_AUDIT_PACK_TRUST_ROOTS - Directory containing trust roots
STELLAOPS_OFFLINE_BUNDLE - Offline bundle path for replay

Examples

Full Compliance Workflow

# 1. Export audit pack from scan
stella audit-pack export \
  --scan-id prod-scan-2025-12-22 \
  --sign \
  --key production-signing-key.pem \
  --output compliance-pack.tar.gz

# 2. Transfer to auditor environment (air-gapped)
scp compliance-pack.tar.gz auditor@secure-env:/audit/

# 3. Auditor verifies and replays
ssh auditor@secure-env
stella audit-pack verify-and-replay /audit/compliance-pack.tar.gz

# Output:
# ✅ Verification PASSED
# ✅ Replay PASSED - Verdicts identical

Implementation Notes

CLI commands are implemented in:

src/Cli/StellaOps.Cli/Commands/AuditPackCommands.cs

Backend services:

StellaOps.AuditPack.Services.AuditPackBuilder
StellaOps.AuditPack.Services.AuditPackImporter
StellaOps.AuditPack.Services.AuditPackReplayer