stella audit

Audience: engineers, release managers, and compliance teams who need to package and verify auditor-ready evidence for a scanned artifact.

The stella audit command group generates and verifies self-contained audit bundles — portable evidence packages that capture the full release-control decision for an artifact (verdict, SBOM, VEX, reachability, policy trace, and replay instructions) so an external reviewer can confirm and reproduce it offline.

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

Audit Bundle Format Specification — full layout and schema of the generated bundle
stella scan replay — replay a verdict to confirm it reproduces
stella export — export evidence in other formats

Last updated: 2026-01-17 (UTC)