stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions Releases Wiki Activity
Files
691028fe6982aa129aebb8ad201da450b8df0a10
git.stella-ops.org/docs/high-level-architecture.md
Vladimir Moushkov 691028fe69
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat: Document completed tasks across multiple components 
- Added completed tasks documentation for Scheduler WebService, ImpactIndex, Models, Queue, Storage.Mongo, Worker, Signals, Signer, UI, Zastava.Observer, Zastava.Webhook, Zastava.Core, Cryptography.Kms, Cryptography, and Plugin.
- Each task includes ID, status, owners, dependencies, descriptions, and exit criteria to ensure clarity and traceability.
- Enhanced integration and unit testing coverage across various components to validate functionality and compliance with specifications.
2025-10-30 18:20:31 +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.