git.stella-ops.org/docs/modules/snapshot/replay-yaml.md

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

version: "1.0.0"

Complete Example

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

# 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
• Merge Preview
• Replay Engine