296 lines
7.2 KiB
Markdown
296 lines
7.2 KiB
Markdown
# 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)
|