stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions Releases Wiki Activity
Files
9e5e958d42ecddbe3e5a321ea0c0d31d1088ce20
git.stella-ops.org/docs/high-level-architecture.md
master 9e5e958d42
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat: Document completed tasks for KMS, Cryptography, and Plugin Libraries 
- Added detailed task completion records for KMS interface implementation and CLI support for file-based keys.
- Documented security enhancements including Argon2id password hashing, audit event contracts, and rate limiting configurations.
- Included scoped service support and integration updates for the Plugin platform, ensuring proper DI handling and testing coverage.
2025-10-31 14:33:05 +02:00

3.1 KiB
Raw Blame History

High-Level Architecture – 10-Minute Tour

Build → Sign → Store → Scan → Policy → Attest → Notify/Export

1. Guiding Principles

  • SBOM-first everything: scanners prefer CycloneDX/SPDX inputs and only unpack images when SBOMs are absent.
  • Restart-time plug-ins: analyzers, exporters, and connectors are loaded at startup, keeping runtime surfaces predictable.
  • Sovereign posture: all services tolerate zero outbound traffic; Offline Update Kits mirror feeds and trust roots.

2. System Map

Tier Services Key responsibilities
Edge / Identity StellaOps.Authority Issues short-lived OpToks (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/SRM bundles, optionally log to 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.UI, StellaOps.Cli, StellaOps.Notify, StellaOps.ExportCenter Surface findings, automate policy workflows, deliver notifications, package offline mirrors.
Data plane MongoDB, Redis, RustFS/object storage, NATS/Redis Streams Deterministic storage, counters, queue orchestration, Delta SBOM cache.

3. Request Lifecycle

  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 Worker, streams SRM events, stores SBOM fragments in content-addressed cache.
  4. Policy Engine merges advisories, VEX, and SBOM inventory, applies lattice logic, emits explain trace.
  5. Signer + Attestor wrap results into DSSE, optionally record to Rekor, and hand proof bundles to Export Center.
  6. UI/CLI surface findings, quotas, and replay manifests; Notify pushes channel-specific digests.

4. Extension Points

  • Scanner analyzers (plugins/scanner/**): ship restart-time plug-ins with deterministic manifests.
  • Concelier connectors (src/Concelier/__Libraries/**): fetch advisories, adhere to Aggregation-Only Contract.
  • Policy packs: upload YAML/Rego bundles with fixtures; simulation endpoints test impacts before promotion.
  • Crypto profiles: import trust-root packs to align with regional signature mandates.

5. Sovereign & Offline Considerations

  • Offline Update Kit carries vulnerability feeds, container images (x86-64 + arm64), Cosign signatures, and detatched JWS manifests.
  • Transparency mirrors: Attestor caches Rekor proofs; mirrors can be deployed on-prem for DSSE verification.
  • Quota enforcement uses Redis counters with local JWT validation, so no central service is required.

6. Where to Learn More

  • Deep dive per module in docs/modules/<module>/architecture.md.
  • Study strategic themes in moat.md.
  • Review API and CLI contracts in 09_API_CLI_REFERENCE.md.