From deb82b4f03bbabf1067f28e3c7aa3a5c1509b583 Mon Sep 17 00:00:00 2001 From: StellaOps Bot Date: Thu, 25 Dec 2025 10:53:53 +0200 Subject: [PATCH] docs consolidation work --- docs/04_FEATURE_MATRIX.md | 7 +- docs/05_SYSTEM_REQUIREMENTS_SPEC.md | 408 +++++++++--------- docs/11_GOVERNANCE.md | 20 +- docs/15_UI_GUIDE.md | 30 +- docs/24_OFFLINE_KIT.md | 4 +- docs/29_LEGAL_FAQ_QUOTA.md | 2 +- docs/30_QUOTA_ENFORCEMENT_FLOW1.md | 16 +- docs/DEVELOPER_ONBOARDING.md | 2 +- docs/_archive/README.md | 1 + docs/_includes/CONSTANTS.md | 2 +- docs/aoc/aoc-guardrails.md | 2 +- docs/aoc/guard-library.md | 2 +- docs/api/policy.md | 2 +- .../authority/authority-plugin-component.mmd | 6 +- .../authority/authority-plugin-component.svg | 2 +- .../vex-justifications.catalog.json | 2 +- docs/cli-vs-ui-parity.md | 8 +- docs/deploy/containers.md | 2 +- docs/key-features.md | 2 +- docs/modules/attestor/AGENTS.md | 2 +- docs/modules/authority/AGENTS.md | 2 +- docs/modules/ci/AGENTS.md | 2 +- docs/modules/cli/AGENTS.md | 2 +- docs/modules/cli/guides/cli-reference.md | 4 +- docs/modules/cli/guides/commands/aoc.md | 2 +- docs/modules/concelier/AGENTS.md | 2 +- docs/modules/concelier/README.md | 2 +- docs/modules/concelier/implementation_plan.md | 40 +- .../concelier/link-not-merge-schema.md | 8 +- docs/modules/devops/AGENTS.md | 20 +- .../devops/governance-rules.md} | 0 .../modules/devops/migrations/semver-style.md | 2 + .../devops/policy-schema-export.md | 0 .../devops/runbooks/deployment-upgrade.md | 6 +- .../modules/devops/runbooks/launch-cutover.md | 4 +- docs/modules/excititor/AGENTS.md | 2 +- docs/modules/excititor/README.md | 8 +- .../excititor/schemas/vex_raw.schema.json | 1 + docs/modules/excititor/vex_observations.md | 6 +- docs/modules/export-center/AGENTS.md | 2 +- docs/modules/export-center/api.md | 132 +++--- docs/modules/export-center/cli.md | 30 +- docs/modules/export-center/mirror-bundles.md | 76 ++-- .../export-center/operations/runbook.md | 24 +- docs/modules/export-center/overview.md | 2 +- docs/modules/graph/AGENTS.md | 2 +- docs/modules/notify/AGENTS.md | 2 +- docs/modules/notify/README.md | 16 +- docs/{notifications => modules/notify}/api.md | 4 +- .../notify/architecture-detail.md} | 2 +- .../notify}/channels.md | 0 .../notify}/digests.md | 0 .../notify}/escalations.md | 0 .../notify}/fixtures/redaction/sample.json | 0 .../notify}/fixtures/rendering/index.ndjson | 0 .../tmpl-incident-start.email.en-US.json | 0 .../notify}/fixtures/traces/sample-trace.json | 0 .../notify}/gaps-nr1-nr10.md | 20 +- .../operations/alerts/notify-slo-alerts.yaml | 0 .../dashboards}/dashboards/notify-slo.json | 0 .../notify}/operations/quotas.md | 2 +- .../notify}/operations/retries.md | 0 .../notify}/overview.md | 12 +- .../notify}/pack-approvals-contract.md | 0 .../notify}/pack-approvals-integration.md | 0 .../notify}/rules.md | 36 +- .../notify}/schemas/README.md | 0 .../notify}/schemas/channel.schema.json | 0 .../notify}/schemas/dlq-notify.schema.json | 0 .../schemas/event-envelope.schema.json | 0 .../notify}/schemas/inputs.lock | 0 .../schemas/notify-schemas-catalog.dsse.json | 0 .../schemas/notify-schemas-catalog.json | 0 .../notify}/schemas/receipt.schema.json | 0 .../notify}/schemas/rule.schema.json | 0 .../notify}/schemas/template.schema.json | 0 .../notify}/schemas/webhook.schema.json | 0 .../notify}/security/README.md | 0 .../notify}/security/redaction-catalog.md | 2 +- .../notify}/security/tenant-approvals.md | 0 .../notify}/security/webhook-ack-hardening.md | 0 .../notify}/simulations/index.ndjson | 0 .../simulations/sample-rule-report.json | 0 .../simulations/sample-simulation-report.json | 0 .../notify}/slo-webhook-schema.md | 2 +- .../notify}/templates.md | 0 docs/modules/platform/AGENTS.md | 2 +- .../modules/platform/architecture-overview.md | 10 +- docs/modules/platform/architecture.md | 2 +- docs/modules/policy/AGENTS.md | 2 +- docs/modules/policy/architecture.md | 292 ++++++------- docs/modules/provcache/README.md | 2 + docs/modules/registry/AGENTS.md | 2 +- docs/modules/scanner/AGENTS.md | 2 +- docs/modules/scheduler/AGENTS.md | 2 +- docs/modules/signer/AGENTS.md | 2 +- docs/modules/telemetry/AGENTS.md | 2 +- docs/modules/ui/AGENTS.md | 2 +- docs/modules/zastava/AGENTS.md | 2 +- docs/modules/zastava/architecture.md | 278 ++++++------ docs/notifications/operations/README.md | 3 - docs/observability/observability.md | 4 +- docs/observability/ui-telemetry.md | 12 +- docs/overview.md | 2 +- docs/quickstart.md | 2 +- docs/reachability/lattice.md | 2 +- docs/reachability/policy-gate.md | 4 +- docs/scripts/sbom-vex/README.md | 2 +- docs/security/authority-scopes.md | 2 +- docs/security/console-security.md | 32 +- docs/technical/architecture/component-map.md | 4 +- docs/technical/development/README.md | 3 +- docs/technical/interfaces/README.md | 4 +- docs/technical/observability/README.md | 8 +- docs/technical/operations/README.md | 6 +- docs/technical/process/README.md | 4 +- docs/technical/security/README.md | 2 +- 117 files changed, 852 insertions(+), 847 deletions(-) rename docs/{devops/contracts-and-rules.md => modules/devops/governance-rules.md} (100%) rename docs/{ => modules}/devops/policy-schema-export.md (100%) rename docs/{notifications => modules/notify}/api.md (94%) rename docs/{notifications/architecture.md => modules/notify/architecture-detail.md} (96%) rename docs/{notifications => modules/notify}/channels.md (100%) rename docs/{notifications => modules/notify}/digests.md (100%) rename docs/{notifications => modules/notify}/escalations.md (100%) rename docs/{notifications => modules/notify}/fixtures/redaction/sample.json (100%) rename docs/{notifications => modules/notify}/fixtures/rendering/index.ndjson (100%) rename docs/{notifications => modules/notify}/fixtures/rendering/tmpl-incident-start.email.en-US.json (100%) rename docs/{notifications => modules/notify}/fixtures/traces/sample-trace.json (100%) rename docs/{notifications => modules/notify}/gaps-nr1-nr10.md (58%) rename docs/{notifications => modules/notify}/operations/alerts/notify-slo-alerts.yaml (100%) rename docs/{notifications/operations => modules/notify/operations/dashboards}/dashboards/notify-slo.json (100%) rename docs/{notifications => modules/notify}/operations/quotas.md (75%) rename docs/{notifications => modules/notify}/operations/retries.md (100%) rename docs/{notifications => modules/notify}/overview.md (88%) rename docs/{notifications => modules/notify}/pack-approvals-contract.md (100%) rename docs/{notifications => modules/notify}/pack-approvals-integration.md (100%) rename docs/{notifications => modules/notify}/rules.md (96%) rename docs/{notifications => modules/notify}/schemas/README.md (100%) rename docs/{notifications => modules/notify}/schemas/channel.schema.json (100%) rename docs/{notifications => modules/notify}/schemas/dlq-notify.schema.json (100%) rename docs/{notifications => modules/notify}/schemas/event-envelope.schema.json (100%) rename docs/{notifications => modules/notify}/schemas/inputs.lock (100%) rename docs/{notifications => modules/notify}/schemas/notify-schemas-catalog.dsse.json (100%) rename docs/{notifications => modules/notify}/schemas/notify-schemas-catalog.json (100%) rename docs/{notifications => modules/notify}/schemas/receipt.schema.json (100%) rename docs/{notifications => modules/notify}/schemas/rule.schema.json (100%) rename docs/{notifications => modules/notify}/schemas/template.schema.json (100%) rename docs/{notifications => modules/notify}/schemas/webhook.schema.json (100%) rename docs/{notifications => modules/notify}/security/README.md (100%) rename docs/{notifications => modules/notify}/security/redaction-catalog.md (74%) rename docs/{notifications => modules/notify}/security/tenant-approvals.md (100%) rename docs/{notifications => modules/notify}/security/webhook-ack-hardening.md (100%) rename docs/{notifications => modules/notify}/simulations/index.ndjson (100%) rename docs/{notifications => modules/notify}/simulations/sample-rule-report.json (100%) rename docs/{notifications => modules/notify}/simulations/sample-simulation-report.json (100%) rename docs/{notifications => modules/notify}/slo-webhook-schema.md (98%) rename docs/{notifications => modules/notify}/templates.md (100%) delete mode 100644 docs/notifications/operations/README.md diff --git a/docs/04_FEATURE_MATRIX.md b/docs/04_FEATURE_MATRIX.md index ebbfd5ecb..7b9587e4a 100755 --- a/docs/04_FEATURE_MATRIX.md +++ b/docs/04_FEATURE_MATRIX.md @@ -58,9 +58,10 @@ |------------|:----:|:---------:|:----------:|-------| | CVE Lookup via Local DB | ✅ | ✅ | ✅ | | | Licence-Risk Detection | ⏳ | ⏳ | ⏳ | Q4-2025 | -| **Language Analyzers (All 8)** | | | | | +| **Language Analyzers (All 11)** | | | | | | — .NET/C#, Java, Go, Python | ✅ | ✅ | ✅ | | -| — Node.js, Ruby, Bun, Native | ✅ | ✅ | ✅ | | +| — Node.js, Ruby, Bun, Deno | ✅ | ✅ | ✅ | | +| — PHP, Rust, Native binaries | ✅ | ✅ | ✅ | | | **Progressive Fidelity Modes** | | | | | | — Quick Mode | ✅ | ✅ | ✅ | | | — Standard Mode | ✅ | ✅ | ✅ | | @@ -423,7 +424,7 @@ ### Free Tier (33 scans/day) **Target:** Individual developers, OSS contributors, evaluation -- All language analyzers (8 languages) +- All language analyzers (11 languages) - All regional crypto (FIPS/eIDAS/GOST/SM/PQ) - Full VEX processing + VEX Hub + Conflict Studio - SSO/SAML/OIDC authentication diff --git a/docs/05_SYSTEM_REQUIREMENTS_SPEC.md b/docs/05_SYSTEM_REQUIREMENTS_SPEC.md index 63af9dc2f..546ba7e7c 100755 --- a/docs/05_SYSTEM_REQUIREMENTS_SPEC.md +++ b/docs/05_SYSTEM_REQUIREMENTS_SPEC.md @@ -1,204 +1,204 @@ -# SYSTEM REQUIREMENTS SPECIFICATION -Stella Ops · self‑hosted supply‑chain‑security platform - -> **Audience** – core maintainers and external contributors who need an -> authoritative checklist of *what* the software must do (functional -> requirements) and *how well* it must do it (non‑functional -> requirements). Implementation details belong in Module Specs -> or ADRs—**not here**. - ---- - -## 1 · Purpose & Scope - -This SRS defines everything the **v0.1.0‑alpha** release of _Stella Ops_ must do, **including the Free‑tier daily quota of {{ quota_token }} SBOM scans per token**. -Scope includes core platform, CLI, UI, quota layer, and plug‑in host; commercial or closed‑source extensions are explicitly out‑of‑scope. - ---- - -## 2 · References - -* [overview.md](overview.md) – market gap & problem statement -* [03_VISION.md](03_VISION.md) – north‑star, KPIs, quarterly themes -* [07_HIGH_LEVEL_ARCHITECTURE.md](07_HIGH_LEVEL_ARCHITECTURE.md) – context & data flow diagrams -* [modules/platform/architecture-overview.md](modules/platform/architecture-overview.md) – component APIs & plug‑in contracts -* [09_API_CLI_REFERENCE.md](09_API_CLI_REFERENCE.md) – REST & CLI surface - ---- - -## 3 · Definitions & Acronyms - -| Term | Meaning | -|------|---------| -| **SBOM** | Software Bill of Materials | -| **Delta SBOM** | Partial SBOM covering only image layers not previously analysed | -| **Registry** | Anonymous, read‑only Docker Registry v2 hosted internally | -| **OPA** | Open Policy Agent (Rego policy engine) | -| **Muting Policy** | Rule that downgrades or ignores specific findings | -| **SLSA** | Supply‑chain Levels for Software Artifacts (provenance framework) | -| **Rekor** | Sigstore transparency log for signatures | - ---- - -## 4 · Overall System Description - -The platform consists of: - -* **Stella Ops Backend** – REST API, queue, policy engine, DB. -* **StellaOps.Registry** – internal container registry for agents. -* **Stella CLI** – extracts SBOMs; supports multi‑format & delta. -* **Zastava Agent** – enforcement hook for admission‑control scenarios. -* **Web UI** – React/Next.js SPA consuming backend APIs. -* **Plug‑ins** – hot‑load binaries extending scanners, attestations, etc. - -All services run in Docker Compose or Kubernetes with optional Internet -access. - ---- - -## 5 · Functional Requirements (FR) - -### 5.1 Core Scanning - -| ID | Requirement | Priority | Verification | -|----|-------------|----------|--------------| -| F‑1 | System SHALL ingest **Trivy‑JSON, SPDX‑JSON, CycloneDX‑JSON** files. | MUST | UT‑SBOM‑001 | -| F‑2 | System SHALL **auto‑detect** SBOM type when `sbomType` param omitted. | MUST | UT‑SBOM‑002 | -| F‑3 | System SHALL **cache analysed layers** and reuse them in subsequent scans. | MUST | IT‑CACHE‑001 | -| F‑4 | System SHALL **enforce a soft limit of {{ quota_token }} scans per token per UTC day**. | MUST | IT‑QUOTA‑001 | -| F‑4a | Remaining quota SHALL be **persisted in Redis** under key `quota::`. | MUST | UT‑QUOTA‑REDIS | -| F‑4b | Exhausted quota SHALL trigger **HTTP 429** with `Retry‑After` header (UTC midnight). | MUST | IT‑QUOTA‑002 | -| F‑4c | When quota is ≤ 40 % remaining, **UI banner** MUST turn yellow and show count‑down. | SHOULD | UI‑E2E‑005 | -| F‑4d | `/quota` endpoint SHALL return JSON `{"limit":{{ quota_token }} ,"remaining":N,"resetsAt":""}`. | SHOULD | API‑DOC‑003 | -| F‑5 | Policy engine SHALL evaluate **YAML rules** against scan results. | MUST | UT‑POL‑001 | -| F‑6 | Hot‑pluggable .NET plug‑ins SHALL be loadable **without service restart**. | MUST | IT‑PLUGIN‑001 | -| F‑7 | CLI (`stella scan`) SHOULD exit **non‑zero** when CVSS≥7 vulnerabilities found. | SHOULD | CL‑INT‑003 | -| *(… all previously documented F‑8 – F‑12 rows retained unchanged …)* | - - -### 5.2 Internal Docker Repository - -| Ref | Requirement | -|-----|-------------| -| **FR‑REPO‑1** | Platform SHALL include **StellaOps.Registry** exposing Docker Registry v2 API (ports 5000/443). | -| **FR‑REPO‑2** | Registry SHALL allow anonymous, *read‑only* pulls for at least three images:
• `stella/sbom‑builder`
• `stella/cli`
• `stella/zastava`. | -| **FR‑REPO‑3** | Registry MAY enable optional basic‑auth without code changes. | - -### 5.3 SBOM Generation & Handling - -| Ref | Requirement | -|-----|-------------| -| **FR‑SBOM‑1** | SBOM builder SHALL produce Trivy‑JSON **and** at least one additional format: SPDX‑JSON and CycloneDX‑JSON. | -| **FR‑SBOM‑2** | For every generated SBOM, builder SHALL create a side‑car file `.sbom.type` containing the format identifier. | -| **FR‑SBOM‑3** | Stella CLI SHALL read the `.sbom.type` file and include `sbomType` parameter when uploading. | -| **FR‑SBOM‑4** | Backend SHALL auto‑detect SBOM type when parameter is missing. | -| **FR‑SBOM‑5** | UI Settings SHALL expose a dropdown to select default SBOM format (system‑wide fallback). | - -#### 5.3.1 Delta SBOM (layer reuse) - -| Ref | Requirement | -|-----|-------------| -| **FR‑DELTA‑1** | Builder SHALL compute SHA256 digests of each image layer and POST array to `/layers/missing`; response time ≤ 20 ms (P95). | -| **FR‑DELTA‑2** | Builder SHALL generate SBOM **only** for layers returned as “missing”. | -| **FR‑DELTA‑3** | End‑to‑end warm scan time (image differing by ≤ 2 layers) SHALL be ≤ 1 s (P95). | - -### 5.4 Policy as Code (Muting & Expiration) - -| Ref | Requirement | -|-----|-------------| -| **FR‑POLICY‑1** | Backend SHALL store policies as YAML by default, convertible to Rego for advanced use‑cases. | -| **FR‑POLICY‑2** | Each policy change SHALL create an immutable history record (timestamp, actor, diff). | -| **FR‑POLICY‑3** | REST endpoints `/policy/import`, `/policy/export`, `/policy/validate` SHALL accept YAML or Rego payloads. | -| **FR‑POLICY‑4** | Web UI Policies tab SHALL provide Monaco editor with linting for YAML and Rego. | -| **FR‑POLICY‑5** | **StellaOps.MutePolicies** module SHALL expose CLI `stella policies apply --file scan‑policy.yaml`. | - -### 5.5 SLSA Attestations & Rekor (TODO > 6 mo) - -| Ref | Requirement | -|-----|-------------| -| **FR‑SLSA‑1** | **TODO** – Generate provenance in SLSA‑Provenance v0.2 for each SBOM. | -| **FR‑REKOR‑1** | **TODO** – Sign SBOM hashes and upload to local Rekor mirror; verify during scan. | - -### 5.6 CLI & API Interface - -| Ref | Requirement | -|-----|-------------| -| **FR‑CLI‑1** | CLI `stella scan` SHALL accept `--sbom-type {trivy,spdx,cyclonedx,auto}`. | -| **FR‑API‑1** | API `/scan` SHALL accept `sbomType` query/body field (optional). | -| **FR‑API‑2** | API `/layers/missing` SHALL accept JSON array of digests and return JSON array of missing digests. | - ---- - -## 6 · Non‑Functional Requirements (NFR) - -| Ref | Category | Requirement | -|-----|----------|-------------| -| **NFR‑PERF‑1** | Performance | P95 cold scan ≤ 5 s; warm ≤ 1 s (see **FR‑DELTA‑3**). | -| **NFR‑PERF‑2** | Throughput | System shall sustain 60 concurrent scans on 8‑core node without queue depth >10. | -| **NFR‑AVAIL‑1** | Availability | All services shall start offline; any Internet call must be optional. | -| **NFR-SCAL-1** | Scalability | Horizontal scaling via Kubernetes replicas for backend, Redis Sentinel, PostgreSQL cluster. | -| **NFR‑SEC‑1** | Security | All inter‑service traffic shall use TLS or localhost sockets. | -| **NFR‑COMP‑1** | Compatibility | Platform shall run on x86‑64 Linux kernel ≥ 5.10; Windows agents (TODO > 6 mo) must support Server 2019+. | -| **NFR‑I18N‑1** | Internationalisation | UI must support EN and at least one additional locale (Cyrillic). | -| **NFR‑OBS‑1** | Observability | Export Prometheus metrics for scan duration, queue length, policy eval duration. | - ---- - -## 7 Acceptance Criteria - -1. Issue {{ quota_token }} `/scan` calls; next returns random slow down and `Retry‑After`. -2. Redis failure during test → API returns **0 remaining** & warns in logs. -3. UI banner activates at 133 remaining; clears next UTC midnight. - ---- -## 8 · System Interfaces - -### 8.1 External APIs - -*(This is the complete original table, plus new `/quota` row.)* - -| Path | Method | Auth | Quota | Description | -|------|--------|------|-------|-------------| -| `/scan` | POST | Bearer | ✅ | Submit SBOM or `imageRef` for scanning. | -| `/quota` | GET | Bearer | ❌ | Return remaining quota for current token. | -| `/policy/rules` | GET/PUT | Bearer+RBAC | ❌ | CRUD YAML or Rego policies. | -| `/plugins` | POST/GET | Bearer+Admin | ❌ | Upload or list plug‑ins. | - -```bash -GET /quota -Authorization: Bearer - -200 OK -{ -"limit": {{ quota_token }}, -"remaining": 121, -"resetsAt": "2025-07-14T23:59:59Z" -} -``` - -## 9 · Assumptions & Constraints - -* Hardware reference: 8 vCPU, 8 GB RAM, NVMe SSD. -* PostgreSQL and Redis run co-located unless horizontal scaling enabled. -* All docker images tagged `latest` are immutable (CI process locks digests). -* Rego evaluation runs in embedded OPA Go‑library (no external binary). - ---- - -## 10 · Future Work (Beyond 12 Months) - -* Rekor transparency log cross‑cluster replication. -* AI‑assisted false‑positive triage plug‑in. -* Cluster‑wide injection for live runtime scanning. - ---- - -## 11 · Revision History - -| Version | Date | Notes | -|---------|------|-------| -| **v1.2** | 11‑Jul‑2025 | Commercial references removed; plug‑in contract (§ 3.3) and new NFR categories added; added User Classes & Traceability. | -| v1.1 | 11‑Jul‑2025 | Split out RU‑specific items; OSS scope | -| v1.0 | 09‑Jul‑2025 | Original unified SRS | - -*(End of System Requirements Specification v1.2‑core)* +# SYSTEM REQUIREMENTS SPECIFICATION +Stella Ops · self‑hosted supply‑chain‑security platform + +> **Audience** – core maintainers and external contributors who need an +> authoritative checklist of *what* the software must do (functional +> requirements) and *how well* it must do it (non‑functional +> requirements). Implementation details belong in Module Specs +> or ADRs—**not here**. + +--- + +## 1 · Purpose & Scope + +This SRS defines everything the **v0.1.0‑alpha** release of _Stella Ops_ must do, **including the Free‑tier daily quota of {{ quota_token }} SBOM scans per token**. +Scope includes core platform, CLI, UI, quota layer, and plug‑in host; commercial or closed‑source extensions are explicitly out‑of‑scope. + +--- + +## 2 · References + +* [overview.md](overview.md) – market gap & problem statement +* [03_VISION.md](03_VISION.md) – north‑star, KPIs, quarterly themes +* [07_HIGH_LEVEL_ARCHITECTURE.md](07_HIGH_LEVEL_ARCHITECTURE.md) – context & data flow diagrams +* [modules/platform/architecture-overview.md](modules/platform/architecture-overview.md) – component APIs & plug‑in contracts +* [09_API_CLI_REFERENCE.md](09_API_CLI_REFERENCE.md) – REST & CLI surface + +--- + +## 3 · Definitions & Acronyms + +| Term | Meaning | +|------|---------| +| **SBOM** | Software Bill of Materials | +| **Delta SBOM** | Partial SBOM covering only image layers not previously analysed | +| **Registry** | Anonymous, read‑only Docker Registry v2 hosted internally | +| **OPA** | Open Policy Agent (Rego policy engine) | +| **Muting Policy** | Rule that downgrades or ignores specific findings | +| **SLSA** | Supply‑chain Levels for Software Artifacts (provenance framework) | +| **Rekor** | Sigstore transparency log for signatures | + +--- + +## 4 · Overall System Description + +The platform consists of: + +* **Stella Ops Backend** – REST API, queue, policy engine, DB. +* **StellaOps.Registry** – internal container registry for agents. +* **Stella CLI** – extracts SBOMs; supports multi‑format & delta. +* **Zastava Agent** – enforcement hook for admission‑control scenarios. +* **Web UI** – Angular 17 SPA consuming backend APIs. +* **Plug‑ins** – hot‑load binaries extending scanners, attestations, etc. + +All services run in Docker Compose or Kubernetes with optional Internet +access. + +--- + +## 5 · Functional Requirements (FR) + +### 5.1 Core Scanning + +| ID | Requirement | Priority | Verification | +|----|-------------|----------|--------------| +| F‑1 | System SHALL ingest **Trivy‑JSON, SPDX‑JSON, CycloneDX‑JSON** files. | MUST | UT‑SBOM‑001 | +| F‑2 | System SHALL **auto‑detect** SBOM type when `sbomType` param omitted. | MUST | UT‑SBOM‑002 | +| F‑3 | System SHALL **cache analysed layers** and reuse them in subsequent scans. | MUST | IT‑CACHE‑001 | +| F‑4 | System SHALL **enforce a soft limit of {{ quota_token }} scans per token per UTC day**. | MUST | IT‑QUOTA‑001 | +| F‑4a | Remaining quota SHALL be **persisted in Valkey** under key `quota::`. | MUST | UT‑QUOTA‑VALKEY | +| F‑4b | Exhausted quota SHALL trigger **HTTP 429** with `Retry‑After` header (UTC midnight). | MUST | IT‑QUOTA‑002 | +| F‑4c | When quota is ≤ 40 % remaining, **UI banner** MUST turn yellow and show count‑down. | SHOULD | UI‑E2E‑005 | +| F‑4d | `/quota` endpoint SHALL return JSON `{"limit":{{ quota_token }} ,"remaining":N,"resetsAt":""}`. | SHOULD | API‑DOC‑003 | +| F‑5 | Policy engine SHALL evaluate **YAML rules** against scan results. | MUST | UT‑POL‑001 | +| F‑6 | Hot‑pluggable .NET plug‑ins SHALL be loadable **without service restart**. | MUST | IT‑PLUGIN‑001 | +| F‑7 | CLI (`stella scan`) SHOULD exit **non‑zero** when CVSS≥7 vulnerabilities found. | SHOULD | CL‑INT‑003 | +| *(… all previously documented F‑8 – F‑12 rows retained unchanged …)* | + + +### 5.2 Internal Docker Repository + +| Ref | Requirement | +|-----|-------------| +| **FR‑REPO‑1** | Platform SHALL include **StellaOps.Registry** exposing Docker Registry v2 API (ports 5000/443). | +| **FR‑REPO‑2** | Registry SHALL allow anonymous, *read‑only* pulls for at least three images:
• `stella/sbom‑builder`
• `stella/cli`
• `stella/zastava`. | +| **FR‑REPO‑3** | Registry MAY enable optional basic‑auth without code changes. | + +### 5.3 SBOM Generation & Handling + +| Ref | Requirement | +|-----|-------------| +| **FR‑SBOM‑1** | SBOM builder SHALL produce Trivy‑JSON **and** at least one additional format: SPDX‑JSON and CycloneDX‑JSON. | +| **FR‑SBOM‑2** | For every generated SBOM, builder SHALL create a side‑car file `.sbom.type` containing the format identifier. | +| **FR‑SBOM‑3** | Stella CLI SHALL read the `.sbom.type` file and include `sbomType` parameter when uploading. | +| **FR‑SBOM‑4** | Backend SHALL auto‑detect SBOM type when parameter is missing. | +| **FR‑SBOM‑5** | UI Settings SHALL expose a dropdown to select default SBOM format (system‑wide fallback). | + +#### 5.3.1 Delta SBOM (layer reuse) + +| Ref | Requirement | +|-----|-------------| +| **FR‑DELTA‑1** | Builder SHALL compute SHA256 digests of each image layer and POST array to `/layers/missing`; response time ≤ 20 ms (P95). | +| **FR‑DELTA‑2** | Builder SHALL generate SBOM **only** for layers returned as “missing”. | +| **FR‑DELTA‑3** | End‑to‑end warm scan time (image differing by ≤ 2 layers) SHALL be ≤ 1 s (P95). | + +### 5.4 Policy as Code (Muting & Expiration) + +| Ref | Requirement | +|-----|-------------| +| **FR‑POLICY‑1** | Backend SHALL store policies as YAML by default, convertible to Rego for advanced use‑cases. | +| **FR‑POLICY‑2** | Each policy change SHALL create an immutable history record (timestamp, actor, diff). | +| **FR‑POLICY‑3** | REST endpoints `/policy/import`, `/policy/export`, `/policy/validate` SHALL accept YAML or Rego payloads. | +| **FR‑POLICY‑4** | Web UI Policies tab SHALL provide Monaco editor with linting for YAML and Rego. | +| **FR‑POLICY‑5** | **StellaOps.MutePolicies** module SHALL expose CLI `stella policies apply --file scan‑policy.yaml`. | + +### 5.5 SLSA Attestations & Rekor (TODO > 6 mo) + +| Ref | Requirement | +|-----|-------------| +| **FR‑SLSA‑1** | **TODO** – Generate provenance in SLSA‑Provenance v0.2 for each SBOM. | +| **FR‑REKOR‑1** | **TODO** – Sign SBOM hashes and upload to local Rekor mirror; verify during scan. | + +### 5.6 CLI & API Interface + +| Ref | Requirement | +|-----|-------------| +| **FR‑CLI‑1** | CLI `stella scan` SHALL accept `--sbom-type {trivy,spdx,cyclonedx,auto}`. | +| **FR‑API‑1** | API `/scan` SHALL accept `sbomType` query/body field (optional). | +| **FR‑API‑2** | API `/layers/missing` SHALL accept JSON array of digests and return JSON array of missing digests. | + +--- + +## 6 · Non‑Functional Requirements (NFR) + +| Ref | Category | Requirement | +|-----|----------|-------------| +| **NFR‑PERF‑1** | Performance | P95 cold scan ≤ 5 s; warm ≤ 1 s (see **FR‑DELTA‑3**). | +| **NFR‑PERF‑2** | Throughput | System shall sustain 60 concurrent scans on 8‑core node without queue depth >10. | +| **NFR‑AVAIL‑1** | Availability | All services shall start offline; any Internet call must be optional. | +| **NFR-SCAL-1** | Scalability | Horizontal scaling via Kubernetes replicas for backend, Valkey cluster, PostgreSQL cluster. | +| **NFR‑SEC‑1** | Security | All inter‑service traffic shall use TLS or localhost sockets. | +| **NFR‑COMP‑1** | Compatibility | Platform shall run on x86‑64 Linux kernel ≥ 5.10; Windows agents (TODO > 6 mo) must support Server 2019+. | +| **NFR‑I18N‑1** | Internationalisation | UI must support EN and at least one additional locale (Cyrillic). | +| **NFR‑OBS‑1** | Observability | Export Prometheus metrics for scan duration, queue length, policy eval duration. | + +--- + +## 7 Acceptance Criteria + +1. Issue {{ quota_token }} `/scan` calls; next returns random slow down and `Retry‑After`. +2. Valkey failure during test → API returns **0 remaining** & warns in logs. +3. UI banner activates at 133 remaining; clears next UTC midnight. + +--- +## 8 · System Interfaces + +### 8.1 External APIs + +*(This is the complete original table, plus new `/quota` row.)* + +| Path | Method | Auth | Quota | Description | +|------|--------|------|-------|-------------| +| `/scan` | POST | Bearer | ✅ | Submit SBOM or `imageRef` for scanning. | +| `/quota` | GET | Bearer | ❌ | Return remaining quota for current token. | +| `/policy/rules` | GET/PUT | Bearer+RBAC | ❌ | CRUD YAML or Rego policies. | +| `/plugins` | POST/GET | Bearer+Admin | ❌ | Upload or list plug‑ins. | + +```bash +GET /quota +Authorization: Bearer + +200 OK +{ +"limit": {{ quota_token }}, +"remaining": 121, +"resetsAt": "2025-07-14T23:59:59Z" +} +``` + +## 9 · Assumptions & Constraints + +* Hardware reference: 8 vCPU, 8 GB RAM, NVMe SSD. +* PostgreSQL and Valkey run co-located unless horizontal scaling enabled. +* All docker images tagged `latest` are immutable (CI process locks digests). +* Rego evaluation runs in embedded OPA Go‑library (no external binary). + +--- + +## 10 · Future Work (Beyond 12 Months) + +* Rekor transparency log cross‑cluster replication. +* AI‑assisted false‑positive triage plug‑in. +* Cluster‑wide injection for live runtime scanning. + +--- + +## 11 · Revision History + +| Version | Date | Notes | +|---------|------|-------| +| **v1.2** | 11‑Jul‑2025 | Commercial references removed; plug‑in contract (§ 3.3) and new NFR categories added; added User Classes & Traceability. | +| v1.1 | 11‑Jul‑2025 | Split out RU‑specific items; OSS scope | +| v1.0 | 09‑Jul‑2025 | Original unified SRS | + +*(End of System Requirements Specification v1.2‑core)* diff --git a/docs/11_GOVERNANCE.md b/docs/11_GOVERNANCE.md index 4b228b94f..a2a16186a 100755 --- a/docs/11_GOVERNANCE.md +++ b/docs/11_GOVERNANCE.md @@ -47,20 +47,20 @@ Approval is recorded via Git forge review or a signed commit trailer ## 4 · Release authority & provenance 🔏 -* Every tag is **co‑signed by at least one Security Maintainer**. -* CI emits a **signed SPDX SBOM** + **Cosign provenance**. -* Release cadence is fixed – see [public Road‑map](05_ROADMAP.md). -* Security fixes may create out‑of‑band `x.y.z‑hotfix` tags. +* Every tag is **co‑signed by at least one Security Maintainer**. +* CI emits a **signed SPDX SBOM** + **Cosign provenance**. +* Release cadence is fixed – see [Release Engineering Playbook](13_RELEASE_ENGINEERING_PLAYBOOK.md). +* Security fixes may create out‑of‑band `x.y.z‑hotfix` tags. --- ## 5 · Escalation lanes 🚦 -| Situation | Escalation | -|-----------|------------| -| Technical deadlock | **Maintainer Summit** (recorded & published) | -| Security bug | Follow [Security Policy](13_SECURITY_POLICY.md) | -| Code of Conduct violation | See `12_CODE_OF_CONDUCT.md` escalation ladder | +| Situation | Escalation | +|-----------|------------| +| Technical deadlock | **Maintainer Summit** (recorded & published) | +| Security bug | Follow [Security Policy](13_SECURITY_POLICY.md) | +| Code of Conduct violation | See `12_CODE_OF_CONDUCT.md` escalation ladder | --- @@ -90,4 +90,4 @@ section directly.)* | `@alice` | Core scanner • Security | 2025‑04 | | `@bob` | UI • Docs | 2025‑06 | ---- +--- diff --git a/docs/15_UI_GUIDE.md b/docs/15_UI_GUIDE.md index 4fdedd28d..c0f0934fa 100755 --- a/docs/15_UI_GUIDE.md +++ b/docs/15_UI_GUIDE.md @@ -82,22 +82,22 @@ See `docs/24_OFFLINE_KIT.md` for packaging and offline verification workflows. ## Deploy and Install References - Deployment configuration and health checks: `docs/deploy/console.md`. -- Container install recipes: `docs/install/docker.md`. +- Container install recipes: `docs/operations/console-docker-install.md`. -## Detailed References - -Operator-facing deep dives (Console): - -- `docs/console/airgap.md` -- `docs/console/admin-tenants.md` -- `docs/console/forensics.md` -- `docs/console/observability.md` - -UX and interaction contracts: - -- `docs/ux/TRIAGE_UX_GUIDE.md` - -## Related Docs +## Detailed References + +Operator-facing deep dives (Console): + +- `docs/console/airgap.md` +- `docs/console/admin-tenants.md` +- `docs/console/forensics.md` +- `docs/console/observability.md` + +UX and interaction contracts: + +- `docs/ux/TRIAGE_UX_GUIDE.md` + +## Related Docs - `docs/16_VEX_CONSENSUS_GUIDE.md` - `docs/20_VULNERABILITY_EXPLORER_GUIDE.md` diff --git a/docs/24_OFFLINE_KIT.md b/docs/24_OFFLINE_KIT.md index 16a65613b..4fb8431ee 100755 --- a/docs/24_OFFLINE_KIT.md +++ b/docs/24_OFFLINE_KIT.md @@ -461,8 +461,8 @@ The scanner enforces the same fair‑use limits offline: * **Free JWT:** {{ quota\_token }} scans per UTC day Soft reminder at 200 scans; throttle above the ceiling but **never block**. -See the detailed rules in -[`33_333_QUOTA_OVERVIEW.md`](33_333_QUOTA_OVERVIEW.md). +See the quota enforcement flow in +[`30_QUOTA_ENFORCEMENT_FLOW1.md`](30_QUOTA_ENFORCEMENT_FLOW1.md). --- diff --git a/docs/29_LEGAL_FAQ_QUOTA.md b/docs/29_LEGAL_FAQ_QUOTA.md index 28a69c5be..cbb0895e7 100755 --- a/docs/29_LEGAL_FAQ_QUOTA.md +++ b/docs/29_LEGAL_FAQ_QUOTA.md @@ -1,7 +1,7 @@ # Legal FAQ — Free‑Tier Quota & AGPL Compliance > **Operational behaviour (limits, counters, delays) is documented in -> [`33_333_QUOTA_OVERVIEW.md`](33_333_QUOTA_OVERVIEW.md).** +> [`30_QUOTA_ENFORCEMENT_FLOW1.md`](30_QUOTA_ENFORCEMENT_FLOW1.md).** > This page covers only the legal aspects of offering Stella Ops as a > service or embedding it into another product while the free‑tier limits are > in place. diff --git a/docs/30_QUOTA_ENFORCEMENT_FLOW1.md b/docs/30_QUOTA_ENFORCEMENT_FLOW1.md index 480753f7e..275943bc2 100755 --- a/docs/30_QUOTA_ENFORCEMENT_FLOW1.md +++ b/docs/30_QUOTA_ENFORCEMENT_FLOW1.md @@ -1,8 +1,8 @@ # Quota Enforcement — Flow Diagram (rev 2.1) -> **Scope** – this document explains *how* the free‑tier limits are enforced -> inside the scanner service. For policy rationale and legal aspects see -> [`33_333_QUOTA_OVERVIEW.md`](33_333_QUOTA_OVERVIEW.md). +> **Scope** – this document explains *how* the free‑tier limits are enforced +> inside the scanner service. For policy rationale and legal aspects, see +> [`29_LEGAL_FAQ_QUOTA.md`](29_LEGAL_FAQ_QUOTA.md). --- @@ -26,10 +26,10 @@ sequenceDiagram participant C as Client participant API as Scanner API - participant REDIS as Redis (quota) + participant VALKEY as Valkey (quota) C->>API: /scan - API->>REDIS: INCR quota: - REDIS-->>API: new_count + API->>VALKEY: INCR quota: + VALKEY-->>API: new_count alt new_count ≤ L_active API-->>C: 202 Accepted (no delay) else new_count ≤ L_active + 30 @@ -45,7 +45,7 @@ sequenceDiagram --- -## 2 · Redis key layout +## 2 · Valkey key layout | Key pattern | TTL | Description | | ---------------------- | ---- | --------------------------------- | @@ -53,7 +53,7 @@ sequenceDiagram | `quota:tid:` | 24 h | Token quota per *hashed* token‑ID | | `quota:ip::ts` | 24 h | First‑seen timestamp (ISO 8601) | -Keys share a common TTL for efficient mass expiry via `redis-cli --scan`. +Keys share a common TTL for efficient mass expiry via `valkey-cli --scan`. --- diff --git a/docs/DEVELOPER_ONBOARDING.md b/docs/DEVELOPER_ONBOARDING.md index cfbcdecf7..f286a8ee0 100644 --- a/docs/DEVELOPER_ONBOARDING.md +++ b/docs/DEVELOPER_ONBOARDING.md @@ -405,7 +405,7 @@ docker compose -f docker-compose.dev.yaml down # 2. Remove database volumes docker volume rm compose_postgres-data -docker volume rm compose_mongo-data +docker volume rm compose_valkey-data # 3. Restart platform (will recreate volumes and databases) docker compose -f docker-compose.dev.yaml up -d diff --git a/docs/_archive/README.md b/docs/_archive/README.md index fa37a0965..6ab80e00f 100644 --- a/docs/_archive/README.md +++ b/docs/_archive/README.md @@ -7,6 +7,7 @@ This directory contains documentation that has been superseded, deprecated, or c | Directory | Reason | Canonical Location | |-----------|--------|-------------------| | `orchestrator-legacy/` | Parallel directory consolidated | `docs/modules/orchestrator/` | +| `stubs/` | Empty placeholder files archived | N/A | ## Policy diff --git a/docs/_includes/CONSTANTS.md b/docs/_includes/CONSTANTS.md index efde601b2..a4f268171 100755 --- a/docs/_includes/CONSTANTS.md +++ b/docs/_includes/CONSTANTS.md @@ -9,7 +9,7 @@ # ───────────────────────────────────────────────────────────────────────────── dotnet: "10 LTS" # Runs on .NET 10 (LTS channel) -angular: "20" # Front‑end framework major +angular: "17" # Front‑end framework major (17.3.x) quota_anon: 33 # Anonymous daily scans quota_token: 333 # Daily scans with free JWT slowdown: "5–60 s" # Delay window after exceeding quota diff --git a/docs/aoc/aoc-guardrails.md b/docs/aoc/aoc-guardrails.md index ab7654ec4..864c26744 100644 --- a/docs/aoc/aoc-guardrails.md +++ b/docs/aoc/aoc-guardrails.md @@ -10,4 +10,4 @@ The Aggregation-Only Contract keeps ingestion services deterministic and policy- For detailed roles and ownership boundaries, see `AGENTS.md` at the repo root and the module-specific dossiers under `docs/modules//architecture.md`. -Need the full contract? Read the [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md) for schemas, error codes, and migration guidance. +Need the full contract? Read the [Aggregation-Only Contract reference](aggregation-only-contract.md) for schemas, error codes, and migration guidance. diff --git a/docs/aoc/guard-library.md b/docs/aoc/guard-library.md index 11298bbae..7298b7ebb 100644 --- a/docs/aoc/guard-library.md +++ b/docs/aoc/guard-library.md @@ -5,7 +5,7 @@ > **Audience:** Concelier/Excititor service owners, Platform guild, QA The Aggregation-Only Contract (AOC) guard library enforces the canonical ingestion -rules described in `docs/ingestion/aggregation-only-contract.md`. Service owners +rules described in `docs/aoc/aggregation-only-contract.md`. Service owners should use the guard whenever raw advisory or VEX payloads are accepted so that forbidden fields are rejected long before they reach PostgreSQL. diff --git a/docs/api/policy.md b/docs/api/policy.md index d0abfd49e..a5a2e5a52 100644 --- a/docs/api/policy.md +++ b/docs/api/policy.md @@ -539,7 +539,7 @@ Returns rule hit sequence: - `policy.run.completed` – emitted with `runId`, `policyId`, `mode`, `stats`, `determinismHash`. - `policy.run.failed` – includes error code, retry count, guidance. - `policy.lifecycle.*` – mirrored from lifecycle APIs (see [Lifecycle guide](../policy/lifecycle.md)). -- Webhook registration occurs via `/api/policy/webhooks` (future work, reserved). For now, integrate with Notifier streams documented in `/docs/notifications/*`. +- Webhook registration occurs via `/api/policy/webhooks` (future work, reserved). For now, integrate with Notifier streams documented in `/docs/modules/notify/`. --- diff --git a/docs/assets/authority/authority-plugin-component.mmd b/docs/assets/authority/authority-plugin-component.mmd index 99efea09c..1e399963c 100644 --- a/docs/assets/authority/authority-plugin-component.mmd +++ b/docs/assets/authority/authority-plugin-component.mmd @@ -19,13 +19,13 @@ flowchart LR identity[IIdentityProviderPlugin (password & bootstrap flows)] store[StandardUserCredentialStore -(Mongo collections)] +(PostgreSQL auth schema)] capability[Capability Metadata (password, bootstrap, clientProvisioning)] end subgraph External["External Systems"] - mongo[(MongoDB cluster + postgres[(PostgreSQL cluster credential + lockout state)] audit[(Audit Sink / Event Bus)] secrets[Offline Secrets Bundle @@ -40,7 +40,7 @@ credential + lockout state)] registrar --> identity identity --> store identity --> audit - store --> mongo + store --> postgres options --> secrets secrets --> registrar api --> identity diff --git a/docs/assets/authority/authority-plugin-component.svg b/docs/assets/authority/authority-plugin-component.svg index 7e69c8740..7a49c6d90 100644 --- a/docs/assets/authority/authority-plugin-component.svg +++ b/docs/assets/authority/authority-plugin-component.svg @@ -76,7 +76,7 @@ - MongoDB cluster + PostgreSQL cluster credential & lockout state diff --git a/docs/benchmarks/vex-justifications.catalog.json b/docs/benchmarks/vex-justifications.catalog.json index 46fa1d9b0..523301bd6 100644 --- a/docs/benchmarks/vex-justifications.catalog.json +++ b/docs/benchmarks/vex-justifications.catalog.json @@ -131,7 +131,7 @@ "security-ops" ], "policy_links": [ - "docs/uncertainty/README.md" + "docs/reachability/uncertainty-entropy.md" ], "uncertainty_gate": "U2-medium" }, diff --git a/docs/cli-vs-ui-parity.md b/docs/cli-vs-ui-parity.md index 9770c253b..b229e2cac 100644 --- a/docs/cli-vs-ui-parity.md +++ b/docs/cli-vs-ui-parity.md @@ -18,7 +18,7 @@ Status key: | UI capability | CLI command(s) | Status | Notes / Tasks | |---------------|----------------|--------|---------------| | Login / token cache status (`/console/profile`) | `stella auth login`, `stella auth status`, `stella auth whoami` | ✅ Available | Command definitions in `CommandFactory.BuildAuthCommand`. | -| Fresh-auth challenge for sensitive actions | `stella auth fresh-auth` | ✅ Available | Referenced in `docs/15_UI_GUIDE.md` (Admin). | +| Fresh-auth challenge for sensitive actions | `stella auth fresh-auth` | ✅ Available | Referenced in `docs/15_UI_GUIDE.md` (Admin). | | Tenant switcher (UI shell) | `--tenant` flag across CLI commands | ✅ Available | All multi-tenant commands require explicit `--tenant`. | | Tenant creation / suspension | *(pending CLI)* | 🟩 Planned | No `stella auth tenant *` commands yet – track via `CLI-TEN-47-001` (scopes & tenancy). | @@ -142,12 +142,12 @@ The script should emit a parity report that feeds into the Downloads workspace ( ## 11 · References -- `docs/15_UI_GUIDE.md` – console workflow overview for parity context. -- `/docs/install/docker.md` – CLI parity section for deployments. +- `docs/15_UI_GUIDE.md` – console workflow overview for parity context. +- `/docs/operations/console-docker-install.md` – CLI parity section for deployments. - `/docs/observability/ui-telemetry.md` – telemetry metrics referencing CLI checks. - `/docs/security/console-security.md` – security metrics & CLI parity expectations. - `src/Cli/StellaOps.Cli/TASKS.md` – authoritative status for CLI backlog. -- `/docs/updates/2025-10-28-docs-guild.md` – coordination note for Authority/Security follow-up. +- `/docs/implplan/archived/updates/2025-10-28-docs-guild.md` – coordination note for Authority/Security follow-up. --- diff --git a/docs/deploy/containers.md b/docs/deploy/containers.md index c4886aded..9c41c7ac6 100644 --- a/docs/deploy/containers.md +++ b/docs/deploy/containers.md @@ -134,7 +134,7 @@ clients: ## 7 · References -- [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../aoc/aggregation-only-contract.md) - [Authority scopes & tenancy](../security/authority-scopes.md) - [Observability guide](../observability/observability.md) - [CLI AOC commands](../modules/cli/guides/cli-reference.md) diff --git a/docs/key-features.md b/docs/key-features.md index 4302c9683..25b990f6e 100644 --- a/docs/key-features.md +++ b/docs/key-features.md @@ -81,7 +81,7 @@ Each card below pairs the headline capability with the evidence that backs it an - **Evidence:** `docs/task-packs/spec.md` and `docs/task-packs/registry.md`; architecture contract in `docs/modules/taskrunner/architecture.md`; runbook in `docs/task-packs/runbook.md`. - **Why it matters:** Security teams get auditable, air-gap-friendly automation with human approvals and provable provenance, reusing the same workflows online or offline. -## 13. Evidence-Grade Testing and Deterministic Gates (2026-12) +## 13. Evidence-Grade Testing and Deterministic Gates (2025-12) - **What it is:** A model-driven test taxonomy and CI lanes that make determinism, offline behavior, and contract stability continuously provable. - **Evidence:** `docs/testing/testing-strategy-models.md` and the catalog in `docs/testing/TEST_CATALOG.yml` define required test types per module; `docs/19_TEST_SUITE_OVERVIEW.md` lists the gated lanes. - **Why it matters:** Regression-proof audits and predictable CI gates ensure that evidence, not assumptions, drives releases. diff --git a/docs/modules/attestor/AGENTS.md b/docs/modules/attestor/AGENTS.md index 9c6b17240..c018f2176 100644 --- a/docs/modules/attestor/AGENTS.md +++ b/docs/modules/attestor/AGENTS.md @@ -17,7 +17,7 @@ Attestor moves signed evidence through the trust chain by accepting DSSE bundles 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/authority/AGENTS.md b/docs/modules/authority/AGENTS.md index fadd29cf4..64d2167f1 100644 --- a/docs/modules/authority/AGENTS.md +++ b/docs/modules/authority/AGENTS.md @@ -17,7 +17,7 @@ Authority is the platform OIDC/OAuth2 control plane that mints short-lived, send 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/ci/AGENTS.md b/docs/modules/ci/AGENTS.md index 6ba14de5f..47978ca38 100644 --- a/docs/modules/ci/AGENTS.md +++ b/docs/modules/ci/AGENTS.md @@ -16,7 +16,7 @@ CI module collects reproducible pipeline recipes for builds, tests, and release 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/cli/AGENTS.md b/docs/modules/cli/AGENTS.md index ab452831c..401cb18d8 100644 --- a/docs/modules/cli/AGENTS.md +++ b/docs/modules/cli/AGENTS.md @@ -16,7 +16,7 @@ The `stella` CLI is the operator-facing Swiss army knife for scans, exports, pol 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/cli/guides/cli-reference.md b/docs/modules/cli/guides/cli-reference.md index 8114b2e15..0292048a5 100644 --- a/docs/modules/cli/guides/cli-reference.md +++ b/docs/modules/cli/guides/cli-reference.md @@ -3,7 +3,7 @@ > **Audience:** DevEx engineers, operators, and CI authors integrating the `stella` CLI with Aggregation-Only Contract (AOC) workflows. > **Scope:** Command synopsis, options, exit codes, and offline considerations for `stella sources ingest --dry-run` and `stella aoc verify` as introduced in Sprint 19. -Both commands are designed to enforce the AOC guardrails documented in the [aggregation-only reference](../../../ingestion/aggregation-only-contract.md) and the [architecture overview](../architecture.md). They consume Authority-issued tokens with tenant scopes and never mutate ingestion stores. +Both commands are designed to enforce the AOC guardrails documented in the [aggregation-only reference](../../../aoc/aggregation-only-contract.md) and the [architecture overview](../architecture.md). They consume Authority-issued tokens with tenant scopes and never mutate ingestion stores. --- @@ -416,7 +416,7 @@ Additional notes: ## 5 · Related references -- [Aggregation-Only Contract reference](../../../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../../../aoc/aggregation-only-contract.md) - [Architecture overview](../../platform/architecture-overview.md) - [Console operator guide](../../../15_UI_GUIDE.md) - [Authority scopes](../../authority/architecture.md) diff --git a/docs/modules/cli/guides/commands/aoc.md b/docs/modules/cli/guides/commands/aoc.md index 3b8563e81..790dc81e7 100644 --- a/docs/modules/cli/guides/commands/aoc.md +++ b/docs/modules/cli/guides/commands/aoc.md @@ -103,7 +103,7 @@ See the [CLI Consolidation Migration Guide](../../../../cli/cli-consolidation-mi ## Related Documentation -- [Aggregation-Only Contract Reference](../../../../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract Reference](../../../../aoc/aggregation-only-contract.md) - [CLI Reference](../cli-reference.md) - [Container Deployment Guide](../../../../deploy/containers.md) diff --git a/docs/modules/concelier/AGENTS.md b/docs/modules/concelier/AGENTS.md index 015934743..f58ec964a 100644 --- a/docs/modules/concelier/AGENTS.md +++ b/docs/modules/concelier/AGENTS.md @@ -16,7 +16,7 @@ Concelier ingests signed advisories from dozens of sources and converts them int 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/concelier/README.md b/docs/modules/concelier/README.md index 1b65e3911..6b7f2d15a 100644 --- a/docs/modules/concelier/README.md +++ b/docs/modules/concelier/README.md @@ -15,7 +15,7 @@ Concelier ingests signed advisories from dozens of sources and converts them int - Exporter packages (`StellaOps.Concelier.Exporter.*`). ## Recent updates -- **2025-11-07:** Paragraph-anchored `/advisories/{advisoryKey}/chunks` endpoint shipped for Advisory AI paragraph retrieval. Details and rollout notes live in [`../../updates/2025-11-07-concelier-advisory-chunks.md`](../../updates/2025-11-07-concelier-advisory-chunks.md). +- **2025-11-07:** Paragraph-anchored `/advisories/{advisoryKey}/chunks` endpoint shipped for Advisory AI paragraph retrieval. Details and rollout notes live in [`../../implplan/archived/updates/2025-11-07-concelier-advisory-chunks.md`](../../implplan/archived/updates/2025-11-07-concelier-advisory-chunks.md). ## Integrations & dependencies - PostgreSQL (schema `vuln`) for canonical observations and schedules. diff --git a/docs/modules/concelier/implementation_plan.md b/docs/modules/concelier/implementation_plan.md index 5c76770a1..d17d11996 100644 --- a/docs/modules/concelier/implementation_plan.md +++ b/docs/modules/concelier/implementation_plan.md @@ -1,8 +1,8 @@ # Implementation plan — Concelier ## Delivery timeline -- **Phase 1 — Guardrails & schema** - Stand up Mongo JSON validators for `advisory_raw` and `vex_raw`, wire the `AOCWriteGuard` repository interceptor, and seed deterministic linkset builders. Freeze legacy normalisation paths and migrate callers to the new raw schema. +- **Phase 1 — Guardrails & schema** + Stand up PostgreSQL JSON schema validators for `advisory_raw` and `vex_raw`, wire the `AOCWriteGuard` repository interceptor, and seed deterministic linkset builders. Freeze legacy normalisation paths and migrate callers to the new raw schema. - **Phase 2 — API & observability** Publish ingestion and verification endpoints (`POST /ingest/*`, `GET /advisories.raw`, `POST /aoc/verify`) with Authority scopes, expose telemetry (`aoc_violation_total`, guard spans, structured logs), and ensure Offline Kit packaging captures validator deployment steps. - **Phase 3 — Experience polish** @@ -10,7 +10,7 @@ ## Work breakdown by component - **Concelier WebService & worker** - - Add Mongo validators and unique indexes over `(tenant, source.vendor, upstream.upstream_id, upstream.content_hash)`. + - Add PostgreSQL validators and unique indexes over `(tenant, source.vendor, upstream.upstream_id, upstream.content_hash)`. - Implement write interceptors rejecting forbidden fields, missing provenance, or merge attempts. - Deterministically compute linksets and persist canonical JSON payloads. - Introduce `/ingest/advisory`, `/advisories/raw*`, and `/aoc/verify` surfaces guarded by `advisory:*` and `aoc:verify` scopes. @@ -34,13 +34,13 @@ - Seed fixtures and run `stella aoc verify` against snapshots in pipeline gating. ## Documentation deliverables -- Update `docs/ingestion/aggregation-only-contract.md` with guard invariants, schemas, error codes, and migration guidance. +- Update `docs/aoc/aggregation-only-contract.md` with guard invariants, schemas, error codes, and migration guidance. - Refresh `docs/modules/concelier/operations/*.md` (mirror, conflict-resolution, authority audit) with validator rollouts and observability dashboards. - Cross-link Authority scope definitions, CLI reference, Console sources guide, and observability runbooks to the AOC guard changes. - Ensure Offline Kit documentation captures validator bootstrap and verify workflows. ## Acceptance criteria -- Mongo validators and runtime guards reject forbidden fields and missing provenance with the documented `ERR_AOC_00x` codes. +- PostgreSQL validators and runtime guards reject forbidden fields and missing provenance with the documented `ERR_AOC_00x` codes. - Linksets and supersedes chains are deterministic; rerunning ingestion over identical payloads yields byte-identical documents. - CLI `stella aoc verify` exits non-zero on seeded violations and zero on clean datasets; Console dashboards show real-time guard status. - Export Center consumes advisory datasets without relying on legacy normalised fields. @@ -56,18 +56,18 @@ - **Unit**: guard rejection paths, provenance enforcement, idempotent insertions, linkset determinism. - **Property**: fuzz upstream payloads to guarantee no forbidden fields emerge. - **Integration**: batch ingest (50k advisories, mixed VEX fixtures), verifying zero guard violations and consistent supersedes. -- **Contract**: Policy Engine consumers verify raw-only reads; Export Center consumes canonical datasets. -- **End-to-end**: ingest/verify flow with CLI + Console actions to confirm observability and guard reporting. - -## Definition of done -- Validators deployed and verified in staging/offline environments. -- Runtime guards, CLI/Console workflows, and CI linting all active. -- Observability dashboards and runbooks updated; metrics visible. -- Documentation updates merged; Offline Kit instructions published. -- ./TASKS.md reflects status transitions; cross-module dependencies acknowledged in ../../TASKS.md. - -## Readiness checkpoints (2025-11-25) -- Sprint 110 attestation chain validated: `/internal/attestations/verify` endpoint and evidence bundle tests green (`TestResults/concelier-attestation/web.trx`, `core.trx`). -- Link-Not-Merge cache + console consumption docs frozen (see `operations/lnm-cache-plan.md`, `operations/console-lnm-consumption.md`); cache headers remain deterministic. -- Observation events transport reviewed; backlog guardrails and NATS/air-gap guidance updated in `operations/observation-events.md`. -- Next gating dependency: TaskRunner contract drop (sprint 0157 blockers) before wiring approvals/pack ingest flows into Concelier. +- **Contract**: Policy Engine consumers verify raw-only reads; Export Center consumes canonical datasets. +- **End-to-end**: ingest/verify flow with CLI + Console actions to confirm observability and guard reporting. + +## Definition of done +- Validators deployed and verified in staging/offline environments. +- Runtime guards, CLI/Console workflows, and CI linting all active. +- Observability dashboards and runbooks updated; metrics visible. +- Documentation updates merged; Offline Kit instructions published. +- ./TASKS.md reflects status transitions; cross-module dependencies acknowledged in ../../TASKS.md. + +## Readiness checkpoints (2025-11-25) +- Sprint 110 attestation chain validated: `/internal/attestations/verify` endpoint and evidence bundle tests green (`TestResults/concelier-attestation/web.trx`, `core.trx`). +- Link-Not-Merge cache + console consumption docs frozen (see `operations/lnm-cache-plan.md`, `operations/console-lnm-consumption.md`); cache headers remain deterministic. +- Observation events transport reviewed; backlog guardrails and NATS/air-gap guidance updated in `operations/observation-events.md`. +- Next gating dependency: TaskRunner contract drop (sprint 0157 blockers) before wiring approvals/pack ingest flows into Concelier. diff --git a/docs/modules/concelier/link-not-merge-schema.md b/docs/modules/concelier/link-not-merge-schema.md index fb3376f44..c136a0883 100644 --- a/docs/modules/concelier/link-not-merge-schema.md +++ b/docs/modules/concelier/link-not-merge-schema.md @@ -11,7 +11,7 @@ _Frozen v1 (add-only) — approved 2025-11-17 for CONCELIER-LNM-21-001/002/101._ - Frozen v1 as of 2025-11-17; further schema changes must go through ADR + sprint gating (CONCELIER-LNM-22x+). - Canonical JSON Schemas + signed manifest live in `docs/modules/concelier/schemas/` (advisory observation, linkset, offline bundle). Verify with `openssl dgst -sha256 -verify schema-signing-pub.pem -signature schema.manifest.sig schema.manifest.json`. -## Observation document (Mongo JSON Schema excerpt) +## Observation document (PostgreSQL JSON Schema excerpt) ```json { "bsonType": "object", @@ -152,11 +152,11 @@ When an advisory source publishes a revised version of an advisory: - Deterministic sort: observations sorted by `source, advisoryId, fetchedAt` before hashing. - Conflicts are additive only and now carry optional `sourceIds[]` to trace which upstream sources produced divergent values. -## Indexes (Mongo) +## Indexes (PostgreSQL) - Observations: `{ tenantId:1, source:1, advisoryId:1, provenance.fetchedAt:-1 }` (compound for ingest); `{ provenance.sourceArtifactSha:1 }` unique to avoid dup writes. - Linksets: `{ tenantId:1, advisoryId:1, source:1 }` unique; `{ observations:1 }` sparse for reverse lookups. -## Collections +## Tables - `advisory_observations` — raw per-source docs (immutable). - `advisory_linksets` — derived normalized aggregates with observation pointers and hashes. @@ -170,7 +170,7 @@ See `docs/samples/lnm/observation-ghsa.json` and `docs/samples/lnm/linkset-ghsa. ## Approval path 1) Architecture + Concelier Core review this document. -2) If accepted, freeze JSON Schema and roll into `src/Concelier/__Libraries/StellaOps.Concelier.Storage.Mongo` migrations. +2) If accepted, freeze JSON Schema and roll into `src/Concelier/__Libraries/StellaOps.Concelier.Storage.Postgres` migrations. 3) Update consumers (policy/CLI/export) to read from linksets only; deprecate Merge endpoints. --- diff --git a/docs/modules/devops/AGENTS.md b/docs/modules/devops/AGENTS.md index 3c4b1ae30..f18e436d8 100644 --- a/docs/modules/devops/AGENTS.md +++ b/docs/modules/devops/AGENTS.md @@ -1,14 +1,14 @@ # DevOps agent guide -## Mission -The DevOps module captures release, deployment, and migration playbooks that keep StellaOps deterministic across environments. - -## Advisory Handling -- Any new/updated advisory triggers immediate doc + sprint updates (no approval). -- Update high-level + detailed docs; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link. -- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. -- Check archived advisories; mark supersedes/extends if overlapping. -- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after. +## Mission +The DevOps module captures release, deployment, and migration playbooks that keep StellaOps deterministic across environments. + +## Advisory Handling +- Any new/updated advisory triggers immediate doc + sprint updates (no approval). +- Update high-level + detailed docs; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link. +- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. +- Check archived advisories; mark supersedes/extends if overlapping. +- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after. ## Key docs - [Module README](./README.md) @@ -24,7 +24,7 @@ The DevOps module captures release, deployment, and migration playbooks that kee 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/devops/contracts-and-rules.md b/docs/modules/devops/governance-rules.md similarity index 100% rename from docs/devops/contracts-and-rules.md rename to docs/modules/devops/governance-rules.md diff --git a/docs/modules/devops/migrations/semver-style.md b/docs/modules/devops/migrations/semver-style.md index d79b2aec3..6dffd0ef1 100644 --- a/docs/modules/devops/migrations/semver-style.md +++ b/docs/modules/devops/migrations/semver-style.md @@ -2,6 +2,8 @@ _Last updated: 2025-10-11_ +> **Note (2025-12):** This runbook is obsolete. MongoDB was fully removed in Sprint 4400 and replaced with PostgreSQL. The migration functionality described here was executed during the transition period and is no longer applicable. Retained for historical reference only. + ## Overview The SemVer style migration populates the new `normalizedVersions` field on advisory documents and ensures diff --git a/docs/devops/policy-schema-export.md b/docs/modules/devops/policy-schema-export.md similarity index 100% rename from docs/devops/policy-schema-export.md rename to docs/modules/devops/policy-schema-export.md diff --git a/docs/modules/devops/runbooks/deployment-upgrade.md b/docs/modules/devops/runbooks/deployment-upgrade.md index fe5c67c16..6bdb3a123 100644 --- a/docs/modules/devops/runbooks/deployment-upgrade.md +++ b/docs/modules/devops/runbooks/deployment-upgrade.md @@ -14,7 +14,7 @@ This runbook describes how to promote a new release across the supported deploym | `stable` | `deploy/releases/2025.09-stable.yaml` | `deploy/helm/stellaops/values-stage.yaml`, `deploy/helm/stellaops/values-prod.yaml` | `deploy/compose/docker-compose.stage.yaml`, `deploy/compose/docker-compose.prod.yaml` | | `airgap` | `deploy/releases/2025.09-airgap.yaml` | `deploy/helm/stellaops/values-airgap.yaml` | `deploy/compose/docker-compose.airgap.yaml` | -Infrastructure components (MongoDB, MinIO, RustFS) are pinned in the release manifests and inherited by the deployment profiles. Supporting dependencies such as `nats` remain on upstream LTS tags; review `deploy/compose/*.yaml` for the authoritative set. +Infrastructure components (PostgreSQL, Valkey, MinIO, RustFS) are pinned in the release manifests and inherited by the deployment profiles. Supporting dependencies such as `nats` remain on upstream LTS tags; review `deploy/compose/*.yaml` for the authoritative set. --- @@ -48,8 +48,8 @@ Infrastructure components (MongoDB, MinIO, RustFS) are pinned in the release man ``` Archive the resulting `out/offline-kit/metadata/debug-store.json` alongside the kit bundle. -5. **Review compatibility matrix** - Confirm MongoDB, MinIO, and RustFS versions in the release manifest match platform SLOs. The default targets are `mongo@sha256:c258…`, `minio@sha256:14ce…`, `rustfs:2025.10.0-edge`. +5. **Review compatibility matrix** + Confirm PostgreSQL, Valkey, MinIO, and RustFS versions in the release manifest match platform SLOs. The default targets are `postgres:16-alpine`, `valkey:8.0`, `minio@sha256:14ce…`, `rustfs:2025.10.0-edge`. 6. **Create a rollback bookmark** Record the current Helm revision (`helm history stellaops -n stellaops`) and compose tag (`git describe --tags`) before applying changes. diff --git a/docs/modules/devops/runbooks/launch-cutover.md b/docs/modules/devops/runbooks/launch-cutover.md index 682d16214..1ec9a113e 100644 --- a/docs/modules/devops/runbooks/launch-cutover.md +++ b/docs/modules/devops/runbooks/launch-cutover.md @@ -1,8 +1,10 @@ # Launch Cutover Runbook - Stella Ops -_Document owner: DevOps Guild (2025-10-26)_ +_Document owner: DevOps Guild (2025-10-26)_ _Scope:_ Full-platform launch from staging to production for release `2025.09.2`. +> **Note (2025-12):** This document reflects the state at initial launch. Since then, MongoDB has been fully removed (Sprint 4400) and replaced with PostgreSQL. MinIO references now use RustFS. Redis references now use Valkey. See current deployment docs in `deploy/` for up-to-date configuration. + ## 1. Roles and Communication | Role | Primary | Backup | Contact | diff --git a/docs/modules/excititor/AGENTS.md b/docs/modules/excititor/AGENTS.md index 5f9423544..23484ae39 100644 --- a/docs/modules/excititor/AGENTS.md +++ b/docs/modules/excititor/AGENTS.md @@ -16,7 +16,7 @@ Excititor converts heterogeneous VEX feeds into raw observations and linksets th 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/excititor/README.md b/docs/modules/excititor/README.md index bac5bf4c5..e6d0a9db7 100644 --- a/docs/modules/excititor/README.md +++ b/docs/modules/excititor/README.md @@ -6,17 +6,17 @@ Excititor converts heterogeneous VEX feeds into raw observations and linksets th - Chunk API documentation remains blocked until CI is green and a pinned OpenAPI spec + deterministic samples are available. - Sprint tracker `docs/implplan/SPRINT_0333_0001_0001_docs_modules_excititor.md` and module `TASKS.md` mirror status. - Observability/runbook assets remain in `operations/observability.md` and `observability/` (timeline, locker manifests); dashboards stay offline-import friendly. -- Prior updates (2025-11-05): Link-Not-Merge readiness and consensus beta note (`../../updates/2025-11-05-excitor-consensus-beta.md`), observability guide additions, DSSE packaging guidance, and Policy/CLI follow-ups tracked in SPRINT_200. -- Link-Not-Merge readiness: release note [Excitor consensus beta](../../updates/2025-11-05-excitor-consensus-beta.md) captures how Excititor feeds power the Excititor consensus beta (sample payload in [consensus JSON](../../vex/consensus-json.md)). +- Prior updates (2025-11-05): Link-Not-Merge readiness and consensus beta note (`../../implplan/archived/updates/2025-11-05-excitor-consensus-beta.md`), observability guide additions, DSSE packaging guidance, and Policy/CLI follow-ups tracked in SPRINT_200. +- Link-Not-Merge readiness: release note [Excitor consensus beta](../../implplan/archived/updates/2025-11-05-excitor-consensus-beta.md) captures how Excititor feeds power the Excititor consensus beta (sample payload in [consensus JSON](../../vex/consensus-json.md)). - Added [observability guide](operations/observability.md) describing the evidence metrics emitted by `EXCITITOR-AIAI-31-003` (request counters, statement histogram, signature status, guard violations) so Ops/Lens can alert on misuse. - README now points policy/UI teams to the upcoming consensus integration work. -- DSSE packaging for consensus bundles and Export Center hooks are documented in the [beta release note](../../updates/2025-11-05-excitor-consensus-beta.md); operators mirroring Excititor exports must verify detached JWS artefacts (`bundle.json.jws`) alongside each bundle. +- DSSE packaging for consensus bundles and Export Center hooks are documented in the [beta release note](../../implplan/archived/updates/2025-11-05-excitor-consensus-beta.md); operators mirroring Excititor exports must verify detached JWS artefacts (`bundle.json.jws`) alongside each bundle. - Follow-ups called out in the release note (Policy weighting knobs `POLICY-ENGINE-30-101`, CLI verb `CLI-VEX-30-002`) remain in-flight and are tracked in `/docs/implplan/SPRINT_200_documentation_process.md`. ## Release references - Consensus beta payload reference: [docs/vex/consensus-json.md](../../vex/consensus-json.md) - Export Center offline packaging: [docs/modules/export-center/devportal-offline.md](../export-center/devportal-offline.md) -- Historical release log: [docs/updates/](../../updates/) +- Historical release log: [docs/implplan/archived/updates/](../../implplan/archived/updates/) ## Responsibilities - Fetch OpenVEX/CSAF/CycloneDX statements via restart-only connectors. diff --git a/docs/modules/excititor/schemas/vex_raw.schema.json b/docs/modules/excititor/schemas/vex_raw.schema.json index 6a308ca1a..eba618cae 100644 --- a/docs/modules/excititor/schemas/vex_raw.schema.json +++ b/docs/modules/excititor/schemas/vex_raw.schema.json @@ -2,6 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://stellaops.dev/schemas/excititor/vex_raw.schema.json", "title": "Excititor VEX Raw Document", + "$comment": "Note (2025-12): The gridFsObjectId field is legacy. Since Sprint 4400, all large content is stored in PostgreSQL with RustFS. This field exists only for backward compatibility with migrated data.", "type": "object", "additionalProperties": true, "required": ["_id", "providerId", "format", "sourceUri", "retrievedAt", "digest"], diff --git a/docs/modules/excititor/vex_observations.md b/docs/modules/excititor/vex_observations.md index 5752c7d68..47b00f8b4 100644 --- a/docs/modules/excititor/vex_observations.md +++ b/docs/modules/excititor/vex_observations.md @@ -1,6 +1,6 @@ # VEX Observation Model (`vex_observations`) -> Authored 2025-11-14 for Sprint 120 (`EXCITITOR-LNM-21-001`). This document is the canonical schema description for Excititor’s immutable observation records. It unblocks downstream documentation tasks (`DOCS-LNM-22-002`) and aligns the WebService/Worker data structures with Mongo persistence. +> Authored 2025-11-14 for Sprint 120 (`EXCITITOR-LNM-21-001`). This document is the canonical schema description for Excititor's immutable observation records. It unblocks downstream documentation tasks (`DOCS-LNM-22-002`) and aligns the WebService/Worker data structures with PostgreSQL persistence. Excititor ingests heterogeneous VEX statements, normalizes them under the Aggregation-Only Contract (AOC), and persists each normalized statement as a **VEX observation**. These observations are the source of truth for: @@ -15,7 +15,7 @@ All observation documents are immutable. New information creates a new observati | Aspect | Value | | --- | --- | -| Collection | `vex_observations` (Mongo) | +| Table | `vex_observations` (PostgreSQL) | | Upstream generator | `VexObservationProjectionService` (WebService) and Worker normalization pipeline | | Primary key | `{tenant, observationId}` | | Required indexes | `{tenant, vulnerabilityId}`, `{tenant, productKey}`, `{tenant, document.digest}`, `{tenant, providerId, status}` | @@ -114,7 +114,7 @@ All observation documents are immutable. New information creates a new observati 2. **Sorted collections** – arrays (`anchors`, `purls`, `cpes`) are sorted lexicographically before persistence. 3. **Guard metadata** – `aoc.guardVersion` records the guard library version (`docs/aoc/guard-library.md`), enabling audits. 4. **Signatures** – only verification metadata proven by the Worker is stored; WebService never recomputes trust. -5. **Time normalization** – all timestamps stored as UTC ISO-8601 strings (Mongo `DateTime`). +5. **Time normalization** – all timestamps stored as UTC ISO-8601 strings (PostgreSQL `timestamptz`). ## API mapping diff --git a/docs/modules/export-center/AGENTS.md b/docs/modules/export-center/AGENTS.md index 7bd3e3045..14867773c 100644 --- a/docs/modules/export-center/AGENTS.md +++ b/docs/modules/export-center/AGENTS.md @@ -17,7 +17,7 @@ Export Center packages reproducible evidence bundles (JSON, Trivy DB, mirror) wi 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/export-center/api.md b/docs/modules/export-center/api.md index defaf84db..8180401e5 100644 --- a/docs/modules/export-center/api.md +++ b/docs/modules/export-center/api.md @@ -16,8 +16,8 @@ This reference describes the Export Center API introduced in Export Center Phase - `export:download` for bundle downloads and manifests. - **Tenant context:** Provide `X-Stella-Tenant` when the token carries multiple tenants; defaults to token tenant otherwise. - **Idempotency:** Mutating endpoints accept `Idempotency-Key` (UUID). Retrying with the same key returns the original result. -- **Rate limits and quotas:** Responses include `X-Stella-Quota-Limit`, `X-Stella-Quota-Remaining`, and `X-Stella-Quota-Reset`. Exceeding quotas returns `429 Too Many Requests` with `ERR_EXPORT_QUOTA`. -- **Integrity headers (downloads):** `Digest: sha-256=`, `X-Stella-Signature: dsse-b64=`, and `X-Stella-Immutability: true` accompany bundle/manifest downloads; clients must validate before use. +- **Rate limits and quotas:** Responses include `X-Stella-Quota-Limit`, `X-Stella-Quota-Remaining`, and `X-Stella-Quota-Reset`. Exceeding quotas returns `429 Too Many Requests` with `ERR_EXPORT_QUOTA`. +- **Integrity headers (downloads):** `Digest: sha-256=`, `X-Stella-Signature: dsse-b64=`, and `X-Stella-Immutability: true` accompany bundle/manifest downloads; clients must validate before use. - **Content negotiation:** Requests and responses use `application/json; charset=utf-8` unless otherwise stated. Downloads stream binary content with profile-specific media types. - **SSE:** Event streams set `Content-Type: text/event-stream` and keep connections alive with comment heartbeats every 15 seconds. @@ -101,29 +101,29 @@ Scopes: export:profile:manage **Request** ```json -{ - "profileId": "prof-airgap-mirror", - "name": "Airgap Mirror Weekly", - "kind": "mirror", - "variant": "full", - "include": ["advisories", "vex", "sboms", "policy"], - "distribution": ["http", "object"], - "encryption": { - "enabled": true, - "recipientKeys": ["age1tenantkey..."], - "strict": false - }, - "retention": {"mode": "days", "value": 30}, - "limits": { - "maxActiveRuns": 4, - "maxQueuedRuns": 50, - "backpressureMode": "reject" - }, - "approval": { - "required": false - } -} -``` +{ + "profileId": "prof-airgap-mirror", + "name": "Airgap Mirror Weekly", + "kind": "mirror", + "variant": "full", + "include": ["advisories", "vex", "sboms", "policy"], + "distribution": ["http", "object"], + "encryption": { + "enabled": true, + "recipientKeys": ["age1tenantkey..."], + "strict": false + }, + "retention": {"mode": "days", "value": 30}, + "limits": { + "maxActiveRuns": 4, + "maxQueuedRuns": 50, + "backpressureMode": "reject" + }, + "approval": { + "required": false + } +} +``` **Response 201** @@ -192,24 +192,24 @@ Scopes: export:run { "runId": "run-20251029-01", "status": "pending", - "profileId": "prof-json-raw", - "createdAt": "2025-10-29T12:12:11Z", - "createdBy": "user:ops", - "selectors": { "...": "..." }, - "links": { - "self": "/api/export/runs/run-20251029-01", - "events": "/api/export/runs/run-20251029-01/events" - }, - "quotas": { - "maxActiveRuns": 4, - "maxQueuedRuns": 50, - "backpressureMode": "reject" - }, - "approval": { - "required": false - } -} -``` + "profileId": "prof-json-raw", + "createdAt": "2025-10-29T12:12:11Z", + "createdBy": "user:ops", + "selectors": { "...": "..." }, + "links": { + "self": "/api/export/runs/run-20251029-01", + "events": "/api/export/runs/run-20251029-01/events" + }, + "quotas": { + "maxActiveRuns": 4, + "maxQueuedRuns": 50, + "backpressureMode": "reject" + }, + "approval": { + "required": false + } +} +``` ### 4.2 List runs @@ -231,15 +231,15 @@ Response fields: | Field | Description | |-------|-------------| -| `status` | `pending`, `running`, `success`, `failed`, `canceled`. | -| `progress` | Object with `adapters`, `bytesWritten`, `recordsProcessed`. | -| `errorCode` | Populated when `status=failed` (`signing`, `distribution`, etc). | -| `policySnapshotId` | Returned for policy-aware profiles. | -| `distributions` | List of available distribution descriptors (type, location, sha256, expiresAt). | -| `rerunHash` | SHA-256 over sorted `contents[*].digest`; used for determinism checks. | -| `integrity` | Expected HTTP headers (`Digest`, `X-Stella-Signature`, `X-Stella-Immutability`) and OCI annotations (`io.stellaops.export.*`). | -| `quotas` | Active limits/backpressure settings returned with the run. | -| `approval` | Cross-tenant approval ticket when selectors span multiple tenants/wildcards. | +| `status` | `pending`, `running`, `success`, `failed`, `canceled`. | +| `progress` | Object with `adapters`, `bytesWritten`, `recordsProcessed`. | +| `errorCode` | Populated when `status=failed` (`signing`, `distribution`, etc). | +| `policySnapshotId` | Returned for policy-aware profiles. | +| `distributions` | List of available distribution descriptors (type, location, sha256, expiresAt). | +| `rerunHash` | SHA-256 over sorted `contents[*].digest`; used for determinism checks. | +| `integrity` | Expected HTTP headers (`Digest`, `X-Stella-Signature`, `X-Stella-Immutability`) and OCI annotations (`io.stellaops.export.*`). | +| `quotas` | Active limits/backpressure settings returned with the run. | +| `approval` | Cross-tenant approval ticket when selectors span multiple tenants/wildcards. | ### 4.4 Cancel a run @@ -294,16 +294,16 @@ GET /api/export/runs/{runId}/download Scopes: export:download ``` -Streams the primary bundle (tarball, zip, or profile-specific layout). Headers: - -- `Content-Disposition: attachment; filename="export-run-20251029-01.tar.zst"` -- `Digest: sha-256=` (EC5) -- `X-Stella-Signature: dsse-b64:` (EC3/EC5) -- `X-Stella-Immutability: true` -- `X-Export-Size: 73482019` -- `X-Export-Encryption: age` (when mirror encryption enabled) - -Supports HTTP range requests for resume functionality. If no bundle exists yet, responds `409` with `ERR_EXPORT_007`. +Streams the primary bundle (tarball, zip, or profile-specific layout). Headers: + +- `Content-Disposition: attachment; filename="export-run-20251029-01.tar.zst"` +- `Digest: sha-256=` (EC5) +- `X-Stella-Signature: dsse-b64:` (EC3/EC5) +- `X-Stella-Immutability: true` +- `X-Export-Size: 73482019` +- `X-Export-Encryption: age` (when mirror encryption enabled) + +Supports HTTP range requests for resume functionality. If no bundle exists yet, responds `409` with `ERR_EXPORT_007`. ### 6.2 Manifest download @@ -312,8 +312,8 @@ GET /api/export/runs/{runId}/manifest Scopes: export:download ``` -Returns signed `export.json`. To fetch the detached signature, append `?signature=true`. -- Integrity annotations are mirrored in response headers (`Digest`, `X-Stella-Signature`, `X-Stella-Immutability`) and in the manifest `integrity` block to keep rerun-hash deterministic. +Returns signed `export.json`. To fetch the detached signature, append `?signature=true`. +- Integrity annotations are mirrored in response headers (`Digest`, `X-Stella-Signature`, `X-Stella-Immutability`) and in the manifest `integrity` block to keep rerun-hash deterministic. ### 6.3 Provenance download @@ -322,7 +322,7 @@ GET /api/export/runs/{runId}/provenance Scopes: export:download ``` -Returns signed `provenance.json`. Supports `?signature=true`. Provenance includes attestation subject digests, policy snapshot ids, adapter versions, and KMS key identifiers. +Returns signed `provenance.json`. Supports `?signature=true`. Provenance includes attestation subject digests, policy snapshot ids, adapter versions, and KMS key identifiers. ### 6.4 Distribution descriptors @@ -356,6 +356,6 @@ Payload includes `targetUrl`, `events` (e.g., `run.succeeded`), and optional sec - [Export Center Architecture](architecture.md) - [Export Center Profiles](profiles.md) - [Export Center CLI Guide](cli.md) *(companion document)* -- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../../aoc/aggregation-only-contract.md) > **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied. diff --git a/docs/modules/export-center/cli.md b/docs/modules/export-center/cli.md index a0d7bb961..724bc2ba8 100644 --- a/docs/modules/export-center/cli.md +++ b/docs/modules/export-center/cli.md @@ -144,20 +144,20 @@ stella export provenance run-20251029-01 --output manifests/provenance.json Retrieves the signed provenance file. `--signature` behaves like the manifest command. -### 4.4 `stella export verify` - -``` -stella export verify run-20251029-01 \ - --manifest manifests/export.json \ - --provenance manifests/provenance.json \ - --key keys/acme-export.pub -``` - -Wrapper around `cosign verify`. Returns exit `0` when signatures and digests validate. Exit `20` when verification fails. - -Integrity and determinism checks (EC1–EC10): -- `stella export manifest` and `provenance` commands emit `Digest`/`X-Stella-Signature` headers; cache them for rerun-hash validation. -- Offline kits: run `docs/modules/export-center/operations/verify-export-kit.sh ` to assert rerunHash, integrity headers vs OCI annotations, quotas/backpressure block, approvals, and log metadata in provenance. +### 4.4 `stella export verify` + +``` +stella export verify run-20251029-01 \ + --manifest manifests/export.json \ + --provenance manifests/provenance.json \ + --key keys/acme-export.pub +``` + +Wrapper around `cosign verify`. Returns exit `0` when signatures and digests validate. Exit `20` when verification fails. + +Integrity and determinism checks (EC1–EC10): +- `stella export manifest` and `provenance` commands emit `Digest`/`X-Stella-Signature` headers; cache them for rerun-hash validation. +- Offline kits: run `docs/modules/export-center/operations/verify-export-kit.sh ` to assert rerunHash, integrity headers vs OCI annotations, quotas/backpressure block, approvals, and log metadata in provenance. ## 5. CI recipe (GitHub Actions example) @@ -230,6 +230,6 @@ Exit codes above 100 are reserved for future profile-specific tooling. - [Export Center Profiles](profiles.md) - [Export Center API reference](api.md) - [Export Center Architecture](architecture.md) -- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../../aoc/aggregation-only-contract.md) > **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied. diff --git a/docs/modules/export-center/mirror-bundles.md b/docs/modules/export-center/mirror-bundles.md index 707d9404f..b3a3454ae 100644 --- a/docs/modules/export-center/mirror-bundles.md +++ b/docs/modules/export-center/mirror-bundles.md @@ -92,11 +92,11 @@ delta/ manifest.diff.json # summary of counts, hashes, base export metadata ``` -- **Base lookup:** The worker verifies that the base export is reachable (download path or OCI reference). If missing, the run fails with `ERR_EXPORT_BASE_MISSING`. -- **Change detection:** Uses deterministic hashing of normalized records to compute additions/updates. Indexes are regenerated only for affected subjects. -- **Application order:** Consumers apply deltas sequentially. A `resetBaseline=true` flag instructs them to drop cached state and apply the bundle as a full refresh. -- **Tombstones required:** Every removal must emit a tombstone entry plus the `removed` list; deltas without tombstones fail verification (`verify-export-kit.sh`). -- **Integrity headers:** Each delta bundle exports `Digest`, `X-Stella-Signature`, and `X-Stella-Immutability` derived from the OCI annotation `io.stellaops.export.manifest-digest`. Consumers must validate before applying. +- **Base lookup:** The worker verifies that the base export is reachable (download path or OCI reference). If missing, the run fails with `ERR_EXPORT_BASE_MISSING`. +- **Change detection:** Uses deterministic hashing of normalized records to compute additions/updates. Indexes are regenerated only for affected subjects. +- **Application order:** Consumers apply deltas sequentially. A `resetBaseline=true` flag instructs them to drop cached state and apply the bundle as a full refresh. +- **Tombstones required:** Every removal must emit a tombstone entry plus the `removed` list; deltas without tombstones fail verification (`verify-export-kit.sh`). +- **Integrity headers:** Each delta bundle exports `Digest`, `X-Stella-Signature`, and `X-Stella-Immutability` derived from the OCI annotation `io.stellaops.export.manifest-digest`. Consumers must validate before applying. Example `manifest.diff.json` (delta): @@ -182,40 +182,40 @@ sequenceDiagram 3. Re-run integrity checks (`mirror verify `). - **Audit logging:** Export Center logs `mirror.bundle.created`, `mirror.delta.applied`, and `mirror.encryption.enabled` events. Consume them in the central observability pipeline. -## 7. Validation checklist (Trivy / mirror bundles) - -- Download and verify: - - `stella export download --format mirror` - - `stella export verify ` -- Delta ordering: - - Ensure `manifest.diff.json.baseExportId` exists locally before applying delta. - - Track applied order in `appliedExportIds.log`. -- Trivy adapter (if enabled): - - `stella export trivy-validate --bundle mirror-YYYYMMDD.tar.zst --policy ./policies/export-center.rego` -- Dry-run import: - - `stella export mirror-validate --bundle mirror-YYYYMMDD.tar.zst --dry-run` -- Post-import checks: - - Recompute SHA256 for `manifest.yaml` and a sample data file; compare to manifest. - - Run `mirror verify` (Offline Kit) and confirm zero mismatches. - - Confirm OCI annotations `io.stellaops.export.profile/run/manifest-digest/provenance-ref` match the bundle being applied. - -## 8. Troubleshooting - -| Symptom | Meaning | Action | -|---------|---------|--------| -| `ERR_EXPORT_BASE_MISSING` | Base export not available | Republish base bundle or rebuild as full export. | -| Delta applies but mirror misses entries | Deltas applied out of order | Rebuild from last full bundle and reapply in sequence. | +## 7. Validation checklist (Trivy / mirror bundles) + +- Download and verify: + - `stella export download --format mirror` + - `stella export verify ` +- Delta ordering: + - Ensure `manifest.diff.json.baseExportId` exists locally before applying delta. + - Track applied order in `appliedExportIds.log`. +- Trivy adapter (if enabled): + - `stella export trivy-validate --bundle mirror-YYYYMMDD.tar.zst --policy ./policies/export-center.rego` +- Dry-run import: + - `stella export mirror-validate --bundle mirror-YYYYMMDD.tar.zst --dry-run` +- Post-import checks: + - Recompute SHA256 for `manifest.yaml` and a sample data file; compare to manifest. + - Run `mirror verify` (Offline Kit) and confirm zero mismatches. + - Confirm OCI annotations `io.stellaops.export.profile/run/manifest-digest/provenance-ref` match the bundle being applied. + +## 8. Troubleshooting + +| Symptom | Meaning | Action | +|---------|---------|--------| +| `ERR_EXPORT_BASE_MISSING` | Base export not available | Republish base bundle or rebuild as full export. | +| Delta applies but mirror misses entries | Deltas applied out of order | Rebuild from last full bundle and reapply in sequence. | | Decryption fails | Recipient key mismatch or corrupted bundle | Confirm key distribution and re-download bundle. | -| Verification errors | Signature mismatch | Do not import; regenerate bundle and investigate signing pipeline. | -| Manifest hash mismatch | Files changed after extraction | Re-extract bundle and re-run verification; check storage tampering. | - -## 9. References - -- [Export Center Overview](overview.md) -- [Export Center Architecture](architecture.md) -- [Export Center API reference](api.md) -- [Export Center CLI Guide](cli.md) +| Verification errors | Signature mismatch | Do not import; regenerate bundle and investigate signing pipeline. | +| Manifest hash mismatch | Files changed after extraction | Re-extract bundle and re-run verification; check storage tampering. | + +## 9. References + +- [Export Center Overview](overview.md) +- [Export Center Architecture](architecture.md) +- [Export Center API reference](api.md) +- [Export Center CLI Guide](cli.md) - [Concelier mirror runbook](../concelier/operations/mirror.md) -- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../../aoc/aggregation-only-contract.md) > **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied. diff --git a/docs/modules/export-center/operations/runbook.md b/docs/modules/export-center/operations/runbook.md index b31a56851..2c504d0a1 100644 --- a/docs/modules/export-center/operations/runbook.md +++ b/docs/modules/export-center/operations/runbook.md @@ -11,17 +11,17 @@ The Export Center packages StellaOps evidence and policy overlays into reproduci - Runbook execution for recovery, retention, and compliance. - Coordination with DevOps validation (cosign + `trivy module db import` smoke tests). -Related documentation: - -- `docs/modules/export-center/overview.md` -- `docs/modules/export-center/architecture.md` -- `docs/modules/export-center/profiles.md` -- `docs/modules/export-center/trivy-adapter.md` -- `docs/modules/export-center/mirror-bundles.md` -- `docs/modules/export-center/api.md` -- `docs/modules/export-center/cli.md` -- `docs/modules/export-center/operations/kms-envelope-pattern.md` -- `docs/modules/export-center/operations/risk-bundle-provider-matrix.md` +Related documentation: + +- `docs/modules/export-center/overview.md` +- `docs/modules/export-center/architecture.md` +- `docs/modules/export-center/profiles.md` +- `docs/modules/export-center/trivy-adapter.md` +- `docs/modules/export-center/mirror-bundles.md` +- `docs/modules/export-center/api.md` +- `docs/modules/export-center/cli.md` +- `docs/modules/export-center/operations/kms-envelope-pattern.md` +- `docs/modules/export-center/operations/risk-bundle-provider-matrix.md` ## 2. Contacts & tooling @@ -199,7 +199,7 @@ If encryption enabled, decrypt using age or AES key before verification. - `docs/modules/export-center/trivy-adapter.md` - `docs/modules/export-center/mirror-bundles.md` - `ops/devops/TASKS.md` (`DEVOPS-EXPORT-36-001`, `DEVOPS-EXPORT-37-001`) -- `docs/ingestion/aggregation-only-contract.md` +- `docs/aoc/aggregation-only-contract.md` - `docs/24_OFFLINE_KIT.md` > **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied. diff --git a/docs/modules/export-center/overview.md b/docs/modules/export-center/overview.md index c20fd4910..c9fbb5256 100644 --- a/docs/modules/export-center/overview.md +++ b/docs/modules/export-center/overview.md @@ -33,7 +33,7 @@ Refer to `docs/modules/export-center/architecture.md` (Sprint 35 task) for compo - **Signing and encryption.** Manifests and payloads are signed using the platform KMS. Mirror profiles support optional in-bundle encryption (age/AES-GCM) with key wrapping. - **Determinism.** Identical inputs yield identical bundles. Timestamps serialize in UTC ISO-8601; manifests include content hashes for audit replay. -See `docs/security/policy-governance.md` and `docs/ingestion/aggregation-only-contract.md` for broader guardrail context. +See `docs/security/policy-governance.md` and `docs/aoc/aggregation-only-contract.md` for broader guardrail context. ## Operating it offline - **Offline Kit integration.** Air-gapped deployments receive pre-built export profiles and object storage layout templates through the Offline Kit bundles. diff --git a/docs/modules/graph/AGENTS.md b/docs/modules/graph/AGENTS.md index 1876052bc..e0253c408 100644 --- a/docs/modules/graph/AGENTS.md +++ b/docs/modules/graph/AGENTS.md @@ -23,7 +23,7 @@ Graph module (upcoming) will power graph-indexed queries for SBOM relationships, 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/notify/AGENTS.md b/docs/modules/notify/AGENTS.md index d72b1b61e..aad7692c9 100644 --- a/docs/modules/notify/AGENTS.md +++ b/docs/modules/notify/AGENTS.md @@ -17,7 +17,7 @@ Notify evaluates operator-defined rules against platform events and dispatches c 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/notify/README.md b/docs/modules/notify/README.md index 4890e9ac3..d7cefbb71 100644 --- a/docs/modules/notify/README.md +++ b/docs/modules/notify/README.md @@ -28,25 +28,25 @@ Notify (Notifications Studio) converts platform events into tenant-scoped alerts Status for these items is tracked in `src/Notifier/StellaOps.Notifier/TASKS.md` and sprint plans; update this README once tasks merge. ## Key docs & release alignment -- [`docs/notifications/overview.md`](../../notifications/overview.md) — summary of capabilities, imposed rules, and customer journey. -- [`docs/notifications/architecture.md`](../../notifications/architecture.md) — Notifications Studio runtime view (published 2025-10-29). -- [`docs/notifications/rules.md`](../../notifications/rules.md) — declarative matcher syntax and evaluation order. -- [`docs/notifications/digests.md`](../../notifications/digests.md) — digest windows, coalescing logic, and delivery samples. -- [`docs/notifications/templates.md`](../../notifications/templates.md) — template helpers, localisation, and redaction guidelines. -- [`docs/updates/2025-10-29-notify-docs.md`](../../updates/2025-10-29-notify-docs.md) — latest release note; follow-ups remain to validate connector metadata, quiet-hours semantics, and simulation payloads once Sprint 39 drops land. +- [`overview.md`](overview.md) — summary of capabilities, imposed rules, and customer journey. +- [`architecture.md`](architecture.md) / [`architecture-detail.md`](architecture-detail.md) — Notifications Studio runtime view. +- [`rules.md`](rules.md) — declarative matcher syntax and evaluation order. +- [`digests.md`](digests.md) — digest windows, coalescing logic, and delivery samples. +- [`templates.md`](templates.md) — template helpers, localisation, and redaction guidelines. +- [`docs/implplan/archived/updates/2025-10-29-notify-docs.md`](../../implplan/archived/updates/2025-10-29-notify-docs.md) — latest release note; follow-ups remain to validate connector metadata, quiet-hours semantics, and simulation payloads once Sprint 39 drops land. ## Integrations & dependencies - **Storage:** PostgreSQL (schema `notify`) for rules, channels, deliveries, digests, and throttles; Valkey for worker coordination. - **Queues:** Valkey Streams or NATS JetStream for ingestion, throttling, and DLQs (`notify.dlq`). - **Authority:** OpTok-protected APIs, DPoP-backed CLI/UI scopes (`notify.viewer`, `notify.operator`, `notify.admin`), and secret references for channel credentials. -- **Observability:** Prometheus metrics (`notify.sent_total`, `notify.failed_total`, `notify.digest_coalesced_total`, etc.), OTEL traces, and dashboards documented in `docs/notifications/architecture.md#12-observability-prometheus--otel`. +- **Observability:** Prometheus metrics (`notify.sent_total`, `notify.failed_total`, `notify.digest_coalesced_total`, etc.), OTEL traces, and dashboards documented in `architecture-detail.md`. ## Operational notes - Schema fixtures live in `./resources/schemas`; event and delivery samples live in `./resources/samples` for contract tests and UI mocks. - Offline Kit bundles ship plug-ins, default templates, and seed rules; update manifests under `ops/offline-kit/` when connectors change. - Dashboards and alert references depend on `DEVOPS-NOTIFY-39-002`; coordinate before renaming metrics or labels. - Observability assets: `operations/observability.md` and `operations/dashboards/notify-observability.json` (offline import). -- When releasing new rule or connector features, mirror guidance into `docs/notifications/*.md` and checklists in `docs/updates/2025-10-29-notify-docs.md` until the follow-ups are closed. +- When releasing new rule or connector features, update guidance in this directory and related checklists until the follow-ups are closed. ## Epic alignment - **Epic 11 – Notifications Studio:** notifications workspace, preview tooling, immutable delivery ledger, throttling/digest controls, and forthcoming correlation/simulation features. diff --git a/docs/notifications/api.md b/docs/modules/notify/api.md similarity index 94% rename from docs/notifications/api.md rename to docs/modules/notify/api.md index 3f451599c..a6bc58f0e 100644 --- a/docs/notifications/api.md +++ b/docs/modules/notify/api.md @@ -7,7 +7,7 @@ Last updated: 2025-11-25 (Docs Tasks Md.V · DOCS-NOTIFY-40-001) All endpoints require `Authorization: Bearer ` and `X-Stella-Tenant` header. Responses use the common error envelope (`docs/api/overview.md`). Paths are rooted at `/api/v1/notify`. ## Channels -- `POST /channels` — create channel. Body matches `notifications/channels.md` schema. Returns `201` + channel. +- `POST /channels` — create channel. Body matches `channels.md` schema. Returns `201` + channel. - `GET /channels` — list channels (deterministic order: type ASC, id ASC). Supports `type` filter. - `GET /channels/{id}` — fetch single channel. - `DELETE /channels/{id}` — soft-delete; fails if referenced by active rules unless `force=true` query. @@ -18,7 +18,7 @@ All endpoints require `Authorization: Bearer ` and `X-Stella-Tenant` head - `POST /rules:preview` — dry-run rule against sample event; returns matched actions and rendered templates. ## Policies & escalations -- `POST /policies/escalations` — create escalation policy (see `notifications/escalations.md`). +- `POST /policies/escalations` — create escalation policy (see `escalations.md`). - `GET /policies/escalations` — list policies. ## Deliveries & digests diff --git a/docs/notifications/architecture.md b/docs/modules/notify/architecture-detail.md similarity index 96% rename from docs/notifications/architecture.md rename to docs/modules/notify/architecture-detail.md index c4805a395..6cf4ddd39 100644 --- a/docs/notifications/architecture.md +++ b/docs/modules/notify/architecture-detail.md @@ -63,7 +63,7 @@ Failures during evaluation are logged with correlation IDs and surfaced through ## 3. Rendering & connectors - **Template resolution.** The renderer picks the template in this order: action template → channel default template → locale fallback → built-in minimal template. Locale negotiation reduces `en-US` to `en-us`. -- **Helpers & partials.** Exposed helpers mirror the list in [`notifications/templates.md`](templates.md#3-variables-helpers-and-context). Plug-ins may register additional helpers but must remain deterministic and side-effect free. +- **Helpers & partials.** Exposed helpers mirror the list in [`templates.md`](templates.md#3-variables-helpers-and-context). Plug-ins may register additional helpers but must remain deterministic and side-effect free. - **Attestation lifecycle suite.** Sprint 171 introduced dedicated `tmpl-attest-*` templates for verification failures, expiring attestations, key rotations, and transparency anomalies (see [`templates.md` §7](templates.md#7-attestation--signing-lifecycle-templates-notify-attest-74-001)). Rule actions referencing those templates must populate the attestation context fields so channels stay consistent online/offline. - **Rendering output.** `NotifyDeliveryRendered` captures: - `channelType`, `format`, `locale` diff --git a/docs/notifications/channels.md b/docs/modules/notify/channels.md similarity index 100% rename from docs/notifications/channels.md rename to docs/modules/notify/channels.md diff --git a/docs/notifications/digests.md b/docs/modules/notify/digests.md similarity index 100% rename from docs/notifications/digests.md rename to docs/modules/notify/digests.md diff --git a/docs/notifications/escalations.md b/docs/modules/notify/escalations.md similarity index 100% rename from docs/notifications/escalations.md rename to docs/modules/notify/escalations.md diff --git a/docs/notifications/fixtures/redaction/sample.json b/docs/modules/notify/fixtures/redaction/sample.json similarity index 100% rename from docs/notifications/fixtures/redaction/sample.json rename to docs/modules/notify/fixtures/redaction/sample.json diff --git a/docs/notifications/fixtures/rendering/index.ndjson b/docs/modules/notify/fixtures/rendering/index.ndjson similarity index 100% rename from docs/notifications/fixtures/rendering/index.ndjson rename to docs/modules/notify/fixtures/rendering/index.ndjson diff --git a/docs/notifications/fixtures/rendering/tmpl-incident-start.email.en-US.json b/docs/modules/notify/fixtures/rendering/tmpl-incident-start.email.en-US.json similarity index 100% rename from docs/notifications/fixtures/rendering/tmpl-incident-start.email.en-US.json rename to docs/modules/notify/fixtures/rendering/tmpl-incident-start.email.en-US.json diff --git a/docs/notifications/fixtures/traces/sample-trace.json b/docs/modules/notify/fixtures/traces/sample-trace.json similarity index 100% rename from docs/notifications/fixtures/traces/sample-trace.json rename to docs/modules/notify/fixtures/traces/sample-trace.json diff --git a/docs/notifications/gaps-nr1-nr10.md b/docs/modules/notify/gaps-nr1-nr10.md similarity index 58% rename from docs/notifications/gaps-nr1-nr10.md rename to docs/modules/notify/gaps-nr1-nr10.md index af0d68533..d0f25f370 100644 --- a/docs/notifications/gaps-nr1-nr10.md +++ b/docs/modules/notify/gaps-nr1-nr10.md @@ -7,22 +7,22 @@ Close NR1–NR10 by defining contracts, evidence, and deterministic test hooks f | ID | Requirement | Evidence to publish | Deterministic tests/fixtures | | --- | --- | --- | --- | -| NR1 | Versioned JSON Schemas for event envelopes, rules, templates, channels, receipts, and webhooks; DSSE-signed catalog with canonical hash recipe (BLAKE3-256 over normalized JSON). | `docs/notifications/schemas/notify-schemas-catalog.json` + `.dsse.json`; `docs/notifications/schemas/inputs.lock` capturing digests and canonicalization flags. | Golden canonicalization harness under `tests/notifications/Schemas/SchemaCanonicalizationTests.cs` using frozen inputs + hash assertions. | -| NR2 | Tenant scoping + approvals for high-impact rules (escalations, PII, cross-tenant fan-out). Every API and receipt carries `tenant_id`; RBAC/approvals enforced. | RBAC/approval matrix (`docs/notifications/security/tenant-approvals.md`) listing actions × roles × required approvals. | API contract tests in `StellaOps.Notifier.Tests/TenantScopeTests.cs` plus integration fixtures with mixed-tenant payloads (should reject). | -| NR3 | Deterministic rendering/localization: stable merge-field ordering, UTC ISO-8601 timestamps, locale whitelist, hashed previews recorded in ledger. | Rendering fixture pack `docs/notifications/fixtures/rendering/*.json`; hash ledger samples `docs/notifications/fixtures/rendering/index.ndjson` with BLAKE3 digests. | `StellaOps.Notifier.Tests/RenderingDeterminismTests.cs` compares golden bodies/subjects across locales/timezones; seeds fixed RNG/time. | -| NR4 | Quotas/backpressure/DLQ: per-tenant/channel quotas, burst budgets, enqueue gating, DLQ schema with redrive + idempotent keys; metrics/alerts for backlog/DLQ growth. | Quota policy `docs/notifications/operations/quotas.md`; DLQ schema `docs/notifications/schemas/dlq-notify.schema.json`. | Worker tests `StellaOps.Notifier.Tests/BackpressureAndDlqTests.cs` validating quota enforcement, DLQ insertion, redrive idempotency. | -| NR5 | Retry & idempotency: canonical `delivery_id` (UUIDv7) + dedupe key (event×rule×channel); bounded exponential backoff with jitter; idempotent connectors; ignore out-of-order acks. | Retry matrix `docs/notifications/operations/retries.md`; connector idempotency checklist. | `StellaOps.Notifier.Tests/RetryPolicyTests.cs` + connector harness fixtures demonstrating dedupe across duplicate events. | -| NR6 | Webhook/ack security: HMAC or mTLS/DPoP required; signed ack URLs/tokens with nonce, expiry, audience, single-use; per-tenant allowlists for domains/paths. | Security policy `docs/notifications/security/webhook-ack-hardening.md`; sample signed-ack token format + validation steps. | Negative-path tests `StellaOps.Notifier.Tests/WebhookSecurityTests.cs` covering wrong HMAC, replayed nonce, expired token, disallowed domain. | -| NR7 | Redaction & PII limits: classify template fields; redact secrets/PII in storage/logs; hash sensitive values; size/field allowlists; previews/logs default to redacted variant. | Redaction catalog `docs/notifications/security/redaction-catalog.md`; sample redacted payloads `docs/notifications/fixtures/redaction/*.json`. | `StellaOps.Notifier.Tests/RedactionTests.cs` asserting stored/preview payloads match redacted expectations. | -| NR8 | Observability SLO alerts: SLOs for delivery latency/success/backlog/DLQ age; standard metrics names; dashboards/alerts/runbooks; traces include tenant/rule/channel IDs with sampling rules. | Dashboard JSON `docs/notifications/operations/dashboards/notify-slo.json`; alert rules `docs/notifications/operations/alerts/notify-slo-alerts.yaml`; runbook link. | `StellaOps.Notifier.Tests/ObservabilityContractsTests.cs` verifying metric names/labels; trace exemplar fixture `docs/notifications/fixtures/traces/sample-trace.json`. | +| NR1 | Versioned JSON Schemas for event envelopes, rules, templates, channels, receipts, and webhooks; DSSE-signed catalog with canonical hash recipe (BLAKE3-256 over normalized JSON). | `docs/modules/notify/schemas/notify-schemas-catalog.json` + `.dsse.json`; `docs/modules/notify/schemas/inputs.lock` capturing digests and canonicalization flags. | Golden canonicalization harness under `tests/notifications/Schemas/SchemaCanonicalizationTests.cs` using frozen inputs + hash assertions. | +| NR2 | Tenant scoping + approvals for high-impact rules (escalations, PII, cross-tenant fan-out). Every API and receipt carries `tenant_id`; RBAC/approvals enforced. | RBAC/approval matrix (`docs/modules/notify/security/tenant-approvals.md`) listing actions × roles × required approvals. | API contract tests in `StellaOps.Notifier.Tests/TenantScopeTests.cs` plus integration fixtures with mixed-tenant payloads (should reject). | +| NR3 | Deterministic rendering/localization: stable merge-field ordering, UTC ISO-8601 timestamps, locale whitelist, hashed previews recorded in ledger. | Rendering fixture pack `docs/modules/notify/fixtures/rendering/*.json`; hash ledger samples `docs/modules/notify/fixtures/rendering/index.ndjson` with BLAKE3 digests. | `StellaOps.Notifier.Tests/RenderingDeterminismTests.cs` compares golden bodies/subjects across locales/timezones; seeds fixed RNG/time. | +| NR4 | Quotas/backpressure/DLQ: per-tenant/channel quotas, burst budgets, enqueue gating, DLQ schema with redrive + idempotent keys; metrics/alerts for backlog/DLQ growth. | Quota policy `docs/modules/notify/operations/quotas.md`; DLQ schema `docs/modules/notify/schemas/dlq-notify.schema.json`. | Worker tests `StellaOps.Notifier.Tests/BackpressureAndDlqTests.cs` validating quota enforcement, DLQ insertion, redrive idempotency. | +| NR5 | Retry & idempotency: canonical `delivery_id` (UUIDv7) + dedupe key (event×rule×channel); bounded exponential backoff with jitter; idempotent connectors; ignore out-of-order acks. | Retry matrix `docs/modules/notify/operations/retries.md`; connector idempotency checklist. | `StellaOps.Notifier.Tests/RetryPolicyTests.cs` + connector harness fixtures demonstrating dedupe across duplicate events. | +| NR6 | Webhook/ack security: HMAC or mTLS/DPoP required; signed ack URLs/tokens with nonce, expiry, audience, single-use; per-tenant allowlists for domains/paths. | Security policy `docs/modules/notify/security/webhook-ack-hardening.md`; sample signed-ack token format + validation steps. | Negative-path tests `StellaOps.Notifier.Tests/WebhookSecurityTests.cs` covering wrong HMAC, replayed nonce, expired token, disallowed domain. | +| NR7 | Redaction & PII limits: classify template fields; redact secrets/PII in storage/logs; hash sensitive values; size/field allowlists; previews/logs default to redacted variant. | Redaction catalog `docs/modules/notify/security/redaction-catalog.md`; sample redacted payloads `docs/modules/notify/fixtures/redaction/*.json`. | `StellaOps.Notifier.Tests/RedactionTests.cs` asserting stored/preview payloads match redacted expectations. | +| NR8 | Observability SLO alerts: SLOs for delivery latency/success/backlog/DLQ age; standard metrics names; dashboards/alerts/runbooks; traces include tenant/rule/channel IDs with sampling rules. | Dashboard JSON `docs/modules/notify/operations/dashboards/notify-slo.json`; alert rules `docs/modules/notify/operations/alerts/notify-slo-alerts.yaml`; runbook link. | `StellaOps.Notifier.Tests/ObservabilityContractsTests.cs` verifying metric names/labels; trace exemplar fixture `docs/modules/notify/fixtures/traces/sample-trace.json`. | | NR9 | Offline notify-kit with DSSE: bundle schemas, rules/templates, connector configs, verify script, hash list, time-anchor hook; deterministic packaging flags; tenant/env scoping; DSSE-signed manifest. | Manifest `offline/notifier/notify-kit.manifest.json`, DSSE `offline/notifier/notify-kit.manifest.dsse.json`, hash list `offline/notifier/artifact-hashes.json`, verify script `offline/notifier/verify_notify_kit.sh`. | Determinism check `tests/offline/NotifyKitDeterminismTests.sh` (shell) verifying hash list, DSSE, scope enforcement, packaging flags. | -| NR10 | Mandatory simulations & evidence before activation: dry-run against frozen fixtures; DSSE-signed simulation results attached to approvals; regression tests per high-impact rule/template change. | Simulation report `docs/notifications/simulations/-report.json` + DSSE; approval evidence log `docs/notifications/simulations/index.ndjson`. | `StellaOps.Notifier.Tests/SimulationGateTests.cs` enforcing simulation requirement and evidence linkage before `active=true`. | +| NR10 | Mandatory simulations & evidence before activation: dry-run against frozen fixtures; DSSE-signed simulation results attached to approvals; regression tests per high-impact rule/template change. | Simulation report `docs/modules/notify/simulations/-report.json` + DSSE; approval evidence log `docs/modules/notify/simulations/index.ndjson`. | `StellaOps.Notifier.Tests/SimulationGateTests.cs` enforcing simulation requirement and evidence linkage before `active=true`. | ## Delivery + governance hooks - Add the above evidence paths to the NOTIFY-GAPS-171-014 task in `docs/implplan/SPRINT_0171_0001_0001_notifier_i.md` and mirror status in `src/Notifier/StellaOps.Notifier/TASKS.md`. - When artifacts land, append TRX/fixture links in the sprint **Execution Log** and reference this doc under **Decisions & Risks**. - Offline kit artefacts must mirror mirror/offline packaging rules (deterministic flags, time-anchor hook, PQ dual-sign toggle) already used by Mirror/Offline sprints. -- Simulation evidence lives in `docs/notifications/simulations/` (index.ndjson + per-rule reports) and is validated by contract tests under `Contracts/PolicyDocsCompletenessTests.cs`. +- Simulation evidence lives in `docs/modules/notify/simulations/` (index.ndjson + per-rule reports) and is validated by contract tests under `Contracts/PolicyDocsCompletenessTests.cs`. - Contract tests under `Contracts/` verify schema catalog ↔ DSSE alignment, fixture hashes, simulation index presence, and offline kit manifest/DSSE consistency. ## Next steps diff --git a/docs/notifications/operations/alerts/notify-slo-alerts.yaml b/docs/modules/notify/operations/alerts/notify-slo-alerts.yaml similarity index 100% rename from docs/notifications/operations/alerts/notify-slo-alerts.yaml rename to docs/modules/notify/operations/alerts/notify-slo-alerts.yaml diff --git a/docs/notifications/operations/dashboards/notify-slo.json b/docs/modules/notify/operations/dashboards/dashboards/notify-slo.json similarity index 100% rename from docs/notifications/operations/dashboards/notify-slo.json rename to docs/modules/notify/operations/dashboards/dashboards/notify-slo.json diff --git a/docs/notifications/operations/quotas.md b/docs/modules/notify/operations/quotas.md similarity index 75% rename from docs/notifications/operations/quotas.md rename to docs/modules/notify/operations/quotas.md index 6314b7e31..1cf3c8b3e 100644 --- a/docs/notifications/operations/quotas.md +++ b/docs/modules/notify/operations/quotas.md @@ -3,5 +3,5 @@ - Per-tenant quotas: 500 deliveries/minute default; channel overrides: webhook 200/min, email 120/min, chat 240/min. - Burst budget: 2x quota for 60 seconds, then hard clamp. - Backpressure: reject enqueue when backlog > quota*10 or DLQ growth > 5%/min. -- DLQ schema: `docs/notifications/schemas/dlq-notify.schema.json`; redrive requires idempotent `delivery_id`/`dedupe_key`. +- DLQ schema: `docs/modules/notify/schemas/dlq-notify.schema.json`; redrive requires idempotent `delivery_id`/`dedupe_key`. - Metrics to alert: backlog depth, DLQ depth, redrive success rate, enqueue reject count. diff --git a/docs/notifications/operations/retries.md b/docs/modules/notify/operations/retries.md similarity index 100% rename from docs/notifications/operations/retries.md rename to docs/modules/notify/operations/retries.md diff --git a/docs/notifications/overview.md b/docs/modules/notify/overview.md similarity index 88% rename from docs/notifications/overview.md rename to docs/modules/notify/overview.md index a095c0289..6771f9c26 100644 --- a/docs/notifications/overview.md +++ b/docs/modules/notify/overview.md @@ -19,12 +19,12 @@ Notifications Studio turns raw platform events into concise, tenant-scoped alert | Capability | What it does | Key docs | |------------|--------------|----------| -| Rules engine | Declarative matchers for event kinds, severities, namespaces, VEX context, KEV flags, and more. | [`notifications/rules.md`](rules.md) | -| Channel catalog | Slack, Teams, Email, Webhook connectors loaded via restart-time plug-ins; metadata stored without secrets. | [`notifications/architecture.md`](architecture.md) | -| Templates | Locale-aware, deterministic rendering via safe helpers; channel defaults plus tenant-specific overrides, including the attestation lifecycle suite (`tmpl-attest-*`). | [`notifications/templates.md`](templates.md#7-attestation--signing-lifecycle-templates-notify-attest-74-001) | -| Digests | Coalesce bursts into periodic summaries with deterministic IDs and audit trails. | [`notifications/digests.md`](digests.md) | -| Delivery ledger | Tracks rendered payload hashes, attempts, throttles, and outcomes for every action. | [`modules/notify/architecture.md`](../modules/notify/architecture.md#7-data-model) | -| Ack tokens | DSSE-signed acknowledgement tokens with webhook allowlists and escalation guardrails enforced by Authority. | [`modules/notify/architecture.md`](../modules/notify/architecture.md#81-ack-tokens--escalation-workflows) | +| Rules engine | Declarative matchers for event kinds, severities, namespaces, VEX context, KEV flags, and more. | [rules.md](rules.md) | +| Channel catalog | Slack, Teams, Email, Webhook connectors loaded via restart-time plug-ins; metadata stored without secrets. | [architecture.md](architecture.md) | +| Templates | Locale-aware, deterministic rendering via safe helpers; channel defaults plus tenant-specific overrides, including the attestation lifecycle suite (`tmpl-attest-*`). | [templates.md](templates.md#7-attestation--signing-lifecycle-templates-notify-attest-74-001) | +| Digests | Coalesce bursts into periodic summaries with deterministic IDs and audit trails. | [digests.md](digests.md) | +| Delivery ledger | Tracks rendered payload hashes, attempts, throttles, and outcomes for every action. | [architecture.md](architecture.md#7-data-model) | +| Ack tokens | DSSE-signed acknowledgement tokens with webhook allowlists and escalation guardrails enforced by Authority. | [architecture.md](architecture.md#81-ack-tokens--escalation-workflows) | --- diff --git a/docs/notifications/pack-approvals-contract.md b/docs/modules/notify/pack-approvals-contract.md similarity index 100% rename from docs/notifications/pack-approvals-contract.md rename to docs/modules/notify/pack-approvals-contract.md diff --git a/docs/notifications/pack-approvals-integration.md b/docs/modules/notify/pack-approvals-integration.md similarity index 100% rename from docs/notifications/pack-approvals-integration.md rename to docs/modules/notify/pack-approvals-integration.md diff --git a/docs/notifications/rules.md b/docs/modules/notify/rules.md similarity index 96% rename from docs/notifications/rules.md rename to docs/modules/notify/rules.md index 5b38369ea..b2b0b7e2d 100644 --- a/docs/notifications/rules.md +++ b/docs/modules/notify/rules.md @@ -81,24 +81,24 @@ Each rule requires at least one action. Actions are deduplicated and sorted by ` | `throttle` | ISO8601 duration? | Optional throttle TTL (`PT300S`, `PT1H`). Prevents duplicate deliveries when the same idempotency hash appears before expiry. | | `locale` | string? | BCP-47 tag (stored lower-case). Template lookup falls back to channel locale then `en-us`. | | `enabled` | bool | Disabled actions skip rendering but remain stored. | -| `metadata` | map | Connector-specific hints (priority, layout, etc.). | - -### 4.0 Attestation lifecycle templates - -Rules targeting attestation/signing events (`attestor.verification.failed`, `attestor.attestation.expiring`, `authority.keys.revoked`, `attestor.transparency.anomaly`) must reference the dedicated template keys documented in [`notifications/templates.md` §7](templates.md#7-attestation--signing-lifecycle-templates-notify-attest-74-001) so payloads remain deterministic across channels and Offline Kits: - -| Event kind | Required template key | Notes | -| --- | --- | --- | -| `attestor.verification.failed` | `tmpl-attest-verify-fail` | Include failure code, Rekor UUID/index, last good attestation link. | -| `attestor.attestation.expiring` | `tmpl-attest-expiry-warning` | Surface issued/expires timestamps, time remaining, renewal instructions. | -| `authority.keys.revoked` / `authority.keys.rotated` | `tmpl-attest-key-rotation` | List rotation batch ID, impacted services, remediation steps. | -| `attestor.transparency.anomaly` | `tmpl-attest-transparency-anomaly` | Highlight Rekor/witness metadata and anomaly classification. | - -Locale-specific variants keep the same template key while varying `locale`; rule actions shouldn't create ad-hoc templates for these events. - -### 4.1 Evaluation order - -1. Verify channel exists and is enabled; disabled channels mark the delivery as `Dropped`. +| `metadata` | map | Connector-specific hints (priority, layout, etc.). | + +### 4.0 Attestation lifecycle templates + +Rules targeting attestation/signing events (`attestor.verification.failed`, `attestor.attestation.expiring`, `authority.keys.revoked`, `attestor.transparency.anomaly`) must reference the dedicated template keys documented in [`templates.md` §7](templates.md#7-attestation--signing-lifecycle-templates-notify-attest-74-001) so payloads remain deterministic across channels and Offline Kits: + +| Event kind | Required template key | Notes | +| --- | --- | --- | +| `attestor.verification.failed` | `tmpl-attest-verify-fail` | Include failure code, Rekor UUID/index, last good attestation link. | +| `attestor.attestation.expiring` | `tmpl-attest-expiry-warning` | Surface issued/expires timestamps, time remaining, renewal instructions. | +| `authority.keys.revoked` / `authority.keys.rotated` | `tmpl-attest-key-rotation` | List rotation batch ID, impacted services, remediation steps. | +| `attestor.transparency.anomaly` | `tmpl-attest-transparency-anomaly` | Highlight Rekor/witness metadata and anomaly classification. | + +Locale-specific variants keep the same template key while varying `locale`; rule actions shouldn't create ad-hoc templates for these events. + +### 4.1 Evaluation order + +1. Verify channel exists and is enabled; disabled channels mark the delivery as `Dropped`. 2. Apply throttle idempotency key: `hash(ruleId|actionId|event.kind|scope.digest|delta.hash|dayBucket)`. Hits are logged as `Throttled`. 3. If the action defines a digest window other than `instant`, append the event to the open window and defer delivery until flush. 4. When delivery proceeds, the renderer resolves the template, locale, and metadata before invoking the connector. diff --git a/docs/notifications/schemas/README.md b/docs/modules/notify/schemas/README.md similarity index 100% rename from docs/notifications/schemas/README.md rename to docs/modules/notify/schemas/README.md diff --git a/docs/notifications/schemas/channel.schema.json b/docs/modules/notify/schemas/channel.schema.json similarity index 100% rename from docs/notifications/schemas/channel.schema.json rename to docs/modules/notify/schemas/channel.schema.json diff --git a/docs/notifications/schemas/dlq-notify.schema.json b/docs/modules/notify/schemas/dlq-notify.schema.json similarity index 100% rename from docs/notifications/schemas/dlq-notify.schema.json rename to docs/modules/notify/schemas/dlq-notify.schema.json diff --git a/docs/notifications/schemas/event-envelope.schema.json b/docs/modules/notify/schemas/event-envelope.schema.json similarity index 100% rename from docs/notifications/schemas/event-envelope.schema.json rename to docs/modules/notify/schemas/event-envelope.schema.json diff --git a/docs/notifications/schemas/inputs.lock b/docs/modules/notify/schemas/inputs.lock similarity index 100% rename from docs/notifications/schemas/inputs.lock rename to docs/modules/notify/schemas/inputs.lock diff --git a/docs/notifications/schemas/notify-schemas-catalog.dsse.json b/docs/modules/notify/schemas/notify-schemas-catalog.dsse.json similarity index 100% rename from docs/notifications/schemas/notify-schemas-catalog.dsse.json rename to docs/modules/notify/schemas/notify-schemas-catalog.dsse.json diff --git a/docs/notifications/schemas/notify-schemas-catalog.json b/docs/modules/notify/schemas/notify-schemas-catalog.json similarity index 100% rename from docs/notifications/schemas/notify-schemas-catalog.json rename to docs/modules/notify/schemas/notify-schemas-catalog.json diff --git a/docs/notifications/schemas/receipt.schema.json b/docs/modules/notify/schemas/receipt.schema.json similarity index 100% rename from docs/notifications/schemas/receipt.schema.json rename to docs/modules/notify/schemas/receipt.schema.json diff --git a/docs/notifications/schemas/rule.schema.json b/docs/modules/notify/schemas/rule.schema.json similarity index 100% rename from docs/notifications/schemas/rule.schema.json rename to docs/modules/notify/schemas/rule.schema.json diff --git a/docs/notifications/schemas/template.schema.json b/docs/modules/notify/schemas/template.schema.json similarity index 100% rename from docs/notifications/schemas/template.schema.json rename to docs/modules/notify/schemas/template.schema.json diff --git a/docs/notifications/schemas/webhook.schema.json b/docs/modules/notify/schemas/webhook.schema.json similarity index 100% rename from docs/notifications/schemas/webhook.schema.json rename to docs/modules/notify/schemas/webhook.schema.json diff --git a/docs/notifications/security/README.md b/docs/modules/notify/security/README.md similarity index 100% rename from docs/notifications/security/README.md rename to docs/modules/notify/security/README.md diff --git a/docs/notifications/security/redaction-catalog.md b/docs/modules/notify/security/redaction-catalog.md similarity index 74% rename from docs/notifications/security/redaction-catalog.md rename to docs/modules/notify/security/redaction-catalog.md index 9494eb6bb..6b086ac94 100644 --- a/docs/notifications/security/redaction-catalog.md +++ b/docs/modules/notify/security/redaction-catalog.md @@ -3,4 +3,4 @@ - Classify merge fields: identifiers (hash), secrets (strip), PII (mask), operational metadata (retain). - Storage and previews must use redacted forms by default; full bodies allowed only with `Notify.Audit` permission. - Log payloads must omit secrets; hashes use BLAKE3-256 over UTF-8 normalized values. -- Fixtures under `docs/notifications/fixtures/redaction/` show expected redacted shapes for templates and receipts. +- Fixtures under `docs/modules/notify/fixtures/redaction/` show expected redacted shapes for templates and receipts. diff --git a/docs/notifications/security/tenant-approvals.md b/docs/modules/notify/security/tenant-approvals.md similarity index 100% rename from docs/notifications/security/tenant-approvals.md rename to docs/modules/notify/security/tenant-approvals.md diff --git a/docs/notifications/security/webhook-ack-hardening.md b/docs/modules/notify/security/webhook-ack-hardening.md similarity index 100% rename from docs/notifications/security/webhook-ack-hardening.md rename to docs/modules/notify/security/webhook-ack-hardening.md diff --git a/docs/notifications/simulations/index.ndjson b/docs/modules/notify/simulations/index.ndjson similarity index 100% rename from docs/notifications/simulations/index.ndjson rename to docs/modules/notify/simulations/index.ndjson diff --git a/docs/notifications/simulations/sample-rule-report.json b/docs/modules/notify/simulations/sample-rule-report.json similarity index 100% rename from docs/notifications/simulations/sample-rule-report.json rename to docs/modules/notify/simulations/sample-rule-report.json diff --git a/docs/notifications/simulations/sample-simulation-report.json b/docs/modules/notify/simulations/sample-simulation-report.json similarity index 100% rename from docs/notifications/simulations/sample-simulation-report.json rename to docs/modules/notify/simulations/sample-simulation-report.json diff --git a/docs/notifications/slo-webhook-schema.md b/docs/modules/notify/slo-webhook-schema.md similarity index 98% rename from docs/notifications/slo-webhook-schema.md rename to docs/modules/notify/slo-webhook-schema.md index 27ce7696d..7f399579f 100644 --- a/docs/notifications/slo-webhook-schema.md +++ b/docs/modules/notify/slo-webhook-schema.md @@ -81,6 +81,6 @@ Purpose: define the payload emitted by Telemetry SLO evaluators toward Notifier ``` ### Evidence to surface in sprint tasks -- File: `docs/notifications/slo-webhook-schema.md` (this document). +- File: `docs/modules/notify/slo-webhook-schema.md` (this document). - Sample payload (canonical) and validation checklist above. - Dependencies: upstream Telemetry evaluator must emit `metric.labels` sanitized; Notifier to persist `id` for idempotency. diff --git a/docs/notifications/templates.md b/docs/modules/notify/templates.md similarity index 100% rename from docs/notifications/templates.md rename to docs/modules/notify/templates.md diff --git a/docs/modules/platform/AGENTS.md b/docs/modules/platform/AGENTS.md index 88d1d91e1..ea8f197a5 100644 --- a/docs/modules/platform/AGENTS.md +++ b/docs/modules/platform/AGENTS.md @@ -17,7 +17,7 @@ Platform module describes cross-cutting architecture, contracts, and guardrails 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/platform/architecture-overview.md b/docs/modules/platform/architecture-overview.md index 64eb7bd65..c29c9fcbf 100644 --- a/docs/modules/platform/architecture-overview.md +++ b/docs/modules/platform/architecture-overview.md @@ -2,7 +2,7 @@ > **Ownership:** Architecture Guild • Docs Guild > **Audience:** Service owners, platform engineers, solution architects -> **Related:** [High-Level Architecture](../../07_HIGH_LEVEL_ARCHITECTURE.md), [Concelier Architecture](../concelier/architecture.md), [Policy Engine Architecture](../policy/architecture.md), [Aggregation-Only Contract](../../ingestion/aggregation-only-contract.md) +> **Related:** [High-Level Architecture](../../07_HIGH_LEVEL_ARCHITECTURE.md), [Concelier Architecture](../concelier/architecture.md), [Policy Engine Architecture](../policy/architecture.md), [Aggregation-Only Contract](../../aoc/aggregation-only-contract.md) This dossier summarises the end-to-end runtime topology after the Aggregation-Only Contract (AOC) rollout. It highlights where raw facts live, how ingest services enforce guardrails, and how downstream components consume those facts to derive policy decisions and user-facing experiences. @@ -158,13 +158,13 @@ sequenceDiagram - **Offline Kit:** Packages raw PostgreSQL snapshots (`advisory_raw`, `vex_raw`) plus guard configuration and CLI verifier binaries so air-gapped sites can re-run AOC checks before promotion. - **Recovery:** Supersedes chains allow rollback to prior revisions without mutating rows. Disaster exercises must rehearse restoring from snapshot, replaying logical replication into Policy Engine, and re-validating guard compliance. -- **Migration:** Legacy normalised fields are moved to temporary views during cutover; ingestion runtime removes writes once guard-enforced path is live (see [Migration playbook](../../ingestion/aggregation-only-contract.md#8-migration-playbook)). +- **Migration:** Legacy normalised fields are moved to temporary views during cutover; ingestion runtime removes writes once guard-enforced path is live (see [Migration playbook](../../aoc/aggregation-only-contract.md#8-migration-playbook)). --- ## 5 · Replay CAS & deterministic bundles -- **Replay CAS:** Content-addressed storage lives under `cas://replay//.tar.zst`. Writers must use [StellaOps.Replay.Core](../../src/__Libraries/StellaOps.Replay.Core/AGENTS.md) helpers to ensure lexicographic file ordering, POSIX mode normalisation (0644/0755), LF newlines, zstd level 19 compression, and shard-by-prefix CAS URIs (`BuildCasUri`). Bundle metadata (size, hash, created) feeds the platform-wide `replay_bundles` collection defined in `docs/data/replay_schema.md`. +- **Replay CAS:** Content-addressed storage lives under `cas://replay//.tar.zst`. Writers must use [StellaOps.Replay.Core](../../src/__Libraries/StellaOps.Replay.Core/AGENTS.md) helpers to ensure lexicographic file ordering, POSIX mode normalisation (0644/0755), LF newlines, zstd level 19 compression, and shard-by-prefix CAS URIs (`BuildCasUri`). Bundle metadata (size, hash, created) feeds the platform-wide `replay_bundles` collection defined in `docs/db/replay-schema.md`. - **Artifacts:** Each recorded scan stores three bundles: 1. `manifest.json` (canonical JSON, hashed and signed via DSSE). 2. `inputbundle.tar.zst` (feeds, policies, tools, environment snapshot). @@ -179,14 +179,14 @@ sequenceDiagram ## 6 · References -- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../../aoc/aggregation-only-contract.md) - [Concelier architecture](../concelier/architecture.md) - [Excititor architecture](../excititor/architecture.md) - [Policy Engine architecture](../policy/architecture.md) - [Authority service](../authority/architecture.md) - [Replay specification](../../replay/DETERMINISTIC_REPLAY.md) - [Replay developer guide](../../replay/DEVS_GUIDE_REPLAY.md) -- [Replay schema](../../data/replay_schema.md) *(pending)* +- [Replay schema](../../db/replay-schema.md) - [Replay test strategy](../../replay/TEST_STRATEGY.md) *(draft)* - [Observability standards (upcoming)](../../observability/policy.md) – interim reference for telemetry naming. diff --git a/docs/modules/platform/architecture.md b/docs/modules/platform/architecture.md index b4724f05f..882ed3c1d 100644 --- a/docs/modules/platform/architecture.md +++ b/docs/modules/platform/architecture.md @@ -5,7 +5,7 @@ This module aggregates cross-cutting contracts and guardrails that every StellaO ## Anchors - High-level system view: `../../07_HIGH_LEVEL_ARCHITECTURE.md` - Platform overview: `architecture-overview.md` -- Aggregation-Only Contract: `../ingestion/aggregation-only-contract.md` (referenced across ingestion/observability docs) +- Aggregation-Only Contract: `../../aoc/aggregation-only-contract.md` (referenced across ingestion/observability docs) ## Scope - **Identity & tenancy**: Authority-issued OpToks, tenant scoping, RBAC, short TTLs; see Authority module docs. diff --git a/docs/modules/policy/AGENTS.md b/docs/modules/policy/AGENTS.md index 942f4bfea..c460c53ea 100644 --- a/docs/modules/policy/AGENTS.md +++ b/docs/modules/policy/AGENTS.md @@ -18,7 +18,7 @@ Policy Engine compiles and evaluates Stella DSL policies deterministically, prod 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/policy/architecture.md b/docs/modules/policy/architecture.md index 8f304a46e..1204a4360 100644 --- a/docs/modules/policy/architecture.md +++ b/docs/modules/policy/architecture.md @@ -5,7 +5,7 @@ > **Ownership:** Policy Guild • Platform Guild > **Services:** `StellaOps.Policy.Engine` (Minimal API + worker host) > **Data Stores:** PostgreSQL (`policy.*` schemas for packs, runs, exceptions, receipts), Object storage (explain bundles), optional queue -> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [SPL v1](../../policy/spl-v1.md), [Lifecycle](../../policy/lifecycle.md), [Runtime](../../policy/runtime.md), [Governance](../../policy/governance.md), [REST API](../../policy/api.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../ingestion/aggregation-only-contract.md) +> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [SPL v1](../../policy/spl-v1.md), [Lifecycle](../../policy/lifecycle.md), [Runtime](../../policy/runtime.md), [Governance](../../policy/governance.md), [REST API](../../policy/api.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../aoc/aggregation-only-contract.md) This dossier describes the internal structure of the Policy Engine service delivered in Epic 2. It focuses on module boundaries, deterministic evaluation, orchestration, and integration contracts with Concelier, Excititor, SBOM Service, Authority, Scheduler, and Observability stacks. @@ -111,7 +111,7 @@ Key notes: | **Authority Client** (`Authority/`) | Acquire tokens, enforce scopes, perform DPoP key rotation. | Only service identity uses `effective:write`. | | **DSL Compiler** (`Dsl/`) | Parse, canonicalise, IR generation, checksum caching. | Uses Roslyn-like pipeline; caches by `policyId+version+hash`. | | **Selection Layer** (`Selection/`) | Batch SBOM ↔ advisory ↔ VEX joiners; apply equivalence tables; support incremental cursors. | Deterministic ordering (SBOM → advisory → VEX). | -| **Evaluator** (`Evaluation/`) | Execute IR with first-match semantics, compute severity/trust/reachability weights, record rule hits, and emit a unified confidence score with factor breakdown (reachability/runtime/VEX/provenance/policy). | Stateless; all inputs provided by selection layer. | +| **Evaluator** (`Evaluation/`) | Execute IR with first-match semantics, compute severity/trust/reachability weights, record rule hits, and emit a unified confidence score with factor breakdown (reachability/runtime/VEX/provenance/policy). | Stateless; all inputs provided by selection layer. | | **Signals** (`Signals/`) | Normalizes reachability, trust, entropy, uncertainty, runtime hits into a single dictionary passed to Evaluator; supplies default `unknown` values when signals missing. Entropy penalties are derived from Scanner `layer_summary.json`/`entropy.report.json` (K=0.5, cap=0.3, block at image opaque ratio > 0.15 w/ unknown provenance) and exported via `policy_entropy_penalty_value` / `policy_entropy_image_opaque_ratio`; SPL scope `entropy.*` exposes `penalty`, `image_opaque_ratio`, `blocked`, `warned`, `capped`, `top_file_opaque_ratio`. | Aligns with `signals.*` namespace in DSL. | | **Materialiser** (`Materialization/`) | Upsert effective findings, append history, manage explain bundle exports. | PostgreSQL transactions per SBOM chunk. | | **Orchestrator** (`Runs/`) | Change-stream ingestion, fairness, retry/backoff, queue writer. | Works with Scheduler Models DTOs. | @@ -203,150 +203,150 @@ Determinism guard instrumentation wraps the evaluator, rejecting access to forbi All payloads are immutable and include analyzer fingerprints (`scanner.native@sha256:...`, `policyEngine@sha256:...`) so replay tooling can recompute identical digests. Determinism tests cover both the OpenVEX JSON and the DSSE payload bytes. - ---- - -### 6.2 · Trust Lattice Policy Gates - -The Policy Engine evaluates Trust Lattice gates after claim score merging to enforce trust-based constraints on VEX verdicts. - -#### Gate Interface - -```csharp -public interface IPolicyGate -{ - Task EvaluateAsync( - MergeResult mergeResult, - PolicyGateContext context, - CancellationToken ct = default); -} - -public sealed record GateResult -{ - public required string GateName { get; init; } - public required bool Passed { get; init; } - public string? Reason { get; init; } - public ImmutableDictionary Details { get; init; } -} -``` - -#### Available Gates - -| Gate | Purpose | Configuration Key | -|------|---------|-------------------| -| **MinimumConfidenceGate** | Reject verdicts below confidence threshold per environment | `gates.minimumConfidence` | -| **UnknownsBudgetGate** | Fail scan if unknowns exceed budget | `gates.unknownsBudget` | -| **SourceQuotaGate** | Prevent single-source dominance without corroboration | `gates.sourceQuota` | -| **ReachabilityRequirementGate** | Require reachability proof for critical CVEs | `gates.reachabilityRequirement` | -| **EvidenceFreshnessGate** | Reject stale evidence below freshness threshold | `gates.evidenceFreshness` | - -#### MinimumConfidenceGate - -Requires minimum confidence threshold for suppression verdicts: - -```yaml -gates: - minimumConfidence: - enabled: true - thresholds: - production: 0.75 # High bar for production - staging: 0.60 # Moderate for staging - development: 0.40 # Permissive for dev - applyToStatuses: - - not_affected - - fixed -``` - -- **Behavior**: `affected` status bypasses this gate (conservative default). -- **Result**: `confidence_below_threshold` when verdict confidence < environment threshold. - -#### UnknownsBudgetGate - -Limits exposure to unknown/unscored dependencies: - -```yaml -gates: - unknownsBudget: - enabled: true - maxUnknownCount: 5 - maxCumulativeUncertainty: 2.0 - escalateOnExceed: true -``` - -- **Behavior**: Fails when unknowns exceed count limit OR cumulative uncertainty exceeds budget. -- **Cumulative uncertainty**: `sum(1 - ClaimScore)` across all verdicts. - -#### SourceQuotaGate - -Prevents single-source verdicts without corroboration: - -```yaml -gates: - sourceQuota: - enabled: true - maxInfluencePercent: 60 - corroborationDelta: 0.10 - requireCorroboration: true -``` - -- **Behavior**: Fails when single source provides > 60% of verdict weight AND no second source is within delta (0.10). -- **Rationale**: Ensures critical decisions have multi-source validation. - -#### ReachabilityRequirementGate - -Requires reachability proof for high-severity vulnerabilities: - -```yaml -gates: - reachabilityRequirement: - enabled: true - applySeverities: - - critical - - high - exemptStatuses: - - not_affected - bypassReasons: - - component_not_present -``` - -- **Behavior**: Fails when CRITICAL/HIGH CVE marked `not_affected` lacks reachability proof (unless bypass reason applies). - -#### Gate Registry - -Gates are registered via DI and evaluated in sequence: - -```csharp -public interface IPolicyGateRegistry -{ - IEnumerable GetEnabledGates(string environment); - Task EvaluateAllAsync( - MergeResult mergeResult, - PolicyGateContext context, - CancellationToken ct = default); -} -``` - -#### Gate Metrics - -- `policy_gate_evaluations_total{gate,result}` — Count of gate evaluations by outcome -- `policy_gate_failures_total{gate,reason}` — Count of gate failures by reason -- `policy_gate_latency_seconds{gate}` — Gate evaluation latency histogram - -#### Gate Implementation Reference - -| Gate | Source File | -|------|-------------| -| MinimumConfidenceGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/MinimumConfidenceGate.cs` | -| UnknownsBudgetGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/UnknownsBudgetGate.cs` | -| SourceQuotaGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/SourceQuotaGate.cs` | -| ReachabilityRequirementGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/ReachabilityRequirementGate.cs` | -| EvidenceFreshnessGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/EvidenceFreshnessGate.cs` | - -See `etc/policy-gates.yaml.sample` for complete gate configuration options. - -**Related Documentation:** -- [Trust Lattice Specification](../excititor/trust-lattice.md) -- [Verdict Manifest Specification](../authority/verdict-manifest.md) + +--- + +### 6.2 · Trust Lattice Policy Gates + +The Policy Engine evaluates Trust Lattice gates after claim score merging to enforce trust-based constraints on VEX verdicts. + +#### Gate Interface + +```csharp +public interface IPolicyGate +{ + Task EvaluateAsync( + MergeResult mergeResult, + PolicyGateContext context, + CancellationToken ct = default); +} + +public sealed record GateResult +{ + public required string GateName { get; init; } + public required bool Passed { get; init; } + public string? Reason { get; init; } + public ImmutableDictionary Details { get; init; } +} +``` + +#### Available Gates + +| Gate | Purpose | Configuration Key | +|------|---------|-------------------| +| **MinimumConfidenceGate** | Reject verdicts below confidence threshold per environment | `gates.minimumConfidence` | +| **UnknownsBudgetGate** | Fail scan if unknowns exceed budget | `gates.unknownsBudget` | +| **SourceQuotaGate** | Prevent single-source dominance without corroboration | `gates.sourceQuota` | +| **ReachabilityRequirementGate** | Require reachability proof for critical CVEs | `gates.reachabilityRequirement` | +| **EvidenceFreshnessGate** | Reject stale evidence below freshness threshold | `gates.evidenceFreshness` | + +#### MinimumConfidenceGate + +Requires minimum confidence threshold for suppression verdicts: + +```yaml +gates: + minimumConfidence: + enabled: true + thresholds: + production: 0.75 # High bar for production + staging: 0.60 # Moderate for staging + development: 0.40 # Permissive for dev + applyToStatuses: + - not_affected + - fixed +``` + +- **Behavior**: `affected` status bypasses this gate (conservative default). +- **Result**: `confidence_below_threshold` when verdict confidence < environment threshold. + +#### UnknownsBudgetGate + +Limits exposure to unknown/unscored dependencies: + +```yaml +gates: + unknownsBudget: + enabled: true + maxUnknownCount: 5 + maxCumulativeUncertainty: 2.0 + escalateOnExceed: true +``` + +- **Behavior**: Fails when unknowns exceed count limit OR cumulative uncertainty exceeds budget. +- **Cumulative uncertainty**: `sum(1 - ClaimScore)` across all verdicts. + +#### SourceQuotaGate + +Prevents single-source verdicts without corroboration: + +```yaml +gates: + sourceQuota: + enabled: true + maxInfluencePercent: 60 + corroborationDelta: 0.10 + requireCorroboration: true +``` + +- **Behavior**: Fails when single source provides > 60% of verdict weight AND no second source is within delta (0.10). +- **Rationale**: Ensures critical decisions have multi-source validation. + +#### ReachabilityRequirementGate + +Requires reachability proof for high-severity vulnerabilities: + +```yaml +gates: + reachabilityRequirement: + enabled: true + applySeverities: + - critical + - high + exemptStatuses: + - not_affected + bypassReasons: + - component_not_present +``` + +- **Behavior**: Fails when CRITICAL/HIGH CVE marked `not_affected` lacks reachability proof (unless bypass reason applies). + +#### Gate Registry + +Gates are registered via DI and evaluated in sequence: + +```csharp +public interface IPolicyGateRegistry +{ + IEnumerable GetEnabledGates(string environment); + Task EvaluateAllAsync( + MergeResult mergeResult, + PolicyGateContext context, + CancellationToken ct = default); +} +``` + +#### Gate Metrics + +- `policy_gate_evaluations_total{gate,result}` — Count of gate evaluations by outcome +- `policy_gate_failures_total{gate,reason}` — Count of gate failures by reason +- `policy_gate_latency_seconds{gate}` — Gate evaluation latency histogram + +#### Gate Implementation Reference + +| Gate | Source File | +|------|-------------| +| MinimumConfidenceGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/MinimumConfidenceGate.cs` | +| UnknownsBudgetGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/UnknownsBudgetGate.cs` | +| SourceQuotaGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/SourceQuotaGate.cs` | +| ReachabilityRequirementGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/ReachabilityRequirementGate.cs` | +| EvidenceFreshnessGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/EvidenceFreshnessGate.cs` | + +See `etc/policy-gates.yaml.sample` for complete gate configuration options. + +**Related Documentation:** +- [Trust Lattice Specification](../excititor/trust-lattice.md) +- [Verdict Manifest Specification](../authority/verdict-manifest.md) --- ## 7 · Security & Tenancy diff --git a/docs/modules/provcache/README.md b/docs/modules/provcache/README.md index f5e3e26a4..13befe16e 100644 --- a/docs/modules/provcache/README.md +++ b/docs/modules/provcache/README.md @@ -1,5 +1,7 @@ # Provcache Module +> **Status: Planned** — This module is documented for upcoming implementation in Sprint 8200. The design is finalized but source code does not yet exist. + > Provenance Cache — Maximizing Trust Evidence Density ## Overview diff --git a/docs/modules/registry/AGENTS.md b/docs/modules/registry/AGENTS.md index 0851e6f31..5c2701c5d 100644 --- a/docs/modules/registry/AGENTS.md +++ b/docs/modules/registry/AGENTS.md @@ -16,7 +16,7 @@ The registry module issues scoped pull tokens for mirrored container registries 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/scanner/AGENTS.md b/docs/modules/scanner/AGENTS.md index eabecbcab..2bc19ddd0 100644 --- a/docs/modules/scanner/AGENTS.md +++ b/docs/modules/scanner/AGENTS.md @@ -22,7 +22,7 @@ Scanner analyses container images layer-by-layer, producing deterministic SBOM f 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/scheduler/AGENTS.md b/docs/modules/scheduler/AGENTS.md index ed8f06dd0..f6c89ecca 100644 --- a/docs/modules/scheduler/AGENTS.md +++ b/docs/modules/scheduler/AGENTS.md @@ -25,7 +25,7 @@ Scheduler detects advisory/VEX deltas, computes impact windows, and orchestrates 5. On completion, set status to `DONE` in both the sprint file and `TASKS.md`; if paused, revert to `TODO` and add a brief note. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see `../../ingestion/aggregation-only-contract.md`). +- Honour the Aggregation-Only Contract where applicable (see `../../aoc/aggregation-only-contract.md`). - No undocumented schema or API contract changes; document deltas in architecture or implementation_plan. - Keep Offline Kit parity—document air-gapped workflows for any new feature. - Prefer deterministic fixtures and avoid machine-specific artefacts in examples. diff --git a/docs/modules/signer/AGENTS.md b/docs/modules/signer/AGENTS.md index 0501f5b3e..5ff8d004f 100644 --- a/docs/modules/signer/AGENTS.md +++ b/docs/modules/signer/AGENTS.md @@ -23,7 +23,7 @@ Signer validates callers, enforces Proof-of-Entitlement, and produces signed DSS 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/telemetry/AGENTS.md b/docs/modules/telemetry/AGENTS.md index 98bf8a8ea..547e21dbe 100644 --- a/docs/modules/telemetry/AGENTS.md +++ b/docs/modules/telemetry/AGENTS.md @@ -26,7 +26,7 @@ Telemetry module captures deployment and operations guidance for the shared obse 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/ui/AGENTS.md b/docs/modules/ui/AGENTS.md index 71886ce7c..f0738b97e 100644 --- a/docs/modules/ui/AGENTS.md +++ b/docs/modules/ui/AGENTS.md @@ -22,7 +22,7 @@ The Console presents operator dashboards for scans, policies, VEX evidence, runt 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/zastava/AGENTS.md b/docs/modules/zastava/AGENTS.md index 0b39a15d7..a0b9d2386 100644 --- a/docs/modules/zastava/AGENTS.md +++ b/docs/modules/zastava/AGENTS.md @@ -24,7 +24,7 @@ Zastava monitors running workloads, verifies supply chain posture, and enforces 4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan. ## Guardrails -- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md). +- Honour the Aggregation-Only Contract where applicable (see ../../aoc/aggregation-only-contract.md). - Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts. - Keep Offline Kit parity in mind—document air-gapped workflows for any new feature. - Update runbooks/observability assets when operational characteristics change. diff --git a/docs/modules/zastava/architecture.md b/docs/modules/zastava/architecture.md index 730e24e29..d64c73ccf 100644 --- a/docs/modules/zastava/architecture.md +++ b/docs/modules/zastava/architecture.md @@ -66,15 +66,15 @@ stellaops/zastava-agent # System service; watch Docker events; observer on "imageRef": "ghcr.io/acme/api@sha256:abcd…", "owner": { "kind": "Deployment", "name": "api" } }, - "process": { - "pid": 12345, - "entrypoint": ["/entrypoint.sh", "--serve"], - "entryTrace": [ - {"file":"/entrypoint.sh","line":3,"op":"exec","target":"/usr/bin/python3"}, - {"file":"","op":"python","target":"/opt/app/server.py"} - ], - "buildId": "9f3a1cd4c0b7adfe91c0e3b51d2f45fb0f76a4c1" - }, + "process": { + "pid": 12345, + "entrypoint": ["/entrypoint.sh", "--serve"], + "entryTrace": [ + {"file":"/entrypoint.sh","line":3,"op":"exec","target":"/usr/bin/python3"}, + {"file":"","op":"python","target":"/opt/app/server.py"} + ], + "buildId": "9f3a1cd4c0b7adfe91c0e3b51d2f45fb0f76a4c1" + }, "loadedLibs": [ { "path": "/lib/x86_64-linux-gnu/libssl.so.3", "inode": 123456, "sha256": "…"}, { "path": "/usr/lib/x86_64-linux-gnu/libcrypto.so.3", "inode": 123457, "sha256": "…"} @@ -116,35 +116,35 @@ stellaops/zastava-agent # System service; watch Docker events; observer on ], "decision": "Allow|Deny", "ttlSeconds": 300 -} -``` - -### 2.3 Schema negotiation & hashing guarantees - -* Every payload is wrapped in an envelope with `schemaVersion` set to `"@v."`. Version negotiation keeps the **major** line in lockstep (`zastava.runtime.event@v1.x`, `zastava.admission.decision@v1.x`) and selects the highest mutually supported **minor**. If no overlap exists, the local default (`@v1.0`) is used. -* Components use the shared `ZastavaContractVersions` helper for parsing/negotiation and the canonical JSON serializer to guarantee identical byte sequences prior to hashing, ensuring multihash IDs such as `sha256-` are reproducible across observers, webhooks, and backend jobs. -* Schema evolution rules: backwards-compatible fields append to the end of the canonical property order; breaking changes bump the **major** and require dual-writer/reader rollout per deployment playbook. - ---- - -## 3) Observer — node agent (DaemonSet) +} +``` + +### 2.3 Schema negotiation & hashing guarantees + +* Every payload is wrapped in an envelope with `schemaVersion` set to `"@v."`. Version negotiation keeps the **major** line in lockstep (`zastava.runtime.event@v1.x`, `zastava.admission.decision@v1.x`) and selects the highest mutually supported **minor**. If no overlap exists, the local default (`@v1.0`) is used. +* Components use the shared `ZastavaContractVersions` helper for parsing/negotiation and the canonical JSON serializer to guarantee identical byte sequences prior to hashing, ensuring multihash IDs such as `sha256-` are reproducible across observers, webhooks, and backend jobs. +* Schema evolution rules: backwards-compatible fields append to the end of the canonical property order; breaking changes bump the **major** and require dual-writer/reader rollout per deployment playbook. + +--- + +## 3) Observer — node agent (DaemonSet) ### 3.1 Responsibilities * **Watch** container lifecycle (start/stop) via CRI (`/run/containerd/containerd.sock` gRPC read‑only) or `/var/log/containers/*.log` tail fallback. * **Resolve** container → image digest, mount point rootfs. * **Trace entrypoint**: attach **short‑lived** nsenter/exec to PID 1 in container, parse shell for `exec` chain (bounded depth), record **terminal program**. -* **Sample loaded libs**: read `/proc//maps` and `exe` symlink to collect **actually loaded** DSOs; compute **sha256** for each mapped file (bounded count/size). -* **Record GNU build-id**: parse `NT_GNU_BUILD_ID` from `/proc//exe` and attach the normalized hex to runtime events for symbol/debug-store correlation. +* **Sample loaded libs**: read `/proc//maps` and `exe` symlink to collect **actually loaded** DSOs; compute **sha256** for each mapped file (bounded count/size). +* **Record GNU build-id**: parse `NT_GNU_BUILD_ID` from `/proc//exe` and attach the normalized hex to runtime events for symbol/debug-store correlation. * **Posture check** (cheap): * Image signature presence (if cosign policies are local; else ask backend). * SBOM **referrers** presence (HEAD to registry, optional). * Rekor UUID known (query Scanner.WebService by image digest). -* **Publish runtime events** to Scanner.WebService `/runtime/events` (batch & compress). -* **Request delta scan** if: no SBOM in catalog OR base differs from known baseline. - -### 3.2 Privileges & mounts (K8s) +* **Publish runtime events** to Scanner.WebService `/runtime/events` (batch & compress). +* **Request delta scan** if: no SBOM in catalog OR base differs from known baseline. + +### 3.2 Privileges & mounts (K8s) * **SecurityContext:** `runAsUser: 0`, `readOnlyRootFilesystem: true`, `allowPrivilegeEscalation: false`. * **Capabilities:** `CAP_SYS_PTRACE` (optional if using nsenter trace), `CAP_DAC_READ_SEARCH`. @@ -154,22 +154,22 @@ stellaops/zastava-agent # System service; watch Docker events; observer on * `/run/containerd/containerd.sock` (or CRI‑O socket) * `/var/lib/containerd/io.containerd.runtime.v2.task` (rootfs paths & pids) * **Networking:** cluster‑internal egress to Scanner.WebService only. -* **Rate limits:** hard caps for bytes hashed and file count per container to avoid noisy tenants. - -### 3.3 Event batching - -* Buffer ND‑JSON; flush by **N events** or **2 s**. -* Backpressure: local disk ring buffer (50 MB default) if Scanner is temporarily unavailable; drop oldest after cap with **metrics** and **warning** event. - -### 3.4 Build-id capture & validation workflow - -1. When Observer sees a `CONTAINER_START` it dereferences `/proc//exe`, extracts the `NT_GNU_BUILD_ID` note, normalises it to lower-case hex, and sends it as `process.buildId` in the runtime envelope. -2. Scanner.WebService persists the observation and propagates the most recent hashes into `/policy/runtime` responses (`buildIds` list) and policy caches consumed by the webhook/CLI. -3. Release engineering copies the matching `.debug` files into the bundle (`debug/.build-id//.debug`) and publishes `debug/debug-manifest.json` with per-hash digests. Offline Kit packaging reuses those artefacts verbatim (see `ops/offline-kit/mirror_debug_store.py`). -4. Operators resolve symbols by either: - * calling `stellaops-cli runtime policy test --image ` to read the current `buildIds` and then fetching the corresponding `.debug` file from the bundle/offline mirror, or - * piping the hash into `debuginfod-find debuginfo ` when a `debuginfod` service is wired against the mirrored tree. -5. Missing hashes indicate stripped binaries without GNU notes; operators should trigger a rebuild with `-Wl,--build-id` or register a fallback symbol package as described in the runtime operations runbook. +* **Rate limits:** hard caps for bytes hashed and file count per container to avoid noisy tenants. + +### 3.3 Event batching + +* Buffer ND‑JSON; flush by **N events** or **2 s**. +* Backpressure: local disk ring buffer (50 MB default) if Scanner is temporarily unavailable; drop oldest after cap with **metrics** and **warning** event. + +### 3.4 Build-id capture & validation workflow + +1. When Observer sees a `CONTAINER_START` it dereferences `/proc//exe`, extracts the `NT_GNU_BUILD_ID` note, normalises it to lower-case hex, and sends it as `process.buildId` in the runtime envelope. +2. Scanner.WebService persists the observation and propagates the most recent hashes into `/policy/runtime` responses (`buildIds` list) and policy caches consumed by the webhook/CLI. +3. Release engineering copies the matching `.debug` files into the bundle (`debug/.build-id//.debug`) and publishes `debug/debug-manifest.json` with per-hash digests. Offline Kit packaging reuses those artefacts verbatim (see `ops/offline-kit/mirror_debug_store.py`). +4. Operators resolve symbols by either: + * calling `stellaops-cli runtime policy test --image ` to read the current `buildIds` and then fetching the corresponding `.debug` file from the bundle/offline mirror, or + * piping the hash into `debuginfod-find debuginfo ` when a `debuginfod` service is wired against the mirrored tree. +5. Missing hashes indicate stripped binaries without GNU notes; operators should trigger a rebuild with `-Wl,--build-id` or register a fallback symbol package as described in the runtime operations runbook. --- @@ -221,20 +221,20 @@ sequenceDiagram `POST /api/v1/scanner/runtime/events` *(OpTok + DPoP/mTLS)* -* Validates event schema; enforces rate caps by tenant/node; persists to **Mongo** (`runtime.events` capped collection or regular with TTL). +* Validates event schema; enforces rate caps by tenant/node; persists to **PostgreSQL** (`runtime.events` table with TTL-based retention). * Performs **correlation**: * Attach nearest **image SBOM** (inventory/usage) and **BOM‑Index** if known. * If unknown/missing, schedule **delta scan** and return `202 Accepted`. * Emits **derived signals** (usedByEntrypoint per component based on `/proc//maps`). -### 5.2 Policy decision API (for webhook) - -`POST /api/v1/scanner/policy/runtime` - -The webhook reuses the shared runtime stack (`AddZastavaRuntimeCore` + `IZastavaAuthorityTokenProvider`) so OpTok caching, DPoP enforcement, and telemetry behave identically to the observer plane. - -Request: +### 5.2 Policy decision API (for webhook) + +`POST /api/v1/scanner/policy/runtime` + +The webhook reuses the shared runtime stack (`AddZastavaRuntimeCore` + `IZastavaAuthorityTokenProvider`) so OpTok caching, DPoP enforcement, and telemetry behave identically to the observer plane. + +Request: ```json { @@ -273,44 +273,44 @@ Response: ```yaml zastava: - mode: - observer: true - webhook: true - backend: - baseAddress: "https://scanner-web.internal" - policyPath: "/api/v1/scanner/policy/runtime" - requestTimeoutSeconds: 5 - allowInsecureHttp: false - runtime: - authority: - issuer: "https://authority.internal" - clientId: "zastava-observer" - audience: ["scanner","zastava"] - scopes: - - "api:scanner.runtime.write" - refreshSkewSeconds: 120 - requireDpop: true - requireMutualTls: true - allowStaticTokenFallback: false - staticTokenPath: null # Optional bootstrap secret - tenant: "tenant-01" - environment: "prod" - deployment: "cluster-a" - logging: - includeScopes: true - includeActivityTracking: true - staticScope: - plane: "runtime" - metrics: - meterName: "StellaOps.Zastava" - meterVersion: "1.0.0" - commonTags: - cluster: "prod-cluster" - engine: "auto" # containerd|cri-o|docker|auto - procfs: "/host/proc" - collect: - entryTrace: true - loadedLibs: true + mode: + observer: true + webhook: true + backend: + baseAddress: "https://scanner-web.internal" + policyPath: "/api/v1/scanner/policy/runtime" + requestTimeoutSeconds: 5 + allowInsecureHttp: false + runtime: + authority: + issuer: "https://authority.internal" + clientId: "zastava-observer" + audience: ["scanner","zastava"] + scopes: + - "api:scanner.runtime.write" + refreshSkewSeconds: 120 + requireDpop: true + requireMutualTls: true + allowStaticTokenFallback: false + staticTokenPath: null # Optional bootstrap secret + tenant: "tenant-01" + environment: "prod" + deployment: "cluster-a" + logging: + includeScopes: true + includeActivityTracking: true + staticScope: + plane: "runtime" + metrics: + meterName: "StellaOps.Zastava" + meterVersion: "1.0.0" + commonTags: + cluster: "prod-cluster" + engine: "auto" # containerd|cri-o|docker|auto + procfs: "/host/proc" + collect: + entryTrace: true + loadedLibs: true maxLibs: 256 maxHashBytesPerContainer: 64_000_000 maxDepth: 48 @@ -327,49 +327,49 @@ zastava: eventsPerSecond: 50 burst: 200 perNodeQueue: 10_000 - security: - mounts: - containerdSock: "/run/containerd/containerd.sock:ro" - proc: "/proc:/host/proc:ro" - runtimeState: "/var/lib/containerd:ro" -``` - -> Implementation note: both `zastava-observer` and `zastava-webhook` call `services.AddZastavaRuntimeCore(configuration, "")` during start-up to bind the `zastava:runtime` section, enforce validation, and register canonical log scopes + meters. - ---- + security: + mounts: + containerdSock: "/run/containerd/containerd.sock:ro" + proc: "/proc:/host/proc:ro" + runtimeState: "/var/lib/containerd:ro" +``` + +> Implementation note: both `zastava-observer` and `zastava-webhook` call `services.AddZastavaRuntimeCore(configuration, "")` during start-up to bind the `zastava:runtime` section, enforce validation, and register canonical log scopes + meters. + +--- ## 7) Security posture * **AuthN/Z**: Authority OpToks (DPoP preferred) to backend; webhook does **not** require client auth from API server (K8s handles). -* **Least privileges**: read‑only host mounts; optional `CAP_SYS_PTRACE`; **no** host networking; **no** write mounts. -* **Isolation**: never exec untrusted code; nsenter only to **read** `/proc/`. -* **Data minimization**: do not exfiltrate env vars or command arguments unless policy explicitly enables diagnostic mode. -* **Rate limiting**: per‑node caps; per‑tenant caps at backend. -* **Hard caps**: bytes hashed, files inspected, depth of shell parsing. -* **Authority guardrails**: `AddZastavaRuntimeCore` binds `zastava.runtime.authority` and refuses tokens without `aud:` scope; optional knobs (`requireDpop`, `requireMutualTls`, `allowStaticTokenFallback`) emit structured warnings when relaxed. +* **Least privileges**: read‑only host mounts; optional `CAP_SYS_PTRACE`; **no** host networking; **no** write mounts. +* **Isolation**: never exec untrusted code; nsenter only to **read** `/proc/`. +* **Data minimization**: do not exfiltrate env vars or command arguments unless policy explicitly enables diagnostic mode. +* **Rate limiting**: per‑node caps; per‑tenant caps at backend. +* **Hard caps**: bytes hashed, files inspected, depth of shell parsing. +* **Authority guardrails**: `AddZastavaRuntimeCore` binds `zastava.runtime.authority` and refuses tokens without `aud:` scope; optional knobs (`requireDpop`, `requireMutualTls`, `allowStaticTokenFallback`) emit structured warnings when relaxed. --- ## 8) Metrics, logs, tracing -**Observer** - -* `zastava.runtime.events.total{kind}` -* `zastava.runtime.backend.latency.ms{endpoint="events"}` -* `zastava.proc_maps.samples.total{result}` -* `zastava.entrytrace.depth{p99}` -* `zastava.hash.bytes.total` -* `zastava.buffer.drops.total` - -**Webhook** - -* `zastava.admission.decisions.total{decision}` -* `zastava.runtime.backend.latency.ms{endpoint="policy"}` -* `zastava.admission.cache.hits.total` -* `zastava.backend.failures.total` - -**Logs** (structured): node, pod, image digest, decision, reasons. -**Tracing**: spans for observe→batch→post; webhook request→resolve→respond. +**Observer** + +* `zastava.runtime.events.total{kind}` +* `zastava.runtime.backend.latency.ms{endpoint="events"}` +* `zastava.proc_maps.samples.total{result}` +* `zastava.entrytrace.depth{p99}` +* `zastava.hash.bytes.total` +* `zastava.buffer.drops.total` + +**Webhook** + +* `zastava.admission.decisions.total{decision}` +* `zastava.runtime.backend.latency.ms{endpoint="policy"}` +* `zastava.admission.cache.hits.total` +* `zastava.backend.failures.total` + +**Logs** (structured): node, pod, image digest, decision, reasons. +**Tracing**: spans for observe→batch→post; webhook request→resolve→respond. --- @@ -486,20 +486,20 @@ webhooks: --- -## 15) Roadmap - -* **eBPF** option for syscall/library load tracing (kernel‑level, opt‑in). -* **Windows containers** support (ETW providers, loaded modules). -* **Network posture** checks: listening ports vs policy. -* **Live **used‑by‑entrypoint** synthesis**: send compact bitset diff to backend to tighten Usage view. -* **Admission dry‑run** dashboards (simulate block lists before enforcing). - ---- - -## 16) Observability (stub) - -- Runbook + dashboard placeholder for offline import: `operations/observability.md`, `operations/dashboards/zastava-observability.json`. -- Metrics to surface: admission latency p95/p99, allow/deny counts, Surface.Env miss rate, Surface.Secrets failures, Surface.FS cache freshness, drift events. -- Health endpoints: `/health/liveness`, `/health/readiness`, `/status`, `/surface/fs/cache/status` (see runbook). -- Alert hints: deny spikes, latency > 800ms p99, cache freshness lag > 10m, any secrets failure. +## 15) Roadmap + +* **eBPF** option for syscall/library load tracing (kernel‑level, opt‑in). +* **Windows containers** support (ETW providers, loaded modules). +* **Network posture** checks: listening ports vs policy. +* **Live **used‑by‑entrypoint** synthesis**: send compact bitset diff to backend to tighten Usage view. +* **Admission dry‑run** dashboards (simulate block lists before enforcing). + +--- + +## 16) Observability (stub) + +- Runbook + dashboard placeholder for offline import: `operations/observability.md`, `operations/dashboards/zastava-observability.json`. +- Metrics to surface: admission latency p95/p99, allow/deny counts, Surface.Env miss rate, Surface.Secrets failures, Surface.FS cache freshness, drift events. +- Health endpoints: `/health/liveness`, `/health/readiness`, `/status`, `/surface/fs/cache/status` (see runbook). +- Alert hints: deny spikes, latency > 800ms p99, cache freshness lag > 10m, any secrets failure. diff --git a/docs/notifications/operations/README.md b/docs/notifications/operations/README.md deleted file mode 100644 index d7032c554..000000000 --- a/docs/notifications/operations/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Notify Operations Artefacts - -Landing zone for NR4, NR5, and NR8 evidence: quota/backpressure policies, DLQ schema, retry matrix, dashboards, and alert rules. Dashboards live under `operations/dashboards/`, alert configs under `operations/alerts/`. diff --git a/docs/observability/observability.md b/docs/observability/observability.md index fb9b78dc8..51b79b0dc 100644 --- a/docs/observability/observability.md +++ b/docs/observability/observability.md @@ -3,7 +3,7 @@ > **Audience:** Observability Guild, Concelier/Excititor SREs, platform operators. > **Scope:** Metrics, traces, logs, dashboards, and runbooks introduced as part of the Aggregation-Only Contract (AOC) rollout (Sprint 19). -This guide captures the canonical signals emitted by Concelier and Excititor once AOC guards are active. It explains how to consume the metrics in dashboards, correlate traces/logs for incident triage, and operate in offline environments. Pair this guide with the [AOC reference](../ingestion/aggregation-only-contract.md) and [architecture overview](../modules/platform/architecture-overview.md). +This guide captures the canonical signals emitted by Concelier and Excititor once AOC guards are active. It explains how to consume the metrics in dashboards, correlate traces/logs for incident triage, and operate in offline environments. Pair this guide with the [AOC reference](../aoc/aggregation-only-contract.md) and [architecture overview](../modules/platform/architecture-overview.md). --- @@ -215,7 +215,7 @@ Update `docs/assets/dashboards/` with screenshots when Grafana capture pipeline ## 7 · References -- [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../aoc/aggregation-only-contract.md) - [Architecture overview](../modules/platform/architecture-overview.md) - [Console guide](../15_UI_GUIDE.md) - [CLI AOC commands](../modules/cli/guides/cli-reference.md) diff --git a/docs/observability/ui-telemetry.md b/docs/observability/ui-telemetry.md index fa900ebb6..298ac044f 100644 --- a/docs/observability/ui-telemetry.md +++ b/docs/observability/ui-telemetry.md @@ -78,7 +78,7 @@ - `ui.api.fetch` – HTTP fetch to backend; attributes: `service`, `endpoint`, `status`, `networkTime`. - `ui.sse.stream` – Server-sent event subscriptions (status ticker, runs); attributes: `channel`, `connectedMillis`, `reconnects`. - `ui.telemetry.batch` – Browser OTLP flush; attributes: `batchSize`, `success`, `retryCount`. - - `ui.policy.action` – Policy workspace actions (simulate, approve, activate) per `docs/15_UI_GUIDE.md`. + - `ui.policy.action` – Policy workspace actions (simulate, approve, activate) per `docs/15_UI_GUIDE.md`. - **Propagation:** Spans use W3C `traceparent`; gateway echoes header to backend APIs so traces stitch across UI → gateway → service. - **Sampling controls:** `OTEL_TRACES_SAMPLER_ARG` (ratio) and feature flag `telemetry.forceSampling` (sets to 100 % for incident debugging). - **Viewing traces:** Grafana Tempo or Jaeger via collector. Filter by `service.name = stellaops-console`. For cross-service debugging, filter on `correlationId` and `tenant`. @@ -147,13 +147,13 @@ Integrate alerts with Notifier (`ui.alerts`) or existing Ops channels. Tag incid | `OTEL_SERVICE_NAME` | Service tag for traces/logs. Set to `stellaops-console`. | auto | | `CONSOLE_TELEMETRY_SSE_ENABLED` | Enables `/console/telemetry` SSE feed for dashboards. | `true` | -Feature flag changes should be tracked in release notes and mirrored in `docs/15_UI_GUIDE.md` (navigation and workflow expectations). +Feature flag changes should be tracked in release notes and mirrored in `docs/15_UI_GUIDE.md` (navigation and workflow expectations). --- ## 8 · Offline / Air-Gapped Workflow -- Mirror the console image and telemetry collector as part of the Offline Kit (see `/docs/install/docker.md` §4). +- Mirror the console image and telemetry collector as part of the Offline Kit (see `/docs/operations/console-docker-install.md` §4). - Scrape metrics locally via `curl -k https://console.local/metrics > metrics.prom`; archive alongside logs for audits. - Use `stella offline kit import` to keep the downloads manifest in sync; dashboards display staleness using `ui_download_manifest_refresh_seconds`. - When collectors are unavailable, console queues OTLP batches (up to 5 min) and exposes backlog through `ui_telemetry_queue_depth`; export queue metrics to prove no data loss. @@ -171,7 +171,7 @@ Feature flag changes should be tracked in release notes and mirrored in `docs/15 - [ ] DPoP/fresh-auth anomalies correlated with Authority audit logs during drill. - [ ] Offline capture workflow exercised; evidence stored in audit vault. - [ ] Screenshots of Grafana dashboards committed once they stabilise (update references). -- [ ] Cross-links verified (`docs/deploy/console.md`, `docs/security/console-security.md`, `docs/15_UI_GUIDE.md`). +- [ ] Cross-links verified (`docs/deploy/console.md`, `docs/security/console-security.md`, `docs/15_UI_GUIDE.md`). --- @@ -179,10 +179,10 @@ Feature flag changes should be tracked in release notes and mirrored in `docs/15 - `/docs/deploy/console.md` – Metrics endpoint, OTLP config, health checks. - `/docs/security/console-security.md` – Security metrics & alert hints. -- `docs/15_UI_GUIDE.md` – Console workflows and offline posture. +- `docs/15_UI_GUIDE.md` – Console workflows and offline posture. - `/docs/observability/observability.md` – Platform-wide practices. - `/ops/telemetry-collector.md` & `/ops/telemetry-storage.md` – Collector deployment. -- `/docs/install/docker.md` – Compose/Helm environment variables. +- `/docs/operations/console-docker-install.md` – Compose/Helm environment variables. --- diff --git a/docs/overview.md b/docs/overview.md index 2654dff02..6fdce8e04 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -36,4 +36,4 @@ Stella Ops delivers **deterministic, sovereign container security** that works - Ready to pull the containers? Head to [quickstart.md](quickstart.md). - Want the capability detail? Browse the five cards in [key-features.md](key-features.md). -- Need to evaluate fit and build a rollout plan? Grab the [evaluation checklist](evaluate/checklist.md). +- Need to evaluate fit and build a rollout plan? Grab the [evaluation checklist](onboarding/evaluation-checklist.md). diff --git a/docs/quickstart.md b/docs/quickstart.md index 96bb8015c..8a4545ab9 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -95,4 +95,4 @@ stella scan image \ - Harden the deployment with [`17_SECURITY_HARDENING_GUIDE.md`](17_SECURITY_HARDENING_GUIDE.md). - Explore feature highlights in [`key-features.md`](key-features.md). -- Plan the rollout using the [evaluation checklist](evaluate/checklist.md). +- Plan the rollout using the [evaluation checklist](onboarding/evaluation-checklist.md). diff --git a/docs/reachability/lattice.md b/docs/reachability/lattice.md index d127be755..a27516b7e 100644 --- a/docs/reachability/lattice.md +++ b/docs/reachability/lattice.md @@ -113,7 +113,7 @@ When evidence is missing or confidence is low, the correct output is **under inv ## 8. Roadmap (tracked in Sprint 0401) -- Introduce first-class uncertainty state lists + entropy-derived `riskScore` (see `docs/uncertainty/README.md`). +- Introduce first-class uncertainty state lists + entropy-derived `riskScore` (see `uncertainty-entropy.md`). - Extend evidence refs to include CAS/DSSE pointers for graph-level and edge-bundle attestations. --- diff --git a/docs/reachability/policy-gate.md b/docs/reachability/policy-gate.md index c0b0a8080..ac678cfbf 100644 --- a/docs/reachability/policy-gate.md +++ b/docs/reachability/policy-gate.md @@ -37,7 +37,7 @@ Guards VEX status transitions based on the v1 lattice state (see `docs/reachabil ### 2.2 Uncertainty Tier Gate -Guards VEX status transitions based on the uncertainty tier (see `docs/uncertainty/README.md` §1.1). +Guards VEX status transitions based on the uncertainty tier (see `uncertainty-entropy.md` §1.1). | Requested VEX Status | Uncertainty Tier | Gate Action | |---------------------|------------------|-------------| @@ -256,7 +256,7 @@ Alert conditions: ## 10. Related Documents - [Lattice Model](./lattice.md) — v1 formal 7-state lattice -- [Uncertainty States](../uncertainty/README.md) — Tier definitions and risk scoring +- [Uncertainty States](uncertainty-entropy.md) — Tier definitions and risk scoring - [Evidence Schema](./evidence-schema.md) — richgraph-v1 schema - [VEX Contract](../contracts/vex-v1.md) — VEX document schema diff --git a/docs/scripts/sbom-vex/README.md b/docs/scripts/sbom-vex/README.md index 62893e005..aacdbe737 100644 --- a/docs/scripts/sbom-vex/README.md +++ b/docs/scripts/sbom-vex/README.md @@ -7,7 +7,7 @@ Contents (stub): - `chain-hash-recipe.md` – canonicalisation steps - `inputs.lock` – pinned tool versions and snapshot - `proof-manifest.json` – chain hash placeholder -- `sbom-vex-blueprint.svg` – diagram placeholder +- ~~`sbom-vex-blueprint.svg`~~ – archived (empty placeholder) Next steps: - Add real SBOM/VEX samples and Rekor bundle snapshot. diff --git a/docs/security/authority-scopes.md b/docs/security/authority-scopes.md index 9a14d2671..8098a7957 100644 --- a/docs/security/authority-scopes.md +++ b/docs/security/authority-scopes.md @@ -374,7 +374,7 @@ tenants: ## 6 · References -- [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md) +- [Aggregation-Only Contract reference](../aoc/aggregation-only-contract.md) - [Architecture overview](../modules/platform/architecture-overview.md) - [Concelier architecture](../modules/concelier/architecture.md) - [Excititor architecture](../modules/excititor/architecture.md) diff --git a/docs/security/console-security.md b/docs/security/console-security.md index 5df530882..39c3ea2a6 100644 --- a/docs/security/console-security.md +++ b/docs/security/console-security.md @@ -52,17 +52,17 @@ The console client is registered in Authority as `console-ui` with scopes: | Policy approvals | `policy:read`, `policy:review`, `policy:approve`, `policy:operate`, `policy:simulate` | `policy:operate` (promote/activate/run) requires fresh-auth. | | Observability panes (status ticker, telemetry) | `ui.telemetry`, `scheduler:runs.read`, `advisory:read`, `vex:read` | `ui.telemetry` drives OTLP export toggles. | | Orchestrator dashboard (queues, workers, rate limits) | `orch:read` | Provision via `Orch.Viewer` role; read-only access to job state and telemetry. | -| Orchestrator control actions (pause/resume, retry, sync-now) | `orch:operate` (plus `orch:read`) | CLI/Console must request tokens with `operator_reason` and `operator_ticket`; Authority denies issuance when either value is missing. | -| Orchestrator backfill runs | `orch:backfill` (plus `orch:read`, `orch:operate`) | Backfill tokens require `backfill_reason` (≤256 chars) and `backfill_ticket` (≤128 chars); Authority stores both alongside operator metadata in audit events. | -| Orchestrator quota & burst controls | `orch:quota` (plus `orch:read`, `orch:operate`) | Tokens must include `quota_reason` (≤256 chars); optional `quota_ticket` (≤128 chars) is captured for audit. | +| Orchestrator control actions (pause/resume, retry, sync-now) | `orch:operate` (plus `orch:read`) | CLI/Console must request tokens with `operator_reason` and `operator_ticket`; Authority denies issuance when either value is missing. | +| Orchestrator backfill runs | `orch:backfill` (plus `orch:read`, `orch:operate`) | Backfill tokens require `backfill_reason` (≤256 chars) and `backfill_ticket` (≤128 chars); Authority stores both alongside operator metadata in audit events. | +| Orchestrator quota & burst controls | `orch:quota` (plus `orch:read`, `orch:operate`) | Tokens must include `quota_reason` (≤256 chars); optional `quota_ticket` (≤128 chars) is captured for audit. | | Downloads parity (SBOM, attestation) | `downloads:read`, `attestation:verify`, `sbom:export` | Console surfaces digests only; download links require CLI parity for write operations. | Guidance: -- **Role mapping**: Provision Authority role `role/ui-console-admin` encapsulating the admin scopes above. -- **Orchestrator viewers**: Assign Authority role `role/orch-viewer` (Authority role string `Orch.Viewer`) to consoles that require read-only access to Orchestrator telemetry. -- **Orchestrator operators**: Assign Authority role `role/orch-operator` (Authority role string `Orch.Operator`) to identities allowed to pause/resume jobs. Tokens must include `operator_reason` (≤256 chars) and `operator_ticket` (≤128 chars); Authority records the values in audit logs. -- **Orchestrator admins**: Assign Authority role `role/orch-admin` (Authority role string `Orch.Admin`) to the handful of identities permitted to raise/lower quotas or trigger backfills. Tokens must include `quota_reason` (≤256 chars) and `backfill_reason` (≤256 chars), plus the corresponding ticket fields (`quota_ticket`, `backfill_ticket`, ≤128 chars each) so audit streams capture the change record. +- **Role mapping**: Provision Authority role `role/ui-console-admin` encapsulating the admin scopes above. +- **Orchestrator viewers**: Assign Authority role `role/orch-viewer` (Authority role string `Orch.Viewer`) to consoles that require read-only access to Orchestrator telemetry. +- **Orchestrator operators**: Assign Authority role `role/orch-operator` (Authority role string `Orch.Operator`) to identities allowed to pause/resume jobs. Tokens must include `operator_reason` (≤256 chars) and `operator_ticket` (≤128 chars); Authority records the values in audit logs. +- **Orchestrator admins**: Assign Authority role `role/orch-admin` (Authority role string `Orch.Admin`) to the handful of identities permitted to raise/lower quotas or trigger backfills. Tokens must include `quota_reason` (≤256 chars) and `backfill_reason` (≤256 chars), plus the corresponding ticket fields (`quota_ticket`, `backfill_ticket`, ≤128 chars each) so audit streams capture the change record. - **Tenant enforcement**: Gateway injects `X-Stella-Tenant` from token claims. Requests missing the header must be rejected by downstream services (Concelier, Excititor, Policy Engine) and logged. - **Separation of duties**: Never grant `ui.admin` and `policy:approve`/`policy:operate` to the same human role without SOC sign-off; automation accounts should use least-privilege dedicated clients. @@ -171,15 +171,15 @@ Document gaps and remediation hooks in `SEC5.*` backlog as they are addressed. ## 9 · Compliance checklist -- [x] Authority client `console-ui` registered with PKCE, DPoP, tenant claim requirement, and scopes from §3. (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#authority-client-validation)) -- [x] CSP enforced per §4 with overrides documented in deployment manifests. (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#csp-enforcement)) -- [x] Fresh-auth timer (300 s) validated for admin and policy actions; audit events captured. (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#fresh-auth-timer)) -- [x] DPoP binding tested (replay attempt blocked; logs show `ui_dpop_failure_total` increment). (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#dpop-binding-test)) -- [x] Offline mode exercises performed (banner, CLI guidance, manifest verification). (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#offline-mode-exercise)) -- [x] Evidence download parity verified with CLI scripts; console never caches sensitive artefacts. (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#evidence-parity)) -- [x] Monitoring dashboards show metrics and alerts outlined in §6; alert runbooks reviewed with Security Guild. (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#monitoring--alerts)) -- [x] Security review sign-off recorded in sprint log with links to Authority threat model references. (see [console security sign-off](../updates/2025-10-27-console-security-signoff.md#sign-off)) -- [x] `/console` Authority endpoints validated for tenant header enforcement, fresh-auth prompts, and introspection flows (Audit IDs `authority.console.tenants.read`, `authority.console.profile.read`, `authority.console.token.introspect`). (see [console security sign-off](../updates/2025-10-31-console-security-refresh.md)) +- [x] Authority client `console-ui` registered with PKCE, DPoP, tenant claim requirement, and scopes from §3. (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#authority-client-validation)) +- [x] CSP enforced per §4 with overrides documented in deployment manifests. (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#csp-enforcement)) +- [x] Fresh-auth timer (300 s) validated for admin and policy actions; audit events captured. (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#fresh-auth-timer)) +- [x] DPoP binding tested (replay attempt blocked; logs show `ui_dpop_failure_total` increment). (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#dpop-binding-test)) +- [x] Offline mode exercises performed (banner, CLI guidance, manifest verification). (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#offline-mode-exercise)) +- [x] Evidence download parity verified with CLI scripts; console never caches sensitive artefacts. (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#evidence-parity)) +- [x] Monitoring dashboards show metrics and alerts outlined in §6; alert runbooks reviewed with Security Guild. (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#monitoring--alerts)) +- [x] Security review sign-off recorded in sprint log with links to Authority threat model references. (see [console security sign-off](../implplan/archived/updates/2025-10-27-console-security-signoff.md#sign-off)) +- [x] `/console` Authority endpoints validated for tenant header enforcement, fresh-auth prompts, and introspection flows (Audit IDs `authority.console.tenants.read`, `authority.console.profile.read`, `authority.console.token.introspect`). (see [console security sign-off](../implplan/archived/updates/2025-10-31-console-security-refresh.md)) --- diff --git a/docs/technical/architecture/component-map.md b/docs/technical/architecture/component-map.md index a2e4c9f2d..a0a630433 100644 --- a/docs/technical/architecture/component-map.md +++ b/docs/technical/architecture/component-map.md @@ -4,7 +4,7 @@ Concise descriptions of every top-level component under `src/`, summarising the ## 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`. +- **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/aoc/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/16_VEX_CONSENSUS_GUIDE.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`). @@ -40,7 +40,7 @@ Concise descriptions of every top-level component under `src/`, summarising the - **TimelineIndexer** — Builds timelines of evidence/events for forensics and audit tooling (`docs/forensics/timeline.md`). ## Notification & UI -- **Notifier** — Current notifications studio (WebService + Worker under `src/Notifier/StellaOps.Notifier`) delivering rule evaluation, digests, incidents, and channel plug-ins. Built on the shared `StellaOps.Notify.*` libraries; see `docs/notifications/overview.md` and `src/Notifier/StellaOps.Notifier/docs/NOTIFY-SVC-38-001-FOUNDATIONS.md`. +- **Notifier** — Current notifications studio (WebService + Worker under `src/Notifier/StellaOps.Notifier`) delivering rule evaluation, digests, incidents, and channel plug-ins. Built on the shared `StellaOps.Notify.*` libraries; see `docs/modules/notify/overview.md` and `src/Notifier/StellaOps.Notifier/docs/NOTIFY-SVC-38-001-FOUNDATIONS.md`. - **Notify (shared libraries / archival hosts)** — The former `StellaOps.Notify.WebService|Worker` hosts were archived on 2025-10-26. The directory now provides the reusable engine, storage, queue, and connector plug-ins that Notifier composes. Legacy guidance in `docs/modules/notify/architecture.md` remains as migration context until the Notifications Studio docs fully supersede it. - **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). diff --git a/docs/technical/development/README.md b/docs/technical/development/README.md index 540656b11..959b35478 100644 --- a/docs/technical/development/README.md +++ b/docs/technical/development/README.md @@ -28,5 +28,4 @@ Resources for contributors building features, plug-ins, connectors, and tests. - [../examples/policies/README.md](../../examples/policies/README.md) – sample policy bundles. - Console UI development: `docs/modules/ui/README.md` and `docs/modules/ui/architecture.md`. - [../task-packs/](../../task-packs/) – reusable task templates for sprints. -- [../faq/policy-faq.md](../../faq/policy-faq.md) – policy author FAQ. -- [../faq/](../../faq/) – additional Q&A sets useful during development. +- [../policy/faq.md](../../policy/faq.md) – policy author FAQ. diff --git a/docs/technical/interfaces/README.md b/docs/technical/interfaces/README.md index 2dfbb6b15..85c649e8f 100644 --- a/docs/technical/interfaces/README.md +++ b/docs/technical/interfaces/README.md @@ -28,9 +28,9 @@ Specifications covering APIs, data contracts, event envelopes, and enforcement m - [../observability/policy.md](../../observability/policy.md) and [../observability/ui-telemetry.md](../../observability/ui-telemetry.md) – telemetry event guidance. ## Ingestion & Evidence Contracts -- [../ingestion/aggregation-only-contract.md](../../ingestion/aggregation-only-contract.md) – Aggregation-Only Contract reference. +- [aggregation-only-contract.md](../../aoc/aggregation-only-contract.md) – Aggregation-Only Contract reference. - [../aoc/aoc-guardrails.md](../../aoc/aoc-guardrails.md) – guardrails checklist. -- [../advisories/aggregation.md](../../advisories/aggregation.md) – advisory observation schema. +- [observations-linksets.md](../../modules/concelier/observations-linksets.md) – advisory observation schema. - [../vex/aggregation.md](../../vex/aggregation.md) – VEX observation schema. - [../../modules/concelier/operations/connectors/](../../modules/concelier/operations/connectors/) – connector-specific payload notes. diff --git a/docs/technical/observability/README.md b/docs/technical/observability/README.md index 30dd07b0e..bc0e6d01c 100644 --- a/docs/technical/observability/README.md +++ b/docs/technical/observability/README.md @@ -16,10 +16,10 @@ Guides for capturing metrics, logs, traces, and delivering notifications. - [../../modules/export-center/provenance-and-signing.md](../../modules/export-center/provenance-and-signing.md) – provenance event integration. ## Notifications Studio -- [../notifications/overview.md](../../notifications/overview.md) – architecture and channels. -- [../notifications/rules.md](../../notifications/rules.md) – rule authoring. -- [../notifications/templates.md](../../notifications/templates.md) – template management. -- [../notifications/digests.md](../../notifications/digests.md) – digest scheduling. +- [../../modules/notify/overview.md](../../modules/notify/overview.md) – architecture and channels. +- [../../modules/notify/rules.md](../../modules/notify/rules.md) – rule authoring. +- [../../modules/notify/templates.md](../../modules/notify/templates.md) – template management. +- [../../modules/notify/digests.md](../../modules/notify/digests.md) – digest scheduling. - [../../modules/notify/architecture.md](../../modules/notify/architecture.md) & [../../modules/notify/implementation_plan.md](../../modules/notify/implementation_plan.md) – implementation detail. ## Metrics & Dashboards diff --git a/docs/technical/operations/README.md b/docs/technical/operations/README.md index 66d4a71bc..dd1ddf165 100644 --- a/docs/technical/operations/README.md +++ b/docs/technical/operations/README.md @@ -4,7 +4,7 @@ Deployment, runtime operations, and air-gap playbooks for running Stella Ops i ## Install & Upgrade - [../21_INSTALL_GUIDE.md](../../21_INSTALL_GUIDE.md) – canonical install guide (Docker, air-gap considerations). -- [../install/docker.md](../../install/docker.md) – Docker install recipes. +- [../operations/console-docker-install.md](../../operations/console-docker-install.md) – Docker install recipes. - [../deploy/containers.md](../../deploy/containers.md) – container deployment guidance for AOC environments. - [../deploy/console.md](../../deploy/console.md) – console deployment specifics. - [../13_RELEASE_ENGINEERING_PLAYBOOK.md](../../13_RELEASE_ENGINEERING_PLAYBOOK.md) – release automation, signing, reproducibility. @@ -31,8 +31,8 @@ Deployment, runtime operations, and air-gap playbooks for running Stella Ops i ## Module Runbooks & Ops Guides - Module operations directories under [../../modules/](../../modules/) (Authority backups/monitoring, Concelier connectors, Scanner analyzers, Scheduler worker dashboards, Export Center runbook, DevOps launch readiness, Telemetry collector/storage, etc.). - [../runtime/SCANNER_RUNTIME_READINESS.md](../../runtime/SCANNER_RUNTIME_READINESS.md) – runtime readiness checklist. -- Notifications Studio operations: see [../notifications/architecture.md](../../notifications/architecture.md), [../notifications/overview.md](../../notifications/overview.md), [../notifications/rules.md](../../notifications/rules.md), [../notifications/templates.md](../../notifications/templates.md), [../notifications/digests.md](../../notifications/digests.md). -- Additional notification flows: [../notifications/pack-approvals-integration.md](../../notifications/pack-approvals-integration.md). +- Notifications Studio operations: see [../modules/notify/architecture.md](../../modules/notify/architecture.md), [../modules/notify/overview.md](../../modules/notify/overview.md), [../modules/notify/rules.md](../../modules/notify/rules.md), [../modules/notify/templates.md](../../modules/notify/templates.md), [../modules/notify/digests.md](../../modules/notify/digests.md). +- Additional notification flows: [../modules/notify/pack-approvals-integration.md](../../modules/notify/pack-approvals-integration.md). - Observability operations: [../observability/observability.md](../../observability/observability.md), [../observability/ui-telemetry.md](../../observability/ui-telemetry.md). ## DevOps & Release Automation diff --git a/docs/technical/process/README.md b/docs/technical/process/README.md index c2473bffa..913bfca23 100644 --- a/docs/technical/process/README.md +++ b/docs/technical/process/README.md @@ -15,8 +15,8 @@ Use these artefacts to understand team ownership, active workstreams, and histor ## Communication & Updates - Architecture decision records: [../adr/index.md](../../adr/index.md) (template in [../adr/0000-template.md](../../adr/0000-template.md)). - RFCs in flight: [../rfcs/authority-plugin-ldap.md](../../rfcs/authority-plugin-ldap.md). -- Release notes & updates: [../updates/](../../updates/). -- Frequently asked questions: [../faq/](../../faq/). +- Release notes & updates: [../implplan/archived/updates/](../../implplan/archived/updates/). +- Policy FAQ: [../policy/faq.md](../../policy/faq.md). - Examples and golden data: [../examples/](../../examples/), [../events/samples/](../../events/samples/). ## Supporting References diff --git a/docs/technical/security/README.md b/docs/technical/security/README.md index 57a210c99..e8716373f 100644 --- a/docs/technical/security/README.md +++ b/docs/technical/security/README.md @@ -32,4 +32,4 @@ Authoritative sources for threat models, governance, compliance, and security op ## Supporting Material - Module operations security notes: [../../modules/authority/operations/key-rotation.md](../../modules/authority/operations/key-rotation.md), [../../modules/concelier/operations/authority-audit-runbook.md](../../modules/concelier/operations/authority-audit-runbook.md), [../../modules/zastava/README.md](../../modules/zastava/README.md) (runtime enforcement). - [../observability/policy.md](../../observability/policy.md) – security-relevant telemetry for policy. -- [../updates/2025-10-27-console-security-signoff.md](../../updates/2025-10-27-console-security-signoff.md) & [../updates/2025-10-31-console-security-refresh.md](../../updates/2025-10-31-console-security-refresh.md) – recent security sign-offs. +- [../implplan/archived/updates/2025-10-27-console-security-signoff.md](../../implplan/archived/updates/2025-10-27-console-security-signoff.md) & [../implplan/archived/updates/2025-10-31-console-security-refresh.md](../../implplan/archived/updates/2025-10-31-console-security-refresh.md) – recent security sign-offs.