feat: Implement IsolatedReplayContext for deterministic audit replay

- Added IsolatedReplayContext class to provide an isolated environment for replaying audit bundles without external calls. - Introduced methods for initializing the context, verifying input digests, and extracting inputs for policy evaluation. - Created supporting interfaces and options for context configuration. feat: Create ReplayExecutor for executing policy re-evaluation and verdict comparison - Developed ReplayExecutor class to handle the execution of replay processes, including input verification and verdict comparison. - Implemented detailed drift detection and error handling during replay execution. - Added interfaces for policy evaluation and replay execution options. feat: Add ScanSnapshotFetcher for fetching scan data and snapshots - Introduced ScanSnapshotFetcher class to retrieve necessary scan data and snapshots for audit bundle creation. - Implemented methods to fetch scan metadata, advisory feeds, policy snapshots, and VEX statements. - Created supporting interfaces for scan data, feed snapshots, and policy snapshots.
2025-12-23 07:46:34 +02:00
parent e47627cfff
commit 7e384ab610
77 changed files with 153346 additions and 209 deletions
--- a/docs/modules/cli/guides/commands/symbols.md
+++ b/docs/modules/cli/guides/commands/symbols.md
@@ -0,0 +1,191 @@
+# stella symbols — Command Guide
+
+> **Audience:** DevOps engineers, build teams, and CI authors working with debug symbols.
+> **Scope:** Commands for ingesting, uploading, and verifying symbol manifests for crash analysis.
+
+---
+
+## Commands
+
+- `stella symbols ingest --binary <path> [--debug <path>] [--server <url>]`
+- `stella symbols upload --manifest <path> --server <url> [--tenant <id>]`
+- `stella symbols verify --path <manifest-or-dsse>`
+- `stella symbols health --server <url>`
+
+---
+
+## 1. `stella symbols ingest`
+
+### Synopsis
+
+```bash
+stella symbols ingest \
+  --binary <path> \
+  [--debug <path>] \
+  [--debug-id <id>] \
+  [--code-id <id>] \
+  [--name <name>] \
+  [--platform <platform>] \
+  [--output <dir>] \
+  [--server <url>] \
+  [--tenant <id>] \
+  [--dry-run] \
+  [--verbose]
+```
+
+### Description
+
+Extracts debug symbols from a binary file (ELF, PE, Mach-O, WASM) and generates a symbol manifest. Optionally uploads the manifest and symbols to a configured symbols server.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--binary` | Path to the binary file (required) |
+| `--debug` | Path to debug symbols file (PDB, DWARF, dSYM) |
+| `--debug-id` | Override the detected debug ID |
+| `--code-id` | Override the detected code ID |
+| `--name` | Override binary name in manifest |
+| `--platform` | Platform identifier (linux-x64, win-x64, osx-arm64, etc.) |
+| `--output` | Output directory for manifest files (default: current directory) |
+| `--server` | Symbols server URL for automatic upload |
+| `--tenant` | Tenant ID for multi-tenant deployments |
+| `--dry-run` | Generate manifest without uploading |
+| `--verbose` | Enable verbose output |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Error (file not found, unknown format, upload failed) |
+
+### Example
+
+```bash
+stella symbols ingest \
+  --binary ./bin/myapp \
+  --debug ./bin/myapp.pdb \
+  --server https://symbols.internal.example \
+  --platform linux-x64
+```
+
+---
+
+## 2. `stella symbols upload`
+
+### Synopsis
+
+```bash
+stella symbols upload \
+  --manifest <path> \
+  --server <url> \
+  [--tenant <id>] \
+  [--dry-run] \
+  [--verbose]
+```
+
+### Description
+
+Uploads a previously generated symbol manifest to the symbols server.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--manifest` | Path to manifest JSON file (required) |
+| `--server` | Symbols server URL (required) |
+| `--tenant` | Tenant ID for multi-tenant uploads |
+| `--dry-run` | Validate without uploading |
+| `--verbose` | Enable verbose output |
+
+### Example
+
+```bash
+stella symbols upload \
+  --manifest ./myapp.manifest.json \
+  --server https://symbols.internal.example
+```
+
+---
+
+## 3. `stella symbols verify`
+
+### Synopsis
+
+```bash
+stella symbols verify \
+  --path <manifest-or-dsse> \
+  [--verbose]
+```
+
+### Description
+
+Verifies a symbol manifest or DSSE envelope. Checks JSON structure, required fields, and signature validity for DSSE envelopes.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--path` | Path to manifest or DSSE file (required) |
+| `--verbose` | Enable verbose output |
+
+### Example
+
+```bash
+stella symbols verify --path ./myapp.manifest.json
+stella symbols verify --path ./myapp.dsse.json
+```
+
+---
+
+## 4. `stella symbols health`
+
+### Synopsis
+
+```bash
+stella symbols health --server <url>
+```
+
+### Description
+
+Checks the health status of a symbols server.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--server` | Symbols server URL (required) |
+
+### Example
+
+```bash
+stella symbols health --server https://symbols.internal.example
+```
+
+---
+
+## Offline/Air-Gap Notes
+
+- Symbol ingestion works entirely offline when not specifying `--server`.
+- Manifests can be generated locally and transferred via secure media for upload in connected environments.
+- Use `--dry-run` to validate configurations before deployment.
+
+---
+
+## Migration from stella-symbols
+
+The standalone `stella-symbols` CLI is deprecated and will be removed on 2025-07-01.
+
+| Old Command | New Command |
+|-------------|-------------|
+| `stella-symbols ingest ...` | `stella symbols ingest ...` |
+| `stella-symbols upload ...` | `stella symbols upload ...` |
+| `stella-symbols verify ...` | `stella symbols verify ...` |
+| `stella-symbols health ...` | `stella symbols health ...` |
+
+See the [CLI Consolidation Migration Guide](../../../../cli/cli-consolidation-migration.md) for details.
+
+---
+
+*Last updated: 2025-12-23 (Sprint 5100).*