# scan replay Command Reference

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

## Synopsis

```bash
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

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

### Replay with Knowledge Snapshot

```bash
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

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

### Save Output to File

```bash
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:

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

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

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

## Related Commands

| 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 |

## See Also

- [Deterministic Replay Specification](../../replay/DETERMINISTIC_REPLAY.md)
- [Offline Kit Documentation](../../24_OFFLINE_KIT.md)
- [Evidence Bundle Format](./evidence-bundle-format.md)