stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
7503c19b8ffa7f2891e5e672f9cfbf7efa4e2efb
git.stella-ops.org/docs/40_ARCHITECTURE_OVERVIEW.md
StellaOps Bot 7503c19b8f Add determinism tests for verdict artifact generation and update SHA256 sums script 
- 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.
2025-12-24 02:17:34 +02:00

4.7 KiB
Executable File
Raw Blame History

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