stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save progress

Browse Source
This commit is contained in:
StellaOps Bot
2026-01-03 00:47:24 +02:00
parent 3f197814c5
commit ca578801fd
319 changed files with 32478 additions and 2202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
docs/technical/architecture/module-matrix.md Normal file
View File

@@ -0,0 +1,248 @@
# Complete Module Matrix
This document provides a comprehensive inventory of all 46+ modules in the StellaOps solution (`src/StellaOps.sln`), explaining the purpose of each module and how they relate to the documented architecture.
## Table of Contents
- [1. Module Count Explanation](#1-module-count-explanation)
- [2. Complete Module Inventory](#2-complete-module-inventory)
- [3. Module Categories](#3-module-categories)
- [4. Service Deployment Matrix](#4-service-deployment-matrix)
- [5. Module Dependencies](#5-module-dependencies)
---
## 1. Module Count Explanation
The solution contains **46 top-level modules** in `src/`. The architecture documentation covers the **~35 core user-facing modules**, while the remaining modules fall into:
| Category | Count | Description |
|----------|-------|-------------|
| Core Platform | 4 | Authority, Gateway, Router, Platform |
| Data Ingestion | 7 | Concelier, Excititor, VexLens, VexHub, IssuerDirectory, Feedser, Mirror |
| Scanning & Analysis | 5 | Scanner, BinaryIndex, AdvisoryAI, Symbols, ReachGraph |
| Artifacts & Evidence | 7 | Attestor, Signer, SbomService, EvidenceLocker, ExportCenter, Provenance, Provcache |
| Policy & Risk | 4 | Policy, RiskEngine, VulnExplorer, Unknowns |
| Operations | 8 | Scheduler, Orchestrator, TaskRunner, Notify, Notifier, PacksRegistry, TimelineIndexer, Replay |
| Integration | 5 | CLI, Zastava, Web, API, Registry |
| Infrastructure | 6 | Cryptography, Telemetry, Graph, Signals, AirGap, AOC |
| Testing & Benchmarks | 2 | Benchmark, Bench |
| Utility & Internal | 6+ | Cartographer, Findings, SrmRemote, Tools, PluginBinaries, etc. |
---
## 2. Complete Module Inventory
### Core Platform (4 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Authority** | `src/Authority/` | Authentication, authorization, OAuth/OIDC, DPoP, tenant management | Yes | No | PostgreSQL (`authority`) |
| **Gateway** | `src/Gateway/` | API gateway with routing, TLS termination, transport abstraction | Yes | No | Stateless |
| **Router** | `src/Router/` | Transport-agnostic messaging (TCP/TLS/UDP/RabbitMQ/Valkey) | Yes | No | Valkey |
| **Platform** | `src/Platform/` | Platform Service aggregation APIs, console data composition | Yes | No | Aggregates |
### Data Ingestion (7 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Concelier** | `src/Concelier/` | Vulnerability advisory ingestion (NVD, OSV, GHSA, CSAF), merge engine with AOC | Yes | Yes | PostgreSQL (`vuln`) |
| **Excititor** | `src/Excititor/` | VEX document ingestion and export (OpenVEX, CSAF VEX) | Yes | Yes | PostgreSQL (`vex`) |
| **VexLens** | `src/VexLens/` | VEX consensus computation across issuers, conflict analysis | Yes | No | PostgreSQL (cache) |
| **VexHub** | `src/VexHub/` | VEX distribution and exchange hub | Yes | No | PostgreSQL |
| **IssuerDirectory** | `src/IssuerDirectory/` | Issuer trust registry for CSAF publishers | Yes | No | PostgreSQL |
| **Feedser** | `src/Feedser/` | Evidence collection library for backport detection | Library | N/A | N/A |
| **Mirror** | `src/Mirror/` | Vulnerability feed mirror and distribution | Yes | Yes | RustFS |
### Scanning & Analysis (5 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Scanner** | `src/Scanner/` | Container scanning with SBOM generation (11 language analyzers), call graphs | Yes | Yes | PostgreSQL (`scanner`) + RustFS |
| **BinaryIndex** | `src/BinaryIndex/` | Binary identity extraction and fingerprinting | Yes | No | PostgreSQL |
| **AdvisoryAI** | `src/AdvisoryAI/` | AI-assisted advisory analysis and summarization | Yes | No | PostgreSQL |
| **Symbols** | `src/Symbols/` | Symbol resolution and debug information | Yes | No | PostgreSQL |
| **ReachGraph** | `src/ReachGraph/` | Reachability graph service, CVE reachability analysis | Yes | No | PostgreSQL |
### Artifacts & Evidence (7 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Attestor** | `src/Attestor/` | in-toto/DSSE attestation generation, Rekor v2 integration | Yes | No | PostgreSQL + RustFS |
| **Signer** | `src/Signer/` | Cryptographic signing operations (PKIX, DSSE) | Yes | No | PostgreSQL |
| **SbomService** | `src/SbomService/` | SBOM storage, versioning, and lineage ledger | Yes | No | PostgreSQL + RustFS |
| **EvidenceLocker** | `src/EvidenceLocker/` | Sealed evidence storage and export | Yes | No | RustFS |
| **ExportCenter** | `src/ExportCenter/` | Batch export and report generation (SARIF, SBOM, evidence bundles) | Yes | No | RustFS |
| **Provenance** | `src/Provenance/` | SLSA/DSSE attestation tooling | Library | N/A | N/A |
| **Provcache** | Library | Provenance cache utilities | Library | N/A | N/A |
### Policy & Risk (4 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Policy** | `src/Policy/` | Policy engine with K4 lattice logic, confidence scoring, VEX emission | Yes | Yes | PostgreSQL (`policy`) |
| **RiskEngine** | `src/RiskEngine/` | Risk scoring runtime with pluggable providers | Yes | No | PostgreSQL |
| **VulnExplorer** | `src/VulnExplorer/` | Vulnerability exploration and triage UI backend | Yes | No | PostgreSQL (cache) |
| **Unknowns** | `src/Unknowns/` | Unknown component and symbol tracking registry | Yes | No | PostgreSQL |
### Operations (8 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Scheduler** | `src/Scheduler/` | Job scheduling and queue management, cron-based rescan | Yes | No | PostgreSQL (`scheduler`) |
| **Orchestrator** | `src/Orchestrator/` | Workflow orchestration and task coordination | Yes | No | PostgreSQL (`orchestrator`) |
| **TaskRunner** | `src/TaskRunner/` | Task pack execution engine | Yes | Yes | PostgreSQL |
| **Notify** | `src/Notify/` | Notification toolkit (Email, Slack, Teams, Webhooks) - shared libraries | Library | N/A | N/A |
| **Notifier** | `src/Notifier/` | Notifications Studio host (WebService + Worker) | Yes | Yes | PostgreSQL (`notify`) |
| **PacksRegistry** | `src/PacksRegistry/` | Task packs registry and distribution | Yes | No | PostgreSQL |
| **TimelineIndexer** | `src/TimelineIndexer/` | Timeline event indexing for audit trails | Yes | No | PostgreSQL |
| **Replay** | `src/Replay/` | Deterministic replay engine | Yes | No | PostgreSQL |
### Integration (5 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **CLI** | `src/Cli/` | Command-line interface (Native AOT, multi-platform) | CLI | N/A | N/A |
| **Zastava** | `src/Zastava/` | Container registry webhook observer, admission control | Yes | No | PostgreSQL |
| **Web** | `src/Web/` | Angular 17 frontend SPA | Static | N/A | N/A |
| **API** | `src/Api/` | OpenAPI contracts and governance | Library | N/A | N/A |
| **Registry** | `src/Registry/` | Container registry integration, token service | Yes | No | PostgreSQL |
### Infrastructure (6 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Cryptography** | `src/Cryptography/` | Crypto plugins (FIPS, eIDAS, GOST, SM, PQ) | Library | N/A | N/A |
| **Telemetry** | `src/Telemetry/` | OpenTelemetry traces, metrics, logging | Library | N/A | N/A |
| **Graph** | `src/Graph/` | Call graph and reachability data structures | Library | N/A | N/A |
| **Signals** | `src/Signals/` | Runtime signal collection and correlation | Library | N/A | N/A |
| **AirGap** | `src/AirGap/` | Air-gapped deployment support, Offline Kit bundling | Yes | Yes | RustFS |
| **AOC** | `src/Aoc/` | Append-Only Contract enforcement (Roslyn analyzers) | Library | N/A | N/A |
### Testing & Benchmarks (2 modules)
| Module | Path | Purpose | WebService | Worker | Storage |
|--------|------|---------|------------|--------|---------|
| **Benchmark** | Scanner library | Competitive benchmarking (accuracy comparison) | Tool | N/A | N/A |
| **Bench** | `src/Bench/` | Performance benchmarks | Tool | N/A | N/A |
### Utility & Internal (6+ modules)
| Module | Path | Purpose | Notes |
|--------|------|---------|-------|
| **Cartographer** | `src/Cartographer/` | Identity graphs from SBOM/advisory data | Feeds Graph Explorer |
| **Findings** | `src/Findings/` | Materializes effective findings from Policy outputs | Feeds UI/CLI/Notify |
| **SrmRemote** | `src/SrmRemote/` | SBOM remote operations | Integration utility |
| **Tools** | `src/Tools/` | Utility programs (fixture generators, migration scripts) | Dev tooling |
| **PluginBinaries** | Various | Authority and Concelier plugin binaries | Plugin hosting |
| **DevPortal** | `src/DevPortal/` | Developer onboarding portal | Documentation |
---
## 3. Module Categories
### By Runtime Type
| Type | Modules |
|------|---------|
| **WebService + Worker** | Scanner, Concelier, Excititor, Policy, Notifier, TaskRunner, AirGap, Mirror |
| **WebService Only** | Authority, Gateway, Router, Platform, VexLens, VexHub, IssuerDirectory, BinaryIndex, AdvisoryAI, Symbols, ReachGraph, Attestor, Signer, SbomService, EvidenceLocker, ExportCenter, RiskEngine, VulnExplorer, Unknowns, Scheduler, Orchestrator, PacksRegistry, TimelineIndexer, Replay, Zastava, Registry |
| **Library** | Feedser, Provenance, Provcache, Notify, API, Cryptography, Telemetry, Graph, Signals, AOC |
| **CLI/Tool** | CLI, Benchmark, Bench, Tools |
| **Static** | Web (Angular SPA) |
### By Data Store
| Store | Modules |
|-------|---------|
| **PostgreSQL** | Authority, Concelier, Excititor, VexLens, VexHub, IssuerDirectory, Scanner, BinaryIndex, AdvisoryAI, Symbols, ReachGraph, Attestor, Signer, SbomService, Policy, RiskEngine, VulnExplorer, Unknowns, Scheduler, Orchestrator, TaskRunner, Notifier, PacksRegistry, TimelineIndexer, Replay, Zastava, Registry |
| **RustFS (S3)** | Scanner, Attestor, SbomService, EvidenceLocker, ExportCenter, AirGap, Mirror |
| **Valkey** | Gateway, Router, Scanner, Policy, Scheduler, Notifier (for queues/cache) |
| **Stateless** | Gateway, Platform, CLI, Web |
### By Communication Pattern
| Pattern | Modules |
|---------|---------|
| **HTTP REST** | All WebService modules |
| **Binary Frame (Router)** | Gateway to all backend services |
| **Event Streams (Valkey/NATS)** | Scanner, Concelier, Excititor, Policy, Scheduler, Notifier |
| **Direct Library** | All Library modules |
---
## 4. Service Deployment Matrix
| Service | Container Image | Replicas | Storage | Queue | Observable |
|---------|-----------------|----------|---------|-------|------------|
| Authority | `stellaops/authority` | 2+ | PostgreSQL | Valkey (DPoP) | Yes |
| Gateway | `stellaops/gateway` | 2+ | Stateless | - | Yes |
| Scanner.Web | `stellaops/scanner-web` | 2+ | PostgreSQL + RustFS | - | Yes |
| Scanner.Worker | `stellaops/scanner-worker` | N | RustFS | Valkey/NATS | Yes |
| Concelier.Web | `stellaops/concelier-web` | 2+ | PostgreSQL | - | Yes |
| Concelier.Worker | `stellaops/concelier-worker` | N | PostgreSQL | Valkey/NATS | Yes |
| Policy.Engine | `stellaops/policy-engine` | 2+ | PostgreSQL | Valkey | Yes |
| Policy.Worker | `stellaops/policy-worker` | N | PostgreSQL | Valkey | Yes |
| Scheduler | `stellaops/scheduler` | 2+ | PostgreSQL | Valkey | Yes |
| Notifier | `stellaops/notifier` | 2+ | PostgreSQL | Valkey | Yes |
| ExportCenter | `stellaops/export-center` | 2+ | RustFS | - | Yes |
| Web (UI) | `stellaops/web` | 2+ | Static | - | Yes |
---
## 5. Module Dependencies
### Core Dependency Graph
```
+-------------+
| Authority |
+------+------+
|
+----------------------------+----------------------------+
| | |
v v v
+----------+ +----------+ +----------+
| Gateway |---------------->| Scanner |---------------->| Policy |
+----+-----+ +----+-----+ +----+-----+
| | |
| v v
| +----------+ +----------+
| | Concelier| | Signer |
| +----+-----+ +----+-----+
| | |
| v v
| +----------+ +----------+
| | Excititor| | Attestor|
| +----------+ +----------+
|
v
+----------+
| UI |
+----------+
```
### Key Integration Points
| From | To | Integration |
|------|----|-------------|
| Gateway | Authority | Token validation (JWKS) |
| Gateway | All Services | Binary frame routing |
| Scanner | Signer | SBOM signing |
| Scanner | Attestor | in-toto attestation |
| Policy | Concelier | Advisory data (read-only) |
| Policy | Excititor | VEX data (read-only) |
| Policy | Scanner | SBOM data (read-only) |
| Scheduler | Scanner | Trigger rescans |
| Scheduler | Concelier | Observe advisory deltas |
| Notifier | All Services | Consume events |
---
## Related Documentation
- [User Flows](user-flows.md)
- [Data Flows](data-flows.md)
- [Schema Mapping](schema-mapping.md)
- [Component Map](component-map.md)
- [Platform Topology](platform-topology.md)