master
b97fc7685a
Some checks failed
Build Test Deploy / authority-container (push) Has been cancelled
Build Test Deploy / docs (push) Has been cancelled
Build Test Deploy / deploy (push) Has been cancelled
Build Test Deploy / build-test (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
389 lines
19 KiB
Markdown
Executable File
389 lines
19 KiB
Markdown
Executable File
# 7 · High‑Level Architecture — **Stella Ops**
|
||
|
||
---
|
||
|
||
## 0 Purpose & Scope
|
||
|
||
Give contributors, DevOps engineers and auditors a **complete yet readable map** of the Core:
|
||
|
||
* Major runtime components and message paths.
|
||
* Where plug‑ins, CLI helpers and runtime agents attach.
|
||
* Technology choices that enable the sub‑5 second SBOM goal.
|
||
* Typical operational scenarios (pipeline scan, mute, nightly re‑scan, etc.).
|
||
|
||
Anything enterprise‑only (signed PDF, custom/regulated TLS, LDAP, enforcement) **must arrive as a plug‑in**; the Core never hard‑codes those concerns.
|
||
---
|
||
## 1 Component Overview
|
||
|
||
| # | Component | Responsibility |
|
||
|---|-----------|---------------|
|
||
| 1 | **API Gateway** | REST endpoints (`/scan`, `/quota`, **`/token/offline`**); token auth; quota enforcement |
|
||
| 2 | **Scan Service** | SBOM parsing, Delta‑SBOM cache, vulnerability lookup |
|
||
| 3 | **Policy Engine** | YAML / (optional) Rego rule evaluation; verdict assembly |
|
||
| 4 | **Quota Service** | Per‑token counters; **333 scans/day**; waits & HTTP 429 |
|
||
| 5 | **Client‑JWT Issuer** | Issues 30‑day offline tokens; bundles them into OUK |
|
||
| 5 | **Registry** | Anonymous internal Docker registry for agents, SBOM uploads |
|
||
| 6 | **Web UI** | React/Blazor SPA; dashboards, policy editor, quota banner |
|
||
| 7 | **Data Stores** | **Redis** (cache, quota) & **MongoDB** (SBOMs, findings, audit) |
|
||
| 8 | **Plugin Host** | Hot‑load .NET DLLs; isolates community plug‑ins |
|
||
| 9 | **Agents** | `sbom‑builder`, `Stella CLI` scanner CLI, future `StellaOpsAttestor` |
|
||
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph "External Actors"
|
||
DEV["Developer / DevSecOps / Manager"]
|
||
CI["CI/CD Pipeline (e.g., Stella CLI)"]
|
||
K8S["Kubernetes Cluster (e.g., Zastava Agent)"]
|
||
end
|
||
|
||
subgraph "Stella Ops Runtime"
|
||
subgraph "Core Services"
|
||
CORE["Stella Core<br>(REST + gRPC APIs, Orchestration)"]
|
||
REDIS[("Redis<br>(Cache, Queues, Trivy DB Mirror)")]
|
||
MONGO[("MongoDB<br>(Optional: Long-term Storage)")]
|
||
POL["Mute Policies<br>(OPA & YAML Evaluator)"]
|
||
REG["StellaOps Registry<br>(Docker Registry v2)"]
|
||
ATT["StellaOps Attestor<br>(SLSA + Rekor)"]
|
||
end
|
||
|
||
subgraph "Agents & Builders"
|
||
SB["SBOM Builder<br>(Go Binary: Extracts Layers, Generates SBOMs)"]
|
||
SA["Stella CLI<br>(Pipeline Helper: Invokes Builder, Triggers Scans)"]
|
||
ZA["Zastava Agent<br>(K8s Webhook: Enforces Policies, Inventories Containers)"]
|
||
end
|
||
|
||
subgraph "Scanners & UI"
|
||
TRIVY["Trivy Scanner<br>(Plugin Container: Vulnerability Scanning)"]
|
||
UI["Web UI<br>(Vue3 + Tailwind: Dashboards, Policy Editor)"]
|
||
CLI["Stella CLI<br>(CLI Helper: Triggers Scans, Mutes)"]
|
||
end
|
||
end
|
||
|
||
DEV -->|Browses Findings, Mutes CVEs| UI
|
||
DEV -->|Triggers Scans| CLI
|
||
CI -->|Generates SBOM, Calls /scan| SA
|
||
K8S -->|Inventories Containers, Enforces Gates| ZA
|
||
|
||
UI -- "REST" --> CORE
|
||
CLI -- "REST/gRPC" --> CORE
|
||
SA -->|Scan Requests| CORE
|
||
SB -->|Uploads SBOMs| CORE
|
||
ZA -->|Policy Gates| CORE
|
||
|
||
CORE -- "Queues, Caches" --> REDIS
|
||
CORE -- "Persists Data" --> MONGO
|
||
CORE -->|Evaluates Policies| POL
|
||
CORE -->|Attests Provenance| ATT
|
||
CORE -->|Scans Vulnerabilities| TRIVY
|
||
|
||
SB -- "Pulls Images" --> REG
|
||
SA -- "Pulls Images" --> REG
|
||
ZA -- "Pulls Images" --> REG
|
||
|
||
style DEV fill:#f9f,stroke:#333
|
||
style CI fill:#f9f,stroke:#333
|
||
style K8S fill:#f9f,stroke:#333
|
||
style CORE fill:#ddf,stroke:#333
|
||
style REDIS fill:#fdd,stroke:#333
|
||
style MONGO fill:#fdd,stroke:#333
|
||
style POL fill:#dfd,stroke:#333
|
||
style REG fill:#dfd,stroke:#333
|
||
style ATT fill:#dfd,stroke:#333
|
||
style SB fill:#fdf,stroke:#333
|
||
style SA fill:#fdf,stroke:#333
|
||
style ZA fill:#fdf,stroke:#333
|
||
style TRIVY fill:#ffd,stroke:#333
|
||
style UI fill:#ffd,stroke:#333
|
||
style CLI fill:#ffd,stroke:#333
|
||
```
|
||
|
||
* **Developer / DevSecOps / Manager** – browses findings, mutes CVEs, triggers scans.
|
||
* **Stella CLI** – generates SBOMs and calls `/scan` during CI.
|
||
* **Zastava Agent** – inventories live containers; Core ships it in *passive* mode only (no kill).
|
||
|
||
### 1.1 Client‑JWT Lifecycle (offline aware)
|
||
|
||
1. **Online instance** – user signs in → `/connect/token` issues JWT valid 12 h.
|
||
2. **Offline instance** – JWT with `exp ≈ 30 days` ships in OUK; backend
|
||
**re‑signs** and stores it during import.
|
||
3. Tokens embed a `tier` claim (“Free”) and `maxScansPerDay: 333`.
|
||
4. On expiry the UI surfaces a red toast **7 days** in advance.
|
||
|
||
---
|
||
|
||
## 2 · Component Responsibilities (runtime view)
|
||
|
||
| Component | Core Responsibility | Implementation Highlights |
|
||
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
||
| **Stella Core** | Orchestrates scans, persists SBOM blobs, serves REST/gRPC APIs, fans out jobs to scanners & policy engine. | .NET {{ dotnet }}, CQRS, Redis Streams; pluggable runner interfaces. |
|
||
| **SBOM Builder** | Extracts image layers, queries Core for *missing* layers, generates SBOMs (multi‑format), uploads blobs. | Go binary; wraps Trivy & Syft libs. |
|
||
| **Stella CLI** | Pipeline‑side helper; invokes Builder, triggers scan, streams progress back to CI/CD. | Static musl build. |
|
||
| **Zastava Agent** | K8s admission webhook enforcing policy verdicts before Pod creation. | Rust for sub‑10 ms latencies. |
|
||
| **UI** | Angular 17 SPA for dashboards, settings, policy editor. | Tailwind CSS; Webpack module federation (future). |
|
||
| **Redis** | Cache, queue, Trivy‑DB mirror, layer diffing. | Single instance or Sentinel. |
|
||
| **MongoDB** (opt.) | Long‑term SBOM & policy audit storage (> 180 days). | Optional; enabled via flag. |
|
||
| **StellaOps.Registry** | Anonymous read‑only Docker v2 registry with optional Cosign verification. | `registry :2` behind nginx reverse proxy. |
|
||
| **StellaOps.MutePolicies** | YAML/Rego evaluator, policy version store, `/policy/*` API. | Embeds OPA‑WASM; falls back to `opa exec`. |
|
||
| **StellaOpsAttestor** | Generate SLSA provenance & Rekor signatures; verify on demand. | Side‑car container; DSSE + Rekor CLI. |
|
||
|
||
All cross‑component calls use dependency‑injected interfaces—no
|
||
intra‑component reach‑ins.
|
||
|
||
---
|
||
|
||
## 3 · Principal Backend Modules & Plug‑in Hooks
|
||
|
||
| Namespace | Responsibility | Built‑in Tech / Default | Plug‑in Contract |
|
||
| --------------- | -------------------------------------------------- | ----------------------- | ------------------------------------------------- |
|
||
| `configuration` | Parse env/JSON, health‑check endpoint | .NET {{ dotnet }} Options | `IConfigValidator` |
|
||
| `identity` | Embedded OAuth2/OIDC (OpenIddict 6) | MIT OpenIddict | `IIdentityProvider` for LDAP/SAML/JWT gateway |
|
||
| `pluginloader` | Discover DLLs, SemVer gate, optional Cosign verify | Reflection + Cosign | `IPluginLifecycleHook` for telemetry |
|
||
| `scanning` | SBOM‑ & image‑flow orchestration; runner pool | Trivy CLI (default) | `IScannerRunner` – e.g., Grype, Copacetic, Clair |
|
||
| `feedser` (vulnerability ingest/merge/export service) | Nightly NVD merge & feed enrichment | Hangfire job | drop-in `*.Schedule.dll` for OSV, GHSA, NVD 2.0, CNNVD, CNVD, ENISA, JVN and BDU feeds |
|
||
| `tls` | TLS provider abstraction | OpenSSL | `ITlsProvider` for custom suites (incl. **SM2**, where law or security requires it) |
|
||
| `reporting` | Render HTML/PDF reports | RazorLight | `IReportRenderer` |
|
||
| `ui` | Angular SPA & i18n | Angular {{ angular }} | new locales via `/locales/{lang}.json` |
|
||
| `scheduling` | Cron + retries | Hangfire | any recurrent job via `*.Schedule.dll` |
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class configuration
|
||
class identity
|
||
class pluginloader
|
||
class scanning
|
||
class feedser
|
||
class tls
|
||
class reporting
|
||
class ui
|
||
class scheduling
|
||
|
||
class AllModules
|
||
|
||
configuration ..> identity : Uses
|
||
identity ..> pluginloader : Authenticates Plugins
|
||
pluginloader ..> scanning : Loads Scanner Runners
|
||
scanning ..> feedser : Triggers Feed Merges
|
||
tls ..> AllModules : Provides TLS Abstraction
|
||
reporting ..> ui : Renders Reports for UI
|
||
scheduling ..> feedser : Schedules Nightly Jobs
|
||
|
||
note for scanning "Pluggable: ISScannerRunner<br>e.g., Trivy, Grype"
|
||
note for feedser "Pluggable: *.Schedule.dll<br>e.g., OSV, GHSA Feeds"
|
||
note for identity "Pluggable: IIdentityProvider<br>e.g., LDAP, SAML"
|
||
note for reporting "Pluggable: IReportRenderer<br>e.g., Custom PDF"
|
||
```
|
||
|
||
**When remaining = 0:**
|
||
API returns `429 Too Many Requests`, `Retry‑After: <UTC‑midnight>` (sequence omitted for brevity).
|
||
|
||
---
|
||
|
||
## 4 · Data Flows
|
||
|
||
### 4.1 SBOM‑First (≤ 5 s P95)
|
||
|
||
Builder produces SBOM locally, so Core never touches the Docker
|
||
socket.
|
||
Trivy path hits ≤ 5 s on alpine:3.19 with warmed DB.
|
||
Image‑unpack fallback stays ≤ 10 s for 200 MB images.
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant CI as CI/CD Pipeline (Stella CLI)
|
||
participant SB as SBOM Builder
|
||
participant CORE as Stella Core
|
||
participant REDIS as Redis Queue
|
||
participant RUN as Scanner Runner (e.g., Trivy)
|
||
participant POL as Policy Evaluator
|
||
|
||
CI->>SB: Invoke SBOM Generation
|
||
SB->>CORE: Check Missing Layers (/layers/missing)
|
||
CORE->>REDIS: Query Layer Diff (SDIFF)
|
||
REDIS-->>CORE: Missing Layers List
|
||
CORE-->>SB: Return Missing Layers
|
||
SB->>SB: Generate Delta SBOM
|
||
SB->>CORE: Upload SBOM Blob (POST /scan(sbom))
|
||
CORE->>REDIS: Enqueue Scan Job
|
||
REDIS->>RUN: Fan Out to Runner
|
||
RUN->>RUN: Perform Vulnerability Scan
|
||
RUN-->>CORE: Return Scan Results
|
||
CORE->>POL: Evaluate Mute Policies
|
||
POL-->>CORE: Policy Verdict
|
||
CORE-->>CI: JSON Verdict & Progress Stream
|
||
Note over CORE,CI: Achieves ≤5s P95 with Warmed DB
|
||
```
|
||
|
||
### 4.2 Delta SBOM
|
||
|
||
Builder collects layer digests.
|
||
`POST /layers/missing` → Redis SDIFF → missing layer list (< 20 ms).
|
||
SBOM generated only for those layers and uploaded.
|
||
|
||
### 4.3 Feedser Harvest & Export
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant SCHED as Feedser Scheduler
|
||
participant CONN as Source Connector Plug-in
|
||
participant FEEDSER as Feedser Core
|
||
participant MONGO as MongoDB (Canonical Advisories)
|
||
participant EXPORT as Exporter (JSON / Trivy DB)
|
||
participant ART as Artifact Store / Offline Kit
|
||
|
||
SCHED->>CONN: Trigger window (init/resume)
|
||
CONN->>CONN: Fetch source documents + metadata
|
||
CONN->>FEEDSER: Submit raw document for parsing
|
||
FEEDSER->>FEEDSER: Parse & normalize to DTO
|
||
FEEDSER->>FEEDSER: Merge & deduplicate canonical advisory
|
||
FEEDSER->>MONGO: Write advisory, provenance, merge_event
|
||
FEEDSER->>EXPORT: Queue export delta request
|
||
EXPORT->>MONGO: Read canonical snapshot/deltas
|
||
EXPORT->>EXPORT: Build deterministic JSON & Trivy DB artifacts
|
||
EXPORT->>ART: Publish artifacts / Offline Kit bundle
|
||
ART-->>FEEDSER: Record export state + digests
|
||
```
|
||
|
||
### 4.4 Identity & Auth Flow
|
||
|
||
OpenIddict issues JWTs via client‑credentials or password grant.
|
||
An IIdentityProvider plug‑in can delegate to LDAP, SAML or external OIDC
|
||
without Core changes.
|
||
---
|
||
## 5 · Runtime Helpers
|
||
|
||
| Helper | Form | Purpose | Extensible Bits |
|
||
|-----------|---------------------------------------|--------------------------------------------------------------------|-------------------------------------------|
|
||
| **Stella CLI** | Distroless CLI | Generates SBOM, calls `/scan`, honours threshold flag | `--engine`, `--pdf-out` piped to plug‑ins |
|
||
| **Zastava** | Static Go binary / DaemonSet | Watches Docker/CRI‑O events; uploads SBOMs; can enforce gate | Policy plug‑in could alter thresholds |
|
||
|
||
---
|
||
|
||
## 6 · Persistence & Cache Strategy
|
||
|
||
| Store | Primary Use | Why chosen |
|
||
|----------------|-----------------------------------------------|--------------------------------|
|
||
| **MongoDB** | Feedser canonical advisories, merge events, export state | Deterministic canonical store with flexible schema |
|
||
| **Redis 7** | CLI quotas, short-lived job scheduling, layer diff cache | Sub-1 ms P99 latency for hot-path coordination |
|
||
| **Local tmpfs**| Trivy layer cache (`/var/cache/trivy`) | Keeps disk I/O off hot path |
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph "Persistence Layers"
|
||
REDIS[(Redis: Quotas & Short-lived Queues<br>Sub-1ms P99)]
|
||
MONGO[(MongoDB: Canonical Advisories<br>Merge Events & Export State)]
|
||
TMPFS[(Local tmpfs: Trivy Layer Cache<br>Low I/O Overhead)]
|
||
end
|
||
|
||
CORE["Stella Core"] -- Queues & SBOM Cache --> REDIS
|
||
CORE -- Long-term Storage --> MONGO
|
||
TRIVY["Trivy Scanner"] -- Layer Unpack Cache --> TMPFS
|
||
|
||
style REDIS fill:#fdd,stroke:#333
|
||
style MONGO fill:#dfd,stroke:#333
|
||
style TMPFS fill:#ffd,stroke:#333
|
||
```
|
||
|
||
---
|
||
|
||
## 7 · Typical Scenarios
|
||
|
||
| # | Flow | Steps |
|
||
|---------|----------------------------|-------------------------------------------------------------------------------------------------|
|
||
| **S‑1** | Pipeline Scan & Alert | Stella CLI → SBOM → `/scan` → policy verdict → CI exit code & link to *Scan Detail* |
|
||
| **S‑2** | Mute Noisy CVE | Dev toggles **Mute** in UI → rule stored in Redis → next build passes |
|
||
| **S‑3** | Nightly Re‑scan | `SbomNightly.Schedule` re‑queues SBOMs (mask‑filter) → dashboard highlights new Criticals |
|
||
| **S‑4** | Feed Update Cycle | `Feedser (vulnerability ingest/merge/export service)` refreshes feeds → UI *Feed Age* tile turns green |
|
||
| **S‑5** | Custom Report Generation | Plug‑in registers `IReportRenderer` → `/report/custom/{digest}` → CI downloads artifact |
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant DEV as Developer
|
||
participant UI as Web UI
|
||
participant CORE as Stella Core
|
||
participant REDIS as Redis
|
||
participant RUN as Scanner Runner
|
||
|
||
DEV->>UI: Toggle Mute for CVE
|
||
UI->>CORE: Update Mute Rule (POST /policy/mute)
|
||
CORE->>REDIS: Store Mute Policy
|
||
Note over CORE,REDIS: YAML/Rego Evaluator Updates
|
||
|
||
alt Next Pipeline Build
|
||
CI->>CORE: Trigger Scan (POST /scan)
|
||
CORE->>RUN: Enqueue & Scan
|
||
RUN-->>CORE: Raw Findings
|
||
CORE->>REDIS: Apply Mute Policies
|
||
REDIS-->>CORE: Filtered Verdict (Passes)
|
||
CORE-->>CI: Success Exit Code
|
||
end
|
||
```
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant CRON as SbomNightly.Schedule
|
||
participant CORE as Stella Core
|
||
participant REDIS as Redis Queue
|
||
participant RUN as Scanner Runner
|
||
participant UI as Dashboard
|
||
|
||
CRON->>CORE: Re-queue SBOMs (Mask-Filter)
|
||
CORE->>REDIS: Enqueue Filtered Jobs
|
||
REDIS->>RUN: Fan Out to Runners
|
||
RUN-->>CORE: New Scan Results
|
||
CORE->>UI: Highlight New Criticals
|
||
Note over CORE,UI: Focus on Changes Since Last Scan
|
||
```
|
||
---
|
||
|
||
## 8 · UI Fast Facts
|
||
|
||
* **Stack** – Angular 17 + Vite dev server; Tailwind CSS.
|
||
* **State** – Signals + RxJS for live scan progress.
|
||
* **i18n / l10n** – JSON bundles served from `/locales/{lang}.json`.
|
||
* **Module Structure** – Lazy‑loaded feature modules (`dashboard`, `scans`, `settings`); runtime route injection by UI plug‑ins (road‑map Q2‑2026).
|
||
|
||
---
|
||
|
||
## 9 · Cross‑Cutting Concerns
|
||
|
||
* **Security** – containers run non‑root, `CAP_DROP:ALL`, read‑only FS, hardened seccomp profiles.
|
||
* **Observability** – Serilog JSON, OpenTelemetry OTLP exporter, Prometheus `/metrics`.
|
||
* **Upgrade Policy** – `/api/v1` endpoints & CLI flags stable across a minor; breaking changes bump major.
|
||
|
||
---
|
||
|
||
## 10 · Performance & Scalability
|
||
|
||
| Scenario | P95 target | Bottleneck | Mitigation |
|
||
|-----------------|-----------:|-----------------|-------------------------------------------------|
|
||
| SBOM‑first | ≤ 5 s | Redis queue | More CPU, increase `ScannerPool.Workers` |
|
||
| Image‑unpack | ≤ 10 s | Layer unpack | Prefer SBOM path, warm Docker cache |
|
||
| High concurrency| 40 rps | Runner CPU | Scale Core replicas + side‑car scanner services |
|
||
|
||
---
|
||
|
||
## 11 · Future Architectural Anchors
|
||
|
||
* **ScanService micro‑split (gRPC)** – isolate heavy runners for large clusters.
|
||
* **UI route plug‑ins** – dynamic Angular module loader (road‑map Q2‑2026).
|
||
* **Redis Cluster** – transparently sharded cache once sustained > 100 rps.
|
||
|
||
---
|
||
|
||
## 12 · Assumptions & Trade‑offs
|
||
|
||
Requires Docker/CRI‑O runtime; .NET 9 available on hosts; Windows containers are out‑of‑scope this cycle.
|
||
Embedded auth simplifies deployment but may need plug‑ins for enterprise IdPs.
|
||
Speed is prioritised over exhaustive feature parity with heavyweight commercial scanners.
|
||
|
||
---
|
||
|
||
## 13 · References & Further Reading
|
||
|
||
* **C4 Model** – <https://c4model.com>
|
||
* **.NET Architecture Guides** – <https://learn.microsoft.com/dotnet/architecture>
|
||
* **OSS Examples** – Kubernetes Architecture docs, Prometheus design papers, Backstage.
|
||
|
||
*(End of High‑Level Architecture v2.2)*
|