160 lines
14 KiB
Markdown
160 lines
14 KiB
Markdown
# Platform topology (detailed)
|
|
|
|
This document provides a comprehensive view of StellaOps platform topology. For module-specific details (APIs, schemas, operations), see `docs/modules/`.
|
|
|
|
## Component topology (quick reference)
|
|
|
|
```
|
|
CLIENT LAYER
|
|
├─ stella CLI → Gateway (JWT + DPoP auth)
|
|
├─ Web UI (Angular) → Gateway (JWT + DPoP auth)
|
|
├─ CI/CD Pipelines → Gateway (JWT + DPoP auth)
|
|
└─ Zastava Observer → Scanner (runtime scans)
|
|
|
|
INFRASTRUCTURE (REQUIRED)
|
|
├─ PostgreSQL v16+ → Primary database (ALL services)
|
|
├─ Valkey v8.0 → Cache, DPoP, queues, events
|
|
└─ RustFS → Object storage (S3 API)
|
|
|
|
INFRASTRUCTURE (OPTIONAL)
|
|
└─ NATS JetStream → Alternative messaging (Valkey is default)
|
|
|
|
GATEWAY LAYER
|
|
└─ Gateway.WebService → Auth, routing, rate limiting
|
|
|
|
AUTH & CRYPTO
|
|
├─ Authority → OAuth2/OIDC, OpTok issuance
|
|
├─ Signer → DSSE signing (FIPS/GOST/SM)
|
|
└─ Attestor → Rekor v2 transparency log
|
|
|
|
CORE ENGINES
|
|
├─ Scanner.WebService → Scan orchestration
|
|
├─ Scanner.Worker → Image analysis, SBOM generation
|
|
├─ Concelier.WebService → Advisory ingestion (NVD, Red Hat, etc.)
|
|
├─ Excititor.WebService → VEX ingestion + consensus
|
|
├─ Policy.Gateway → OPA/Rego policy evaluation
|
|
├─ Scheduler.WebService → Re-scan orchestration
|
|
├─ Notify.WebService → Notification orchestration
|
|
├─ Notify.Worker → Slack/Teams/Email delivery
|
|
└─ Orchestrator.WebService → DAG workflows, pack runs
|
|
|
|
SUPPORTING
|
|
└─ IssuerDirectory → VEX issuer trust registry
|
|
```
|
|
|
|
## Layers (tabular reference)
|
|
|
|
| Layer | Primary components | Responsibility |
|
|
| --- | --- | --- |
|
|
| Client | CLI, Web UI, CI/CD pipelines, runtime observers | Submit scan requests, query results, manage policy/tenancy. |
|
|
| Gateway | Gateway.WebService | Auth enforcement, tenant routing, rate limiting, request correlation, API routing. |
|
|
| Auth & crypto | Authority, Signer, Attestor, IssuerDirectory | Token issuance, signing, transparency/attestation workflows, issuer trust registry. |
|
|
| Core engines | Scanner, Concelier, Excititor, Policy, Scheduler, Notify, Orchestrator | Scanning, ingestion, verdicts, orchestration, notifications, exports. |
|
|
| Data plane | PostgreSQL, Valkey, RustFS (S3), optional NATS | Persistent state, queues/streams, artifact storage, optional alternative messaging. |
|
|
|
|
## Service categories (detailed)
|
|
|
|
| Category | Services | Purpose |
|
|
|----------|----------|---------|
|
|
| **Gateway** | Gateway.WebService | API routing, auth enforcement |
|
|
| **Auth & Security** | Authority, Signer, Attestor | OAuth2, signing, transparency |
|
|
| **Scanning** | Scanner.Web, Scanner.Worker | Container analysis, SBOM |
|
|
| **Advisory** | Concelier.Web, Concelier.Worker | Vulnerability ingestion |
|
|
| **VEX** | Excititor.Web, Excititor.Worker | Exploitability statements |
|
|
| **Policy** | Policy.Gateway, Policy Engine | OPA/Rego evaluation |
|
|
| **Orchestration** | Scheduler, Orchestrator | Job coordination |
|
|
| **Notifications** | Notify.Web, Notify.Worker | Delivery to Slack/Teams/Email |
|
|
|
|
## Layered architecture diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ USER EXPERIENCE │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Gateway │ │ Web (UI) │ │ CLI │ │
|
|
│ │ (API Router) │ │ (Angular v17)│ │(Multi-plat) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ DATA & EXPORT │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ExportCenter │ │EvidenceLocker│ │FindingsLedger│ │
|
|
│ │(SARIF/SBOM) │ │(Artifacts) │ │(Audit Trail) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ EVENTS & NOTIFICATIONS │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Notify │ │ Notifier │ │TimelineIndex │ │
|
|
│ │(Slack/Teams) │ │ (Advanced) │ │ (Events) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ ORCHESTRATION & WORKFLOW │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Scheduler │ │ Orchestrator │ │ TaskRunner │ │
|
|
│ │(Job Sched) │ │(Coordinator) │ │(Executor) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ SCANNING & ANALYSIS │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │Scanner.Web │ │Scanner.Worker│ │ AdvisoryAI │ │
|
|
│ │(API/Control) │ │(Analyzers) │ │(ML Analysis) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ RiskEngine │ │ Policy │ │
|
|
│ │ (Scoring) │ │ (Engine) │ │
|
|
│ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ INGESTION & AGGREGATION │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Concelier │ │ Excititor │ │IssuerDirectry│ │
|
|
│ │(Advisories) │ │ (VEX) │ │(CSAF Pubshrs)│ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ AUTHENTICATION & SIGNING │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Authority │─▶│ Signer │─▶│ Attestor │ │
|
|
│ │ (OAuth2/OIDC)│ │(DSSE/PKIX) │ │(in-toto/DSSE)│ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ INFRASTRUCTURE LAYER │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │
|
|
│ │ PostgreSQL │ │ Valkey │ │ RustFS │ │
|
|
│ │ (v16+ ONLY) │ │ (Redis-compat) │ │ (S3-like API) │ │
|
|
│ │ │ │ - Caching │ │ - Artifacts │ │
|
|
│ │ All services use │ │ - DPoP nonces │ │ - SBOMs │ │
|
|
│ │ PostgreSQL for │ │ - Event queues │ │ - Signatures │ │
|
|
│ │ persistent data │ │ - Rate limiting│ │ │ │
|
|
│ └──────────────────┘ └──────────────────┘ └─────────────────┘ │
|
|
│ │
|
|
│ ┌──────────────────────────────────────────────────────────────┐ │
|
|
│ │ Optional: NATS JetStream (alternative transport for queues) │ │
|
|
│ │ Only used if explicitly configured in appsettings │ │
|
|
│ └──────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Module dossiers live under `docs/modules/<module>/architecture.md`.
|
|
- Deployment defaults (ports, profile overlays, pinned digests) live under `deploy/` (`deploy/compose/`, `deploy/helm/`, `deploy/releases/`).
|