test

2025-12-22 09:56:20 +02:00
parent 00bc4f79dd
commit dfaa2079aa
7 changed files with 1574 additions and 12 deletions
--- a/docs/modules/snapshot/replay-yaml.md
+++ b/docs/modules/snapshot/replay-yaml.md
@@ -0,0 +1,295 @@
+# REPLAY.yaml Manifest Specification
+
+## Overview
+
+The **REPLAY.yaml** manifest defines the complete set of inputs required to reproduce a StellaOps evaluation. It is the root document in a `.stella-replay.tgz` bundle.
+
+## File Location
+
+```
+.stella-replay.tgz
+├── REPLAY.yaml          # This manifest
+├── sboms/
+├── vex/
+├── reach/
+├── exceptions/
+├── policies/
+├── feeds/
+├── config/
+└── SIGNATURE.sig        # Optional DSSE signature
+```
+
+## Schema Version
+
+Current schema version: `1.0.0`
+
+```yaml
+version: "1.0.0"
+```
+
+## Complete Example
+
+```yaml
+version: "1.0.0"
+
+snapshot:
+  id: "snap-20241222-abc123"
+  createdAt: "2024-12-22T12:00:00Z"
+  artifact: "sha256:abc123..."
+  previousId: "snap-20241221-xyz789"
+
+inputs:
+  sboms:
+    - path: "sboms/cyclonedx.json"
+      format: "cyclonedx-1.6"
+      digest: "sha256:def456..."
+    - path: "sboms/spdx.json"
+      format: "spdx-3.0.1"
+      digest: "sha256:ghi789..."
+
+  vex:
+    - path: "vex/vendor-lodash.json"
+      source: "vendor:lodash"
+      format: "openvex"
+      digest: "sha256:jkl012..."
+      trustScore: 0.95
+    - path: "vex/redhat-csaf.json"
+      source: "distro:redhat"
+      format: "csaf"
+      digest: "sha256:mno345..."
+      trustScore: 0.90
+
+  reachability:
+    - path: "reach/api-handler.json"
+      entryPoint: "/api/handler"
+      digest: "sha256:pqr678..."
+      nodeCount: 42
+      edgeCount: 57
+
+  exceptions:
+    - path: "exceptions/exc-001.json"
+      exceptionId: "exc-001"
+      digest: "sha256:stu901..."
+
+  policies:
+    bundlePath: "policies/bundle.tar.gz"
+    digest: "sha256:vwx234..."
+    version: "2.1.0"
+    rulesHash: "sha256:yza567..."
+
+  feeds:
+    - feedId: "nvd"
+      name: "National Vulnerability Database"
+      version: "2024-12-22T00:00:00Z"
+      digest: "sha256:bcd890..."
+      fetchedAt: "2024-12-22T06:00:00Z"
+    - feedId: "ghsa"
+      name: "GitHub Security Advisories"
+      version: "2024-12-22T01:00:00Z"
+      digest: "sha256:efg123..."
+      fetchedAt: "2024-12-22T06:15:00Z"
+
+  lattice:
+    type: "K4"
+    configDigest: "sha256:hij456..."
+
+  trust:
+    configDigest: "sha256:klm789..."
+    defaultWeight: 0.5
+
+outputs:
+  verdictPath: "verdict.json"
+  verdictDigest: "sha256:nop012..."
+  findingsPath: "findings.ndjson"
+  findingsDigest: "sha256:qrs345..."
+
+seeds:
+  rng: 12345678
+  sampling: 87654321
+
+environment:
+  STELLAOPS_POLICY_VERSION: "2.1.0"
+  STELLAOPS_LATTICE_TYPE: "K4"
+
+signature:
+  algorithm: "ecdsa-p256"
+  keyId: "signing-key-prod-2024"
+  value: "MEUCIQDx..."
+```
+
+## Field Reference
+
+### snapshot
+
+Metadata about the snapshot itself.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | Yes | Unique snapshot identifier |
+| createdAt | datetime | Yes | ISO 8601 timestamp |
+| artifact | string | Yes | Artifact digest being evaluated |
+| previousId | string | No | Previous snapshot for diff |
+
+### inputs.sboms
+
+SBOM documents included in bundle.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Path within bundle |
+| format | string | Yes | `cyclonedx-1.6` or `spdx-3.0.1` |
+| digest | string | Yes | Content digest |
+
+### inputs.vex
+
+VEX documents from various sources.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Path within bundle |
+| source | string | Yes | Source identifier (vendor:*, distro:*, etc.) |
+| format | string | Yes | `openvex`, `csaf`, `cyclonedx-vex` |
+| digest | string | Yes | Content digest |
+| trustScore | number | Yes | Trust weight (0.0-1.0) |
+
+### inputs.reachability
+
+Reachability subgraph data.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Path within bundle |
+| entryPoint | string | Yes | Entry point identifier |
+| digest | string | Yes | Content digest |
+| nodeCount | integer | No | Number of nodes |
+| edgeCount | integer | No | Number of edges |
+
+### inputs.exceptions
+
+Active exceptions at snapshot time.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Path within bundle |
+| exceptionId | string | Yes | Exception identifier |
+| digest | string | Yes | Content digest |
+
+### inputs.policies
+
+Policy bundle reference.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| bundlePath | string | Yes | Path to policy bundle |
+| digest | string | Yes | Bundle digest |
+| version | string | No | Policy version |
+| rulesHash | string | Yes | Hash of compiled rules |
+
+### inputs.feeds
+
+Advisory feed versions at snapshot time.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| feedId | string | Yes | Feed identifier |
+| name | string | No | Human-readable name |
+| version | string | Yes | Feed version/timestamp |
+| digest | string | Yes | Feed content digest |
+| fetchedAt | datetime | Yes | When feed was fetched |
+
+### inputs.lattice
+
+Lattice configuration for merge semantics.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| type | string | Yes | `K4`, `Boolean`, `8-state` |
+| configDigest | string | Yes | Configuration hash |
+
+### inputs.trust
+
+Trust weight configuration.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| configDigest | string | Yes | Configuration hash |
+| defaultWeight | number | No | Default trust weight |
+
+### outputs
+
+Evaluation outputs for verification.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| verdictPath | string | Yes | Path to verdict file |
+| verdictDigest | string | Yes | Verdict content digest |
+| findingsPath | string | No | Path to findings file |
+| findingsDigest | string | No | Findings content digest |
+
+### seeds
+
+Random seeds for deterministic evaluation.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| rng | integer | No | Random number generator seed |
+| sampling | integer | No | Sampling algorithm seed |
+
+### environment
+
+Environment variables captured (non-sensitive).
+
+Key-value pairs of environment configuration.
+
+### signature
+
+DSSE signature over manifest.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| algorithm | string | Yes | Signing algorithm |
+| keyId | string | Yes | Signing key identifier |
+| value | string | Yes | Base64-encoded signature |
+
+## Digest Format
+
+All digests use the format:
+```
+sha256:<64-char-hex>
+```
+
+Example:
+```
+sha256:a1b2c3d4e5f6...
+```
+
+## Validation
+
+Bundle validation checks:
+1. REPLAY.yaml exists at bundle root
+2. All referenced files exist
+3. All digests match content
+4. Schema validates against JSON Schema
+5. Signature verifies (if present)
+
+## CLI Usage
+
+```bash
+# Create bundle
+stella snapshot export --output snapshot.stella-replay.tgz
+
+# Verify bundle
+stella snapshot verify snapshot.stella-replay.tgz
+
+# Replay from bundle
+stella replay --bundle snapshot.stella-replay.tgz
+
+# View manifest
+stella snapshot manifest snapshot.stella-replay.tgz
+```
+
+## Related Documentation
+
+- [Knowledge Snapshot Model](./knowledge-snapshot.md)
+- [Merge Preview](./merge-preview.md)
+- [Replay Engine](../../modules/policy/implementation_plan.md)