216 lines
4.5 KiB
Markdown
216 lines
4.5 KiB
Markdown
# 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`
|