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.
This commit is contained in:
StellaOps Bot
@@ -1,21 +1,112 @@
|
||||
# stella aoc — Command Guide
|
||||
|
||||
> **Audience:** DevOps engineers, compliance teams, and CI authors working with AOC verification.
|
||||
> **Scope:** Commands for verifying Aggregation-Only Contract compliance.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
- `stella aoc verify --input <evidence> [--policy <path>] [--offline]`
|
||||
- `stella aoc explain --input <evidence> [--output json|table]`
|
||||
|
||||
## Flags (common)
|
||||
- `--offline`: verify evidence without remote calls; exit code 5 if network would be required.
|
||||
- `--policy`: optional AOC policy file; defaults to platform policy.
|
||||
- `--output`: json (default), table.
|
||||
- `stella aoc verify --since <ref> --postgres <conn> [options]`
|
||||
|
||||
## Inputs/outputs
|
||||
- Inputs: AOC evidence bundle; optional policy file.
|
||||
- Outputs: verification results with rationale; aggregation-only.
|
||||
- Exit codes per `output-and-exit-codes.md`; 3 for auth failures, 4 for missing evidence, 5 for offline violation.
|
||||
---
|
||||
|
||||
## Determinism rules
|
||||
- Stable ordering of findings; timestamps UTC; hashes lowercase hex.
|
||||
## 1. `stella aoc verify`
|
||||
|
||||
## Offline/air-gap notes
|
||||
- Trust roots loaded locally; no remote downloads allowed in offline mode.
|
||||
### Synopsis
|
||||
|
||||
```bash
|
||||
stella aoc verify \
|
||||
--since <git-sha|timestamp> \
|
||||
--postgres <connection-string> \
|
||||
[--output <path>] \
|
||||
[--ndjson <path>] \
|
||||
[--tenant <id>] \
|
||||
[--dry-run] \
|
||||
[--verbose]
|
||||
```
|
||||
|
||||
### Description
|
||||
|
||||
Verifies AOC compliance by comparing git history against database records. Detects violations where data was modified or deleted in violation of the append-only contract.
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--since, -s` | Git commit SHA or ISO timestamp to verify from (required) |
|
||||
| `--postgres, -p` | PostgreSQL connection string (required) |
|
||||
| `--output, -o` | Path for JSON output report |
|
||||
| `--ndjson, -n` | Path for NDJSON output (one violation per line) |
|
||||
| `--tenant, -t` | Filter by tenant ID |
|
||||
| `--dry-run` | Validate configuration without querying database |
|
||||
| `--verbose, -v` | Enable verbose output |
|
||||
|
||||
### Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| `0` | Verification passed - no violations |
|
||||
| `1` | Violations detected |
|
||||
| `2` | Configuration or connection error |
|
||||
|
||||
### Examples
|
||||
|
||||
Daily verification:
|
||||
|
||||
```bash
|
||||
stella aoc verify \
|
||||
--since 24h \
|
||||
--postgres "Host=localhost;Database=stellaops;Username=verifier;Password=..."
|
||||
```
|
||||
|
||||
CI pipeline verification from last commit:
|
||||
|
||||
```bash
|
||||
stella aoc verify \
|
||||
--since ${{ github.event.before }} \
|
||||
--postgres "$POSTGRES_CONN" \
|
||||
--output artifacts/aoc-verify.json
|
||||
```
|
||||
|
||||
Tenant-scoped verification:
|
||||
|
||||
```bash
|
||||
stella aoc verify \
|
||||
--since 2025-01-01T00:00:00Z \
|
||||
--postgres "$POSTGRES_CONN" \
|
||||
--tenant acme-corp \
|
||||
--ndjson violations.ndjson
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Offline/Air-Gap Notes
|
||||
|
||||
- Connect to local PostgreSQL instances included in Offline Kit deployments.
|
||||
- Use `--output` to generate reports for transfer to connected environments.
|
||||
- Verification is read-only and does not modify any data.
|
||||
|
||||
---
|
||||
|
||||
## Migration from stella-aoc
|
||||
|
||||
The standalone `stella-aoc` CLI is deprecated and will be removed on 2025-07-01.
|
||||
|
||||
| Old Command | New Command |
|
||||
|-------------|-------------|
|
||||
| `stella-aoc verify ...` | `stella aoc verify ...` |
|
||||
|
||||
See the [CLI Consolidation Migration Guide](../../../../cli/cli-consolidation-migration.md) for details.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Aggregation-Only Contract Reference](../../../../ingestion/aggregation-only-contract.md)
|
||||
- [CLI Reference](../cli-reference.md)
|
||||
- [Container Deployment Guide](../../../../deploy/containers.md)
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-12-23 (Sprint 5100).*
|
||||
|
||||
191
docs/modules/cli/guides/commands/symbols.md
Normal file
191
docs/modules/cli/guides/commands/symbols.md
Normal file
@@ -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).*
|
||||
Reference in New Issue
Block a user