git.stella-ops.org/docs/modules/cli/guides/commands/audit.md

stella audit

Sprint: SPRINT_20260117_027_CLI_audit_bundle_command
Task: AUD-007 - Documentation

Commands for audit operations including bundle generation and verification.

Synopsis

stella audit <command> [options]

Commands

Command	Description
bundle	Generate self-contained audit bundle for an artifact
verify	Verify audit bundle integrity

---

stella audit bundle

Generate a self-contained, auditor-ready evidence package for an artifact.

Synopsis

stella audit bundle <digest> [options]

Arguments

Argument	Description
<digest>	Artifact digest (e.g., sha256:abc123...)

Options

Option	Default	Description
--output <path>	./audit-bundle-<digest>/	Output path for the bundle
--format <format>	dir	Output format: dir, tar.gz, zip
--include-call-graph	false	Include call graph visualization
--include-schemas	false	Include JSON schema files
--include-trace	true	Include policy evaluation trace
--policy-version <ver>	(current)	Use specific policy version
--overwrite	false	Overwrite existing output
--verbose	false	Show progress during generation

Examples

# Generate bundle as directory
stella audit bundle sha256:abc123def456

# Generate tar.gz archive
stella audit bundle sha256:abc123def456 --format tar.gz

# Specify output location
stella audit bundle sha256:abc123def456 --output ./audits/release-v2.5/

# Include all optional content
stella audit bundle sha256:abc123def456 \
  --include-call-graph \
  --include-schemas \
  --verbose

# Use specific policy version
stella audit bundle sha256:abc123def456 --policy-version v2.3.1

Output

The bundle contains:

audit-bundle-<digest>-<timestamp>/
├── manifest.json              # Bundle manifest with cryptographic hashes
├── README.md                  # Human-readable guide for auditors
├── verdict/
│   ├── verdict.json           # StellaVerdict artifact
│   └── verdict.dsse.json      # DSSE envelope with signatures
├── evidence/
│   ├── sbom.json              # SBOM (CycloneDX format)
│   ├── vex-statements/        # All VEX statements considered
│   │   ├── index.json
│   │   └── *.json
│   ├── reachability/
│   │   ├── analysis.json
│   │   └── call-graph.dot     # Optional
│   └── provenance/
│       └── slsa-provenance.json
├── policy/
│   ├── policy-snapshot.json
│   ├── gate-decision.json
│   └── evaluation-trace.json
├── replay/
│   ├── knowledge-snapshot.json
│   └── replay-instructions.md
└── schema/                    # Optional
    ├── verdict-schema.json
    └── vex-schema.json

Exit Codes

Code	Description
0	Bundle generated successfully
1	Bundle generated with missing evidence (warnings)
2	Error (artifact not found, permission denied, etc.)

---

stella audit verify

Verify the integrity of an audit bundle.

Synopsis

stella audit verify <bundle-path> [options]

Arguments

Argument	Description
<bundle-path>	Path to audit bundle (directory or archive)

Options

Option	Default	Description
--strict	false	Fail on any missing optional files
--check-signatures	false	Verify DSSE signatures
--trusted-keys <path>	(none)	Path to trusted keys file for signature verification

Examples

# Basic verification
stella audit verify ./audit-bundle-abc123-20260117/

# Strict mode (fail on any missing files)
stella audit verify ./audit-bundle-abc123-20260117/ --strict

# Verify signatures
stella audit verify ./audit-bundle.tar.gz \
  --check-signatures \
  --trusted-keys ./trusted-keys.json

# Verify archive directly
stella audit verify ./audit-bundle-abc123.zip

Output

Verifying bundle: ./audit-bundle-abc123-20260117/

Bundle ID: urn:stella:audit-bundle:sha256:abc123...
Artifact: sha256:abc123def456...
Generated: 2026-01-17T10:30:00Z
Files: 15

Verifying files...
✓ Verified 15/15 files
✓ Integrity hash verified

✓ Bundle integrity verified

Exit Codes

Code	Description
0	Bundle is valid
1	Bundle integrity check failed
2	Error (bundle not found, invalid format, etc.)

---

Trusted Keys File Format

For signature verification, provide a JSON file with trusted public keys:

{
  "keys": [
    {
      "keyId": "urn:stella:key:sha256:abc123...",
      "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
    }
  ]
}

---

Use Cases

Generating Bundles for External Auditors

# Generate comprehensive bundle for SOC 2 audit
stella audit bundle sha256:prod-release-v2.5 \
  --format zip \
  --include-schemas \
  --output ./soc2-audit-2026/release-evidence.zip

Verifying Received Bundles

# Verify bundle received from another team
stella audit verify ./received-bundle.tar.gz --strict

# Verify with signature checking
stella audit verify ./received-bundle/ \
  --check-signatures \
  --trusted-keys ./company-signing-keys.json

CI/CD Integration

# GitLab CI example
audit-bundle:
  stage: release
  script:
    - stella audit bundle $IMAGE_DIGEST --format tar.gz --output ./audit/
  artifacts:
    paths:
      - audit/
    expire_in: 5 years

---

Related

• Audit Bundle Format Specification
• stella replay - Replay verdicts for verification
• stella export - Export evidence in various formats

---

Last updated: 2026-01-17 (UTC)