134 lines
5.1 KiB
Markdown
Executable File
134 lines
5.1 KiB
Markdown
Executable File
# Stella Ops — High‑Level Architecture
|
||
|
||
<!--
|
||
Use constants injected at build:
|
||
{{ dotnet }} = "10 LTS"
|
||
{{ angular }} = "20"
|
||
-->
|
||
|
||
This document offers a birds‑eye view of how the major components interact,
|
||
why the system leans *monolith‑plus‑plug‑ins*, and where extension points live.
|
||
|
||
> For a *timeline* of when features arrive, see the public
|
||
> [road‑map](/roadmap/) — no version details are repeated here.
|
||
|
||
---
|
||
|
||
## 0 · Guiding principles
|
||
|
||
| Principle | Rationale |
|
||
|-----------|-----------|
|
||
| **SBOM‑first** | Scan existing CycloneDX/SPDX if present; fall back to layer unpack. |
|
||
| **Δ‑processing** | Re‑analyse only changed layers; reduces P95 warm path to \< 5 s. |
|
||
| **All‑managed code** | Entire stack is 100 % managed (.NET / TypeScript); no `unsafe` blocks or native extensions — eases review and reproducible builds. |
|
||
| **Restart‑time plug‑ins** | Avoids the attack surface of runtime DLL injection; still allows custom scanners & exporters. |
|
||
| **Sovereign‑by‑design** | No mandatory outbound traffic; Offline Kit distributes feeds. |
|
||
|
||
---
|
||
|
||
## 1 · Module graph
|
||
|
||
```mermaid
|
||
graph TD
|
||
A(API Gateway)
|
||
B1(Scanner Core<br/>.NET latest LTS)
|
||
B2(Concelier service\n(vuln ingest/merge/export))
|
||
B3(Policy Engine OPA)
|
||
C1(Redis 7)
|
||
C2(MongoDB 7)
|
||
D(UI SPA<br/>Angular latest version)
|
||
A -->|gRPC| B1
|
||
B1 -->|async| B2
|
||
B1 -->|OPA| B3
|
||
B1 --> C1
|
||
B1 --> C2
|
||
A -->|REST/WS| D
|
||
````
|
||
|
||
---
|
||
|
||
## 2 · Key components
|
||
|
||
| Component | Language / tech | Responsibility |
|
||
| ---------------------------- | --------------------- | ---------------------------------------------------- |
|
||
| **API Gateway** | ASP.NET Minimal API | Auth (JWT), quotas, request routing |
|
||
| **Scanner Core** | C# 12, Polly | Layer diffing, SBOM generation, vuln correlation |
|
||
| **Concelier (vulnerability ingest/merge/export service)** | C# source-gen workers | Consolidate NVD + regional CVE feeds into the canonical MongoDB store and drive JSON / Trivy DB exports |
|
||
| **Policy Engine** | OPA (Rego) | admission decisions, custom org rules |
|
||
| **Redis 7** | Key‑DB compatible | LRU cache, quota counters |
|
||
| **MongoDB 7** | WiredTiger | SBOM & findings storage |
|
||
| **Angular {{ angular }} UI** | RxJS, Tailwind | Dashboard, reports, admin UX |
|
||
|
||
---
|
||
|
||
## 3 · Plug‑in system
|
||
|
||
* Discovered once at start‑up from `/opt/stella/plugins/**`.
|
||
* Runs under Linux user `stella‑plugin` (UID 1001).
|
||
* Extension points:
|
||
|
||
* `ISbomMutator`
|
||
* `IVulnerabilityProvider`
|
||
* `IResultSink`
|
||
* Policy files (`*.rego`)
|
||
* Each DLL is SHA‑256 hashed; digest embedded in the run report for provenance.
|
||
|
||
Hot‑plugging is deferred until after v 1.0 for security review.
|
||
|
||
---
|
||
|
||
## 4 · Data & control flow
|
||
|
||
1. **Client** calls `/api/scan` with image reference.
|
||
2. **Gateway** enforces quota, forwards to **Scanner Core** via gRPC.
|
||
3. **Core**:
|
||
|
||
* Queries Redis for cached SBOM.
|
||
* If miss → pulls layers, generates SBOM.
|
||
* Executes plug‑ins (mutators, additional scanners).
|
||
4. **Policy Engine** evaluates `scanResult` document.
|
||
5. **Findings** stored in MongoDB; WebSocket event notifies UI.
|
||
6. **ResultSink plug‑ins** export to Slack, Splunk, JSON file, etc.
|
||
|
||
---
|
||
|
||
## 5 · Security hardening
|
||
|
||
| Surface | Mitigation |
|
||
| ----------------- | ------------------------------------------------------------ |
|
||
| Container runtime | Distroless base, non‑root UID, seccomp + AppArmor |
|
||
| Plug‑in sandbox | Separate UID, SELinux profile, cgroup 1 CPU / 256 MiB |
|
||
| Supply chain | Cosign signatures, in‑toto SLSA Level 3 (target) |
|
||
| Secrets | `Docker secrets` or K8s `Secret` mounts; never hard‑coded |
|
||
| Quota abuse | Redis rate‑limit gates (see `30_QUOTA_ENFORCEMENT_FLOW1.md`) |
|
||
|
||
---
|
||
|
||
## 6 · Build & release pipeline (TL;DR)
|
||
|
||
* **Git commits** trigger CI → unit / integration / E2E tests.
|
||
* Successful merge to `main`:
|
||
|
||
* Build `.NET {{ dotnet }}` trimmed self‑contained binary.
|
||
* `docker build --sbom=spdx-json`.
|
||
* Sign image and tarball with Cosign.
|
||
* Attach SBOM + provenance; push to registry and download portal.
|
||
|
||
---
|
||
|
||
## 7 · Future extraction path
|
||
|
||
Although the default deployment is a single container, each sub‑service can be
|
||
extracted:
|
||
|
||
* Concelier → standalone cron pod.
|
||
* Policy Engine → side‑car (OPA) with gRPC contract.
|
||
* ResultSink → queue worker (RabbitMQ or Azure Service Bus).
|
||
|
||
Interfaces are stable **as of v0.2 β**; extraction requires a recompilation
|
||
only, not a fork of the core.
|
||
|
||
---
|
||
|
||
*Last updated {{ "now" | date: "%Y‑%m‑%d" }} – constants auto‑injected.*
|