stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

feat: Implement IsolatedReplayContext for deterministic audit replay

Browse Source 
- 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
2025-12-23 07:46:34 +02:00
parent e47627cfff
commit 7e384ab610
77 changed files with 153346 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/modules/cli/guides/cli-reference.md
View File

@@ -36,7 +36,7 @@ stella sources ingest --dry-run \
### 2.2 Description
Previews an ingestion write without touching MongoDB. The command loads an upstream advisory or VEX document, computes the would-write payload, runs it through the `AOCWriteGuard`, and reports any forbidden fields, provenance gaps, or idempotency issues. Use it during connector development, CI validation, or while triaging incidents.
Previews an ingestion write without touching the database. The command loads an upstream advisory or VEX document, computes the would-write payload, runs it through the `AOCWriteGuard`, and reports any forbidden fields, provenance gaps, or idempotency issues. Use it during connector development, CI validation, or while triaging incidents.
### 2.3 Options
@@ -370,7 +370,7 @@ sha256sum /mnt/offline/aoc-verify-*.json > /mnt/offline/checksums.txt
### 3.8 Offline notes
- Works against Offline Kit Mongo snapshots when CLI is pointed at the local API gateway included in the bundle.
- Works against Offline Kit PostgreSQL snapshots when CLI is pointed at the local API gateway included in the bundle.
- When fully disconnected, run against exported `aoc verify` reports generated on production and replay them using `--format json --export` (automation recipe above).
- Include verification output in compliance packages alongside Offline Kit manifests.

119
docs/modules/cli/guides/commands/aoc.md
View File

@@ -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
View 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).*