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/cli/cli-consolidation-migration.md
+++ b/docs/cli/cli-consolidation-migration.md
@@ -0,0 +1,219 @@
+# CLI Consolidation Migration Guide
+
+**Sprint:** SPRINT_5100_0001_0001
+**Status:** In Progress
+**Effective Date:** 2025-01-01 (deprecation begins)
+**Sunset Date:** 2025-07-01 (old CLIs removed)
+
+## Overview
+
+StellaOps is consolidating multiple standalone CLI tools into a single unified `stella` command with plugin-based subcommands. This improves developer experience, simplifies distribution, and ensures consistent behavior across all CLI operations.
+
+## Migration Summary
+
+| Old CLI | New Command | Status |
+|---------|-------------|--------|
+| `stella-aoc verify` | `stella aoc verify` | Available |
+| `stella-symbols ingest` | `stella symbols ingest` | Available |
+| `stella-symbols upload` | `stella symbols upload` | Available |
+| `stella-symbols verify` | `stella symbols verify` | Available |
+| `stella-symbols health` | `stella symbols health` | Available |
+| `cryptoru` | `cryptoru` (unchanged) | Separate |
+
+**Note:** `cryptoru` CLI remains separate due to regional compliance requirements.
+
+## Migration Steps
+
+### 1. AOC CLI Migration
+
+**Before (deprecated):**
+```bash
+stella-aoc verify --since 2025-01-01 --postgres "Host=localhost;..."
+```
+
+**After:**
+```bash
+stella aoc verify --since 2025-01-01 --postgres "Host=localhost;..."
+```
+
+**Command Options (unchanged):**
+- `--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
+
+### 2. Symbols CLI Migration
+
+#### Ingest Command
+
+**Before (deprecated):**
+```bash
+stella-symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com
+```
+
+**After:**
+```bash
+stella symbols ingest --binary ./myapp --debug ./myapp.pdb --server https://symbols.example.com
+```
+
+#### Upload Command
+
+**Before (deprecated):**
+```bash
+stella-symbols upload --manifest ./manifest.json --server https://symbols.example.com
+```
+
+**After:**
+```bash
+stella symbols upload --manifest ./manifest.json --server https://symbols.example.com
+```
+
+#### Verify Command
+
+**Before (deprecated):**
+```bash
+stella-symbols verify --path ./manifest.json
+```
+
+**After:**
+```bash
+stella symbols verify --path ./manifest.json
+```
+
+#### Health Command
+
+**Before (deprecated):**
+```bash
+stella-symbols health --server https://symbols.example.com
+```
+
+**After:**
+```bash
+stella symbols health --server https://symbols.example.com
+```
+
+## CI/CD Updates
+
+### GitHub Actions
+
+**Before:**
+```yaml
+- name: Verify AOC compliance
+  run: stella-aoc verify --since ${{ github.event.before }} --postgres "$POSTGRES_CONN"
+```
+
+**After:**
+```yaml
+- name: Verify AOC compliance
+  run: stella aoc verify --since ${{ github.event.before }} --postgres "$POSTGRES_CONN"
+```
+
+### GitLab CI
+
+**Before:**
+```yaml
+aoc-verify:
+  script:
+    - stella-aoc verify --since $CI_COMMIT_BEFORE_SHA --postgres "$POSTGRES_CONN"
+```
+
+**After:**
+```yaml
+aoc-verify:
+  script:
+    - stella aoc verify --since $CI_COMMIT_BEFORE_SHA --postgres "$POSTGRES_CONN"
+```
+
+### Shell Scripts
+
+Update any shell scripts that invoke the old CLIs:
+
+```bash
+# Find and replace patterns
+sed -i 's/stella-aoc /stella aoc /g' scripts/*.sh
+sed -i 's/stella-symbols /stella symbols /g' scripts/*.sh
+```
+
+## Deprecation Timeline
+
+| Date | Action |
+|------|--------|
+| 2025-01-01 | Deprecation warnings added to old CLIs |
+| 2025-03-01 | Warning frequency increased (every invocation) |
+| 2025-05-01 | Old CLIs emit error + warning, still functional |
+| 2025-07-01 | Old CLIs removed from distribution |
+
+## Deprecation Warnings
+
+When using deprecated CLIs, you will see warnings like:
+
+```
+[DEPRECATED] stella-aoc is deprecated and will be removed on 2025-07-01.
+Please migrate to: stella aoc verify ...
+See: https://docs.stellaops.io/cli/migration
+```
+
+## Plugin Architecture
+
+The new `stella` CLI uses a plugin architecture. Plugins are automatically discovered from:
+- `<stella-install-dir>/plugins/cli/`
+- Custom directories via `STELLAOPS_CLI_PLUGINS_DIR`
+
+Each plugin provides:
+- A manifest file (`*.manifest.json`)
+- A .NET assembly implementing `ICliCommandModule`
+
+## Troubleshooting
+
+### Plugin Not Found
+
+If a subcommand is not available:
+
+1. Check plugin directory exists:
+   ```bash
+   ls $(dirname $(which stella))/plugins/cli/
+   ```
+
+2. Verify manifest file:
+   ```bash
+   cat $(dirname $(which stella))/plugins/cli/StellaOps.Cli.Plugins.Aoc/stellaops.cli.plugins.aoc.manifest.json
+   ```
+
+3. Enable verbose logging:
+   ```bash
+   stella --verbose aoc verify ...
+   ```
+
+### Version Compatibility
+
+Ensure all components are from the same release:
+```bash
+stella --version
+# StellaOps CLI v1.0.0
+```
+
+## Environment Variables
+
+The unified CLI respects all existing environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `STELLAOPS_BACKEND_URL` | Backend API URL |
+| `STELLAOPS_CLI_PLUGINS_DIR` | Custom plugins directory |
+| `STELLAOPS_AUTHORITY_URL` | Authority service URL |
+| `STELLAOPS_LOG_LEVEL` | Logging verbosity |
+
+## Getting Help
+
+- Documentation: https://docs.stellaops.io/cli
+- Issues: https://github.com/stellaops/stellaops/issues
+- Migration support: support@stellaops.io
+
+## Related Documentation
+
+- [CLI Reference](../09_API_CLI_REFERENCE.md)
+- [Audit Pack Commands](./audit-pack-commands.md)
+- [Unknowns CLI Reference](./unknowns-cli-reference.md)