synergy moats product advisory implementations
This commit is contained in:
master
256
docs/operations/guides/auditor-guide.md
Normal file
256
docs/operations/guides/auditor-guide.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Auditor Guide
|
||||
|
||||
> **Sprint:** SPRINT_20260117_027_CLI_audit_bundle_command
|
||||
> **Task:** AUD-007 - Documentation
|
||||
|
||||
This guide is for external auditors reviewing Stella Ops release evidence.
|
||||
|
||||
## Overview
|
||||
|
||||
Stella Ops generates comprehensive, tamper-evident audit bundles that contain all evidence required to verify release decisions. This guide explains how to interpret and verify these bundles.
|
||||
|
||||
## Receiving an Audit Bundle
|
||||
|
||||
Audit bundles may be delivered as:
|
||||
- **Directory:** A folder containing all evidence files
|
||||
- **Archive:** A `.tar.gz` or `.zip` file
|
||||
|
||||
### Extracting Archives
|
||||
|
||||
```bash
|
||||
# tar.gz
|
||||
tar -xzf audit-bundle-sha256-abc123.tar.gz
|
||||
|
||||
# zip
|
||||
unzip audit-bundle-sha256-abc123.zip
|
||||
```
|
||||
|
||||
## Bundle Structure
|
||||
|
||||
```
|
||||
audit-bundle-<digest>-<timestamp>/
|
||||
├── manifest.json # Integrity manifest
|
||||
├── README.md # Quick reference
|
||||
├── verdict/ # Release decision
|
||||
├── evidence/ # Supporting evidence
|
||||
├── policy/ # Policy configuration
|
||||
└── replay/ # Verification instructions
|
||||
```
|
||||
|
||||
## Step 1: Verify Bundle Integrity
|
||||
|
||||
Before reviewing contents, verify the bundle has not been tampered with.
|
||||
|
||||
### Using Stella CLI
|
||||
|
||||
```bash
|
||||
stella audit verify ./audit-bundle-sha256-abc123/
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
✓ Verified 15/15 files
|
||||
✓ Integrity hash verified
|
||||
✓ Bundle integrity verified
|
||||
```
|
||||
|
||||
### Manual Verification
|
||||
|
||||
1. Open `manifest.json`
|
||||
2. For each file listed, compute SHA-256 and compare:
|
||||
```bash
|
||||
sha256sum verdict/verdict.json
|
||||
```
|
||||
3. Verify the `integrityHash` by hashing all file hashes
|
||||
|
||||
## Step 2: Review the Verdict
|
||||
|
||||
The verdict is the official release decision.
|
||||
|
||||
### verdict/verdict.json
|
||||
|
||||
```json
|
||||
{
|
||||
"artifactDigest": "sha256:abc123...",
|
||||
"decision": "PASS",
|
||||
"timestamp": "2026-01-17T10:25:00Z",
|
||||
"gates": [
|
||||
{
|
||||
"gateId": "sbom-required",
|
||||
"status": "PASS",
|
||||
"reason": "Valid CycloneDX SBOM present"
|
||||
},
|
||||
{
|
||||
"gateId": "vex-trust",
|
||||
"status": "PASS",
|
||||
"reason": "Trust score 0.85 >= 0.70 threshold"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Decision Values
|
||||
|
||||
| Decision | Meaning |
|
||||
|----------|---------|
|
||||
| `PASS` | All gates passed, artifact approved for deployment |
|
||||
| `BLOCKED` | One or more gates failed, artifact not approved |
|
||||
| `PENDING` | Evaluation incomplete, awaiting additional evidence |
|
||||
|
||||
### verdict/verdict.dsse.json
|
||||
|
||||
This file contains the cryptographically signed verdict envelope (DSSE format). Verify signatures using:
|
||||
|
||||
```bash
|
||||
stella audit verify ./bundle/ --check-signatures
|
||||
```
|
||||
|
||||
## Step 3: Review Evidence
|
||||
|
||||
### evidence/sbom.json
|
||||
|
||||
Software Bill of Materials (SBOM) listing all components in the artifact.
|
||||
|
||||
**Key fields:**
|
||||
- `components[]` - List of all software components
|
||||
- `dependencies[]` - Dependency relationships
|
||||
- `metadata.timestamp` - When SBOM was generated
|
||||
|
||||
### evidence/vex-statements/
|
||||
|
||||
Vulnerability Exploitability eXchange (VEX) statements that justify vulnerability assessments.
|
||||
|
||||
**index.json:**
|
||||
```json
|
||||
{
|
||||
"statementCount": 3,
|
||||
"statements": [
|
||||
{"fileName": "vex-001.json", "source": "vendor-security"},
|
||||
{"fileName": "vex-002.json", "source": "internal-analysis"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Each VEX statement explains why a vulnerability does or does not affect this artifact.
|
||||
|
||||
### evidence/reachability/analysis.json
|
||||
|
||||
Reachability analysis showing which vulnerabilities are actually reachable in the code.
|
||||
|
||||
```json
|
||||
{
|
||||
"components": [
|
||||
{
|
||||
"purl": "pkg:npm/lodash@4.17.21",
|
||||
"vulnerabilities": [
|
||||
{
|
||||
"id": "CVE-2021-23337",
|
||||
"reachable": false,
|
||||
"reason": "Vulnerable function not in call graph"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Step 4: Review Policy
|
||||
|
||||
### policy/policy-snapshot.json
|
||||
|
||||
The policy configuration used for evaluation:
|
||||
|
||||
```json
|
||||
{
|
||||
"policyVersion": "v2.3.1",
|
||||
"gates": ["sbom-required", "vex-trust", "cve-threshold"],
|
||||
"thresholds": {
|
||||
"vexTrustScore": 0.70,
|
||||
"maxCriticalCves": 0,
|
||||
"maxHighCves": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### policy/gate-decision.json
|
||||
|
||||
Detailed breakdown of each gate evaluation:
|
||||
|
||||
```json
|
||||
{
|
||||
"gates": [
|
||||
{
|
||||
"gateId": "vex-trust",
|
||||
"decision": "PASS",
|
||||
"inputs": {
|
||||
"vexStatements": 3,
|
||||
"trustScore": 0.85,
|
||||
"threshold": 0.70
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Step 5: Replay Verification (Optional)
|
||||
|
||||
For maximum assurance, you can replay the verdict evaluation.
|
||||
|
||||
### Using Stella CLI
|
||||
|
||||
```bash
|
||||
cd audit-bundle-sha256-abc123/
|
||||
stella replay snapshot --manifest replay/knowledge-snapshot.json
|
||||
```
|
||||
|
||||
This re-evaluates the policy using the frozen inputs and should produce an identical verdict.
|
||||
|
||||
### Manual Replay Steps
|
||||
|
||||
See `replay/replay-instructions.md` for detailed steps.
|
||||
|
||||
## Compliance Mapping
|
||||
|
||||
| Compliance Framework | Relevant Bundle Components |
|
||||
|---------------------|---------------------------|
|
||||
| **SOC 2 (CC7.1)** | verdict/, policy/ |
|
||||
| **ISO 27001 (A.12.6)** | evidence/sbom.json |
|
||||
| **FedRAMP** | All components |
|
||||
| **SLSA Level 3** | evidence/provenance/ |
|
||||
|
||||
## Common Questions
|
||||
|
||||
### Q: Why was this artifact blocked?
|
||||
|
||||
Review `policy/gate-decision.json` for the specific gate that failed and its reason.
|
||||
|
||||
### Q: How do I verify the SBOM is accurate?
|
||||
|
||||
The SBOM digest is included in the manifest. Compare against the organization's SBOM generation process.
|
||||
|
||||
### Q: What if replay produces a different result?
|
||||
|
||||
This may indicate:
|
||||
1. Policy version mismatch
|
||||
2. Missing evidence files
|
||||
3. Time-dependent policy rules
|
||||
|
||||
Contact the organization's security team for clarification.
|
||||
|
||||
### Q: How long should audit bundles be retained?
|
||||
|
||||
Stella Ops recommends:
|
||||
- Production releases: 5 years minimum
|
||||
- Security-critical systems: 7 years
|
||||
- Regulated industries: Per compliance requirements
|
||||
|
||||
## Support
|
||||
|
||||
For questions about this audit bundle:
|
||||
1. Contact the organization's Stella Ops administrator
|
||||
2. Reference the Bundle ID from `manifest.json`
|
||||
3. Include the artifact digest
|
||||
|
||||
---
|
||||
|
||||
_Last updated: 2026-01-17 (UTC)_
|
||||
Reference in New Issue
Block a user