# Audit Pack CLI Commands

## Overview

The `stella audit-pack` command provides functionality for exporting, importing, verifying, and replaying audit packs for compliance and verification workflows.

## Commands

### Export

Export an audit pack from a scan result.

```bash
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:**
```bash
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.

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

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

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

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

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