feat: Document completed tasks for KMS, Cryptography, and Plugin Libraries
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
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.
This commit is contained in:
49
docs/high-level-architecture.md
Normal file
49
docs/high-level-architecture.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user