Refactor code structure for improved readability and maintainability; optimize performance in key functions.
This commit is contained in:
master
215
docs/cli/audit-pack-commands.md
Normal file
215
docs/cli/audit-pack-commands.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user