# 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

```bash
# 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

```bash
# 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:

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

---

## Use Cases

### Generating Bundles for External Auditors

```bash
# 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

```bash
# 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

```yaml
# 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](audit-bundle-format.md)
- [stella replay](../replay.md) - Replay verdicts for verification
- [stella export](export.md) - Export evidence in various formats

---

_Last updated: 2026-01-17 (UTC)_