3a2100aa78
- Implemented comprehensive unit tests for VexCandidateEmitter to validate candidate emission logic based on various scenarios including absent and present APIs, confidence thresholds, and rate limiting. - Added integration tests for SmartDiff PostgreSQL repositories, covering snapshot storage and retrieval, candidate storage, and material risk change handling. - Ensured tests validate correct behavior for storing, retrieving, and querying snapshots and candidates, including edge cases and expected outcomes.
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(PostgreSQL 16)
|
||
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 PostgreSQL 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 |
|
||
| **PostgreSQL 16** | JSONB storage | 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 PostgreSQL; 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.*
|