feat: Document completed tasks for KMS, Cryptography, and Plugin Libraries
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled

- Added detailed task completion records for KMS interface implementation and CLI support for file-based keys.
- Documented security enhancements including Argon2id password hashing, audit event contracts, and rate limiting configurations.
- Included scoped service support and integration updates for the Plugin platform, ensuring proper DI handling and testing coverage.
This commit is contained in:
master
2025-10-31 14:33:05 +02:00
parent 240e8ff25d
commit 9e5e958d42
312 changed files with 6399 additions and 3319 deletions

View File

@@ -0,0 +1,44 @@
# Platform Architecture & Module Dossiers
Use this index to locate architecture narratives, boundaries, and implementation plans for every StellaOps component.
## Core Views
- [../high-level-architecture.md](../../high-level-architecture.md) 10-minute overview of the end-to-end flow.
- [../07_HIGH_LEVEL_ARCHITECTURE.md](../../07_HIGH_LEVEL_ARCHITECTURE.md) exhaustive reference (data flows, trust boundaries, operational traits).
- [../40_ARCHITECTURE_OVERVIEW.md](../../40_ARCHITECTURE_OVERVIEW.md) design principles applied across modules.
- [../scanner-core-contracts.md](../../scanner-core-contracts.md) canonical DTOs shared by Scanner services and consumers.
- Legacy service dossier: [../11_AUTHORITY.md](../../11_AUTHORITY.md) Authority overview before module split.
- UI documentation set: [../../ui/](../../ui/) (navigation, policies, findings, runs, tours).
- Component map: [component-map.md](component-map.md) quick descriptions of every `src/` module and how they interact.
## Module Catalogue
Each module directory bundles an ownership charter (`AGENTS.md`), current work (`TASKS.md`), architecture dossier, and implementation plan. Operations guides live under `operations/` where applicable.
| Module | Architecture | Implementation Plan | Operations / Extras |
|--------|--------------|---------------------|---------------------|
| Authority | [architecture.md](../../modules/authority/architecture.md) | [implementation_plan.md](../../modules/authority/implementation_plan.md) | [operations](../../modules/authority/operations/) |
| Advisory AI | [architecture.md](../../modules/advisory-ai/architecture.md) | [implementation_plan.md](../../modules/advisory-ai/implementation_plan.md) | — |
| Attestor | [architecture.md](../../modules/attestor/architecture.md) | [implementation_plan.md](../../modules/attestor/implementation_plan.md) | — |
| CLI | [architecture.md](../../modules/cli/architecture.md) | [implementation_plan.md](../../modules/cli/implementation_plan.md) | [operations/release-and-packaging.md](../../modules/cli/operations/release-and-packaging.md) |
| CI Recipes | [architecture.md](../../modules/ci/architecture.md) | [implementation_plan.md](../../modules/ci/implementation_plan.md) | [recipes.md](../../modules/ci/recipes.md) |
| Concelier | [architecture.md](../../modules/concelier/architecture.md) | [implementation_plan.md](../../modules/concelier/implementation_plan.md) | [operations/](../../modules/concelier/operations/) |
| DevOps / Release | [architecture.md](../../modules/devops/architecture.md) | [implementation_plan.md](../../modules/devops/implementation_plan.md) | [runbooks](../../modules/devops/runbooks/) |
| Excititor | [architecture.md](../../modules/excititor/architecture.md) | [implementation_plan.md](../../modules/excititor/implementation_plan.md) | [mirrors.md](../../modules/excititor/mirrors.md) |
| Export Center | [architecture.md](../../modules/export-center/architecture.md) | [implementation_plan.md](../../modules/export-center/implementation_plan.md) | [operations/runbook.md](../../modules/export-center/operations/runbook.md) |
| Graph | [architecture.md](../../modules/graph/architecture.md) | [implementation_plan.md](../../modules/graph/implementation_plan.md) | — |
| Notify | [architecture.md](../../modules/notify/architecture.md) | [implementation_plan.md](../../modules/notify/implementation_plan.md) | — |
| Orchestrator | [architecture.md](../../modules/orchestrator/architecture.md) | [implementation_plan.md](../../modules/orchestrator/implementation_plan.md) | — |
| Platform | [architecture-overview.md](../../modules/platform/architecture-overview.md) + [architecture.md](../../modules/platform/architecture.md) | [implementation_plan.md](../../modules/platform/implementation_plan.md) | — |
| Policy Engine | [architecture.md](../../modules/policy/architecture.md) | [implementation_plan.md](../../modules/policy/implementation_plan.md) | — |
| Registry Token Service | [architecture.md](../../modules/registry/architecture.md) | [implementation_plan.md](../../modules/registry/implementation_plan.md) | [operations/token-service.md](../../modules/registry/operations/token-service.md) |
| Scanner | [architecture.md](../../modules/scanner/architecture.md) | [implementation_plan.md](../../modules/scanner/implementation_plan.md) | [operations/](../../modules/scanner/operations/) |
| Scheduler | [architecture.md](../../modules/scheduler/architecture.md) | [implementation_plan.md](../../modules/scheduler/implementation_plan.md) | [operations/](../../modules/scheduler/operations/) |
| Signer | [architecture.md](../../modules/signer/architecture.md) | [implementation_plan.md](../../modules/signer/implementation_plan.md) | — |
| Telemetry Stack | [architecture.md](../../modules/telemetry/architecture.md) | [implementation_plan.md](../../modules/telemetry/implementation_plan.md) | [operations/collector.md](../../modules/telemetry/operations/collector.md), [operations/storage.md](../../modules/telemetry/operations/storage.md) |
| UI / Console | [architecture.md](../../modules/ui/architecture.md), [console-architecture.md](../../modules/ui/console-architecture.md) | [implementation_plan.md](../../modules/ui/implementation_plan.md) | — |
| Vuln Explorer | [architecture.md](../../modules/vuln-explorer/architecture.md) | [implementation_plan.md](../../modules/vuln-explorer/implementation_plan.md) | — |
| VEX Lens | [architecture.md](../../modules/vex-lens/architecture.md) | [implementation_plan.md](../../modules/vex-lens/implementation_plan.md) | — |
| Vexer | [architecture.md](../../modules/vexer/architecture.md) | [implementation_plan.md](../../modules/vexer/implementation_plan.md) | [scoring.md](../../modules/vexer/scoring.md) |
| Zastava | [architecture.md](../../modules/zastava/architecture.md) | [implementation_plan.md](../../modules/zastava/implementation_plan.md) | — |
> **Tip:** Every module directory also exposes `README.md`, `AGENTS.md`, and `TASKS.md` for roles, current backlog, and ownership responsibilities.

