7503c19b8f
- Implemented comprehensive tests for verdict artifact generation to ensure deterministic outputs across various scenarios, including identical inputs, parallel execution, and change ordering. - Created helper methods for generating sample verdict inputs and computing canonical hashes. - Added tests to validate the stability of canonical hashes, proof spine ordering, and summary statistics. - Introduced a new PowerShell script to update SHA256 sums for files, ensuring accurate hash generation and file integrity checks.
81 lines
4.7 KiB
Markdown
Executable File
81 lines
4.7 KiB
Markdown
Executable File
# Architecture Overview (High-Level)
|
|
|
|
This document is the 10-minute tour for StellaOps: what components exist, how they fit together, and what "offline-first + deterministic + evidence-linked decisions" means in practice.
|
|
|
|
For the full reference map (services, boundaries, detailed flows), see `docs/07_HIGH_LEVEL_ARCHITECTURE.md`.
|
|
|
|
## Guiding Principles
|
|
|
|
- **SBOM-first:** scan and reason over SBOMs; fall back to unpacking only when needed.
|
|
- **Deterministic replay:** the same inputs yield the same outputs (stable ordering, canonical hashing, UTC timestamps).
|
|
- **Evidence-linked decisions:** policy decisions link back to specific evidence artifacts (SBOM slices, advisory/VEX observations, reachability proofs, attestations).
|
|
- **Aggregation-not-merge:** upstream advisories and VEX are stored and exposed with provenance; conflicts are visible, not silently collapsed.
|
|
- **Offline-first:** the same workflow runs connected or air-gapped via Offline Kit snapshots and signed bundles.
|
|
|
|
## System Map (What Runs)
|
|
|
|
```
|
|
Build -> Sign -> Store -> Scan -> Decide -> Attest -> Notify/Export
|
|
```
|
|
|
|
At a high level, StellaOps is a set of services grouped by responsibility:
|
|
|
|
- **Identity and authorization:** Authority (OIDC/OAuth2, scopes/tenancy)
|
|
- **Scanning and SBOM:** Scanner WebService + Worker (facts generation)
|
|
- **Advisories:** Concelier (ingest/normalize/export vulnerability sources)
|
|
- **VEX:** Excititor + VEX Lens (VEX observations/linksets and exploration)
|
|
- **Decisioning:** Policy Engine surfaces (lattice-style explainable policy)
|
|
- **Signing and transparency:** Signer + Attestor (DSSE/in-toto and optional transparency)
|
|
- **Orchestration and delivery:** Scheduler, Notify, Export Center
|
|
- **Console:** Web UI for operators and auditors
|
|
|
|
| Tier | Services | Key responsibilities |
|
|
|------|----------|----------------------|
|
|
| **Edge / Identity** | `StellaOps.Authority` | Issues short-lived tokens (DPoP + mTLS), exposes OIDC device-code + auth-code flows, rotates JWKS. |
|
|
| **Scan & attest** | `StellaOps.Scanner` (API + Worker), `StellaOps.Signer`, `StellaOps.Attestor` | Accept SBOMs/images, drive analyzers, produce DSSE bundles, optionally log to a Rekor mirror. |
|
|
| **Evidence graph** | `StellaOps.Concelier`, `StellaOps.Excititor`, `StellaOps.Policy.Engine` | Ingest advisories/VEX, correlate linksets, run lattice policy and VEX-first decisioning. |
|
|
| **Experience** | `StellaOps.Web` (Console), `StellaOps.Cli`, `StellaOps.Notify`, `StellaOps.ExportCenter` | Operator UX, automation, notifications, and offline/mirror packaging. |
|
|
| **Data plane** | PostgreSQL, Valkey, RustFS/object storage (optional NATS JetStream) | Canonical store, counters/queues, and artifact storage with deterministic layouts. |
|
|
|
|
## Infrastructure (What Is Required)
|
|
|
|
**Required**
|
|
|
|
- **PostgreSQL:** canonical persistent store for module schemas.
|
|
- **Valkey:** Redis-compatible cache/streams and DPoP nonce store.
|
|
- **RustFS (or equivalent S3-compatible store):** object storage for artifacts, bundles, and evidence.
|
|
|
|
**Optional (deployment-dependent)**
|
|
|
|
- **NATS JetStream:** optional messaging transport in some deployments.
|
|
- **Transparency log services:** Rekor mirror (and CA services) when transparency is enabled.
|
|
|
|
## End-to-End Flow (Typical)
|
|
|
|
1. **Evidence enters** via Concelier and Excititor connectors (Aggregation-Only Contract).
|
|
2. **SBOM arrives** from CLI/CI; Scanner deduplicates layers and enqueues work.
|
|
3. **Analyzer bundle** runs inside the Worker and stores evidence in content-addressed caches.
|
|
4. **Policy Engine** merges advisories, VEX, and inventory/usage facts; emits explain traces and stable dispositions.
|
|
5. **Signer + Attestor** wrap outputs into DSSE bundles and (optionally) anchor them in a Rekor mirror.
|
|
6. **Console/CLI/Export** surface findings and package verifiable evidence; Notify emits digests/incidents.
|
|
|
|
## Extension Points (Where You Customize)
|
|
|
|
- **Scanner analyzers** (restart-time plug-ins) for ecosystem-specific parsing and facts extraction.
|
|
- **Concelier connectors** for new advisory sources (preserving aggregation-only guardrails).
|
|
- **Policy packs** for organization-specific gating and waivers/justifications.
|
|
- **Export profiles** for output formats and offline bundle shapes.
|
|
|
|
## Offline & Sovereign Notes
|
|
|
|
- Offline Kit carries vulnerability feeds, container images, signatures, and verification material so the workflow stays identical when air-gapped.
|
|
- Authority + token verification remain local; quota enforcement is verifiable offline.
|
|
- Attestor can cache transparency proofs for offline verification.
|
|
|
|
## References
|
|
|
|
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
|
|
- `docs/24_OFFLINE_KIT.md`
|
|
- `docs/09_API_CLI_REFERENCE.md`
|
|
- `docs/modules/platform/architecture-overview.md`
|