git.stella-ops.org/docs/07_HIGH_LEVEL_ARCHITECTURE.md

# 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

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

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.

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

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

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

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

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)