Add signal contracts for reachability, exploitability, trust, and unknown symbols

- Introduced `ReachabilityState`, `RuntimeHit`, `ExploitabilitySignal`, `ReachabilitySignal`, `SignalEnvelope`, `SignalType`, `TrustSignal`, and `UnknownSymbolSignal` records to define various signal types and their properties. - Implemented JSON serialization attributes for proper data interchange. - Created project files for the new signal contracts library and corresponding test projects. - Added deterministic test fixtures for micro-interaction testing. - Included cryptographic keys for secure operations with cosign.
2025-12-05 00:27:00 +02:00
parent b018949a8d
commit 8768c27f30
192 changed files with 27569 additions and 2552 deletions
--- a/docs/deployment/VERSION_MATRIX.md
+++ b/docs/deployment/VERSION_MATRIX.md
@@ -0,0 +1,296 @@
+# StellaOps Deployment Version Matrix
+
+> **Last Updated:** 2025-12-04
+> **Purpose:** Single source of truth for service versions across deployment environments
+> **Unblocks:** COMPOSE-44-001, 44-001, 44-002, 44-003, 45-001, 45-002, 45-003 (7 tasks)
+
+## Quick Reference
+
+| Environment | Core Version | Status |
+|-------------|-------------|--------|
+| **Development** | `2025.10.0-edge` | Active |
+| **Staging** | `2025.09.2` | Stable |
+| **Production** | `2025.09.2` | Stable |
+| **Air-Gap** | `2025.09.2-airgap` | Certified |
+
+---
+
+## Service Version Matrix
+
+### Core Services
+
+| Service | Dev | Staging | Prod | Air-Gap | Notes |
+|---------|-----|---------|------|---------|-------|
+| Authority | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | OAuth 2.1 / mTLS |
+| Signer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | ECDSA/RSA/EdDSA |
+| Attestor | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | in-toto/DSSE |
+| Concelier | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Advisory ingestion |
+| Scanner | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | SBOM/Vuln scanning |
+| Excititor | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | VEX export |
+| Policy | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | OPA/Rego engine |
+| Scheduler | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Job scheduling |
+| Notify | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Notifications |
+
+### Platform Services
+
+| Service | Dev | Staging | Prod | Air-Gap | Notes |
+|---------|-----|---------|------|---------|-------|
+| Orchestrator Web | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | API Gateway |
+| Orchestrator Worker | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Background jobs |
+| Graph API | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Graph queries |
+| Graph Indexer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Graph ingest |
+| Timeline Indexer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Event timeline |
+| Findings Ledger | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Finding storage |
+
+### Infrastructure Dependencies
+
+| Component | Version | Digest | Notes |
+|-----------|---------|--------|-------|
+| MongoDB | `7.0` | `sha256:c258b26dbb7774f97f52aff52231ca5f228273a84329c5f5e451c3739457db49` | Primary database |
+| PostgreSQL | `16-alpine` | N/A | Scheduler/metadata |
+| MinIO | `RELEASE.2024-01-01` | `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e` | Object storage |
+| NATS | `2.10` | `sha256:c82559e4476289481a8a5196e675ebfe67eea81d95e5161e3e78eccfe766608e` | Message queue |
+| RustFS | `2025.10.0-edge` | N/A | Content-addressed storage |
+
+---
+
+## Container Image Registry
+
+### Primary Registry
+
+```
+registry.stella-ops.org/stellaops/<service>:<version>
+```
+
+### Image Naming Convention
+
+| Pattern | Example | Use Case |
+|---------|---------|----------|
+| `<service>:<version>` | `authority:2025.09.2` | Tagged releases |
+| `<service>:<version>-<variant>` | `authority:2025.09.2-airgap` | Environment variants |
+| `<service>:edge` | `authority:edge` | Latest dev build |
+| `<service>@sha256:<digest>` | `authority@sha256:abc123...` | Immutable reference |
+
+### Air-Gap Bundle Images
+
+Air-gap deployments use pre-bundled images with all dependencies:
+
+```
+registry.stella-ops.org/stellaops/airgap-bundle:2025.09.2
+```
+
+Bundle contents:
+- All core services at matching version
+- Infrastructure containers (Mongo, MinIO, NATS)
+- CLI tools and migration utilities
+- Offline kit documentation
+
+---
+
+## Version Promotion Workflow
+
+### Stages
+
+```
+Dev (edge) → Staging → Production → Air-Gap (certified)
+```
+
+### Promotion Criteria
+
+| Stage | Criteria |
+|-------|----------|
+| Dev → Staging | All unit tests pass, integration tests pass |
+| Staging → Prod | E2E tests pass, security scan clean, performance benchmarks pass |
+| Prod → Air-Gap | Offline validation complete, bundle integrity verified, documentation updated |
+
+### Promotion Commands
+
+```bash
+# Promote dev to staging
+./scripts/promote.sh --from dev --to staging --version 2025.10.0
+
+# Promote staging to production
+./scripts/promote.sh --from staging --to prod --version 2025.10.0
+
+# Create air-gap certified bundle
+./scripts/create-airgap-bundle.sh --version 2025.09.2
+```
+
+---
+
+## Helm Chart Values
+
+### Development (`values-dev.yaml`)
+
+```yaml
+global:
+  imageTag: "2025.10.0-edge"
+  imagePullPolicy: Always
+  environment: development
+
+services:
+  authority:
+    replicaCount: 1
+    resources:
+      requests:
+        memory: "256Mi"
+        cpu: "100m"
+```
+
+### Production (`values-prod.yaml`)
+
+```yaml
+global:
+  imageTag: "2025.09.2"
+  imagePullPolicy: IfNotPresent
+  environment: production
+
+services:
+  authority:
+    replicaCount: 3
+    resources:
+      requests:
+        memory: "512Mi"
+        cpu: "250m"
+```
+
+### Air-Gap (`values-airgap.yaml`)
+
+```yaml
+global:
+  imageTag: "2025.09.2-airgap"
+  imagePullPolicy: Never  # Images pre-loaded
+  environment: airgap
+  offlineMode: true
+
+airgap:
+  enabled: true
+  bundleVersion: "2025.09.2"
+  stalenessThresholdSeconds: 604800  # 7 days
+```
+
+---
+
+## Docker Compose Reference
+
+### Quick Start (Development)
+
+```yaml
+# docker-compose.dev.yaml
+version: "3.8"
+services:
+  authority:
+    image: registry.stella-ops.org/stellaops/authority:2025.10.0-edge
+
+  concelier:
+    image: registry.stella-ops.org/stellaops/concelier:2025.10.0-edge
+
+  scanner:
+    image: registry.stella-ops.org/stellaops/scanner:2025.10.0-edge
+```
+
+### Production
+
+```yaml
+# docker-compose.prod.yaml
+version: "3.8"
+services:
+  authority:
+    image: registry.stella-ops.org/stellaops/authority@sha256:...
+    deploy:
+      replicas: 3
+
+  concelier:
+    image: registry.stella-ops.org/stellaops/concelier@sha256:...
+    deploy:
+      replicas: 2
+```
+
+---
+
+## Service Dependencies
+
+### Startup Order
+
+```
+1. Infrastructure (MongoDB, NATS, MinIO)
+   ↓
+2. Core Auth (Authority, Signer)
+   ↓
+3. Data Services (Concelier, Excititor)
+   ↓
+4. Compute Services (Scanner, Policy, Scheduler)
+   ↓
+5. Platform Services (Orchestrator, Graph, Timeline)
+   ↓
+6. UI/CLI
+```
+
+### Health Check Endpoints
+
+| Service | Health Endpoint | Ready Endpoint |
+|---------|-----------------|----------------|
+| All | `/health` | `/ready` |
+| Authority | `/health` | `/ready` (includes JWKS) |
+| Scanner | `/health` | `/ready` (includes analyzer check) |
+
+---
+
+## Breaking Changes Log
+
+### 2025.10.0 (Upcoming)
+
+- **Authority:** New OAuth 2.1 endpoints (backward compatible)
+- **Scanner:** Analyzer plugin format v2 (migration required)
+- **Concelier:** LNM API v2 (v1 deprecated, removed in 2025.11.0)
+
+### 2025.09.2 (Current Stable)
+
+- **All:** Initial GA release
+- **Air-Gap:** First certified offline bundle
+
+---
+
+## Rollback Procedure
+
+### Helm Rollback
+
+```bash
+# List releases
+helm history stellaops -n stellaops
+
+# Rollback to previous
+helm rollback stellaops 1 -n stellaops
+```
+
+### Compose Rollback
+
+```bash
+# Stop current
+docker-compose down
+
+# Edit .env to previous version
+# VERSION=2025.09.1
+
+# Start previous
+docker-compose up -d
+```
+
+---
+
+## Related Documents
+
+- [Helm Chart Documentation](../deploy/helm/stellaops/README.md)
+- [Compose Quickstart](../deploy/compose/README.md)
+- [Offline Kit Guide](./24_OFFLINE_KIT.md)
+- [Air-Gap Provenance](../modules/findings-ledger/airgap-provenance.md)
+- [Staleness Schema](../schemas/ledger-airgap-staleness.schema.json)
+
+---
+
+## Changelog
+
+| Date | Change | Author |
+|------|--------|--------|
+| 2025-12-04 | Initial version matrix created | Claude |
+| 2025-12-04 | Added air-gap certification workflow | Claude |