docs consolidation

2025-12-24 21:45:46 +02:00
parent 4231305fec
commit 43e2af88f6
76 changed files with 2887 additions and 796 deletions
--- a/docs/modules/cli/guides/commands/evidence-bundle-format.md
+++ b/docs/modules/cli/guides/commands/evidence-bundle-format.md
@@ -0,0 +1,329 @@
+# Evidence Bundle Format Specification
+
+Version: 1.0  
+Status: Stable  
+Sprint: SPRINT_9200_0001_0003
+
+## Overview
+
+Evidence bundles are downloadable archives containing complete evidence packages for findings or scan runs. They enable:
+
+- **Offline verification**: All evidence is self-contained
+- **Deterministic replay**: Includes scripts and hashes for verdict reproduction
+- **Audit compliance**: Provides cryptographic verification of all evidence
+- **Human readability**: Includes README and manifest for easy inspection
+
+## Archive Formats
+
+Evidence bundles are available in two formats:
+
+| Format | Extension | MIME Type | Use Case |
+|--------|-----------|-----------|----------|
+| ZIP | `.zip` | `application/zip` | General use, Windows compatible |
+| TAR.GZ | `.tar.gz` | `application/gzip` | Unix systems, better compression |
+
+## Endpoints
+
+### Single Finding Bundle
+
+```
+GET /v1/triage/findings/{findingId}/evidence/export?format=zip
+```
+
+Response headers:
+- `Content-Type: application/zip`
+- `Content-Disposition: attachment; filename="evidence-{findingId}.zip"`
+- `X-Archive-Digest: sha256:{digest}`
+
+### Scan Run Bundle
+
+```
+GET /v1/triage/scans/{scanId}/evidence/export?format=zip
+```
+
+Response headers:
+- `Content-Type: application/zip`
+- `Content-Disposition: attachment; filename="evidence-run-{scanId}.zip"`
+- `X-Archive-Digest: sha256:{digest}`
+
+## Finding Bundle Structure
+
+```
+evidence-{findingId}/
+├── manifest.json              # Archive manifest with file hashes
+├── README.md                  # Human-readable documentation
+├── sbom.cdx.json             # CycloneDX SBOM slice
+├── reachability.json         # Reachability analysis data
+├── vex/
+│   ├── vendor.json           # Vendor VEX statements
+│   ├── nvd.json              # NVD VEX data
+│   └── cisa-kev.json         # CISA KEV data
+├── attestations/
+│   ├── sbom.dsse.json        # SBOM DSSE envelope
+│   └── scan.dsse.json        # Scan DSSE envelope
+├── policy/
+│   └── evaluation.json       # Policy evaluation result
+├── delta.json                # Delta comparison (if available)
+├── replay-command.txt        # Copy-ready replay command
+├── replay.sh                 # Bash replay script
+└── replay.ps1                # PowerShell replay script
+```
+
+## Scan Run Bundle Structure
+
+```
+evidence-run-{scanId}/
+├── MANIFEST.json             # Run-level manifest
+├── README.md                 # Run-level documentation
+└── findings/
+    ├── {findingId1}/
+    │   ├── manifest.json
+    │   ├── README.md
+    │   ├── sbom.cdx.json
+    │   ├── reachability.json
+    │   ├── vex/
+    │   ├── attestations/
+    │   ├── policy/
+    │   ├── delta.json
+    │   ├── replay-command.txt
+    │   ├── replay.sh
+    │   └── replay.ps1
+    ├── {findingId2}/
+    │   └── ...
+    └── ...
+```
+
+## Manifest Schema
+
+### Finding Manifest (manifest.json)
+
+```json
+{
+  "schemaVersion": "1.0",
+  "findingId": "f-abc123",
+  "generatedAt": "2025-01-15T10:30:00Z",
+  "cacheKey": "sha256:abc123...",
+  "scannerVersion": "10.1.3",
+  "files": [
+    {
+      "path": "sbom.cdx.json",
+      "sha256": "abc123def456...",
+      "size": 12345,
+      "contentType": "application/json"
+    },
+    {
+      "path": "reachability.json",
+      "sha256": "789xyz...",
+      "size": 5678,
+      "contentType": "application/json"
+    }
+  ]
+}
+```
+
+### Run Manifest (MANIFEST.json)
+
+```json
+{
+  "schemaVersion": "1.0",
+  "scanId": "scan-xyz789",
+  "generatedAt": "2025-01-15T10:30:00Z",
+  "totalFiles": 42,
+  "scannerVersion": "10.1.3",
+  "findings": [
+    {
+      "findingId": "f-abc123",
+      "generatedAt": "2025-01-15T10:30:00Z",
+      "cacheKey": "sha256:abc123...",
+      "files": [...]
+    },
+    {
+      "findingId": "f-def456",
+      "generatedAt": "2025-01-15T10:30:00Z",
+      "cacheKey": "sha256:def456...",
+      "files": [...]
+    }
+  ]
+}
+```
+
+## Replay Scripts
+
+### Bash Script (replay.sh)
+
+```bash
+#!/usr/bin/env bash
+# StellaOps Evidence Bundle Replay Script
+# Generated: 2025-01-15T10:30:00Z
+# Finding: f-abc123
+# CVE: CVE-2024-1234
+
+set -euo pipefail
+
+# Input hashes for deterministic replay
+ARTIFACT_DIGEST="sha256:a1b2c3d4e5f6..."
+MANIFEST_HASH="sha256:abc123def456..."
+FEED_HASH="sha256:feed789feed..."
+POLICY_HASH="sha256:policy321..."
+
+# Verify prerequisites
+if ! command -v stella &> /dev/null; then
+    echo "Error: stella CLI not found. Install from https://stellaops.org/install"
+    exit 1
+fi
+
+echo "Replaying verdict for finding: ${ARTIFACT_DIGEST}"
+echo "Using manifest: ${MANIFEST_HASH}"
+
+# Execute replay
+stella scan replay \
+    --artifact "${ARTIFACT_DIGEST}" \
+    --manifest "${MANIFEST_HASH}" \
+    --feeds "${FEED_HASH}" \
+    --policy "${POLICY_HASH}"
+
+echo "Replay complete. Verify verdict matches original."
+```
+
+### PowerShell Script (replay.ps1)
+
+```powershell
+# StellaOps Evidence Bundle Replay Script
+# Generated: 2025-01-15T10:30:00Z
+# Finding: f-abc123
+# CVE: CVE-2024-1234
+
+$ErrorActionPreference = 'Stop'
+
+# Input hashes for deterministic replay
+$ArtifactDigest = "sha256:a1b2c3d4e5f6..."
+$ManifestHash = "sha256:abc123def456..."
+$FeedHash = "sha256:feed789feed..."
+$PolicyHash = "sha256:policy321..."
+
+# Verify prerequisites
+if (-not (Get-Command stella -ErrorAction SilentlyContinue)) {
+    Write-Error "stella CLI not found. Install from https://stellaops.org/install"
+    exit 1
+}
+
+Write-Host "Replaying verdict for finding: $ArtifactDigest"
+Write-Host "Using manifest: $ManifestHash"
+
+# Execute replay
+stella scan replay `
+    --artifact $ArtifactDigest `
+    --manifest $ManifestHash `
+    --feeds $FeedHash `
+    --policy $PolicyHash
+
+Write-Host "Replay complete. Verify verdict matches original."
+```
+
+## README Format
+
+### Finding README (README.md)
+
+```markdown
+# StellaOps Evidence Bundle
+
+## Overview
+
+- **Finding ID:** `f-abc123`
+- **CVE:** `CVE-2024-1234`
+- **Component:** `pkg:npm/lodash@4.17.15`
+- **Generated:** 2025-01-15T10:30:00Z
+
+## Input Hashes for Deterministic Replay
+
+| Input | Hash |
+|-------|------|
+| Artifact Digest | `sha256:a1b2c3d4e5f6...` |
+| Run Manifest | `sha256:abc123def456...` |
+| Feed Snapshot | `sha256:feed789feed...` |
+| Policy | `sha256:policy321...` |
+
+## Replay Instructions
+
+### Using Bash
+```bash
+chmod +x replay.sh
+./replay.sh
+```
+
+### Using PowerShell
+```powershell
+.\replay.ps1
+```
+
+## Bundle Contents
+
+| File | SHA-256 | Size |
+|------|---------|------|
+| `sbom.cdx.json` | `abc123...` | 12.3 KB |
+| `reachability.json` | `789xyz...` | 5.6 KB |
+| ... | ... | ... |
+
+## Verification Status
+
+- **Status:** verified
+- **Hashes Verified:** ✓
+- **Attestations Verified:** ✓
+- **Evidence Complete:** ✓
+
+---
+
+*Generated by StellaOps Scanner*
+```
+
+## Integrity Verification
+
+To verify bundle integrity:
+
+1. **Download with digest header**: The `X-Archive-Digest` response header contains the archive's SHA-256 hash
+2. **Verify archive hash**: `sha256sum evidence-{findingId}.zip`
+3. **Verify file hashes**: Compare each file's SHA-256 against `manifest.json`
+
+Example verification:
+
+```bash
+# Verify archive integrity
+EXPECTED_HASH="abc123..."
+ACTUAL_HASH=$(sha256sum evidence-f-abc123.zip | cut -d' ' -f1)
+if [ "$EXPECTED_HASH" = "$ACTUAL_HASH" ]; then
+    echo "Archive integrity verified"
+else
+    echo "Archive integrity check FAILED"
+    exit 1
+fi
+
+# Verify individual files
+cd evidence-f-abc123
+for file in $(jq -r '.files[].path' manifest.json); do
+    expected=$(jq -r ".files[] | select(.path==\"$file\") | .sha256" manifest.json)
+    actual=$(sha256sum "$file" | cut -d' ' -f1)
+    if [ "$expected" = "$actual" ]; then
+        echo "✓ $file"
+    else
+        echo "✗ $file"
+    fi
+done
+```
+
+## Content Types
+
+| File Type | Content-Type | Description |
+|-----------|--------------|-------------|
+| `.json` | `application/json` | JSON data files |
+| `.cdx.json` | `application/json` | CycloneDX SBOM |
+| `.dsse.json` | `application/json` | DSSE envelope |
+| `.sh` | `text/x-shellscript` | Bash script |
+| `.ps1` | `text/plain` | PowerShell script |
+| `.md` | `text/markdown` | Markdown documentation |
+| `.txt` | `text/plain` | Plain text |
+
+## See Also
+
+- [stella scan replay Command Reference](../cli/guides/commands/scan-replay.md)
+- [Deterministic Replay Specification](../replay/DETERMINISTIC_REPLAY.md)
+- [Unified Evidence Endpoint API](./unified-evidence-endpoint.md)
--- a/docs/modules/cli/guides/commands/scan-replay.md
+++ b/docs/modules/cli/guides/commands/scan-replay.md
@@ -0,0 +1,162 @@
+# scan replay Command Reference
+
+The `stella scan replay` command performs deterministic verdict reproduction using explicit input hashes.
+
+## Synopsis
+
+```bash
+stella scan replay [options]
+```
+
+## Description
+
+Replays a scan with explicit hashes for **deterministic verdict reproduction**. This command enables:
+
+- **Reproducibility**: Re-execute a scan with the same inputs to verify identical results
+- **Audit compliance**: Prove historical decisions can be recreated
+- **Offline verification**: Replay verdicts in air-gapped environments
+
+Unlike `stella replay --manifest <file>` which uses a manifest file, `stella scan replay` accepts individual hash parameters directly, making it suitable for:
+
+- Commands copied from evidence bundles
+- CI/CD pipeline integration
+- Backend-generated replay commands
+
+## Options
+
+### Required Parameters
+
+| Option | Description |
+|--------|-------------|
+| `--artifact <digest>` | Artifact digest to replay (e.g., `sha256:abc123...`) |
+| `--manifest <hash>` | Run manifest hash for configuration |
+| `--feeds <hash>` | Feed snapshot hash at time of scan |
+| `--policy <hash>` | Policy ruleset hash |
+
+### Optional Parameters
+
+| Option | Description |
+|--------|-------------|
+| `--snapshot <id>` | Knowledge snapshot ID for offline replay |
+| `--offline` | Run in offline/air-gapped mode. Requires all inputs to be locally cached |
+| `--verify-inputs` | Verify all input hashes before starting replay |
+| `-o, --output <path>` | Output file path for verdict JSON (defaults to stdout) |
+| `--verbose` | Enable verbose output with hash confirmation |
+
+## Usage Examples
+
+### Basic Replay
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321...
+```
+
+### Replay with Knowledge Snapshot
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321... \
+    --snapshot KS-2025-01-15-001
+```
+
+### Offline Replay with Verification
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321... \
+    --offline \
+    --verify-inputs \
+    --verbose
+```
+
+### Save Output to File
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321... \
+    --output replay-result.json
+```
+
+## Input Hash Verification
+
+When `--verify-inputs` is specified, the command validates:
+
+1. **Artifact digest format**: Must start with `sha256:` or `sha512:`
+2. **Hash lengths**: SHA256 = 64 hex characters, SHA512 = 128 hex characters
+3. **Local availability** (in offline mode): Verifies cached inputs exist
+
+## Offline Mode
+
+The `--offline` flag enables air-gapped replay:
+
+- All inputs must be pre-cached locally
+- No network calls are made
+- Use `stella offline prepare` to pre-fetch required data
+
+## Output Format
+
+```json
+{
+  "status": "success",
+  "artifactDigest": "sha256:a1b2c3d4e5f6...",
+  "manifestHash": "sha256:abc123def456...",
+  "feedSnapshotHash": "sha256:feed789feed...",
+  "policyHash": "sha256:policy321...",
+  "knowledgeSnapshotId": "KS-2025-01-15-001",
+  "offlineMode": false,
+  "startedAt": "2025-01-15T10:30:00Z",
+  "completedAt": "2025-01-15T10:30:45Z",
+  "verdict": {
+    "findingId": "f-abc123",
+    "status": "affected",
+    "confidence": 0.95
+  }
+}
+```
+
+## Integration with Evidence Bundles
+
+Evidence bundles generated by the `/v1/triage/findings/{id}/evidence/export` endpoint include ready-to-run replay scripts:
+
+- `replay.sh` - Bash script for Linux/macOS
+- `replay.ps1` - PowerShell script for Windows
+- `replay-command.txt` - Raw command for copy-paste
+
+Example from evidence bundle:
+
+```bash
+# From evidence bundle replay.sh
+stella scan replay \
+    --artifact "sha256:a1b2c3d4e5f6..." \
+    --manifest "sha256:abc123def456..." \
+    --feeds "sha256:feed789feed..." \
+    --policy "sha256:policy321..."
+```
+
+## Related Commands
+
+| Command | Description |
+|---------|-------------|
+| `stella replay --manifest <file>` | Replay using a manifest file |
+| `stella replay verify` | Verify determinism by replaying twice |
+| `stella replay snapshot` | Replay using knowledge snapshot ID |
+| `stella offline prepare` | Pre-fetch data for offline replay |
+
+## See Also
+
+- [Deterministic Replay Specification](../../replay/DETERMINISTIC_REPLAY.md)
+- [Offline Kit Documentation](../../24_OFFLINE_KIT.md)
+- [Evidence Bundle Format](./evidence-bundle-format.md)