synergy moats product advisory implementations
This commit is contained in:
master
251
docs/modules/cli/guides/commands/audit.md
Normal file
251
docs/modules/cli/guides/commands/audit.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# 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)_
|
||||
Reference in New Issue
Block a user