REPLAY.yaml Manifest Specification

Audience: engineers building or verifying replay bundles, and integrators producing .stella-replay.tgz artifacts. Part of the Snapshot concept.

Overview

The REPLAY.yaml manifest defines the complete set of inputs required to reproduce a Stella Ops evaluation. It is the root document in a .stella-replay.tgz bundle: pin every input by content digest, capture the seeds and configuration, and the same verdict can be reproduced offline at any later time.

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.

inputs.sboms

SBOM documents included in bundle.

inputs.vex

VEX documents from various sources.

inputs.reachability

Reachability subgraph data.

inputs.exceptions

Active exceptions at snapshot time.

inputs.policies

Policy bundle reference.

inputs.feeds

Advisory feed versions at snapshot time.

inputs.lattice

Lattice configuration for merge semantics.

inputs.trust

Trust weight configuration.

outputs

Evaluation outputs for verification.

seeds

Random seeds for deterministic evaluation.

environment

Environment variables captured (non-sensitive).

Key-value pairs of environment configuration.

signature

DSSE signature over manifest.

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

• Snapshot overview (knowledge snapshot model)
• Merge Preview
• Replay module
• Policy Engine implementation plan