synergy moats product advisory implementations

2026-01-17 01:30:03 +02:00
parent 77ff029205
commit 702a27ac83
112 changed files with 21356 additions and 127 deletions
--- a/docs/modules/cli/guides/audit-bundle-format.md
+++ b/docs/modules/cli/guides/audit-bundle-format.md
@@ -0,0 +1,271 @@
+# Audit Bundle Format Specification
+
+> **Sprint:** SPRINT_20260117_027_CLI_audit_bundle_command  
+> **Task:** AUD-001 - Audit Bundle Format Specification  
+> **Version:** 1.0.0
+
+## Overview
+
+The Stella Ops Audit Bundle is a self-contained, tamper-evident package containing all evidence required for an auditor to verify a release decision. The bundle is designed for:
+
+- **Completeness:** Contains everything needed to verify a verdict without additional tool invocations
+- **Reproducibility:** Includes replay instructions for deterministic re-verification
+- **Portability:** Standard formats (JSON, Markdown) readable by common tools
+- **Integrity:** Cryptographic manifest ensures tamper detection
+
+## Bundle Structure
+
+```
+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         # VEX index with sources
+│   │   └── *.json             # Individual VEX documents
+│   ├── reachability/
+│   │   ├── analysis.json      # Reachability analysis result
+│   │   └── call-graph.dot     # Call graph visualization (optional)
+│   └── provenance/
+│       └── slsa-provenance.json
+├── policy/
+│   ├── policy-snapshot.json   # Policy version and rules used
+│   ├── gate-decision.json     # Gate evaluation result
+│   └── evaluation-trace.json  # Full policy trace (optional)
+├── replay/
+│   ├── knowledge-snapshot.json  # Frozen inputs for replay
+│   └── replay-instructions.md   # How to replay verdict
+└── schema/                    # Schema references (optional)
+    ├── verdict-schema.json
+    └── vex-schema.json
+```
+
+## File Specifications
+
+### manifest.json
+
+The manifest provides cryptographic integrity and bundle metadata.
+
+```json
+{
+  "$schema": "https://schema.stella-ops.org/audit-bundle/manifest/v1",
+  "version": "1.0.0",
+  "bundleId": "urn:stella:audit-bundle:sha256:abc123...",
+  "artifactDigest": "sha256:abc123...",
+  "generatedAt": "2026-01-17T10:30:00Z",
+  "generatedBy": "stella-cli/2.5.0",
+  "files": [
+    {
+      "path": "verdict/verdict.json",
+      "sha256": "abc123...",
+      "size": 12345,
+      "required": true
+    },
+    {
+      "path": "evidence/sbom.json",
+      "sha256": "def456...",
+      "size": 98765,
+      "required": true
+    }
+  ],
+  "totalFiles": 12,
+  "totalSize": 234567,
+  "integrityHash": "sha256:manifest-hash-of-all-file-hashes"
+}
+```
+
+### README.md
+
+Auto-generated guide for auditors with:
+- Bundle overview and artifact identification
+- Quick verification steps
+- File inventory with descriptions
+- Contact information for questions
+
+### verdict/verdict.json
+
+The StellaVerdict artifact in standard format:
+
+```json
+{
+  "$schema": "https://schema.stella-ops.org/verdict/v1",
+  "artifactDigest": "sha256:abc123...",
+  "artifactType": "container-image",
+  "decision": "BLOCKED",
+  "timestamp": "2026-01-17T10:25:00Z",
+  "gates": [
+    {
+      "gateId": "vex-trust",
+      "status": "BLOCKED",
+      "reason": "Trust score below threshold (0.45 < 0.70)",
+      "evidenceRefs": ["evidence/vex-statements/vendor-x.json"]
+    }
+  ],
+  "contentId": "urn:stella:verdict:sha256:xyz..."
+}
+```
+
+### verdict/verdict.dsse.json
+
+DSSE (Dead Simple Signing Envelope) containing the signed verdict:
+
+```json
+{
+  "payloadType": "application/vnd.stella-ops.verdict+json",
+  "payload": "base64-encoded-verdict",
+  "signatures": [
+    {
+      "keyid": "urn:stella:key:sha256:...",
+      "sig": "base64-signature"
+    }
+  ]
+}
+```
+
+### evidence/sbom.json
+
+CycloneDX SBOM in JSON format (or SPDX if configured).
+
+### evidence/vex-statements/
+
+Directory containing all VEX statements considered during evaluation:
+
+- `index.json` - Index of VEX statements with metadata
+- Individual VEX documents named by source and ID
+
+### evidence/reachability/analysis.json
+
+Reachability analysis results:
+
+```json
+{
+  "artifactDigest": "sha256:abc123...",
+  "analysisType": "static",
+  "analysisTimestamp": "2026-01-17T10:20:00Z",
+  "components": [
+    {
+      "purl": "pkg:npm/lodash@4.17.21",
+      "vulnerabilities": [
+        {
+          "id": "CVE-2021-23337",
+          "reachable": false,
+          "reason": "Vulnerable function not in call graph"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### policy/policy-snapshot.json
+
+Snapshot of policy configuration at evaluation time:
+
+```json
+{
+  "policyVersion": "v2.3.1",
+  "policyDigest": "sha256:policy-hash...",
+  "gates": ["sbom-required", "vex-trust", "cve-threshold"],
+  "thresholds": {
+    "vexTrustScore": 0.70,
+    "maxCriticalCves": 0,
+    "maxHighCves": 5
+  },
+  "evaluatedAt": "2026-01-17T10:25:00Z"
+}
+```
+
+### policy/gate-decision.json
+
+Detailed gate evaluation result:
+
+```json
+{
+  "artifactDigest": "sha256:abc123...",
+  "overallDecision": "BLOCKED",
+  "gates": [
+    {
+      "gateId": "vex-trust",
+      "decision": "BLOCKED",
+      "inputs": {
+        "vexStatements": 3,
+        "trustScore": 0.45,
+        "threshold": 0.70
+      },
+      "reason": "Trust score below threshold",
+      "suggestion": "Obtain VEX from trusted issuer or adjust trust registry"
+    }
+  ]
+}
+```
+
+### replay/knowledge-snapshot.json
+
+Frozen inputs for deterministic replay:
+
+```json
+{
+  "$schema": "https://schema.stella-ops.org/knowledge-snapshot/v1",
+  "snapshotId": "urn:stella:snapshot:sha256:...",
+  "capturedAt": "2026-01-17T10:25:00Z",
+  "inputs": {
+    "sbomDigest": "sha256:sbom-hash...",
+    "vexStatements": ["sha256:vex1...", "sha256:vex2..."],
+    "policyDigest": "sha256:policy-hash...",
+    "reachabilityDigest": "sha256:reach-hash..."
+  },
+  "replayCommand": "stella replay snapshot --manifest replay/knowledge-snapshot.json"
+}
+```
+
+### replay/replay-instructions.md
+
+Human-readable replay instructions (auto-generated, see AUD-004).
+
+## Archive Formats
+
+The bundle can be output in three formats:
+
+| Format | Extension | Use Case |
+|--------|-----------|----------|
+| Directory | (none) | Local inspection, development |
+| tar.gz | `.tar.gz` | Transfer, archival (default for remote) |
+| zip | `.zip` | Windows compatibility |
+
+## Verification
+
+To verify a bundle's integrity:
+
+```bash
+stella audit verify ./audit-bundle-sha256-abc123/
+```
+
+Verification checks:
+1. Parse `manifest.json`
+2. Verify each file's SHA-256 hash matches manifest
+3. Verify `integrityHash` (hash of all file hashes)
+4. Optionally verify DSSE signatures
+
+## Compliance Mapping
+
+| Compliance Framework | Bundle Component |
+|---------------------|------------------|
+| SOC 2 (CC7.1) | verdict/, policy/ |
+| ISO 27001 (A.12.6) | evidence/sbom.json |
+| FedRAMP | All components |
+| SLSA Level 3 | evidence/provenance/ |
+
+## Extensibility
+
+Custom evidence can be added to `evidence/custom/` directory. Custom files must be:
+- Listed in `manifest.json`
+- JSON or Markdown format
+- Include schema reference if JSON
+
+---
+
+_Last updated: 2026-01-17 (UTC)_