9e5e958d42
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- 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.
50 lines
3.1 KiB
Markdown
50 lines
3.1 KiB
Markdown
# 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](moat.md).
|
||
- Review API and CLI contracts in [09_API_CLI_REFERENCE.md](09_API_CLI_REFERENCE.md).
|