5590a99a1a
- Created `StellaOps.TestKit.Tests` project for unit tests related to determinism. - Implemented `DeterminismManifestTests` to validate deterministic output for canonical bytes and strings, file read/write operations, and error handling for invalid schema versions. - Added `SbomDeterminismTests` to ensure identical inputs produce consistent SBOMs across SPDX 3.0.1 and CycloneDX 1.6/1.7 formats, including parallel execution tests. - Updated project references in `StellaOps.Integration.Determinism` to include the new determinism testing library.
3.4 KiB
Executable File
3.4 KiB
Executable File
Architecture Overview (High-Level)
This document is a high-level orientation to 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)
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
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)
- Ingest evidence sources: Concelier and Excititor ingest upstream advisories/VEX into immutable observations with provenance.
- Scan: Scanner accepts an SBOM or image reference, produces scan facts and evidence artifacts.
- Decide: Policy evaluation merges scan facts with advisory/VEX evidence to produce an explainable verdict.
- Seal: Signer/Attestor wrap outputs into signed bundles (DSSE/in-toto) and optionally anchor in transparency logs.
- Export and notify: Export Center produces portable evidence bundles and Offline Kit material; Notify delivers digests/incidents.
- Operate: Console exposes triage, explainability, verification, and governance workflows.
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.
References
docs/07_HIGH_LEVEL_ARCHITECTURE.mddocs/24_OFFLINE_KIT.mddocs/09_API_CLI_REFERENCE.mddocs/modules/platform/architecture-overview.md