stella-ops.org/git.stella-ops.org

Fork 0

Files

StellaOps Bot 43e2af88f6 docs consolidation

2025-12-24 21:45:46 +02:00

4.6 KiB

Raw Blame History

scan replay Command Reference

The stella scan replay command performs deterministic verdict reproduction using explicit input hashes.

Synopsis

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

stella scan replay \
    --artifact sha256:a1b2c3d4e5f6... \
    --manifest sha256:abc123def456... \
    --feeds sha256:feed789feed... \
    --policy sha256:policy321...

Replay with Knowledge Snapshot

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

stella scan replay \
    --artifact sha256:a1b2c3d4e5f6... \
    --manifest sha256:abc123def456... \
    --feeds sha256:feed789feed... \
    --policy sha256:policy321... \
    --offline \
    --verify-inputs \
    --verbose

Save Output to File

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:

Artifact digest format: Must start with sha256: or sha512:
Hash lengths: SHA256 = 64 hex characters, SHA512 = 128 hex characters
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

{
  "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:

# From evidence bundle replay.sh
stella scan replay \
    --artifact "sha256:a1b2c3d4e5f6..." \
    --manifest "sha256:abc123def456..." \
    --feeds "sha256:feed789feed..." \
    --policy "sha256:policy321..."

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

4.6 KiB Raw Blame History