View File

@@ -0,0 +1,77 @@
# Platform Component Map
Concise descriptions of every top-level component under `src/`, summarising the role documented across StellaOps technical guides and how each module interacts with the rest of the platform. Use this as a quick orientation map before diving into the module-specific dossiers listed in [architecture/README.md](README.md).
## Advisory & Evidence Services
- **AdvisoryAI** — Experimental intelligence helpers that summarise and prioritise advisory data for humans. Ingests canonical observations from Concelier/Excititor, adds explainable insights, and feeds UI/CLI and Policy workflows. See `docs/modules/advisory-ai/architecture.md`.
- **Concelier** — Canonical advisory ingestion engine enforcing the Aggregation-Only Contract (AOC). Produces immutable observations/linksets consumed by Policy Engine, Graph, Scheduler, and Export Center. Docs in `docs/modules/concelier/architecture.md` and `docs/ingestion/aggregation-only-contract.md`.
- **Excititor** — VEX statement normaliser applying AOC guardrails. Supplies VEX observations to Policy Engine, VEX Lens, Scheduler, and UI. Reference `docs/modules/excititor/architecture.md` and `docs/vex/aggregation.md`.
- **VexLens** — Provides focused exploration of VEX evidence, conflict analysis, and waiver insights for UI/CLI. Backed by Excititor and Policy Engine (`docs/modules/vex-lens/architecture.md`).
- **EvidenceLocker** — Long-term store for signed evidence bundles (DSSE, SRM, policy waivers). Integrates with Attestor, Export Center, Policy, and replay tooling (`docs/forensics/evidence-locker.md`).
- **ExportCenter** — Packages reproducible evidence bundles and mirror artefacts for online/offline distribution. Pulls from Concelier, Excititor, Policy, Scanner, Attestor, and Registry (`docs/modules/export-center/architecture.md`).
- **Mirror** — Feed and artefact mirroring services supporting Offline Update Kits, registry mirrors, and air-gapped updates (`docs/modules/devops/architecture.md`, `docs/airgap/`).
## Scanning, SBOM & Risk
- **Scanner** — Deterministic scanning with API + worker pair. Generates SBOM fragments, emits SRM/DSSE-ready reports, hands results to Signer/Attestor, and surfaces status to Scheduler/CLI/UI (`docs/modules/scanner/architecture.md`).
- **SbomService** — SBOM inventory store and delta cache leveraged by Scanner, Policy Engine, Cartographer, and Export Center (`docs/modules/scanner/architecture.md`, SBOM sections).
- **RiskEngine** — Consolidates Policy verdicts, runtime signals, and graph overlays into prioritised risk views (`docs/modules/policy/architecture.md`, `docs/modules/graph/architecture.md`).
- **Findings** — Materialises effective findings from Policy Engine outputs and evidence. Feeds UI, CLI, Notify, and Governance dashboards (`docs/modules/policy/architecture.md`, findings sections).
- **Cartographer** — Builds identity graphs from SBOM/advisory data for Graph Explorer and RiskEngine (`docs/modules/graph/architecture.md`).
- **Graph** — Graph API + indexer, exposing relationship queries to UI/CLI/Scheduler (`docs/modules/graph/architecture.md`).
- **VulnExplorer** — Explorer for vulnerabilities that combines Concelier data, graph overlays, and Policy results for UI/CLI consumption (`docs/modules/vuln-explorer/architecture.md`).
## Policy & Governance
- **Policy** — Policy Engine core libraries and services executing lattice logic across SBOM, advisory, and VEX evidence. Emits explain traces, drives Findings, Notifier, and Export Center (`docs/modules/policy/architecture.md`).
- **Policy Studio / TaskRunner / PacksRegistry** — Authoring, automation, and reusable template services that orchestrate policy and operational workflows (`docs/task-packs/`, `docs/modules/cli/`, `docs/modules/ui/`).
- **Governance components** (Authority scopes, Policy governance, Console policy UI) are covered in `docs/security/policy-governance.md` and `docs/modules/ui/policies.md`.
## Identity, Signing & Provenance
- **Authority** — Identity provider issuing short-lived OpToks, enforcing scopes/tenancy, and powering every modules authentication story (`docs/11_AUTHORITY.md`, `docs/modules/authority/architecture.md`).
- **Signer** — DSSE signing backend supporting keyless/keyful modes with Authority-managed trust roots (`docs/modules/signer/architecture.md`).
- **Attestor** — Manages proof bundles, optional Rekor mirror, and distribution to consumers (`docs/modules/attestor/architecture.md`).
- **Provenance** — Utilities and services for DSSE/SLSA provenance verification, consumed by Export Center, EvidenceLocker, and Replay (`docs/modules/export-center/provenance-and-signing.md`).
- **IssuerDirectory** — Directory of trust issuers/KMS bindings used by Authority, Signer, Attestor, Export Center, and AirGap cryptographic profiles (`docs/modules/authority/architecture.md`, trust sections).
## Scheduling, Orchestration & Automation
- **Scheduler** — Detects advisory/VEX deltas and orchestrates deterministic rescan runs toward Scanner and Policy Engine (`docs/modules/scheduler/architecture.md`).
- **Orchestrator** — Central coordination service dispatching jobs (scans, exports, policy runs) to modules, working closely with Scheduler, CLI, and UI (`docs/modules/orchestrator/architecture.md`).
- **TaskRunner** — Executes automation packs sourced from PacksRegistry, integrating with Orchestrator, CLI, Notify, and Authority (`docs/task-packs/runbook.md`).
- **Signals** — Ingests runtime posture signals and feeds Policy/Notifier workflows (`docs/modules/zastava/architecture.md`, signals sections).
- **TimelineIndexer** — Builds timelines of evidence/events for forensics and audit tooling (`docs/forensics/timeline.md`).
## Notification & UI
- **Notifier** — New notifications studio with rule engine, digesting, and channel plug-ins (`docs/notifications/overview.md`).
- **Notify** — Legacy notification service referenced in backlog/cleanup docs; still handles existing deployments (`docs/modules/notify/architecture.md`).
- **UI** — Angular console surfacing scans, policy authoring, VEX evidence, runtime posture, and admin flows. Talks to Web gateway, Authority, Policy, Concelier, Scheduler, Notify, etc. (`docs/modules/ui/architecture.md`).
- **DevPortal** — Developer onboarding portal consuming Api definitions, CLI samples, and Authority auth flows (`docs/modules/devops/architecture.md`, dev portal sections).
## Runtime & Registry
- **Registry** — Anonymous registry/token service hosting platform images and Offline Kit artefacts (`docs/modules/registry/architecture.md`).
- **Zastava** — Runtime observer/admission controller ensuring signed images, SBOM availability, and policy verdict enforcement in live clusters (`docs/modules/zastava/architecture.md`).
- **Signals** (shared above) plus runtime components integrate tightly with Zastava and Policy Engine.
- **Bench** — Performance benchmarking toolset validating platform SLAs (`docs/12_PERFORMANCE_WORKBOOK.md`).
## Offline, Telemetry & Infrastructure
- **AirGap** — Bundles Offline Update Kits, enforces sealed-mode operations, and distributes trust roots/feeds (`docs/10_OFFLINE_KIT.md`, `docs/airgap/`).
- **Telemetry** — OpenTelemetry collector/storage deployment tooling, observability integrations, and offline metrics packages (`docs/modules/telemetry/architecture.md`, `docs/observability/`).
- **Mirror** and **ExportCenter** (above) complement AirGap by keeping offline mirrors in sync.
- **Tools** — Collection of utility programs (fixture generators, smoke tests, migration scripts) supporting all modules (`docs/dev/fixtures.md`, module-specific tooling sections).
## CLI, SDK, Web Gateway
- **Cli** — Native command-line interface orchestrating scans, policy operations, offline workflows, and evidence replay (`docs/modules/cli/architecture.md`).
- **Sdk** — Shared SDK packages for third-party integration (C#, TS, etc.), wrapping Authority auth and API definitions (`docs/api/`).
- **Web** — API gateway/BFF exposing module APIs to UI/CLI and external clients, performing auth & route orchestration (`docs/modules/platform/architecture-overview.md`, gateway sections).
## Remaining Shared Libraries
- **Api**, **Sdk**, **__Libraries** — Core shared contracts and helper libraries referenced throughout modules (configuration, messaging, federation). Each module dossier highlights its shared dependencies.
- **Aoc** library (mentioned above) is reused by ingestion components and verification tooling to enforce the Aggregation-Only Contract.
## How It All Connects
High-level flows (see `docs/high-level-architecture.md` for diagrams):
1. **Ingest** — Concelier and Excititor use AOC to ingest advisories/VEX; Scheduler observes deltas.
2. **Scan & Evaluate** — Scanner generates SBOM evidence and hands to Signer/Attestor; Policy Engine merges SBOM, advisory, VEX, runtime signals; RiskEngine prioritises.
3. **Store & Export** — EvidenceLocker and Export Center package results; Registry serves artefacts; AirGap bundles offline editions.
4. **Observe & Notify** — Telemetry captures metrics/traces/logs; Notifier/Notify deliver alerts; UI/CLI/Web expose operations; TimelineIndexer builds audit trails.
5. **Govern & Secure** — Authority, IssuerDirectory, Signer, and Attestor maintain trust; Policy governance and console experiences let teams manage waivers and approvals.
Refer back to module-specific documentation for APIs, configuration, schema details, and operational runbooks. This component map will stay updated alongside module architecture changes—log updates in `docs/updates/` whenever new modules are introduced or deprecated.