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

feat: Document completed tasks across multiple components
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- Added completed tasks documentation for Scheduler WebService, ImpactIndex, Models, Queue, Storage.Mongo, Worker, Signals, Signer, UI, Zastava.Observer, Zastava.Webhook, Zastava.Core, Cryptography.Kms, Cryptography, and Plugin.
- Each task includes ID, status, owners, dependencies, descriptions, and exit criteria to ensure clarity and traceability.
- Enhanced integration and unit testing coverage across various components to validate functionality and compliance with specifications.
This commit is contained in:
Vladimir Moushkov
2025-10-30 18:20:31 +02:00
parent a77eb92fee
commit 691028fe69
312 changed files with 6399 additions and 3319 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.gitea/workflows/build-test-deploy.yml
View File

@@ -70,6 +70,9 @@ jobs:
- name: Validate NuGet restore source ordering
run: python3 ops/devops/validate_restore_sources.py
- name: Validate telemetry storage configuration
run: python3 ops/devops/telemetry/validate_storage_stack.py
- name: Setup .NET ${{ env.DOTNET_VERSION }}
uses: actions/setup-dotnet@v4
with:

3
.gitea/workflows/release.yml
View File

@@ -47,6 +47,9 @@ jobs:
- name: Validate NuGet restore source ordering
run: python3 ops/devops/validate_restore_sources.py
- name: Validate telemetry storage configuration
run: python3 ops/devops/telemetry/validate_storage_stack.py
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3

1
NuGet.config
View File

@@ -38,6 +38,7 @@
<package pattern="Microsoft.Extensions.*" />
<package pattern="Microsoft.AspNetCore.*" />
<package pattern="Microsoft.Data.Sqlite" />
<package pattern="Microsoft.OpenApi*" />
<package pattern="System.Diagnostics.*" />
</packageSource>
<packageSource key="nuget.org">

3
deploy/telemetry/storage/README.md
View File

@@ -24,6 +24,9 @@ These configurations are referenced by the Docker Compose overlay
connected environments. Place the Prometheus bearer token in `auth/token` when using the
Compose overlay (the directory contains a `.gitkeep` placeholder and is gitignored by default).
Run `python ops/devops/telemetry/validate_storage_stack.py` after editing any of these files to
ensure TLS, multitenancy, and override references remain intact.
## Security
- Both Tempo and Loki require mutual TLS.

77
docs/01_WHAT_IS_IT.md
View File

@@ -1,77 +0,0 @@
# 1 · What Is - **Stella Ops**?
Stella Ops is a **self‑hosted, SBOM‑first DevSecOps platform** that gives engineering and security teams instant (< 5 s) feedback on container and artifact risk—even when they run completely offline.
It is built around five design pillars: **modular, open, fast, local, and UI‑controllable**.
---
## 1. What the Product Does — 7‑Point Snapshot
| # | Capability | What It Means in Practice |
|---|------------|---------------------------|
| **1** | **SBOM‑Centric Scanning** | Generates and scans *Software Bills of Materials* (Trivy JSON, SPDX‑JSON, CycloneDX‑JSON); auto‑detects format and stores each SBOM as a blob. |
| **2** | **Delta‑SBOM Engine** | Uploads SBOM only for *new* layers; warm‑cache image rescans complete in < 1 s. |
| **3** | **Anonymous Internal Registry** | Ships a built‑in `StellaOps.Registry` so agents (`Stella CLI`, `Zastava`, SBOM‑builder) can be pulled inside air‑gapped networks without external credentials. |
| **4** | **Policy‑as‑Code** | Supports YAML rules today and OPA/Rego (`StellaOps.MutePolicies`) tomorrow—edit in the web UI, versioned in Mongo, enforce at scan time. |
| **5** | **Pluggable Modules** | Every scanner, exporter, or attestor is a hot‑load .NET plug‑in (e.g., `StellaOpsAttestor` for SLSA/Rekor in the roadmap). |
| **6** | **Horizontally Scalable** | Stateless API backed by Redis & Mongo; optional Kubernetes charts for multi‑node performance. |
| **7** | **Sovereign & Localized** | Localized UI, optional connectors to regional catalogues, and zero telemetry by default—ready for high‑compliance, air‑gapped deployments. |
> **🆓 Free tier update (July 2025)** – Every self‑hosted instance now includes **{{ quota_token }} scans per UTC day**.
> A yellow banner appears once you cross **200 scans** (≈ 60 % of quota).
> Past {{ quota_token }} , `/scan` responds with soft 5 s waits (graceful back‑off), and may return **429 + Retry‑After (to UTC midnight)** after repeated hits.
---
## 2. How It Works — End‑to‑End Flow (30 sec tour)
1. **Build Phase**
`sbom‑builder` container runs inside CI, pulls base layers metadata, and queries `/layers/missing`—receiving in ~20 ms which layers still need SBOMs.
• New layers ➟ SBOM generated ➟ `*.sbom.<type>` + `*.sbom.type` dropped next to image tarball.
2. **Push to Registry**
Image and SBOM blobs are pushed to the **anonymous internal registry** (`StellaOps.Registry`). Cosign tags are attached if enabled.
3. **Scan Phase**
`Stella CLI` agent pulls the SBOM blob, sends `/scan?sbomType=spdx-json` to backend. If flag is absent, backend auto‑detects.
• Free‑tier tokens inherit the **333‑scan/day quota**; response headers expose remaining scans and reset time.
4. **Policy & Risk Evaluation**
Backend hydrates CVE data, merges any cached layer scores, and calls the **Policy‑as‑Code engine**:
* YAML rules → built‑in interpreter;
* Rego policies (future) → embedded OPA.
5. **Attestation & Transparency** *(Roadmap)*
`StellaOpsAttestor` signs results with SLSA provenance and records them in a local **Rekor** mirror for tamper‑proof history.
6. **Feedback Loop**
• CLI exits with non‑zero on policy block.
• UI dashboard shows findings, quota banner, and per‑token scan counters; triagers can mute or set expiry dates directly.
---
## 3. Why Such a Product Is Needed
> *“Software supply‑chain attacks have increased **742 %** over the past three years.”* – Sonatype 2024 State of the Software Supply Chain
### Key Drivers & Regulations
| Driver | Detail & Obligation |
|--------|--------------------|
| **Government SBOM Mandates** | • **US EO 14028** & NIST SP 800‑218 require suppliers to provide SBOMs.<br>• EU **Cyber Resilience Act (CRA)** will demand attestations of secure development by 2026. |
| **SLSA & SSDF Frameworks** | Industry pushes toward **SLSA v1.0** levels 2‑3 and NIST **SSDF 1.1** controls, emphasising provenance and policy enforcement. |
| **Transparency Logs** | **Sigstore Rekor** gains traction as a standard for tamper‑evident signatures—even for air‑gapped replicas. |
| **Offline & Sovereign Deployments** | Critical‑infra operators (finance, telecom, defence) must run security tooling without Internet and with local language/VDB support. |
| **Performance Expectations** | Modern CI/CD pipelines trigger hundreds of image builds daily; waiting 30‑60 s per scan is no longer acceptable—and now **must be achieved within a 333‑scan/day free quota**. |
### Gap in Existing Tools
* SaaS‑only scanners can’t run in regulated or disconnected environments.
* Monolithic open‑source scanners are hard‑wired to Trivy or Syft formats, lacking delta optimisation.
* Few products expose **Policy‑as‑Code** with full UI editing **and** history audit in a single package.
* None address quota‑aware throttling without hidden paywalls.
**Stella Ops** fills this gap by combining *speed*, *modular openness*, *sovereign readiness* **and transparent quota limits**—making thorough supply‑chain security attainable for every team, not just cloud‑native startups.
---
*Last updated: 14 Jul 2025*

121
docs/02_WHY.md
View File

@@ -1,121 +0,0 @@
# 2 · WHY — Why Stella Ops Exists
> Explaining the concrete pain we solve, why the world needs **one more** DevSecOps
> platform, and the success signals that prove we are on the right track.
Software‑supply‑chain attacks, licence‑risk, and incomplete SBOM coverage slow
teams and compliance audits to a crawl. Most existing scanners:
* **Assume Internet** access for CVE feeds or SaaS back‑ends.
* **Parse an entire image** every build (no layer‑delta optimisation).
* **Accept a single SBOM format** (usually Trivy JSON) and choke on anything else.
* Offer **no built‑in policy history / audit trail**.
* Require 30‑60 s wall‑time per scan, an order of magnitude slower than modern CI
expectations.
* **Hide quota limits** or throttle without warning once you move past free trials.
---
# 1 Free‑Tier Quota — Why **{{ quota_token }} **?
The limit of **{{ quota_token }} SBOM scans per UTC day** was not chosen at random.
| Constraint | Analysis | Outcome |
|------------|----------|---------|
| **SMB workload** | Internal survey across 37 SMBs shows median **210** container builds/day (p95 ≈ 290). | {{ quota_token }} gives ≈ 1.6 × head‑room without forcing a paid tier. |
| **Cost of feeds** | Hosting, Trivy DB mirrors & CVE merge traffic average **≈ $14 / 1 000 scans**. | {{ quota_token }} /day yields <$5 infra cost per user — sustainable for an OSS project. |
| **Incentive to upgrade** | Larger orgs (> 300 builds/day) gain ROI from Plus/Pro tiers anyway. | Clear upsell path without hurting hobbyists. |
> **In one sentence:**  *{{ quota_token }} scans cover the daily needs of a typical small /
> medium business, keep free usage genuinely useful and still leave a financial
> runway for future development*.
## 1.1 How the Quota Is Enforced (1‑minute view)
* Backend loads the **Quota plug‑in** at startup.
* Every `/scan` call passes the caller’s **Client‑JWT** to the plug‑in.
* The plug‑in **increments a counter in Redis** under
`quota:<token>:<yyyy‑mm‑dd>` (expires at UTC midnight).
* Soft wait‑wall (5 s) after limit; hard wait‑wall (60 s) after 30 blocked calls.
* For **offline installs**, a *1‑month validity Client‑JWT* ships inside every
**Offline Update Kit (OUK)** tarball. Uploading the OUK refreshes the token
automatically.
Detailed sequence living in **30_QUOTA_ENFORCEMENT_FLOW.md**.
---
## 2 · Why *Another* DevSecOps Product? — Macro Drivers
| Driver | Evidence | Implication for Tooling |
|--------|----------|-------------------------|
| **Exploding supply‑chain attacks** | Sonatype 2024 report shows **742 %** growth since 2020. | SBOMs & provenance checks must be default, not “best‑practice”. |
| **Regulation tsunami** | • US EO 14028 & NIST SP 800‑218<br>• EU Cyber‑Resilience Act (CRA) in force 2026<br>• Local critical‑infrastructure rules in some jurisdictions | Vendors must *attest* build provenance (SLSA) and store tamper‑proof SBOMs. |
| **Runtime‑cost intolerance** | Pipelines build hundreds of images/day; waiting > 10 s per scan breaks SLA. | Need **delta‑aware** engines that reuse layer analyses (< 1 s warm scans). |
| **Air‑gap & sovereignty demands** | Finance/defence prohibit outbound traffic; data must stay on‑prem. | Ship **self‑contained registry + CVE DB** and run offline. |
| **Predictable free‑tier limits** | Teams want clarity, not surprise throttling. | Provide **transparent {{ quota_token }} scans/day quota**, early banner & graceful wait‑wall. |
> **Therefore:** The market demands a **modular, SBOM‑first, sub‑5 s, 100 % self‑hosted**
> platform **with a transparent free‑tier quota**—precisely the niche Stella Ops targets.
---
## 3 · Gap in Current Tooling
* Trivy / Syft create SBOMs but re‑analyse **every** layer → wasted minutes/day.
* Policy engines (OPA/Rego) are separate binaries, with no UI or change history.
* No mainstream OSS bundle ships an **anonymous internal registry** for air‑gapped pulls.
* Provenance attestation (SLSA) and Rekor transparency logs remain “bring‑your‑own”.
* Free tiers either stop at 100 scans **or** silently throttle; none announce a **clear {{ quota_token }} /day allowance**.
---
## 4 · Why Stella Ops Can Win
1. **Speed First** — Delta‑SBOM flow uses cached layers to hit `< 1 s` warm scans.
2. **Multi‑Format Ready** — Auto‑detects Trivy‑JSON, SPDX‑JSON, CycloneDX‑JSON; UI
lets teams choose per‑project defaults.
3. **Offline by Default** — Ships an **anonymous internal Docker registry**
(`StellaOps.Registry`) plus Redis, Mongo, CVE DB, and UI in a single compose up.
4. **Open & Modular** — .NET hot‑load plug‑ins (`StellaOpsAttestor`, future scanners)
under AGPL; anyone can extend.
5. **Policy as Code** — YAML rules today, upgrade path to OPA/Rego with history stored
in Mongo via `StellaOps.MutePolicies`.
6. **Sovereign‑Ready** — Russian‑language UI, local vulnerability mirrors, zero
telemetry by default.
7. **Honest Free‑tier Boundaries** — Clear **{{ quota_token }} scans/day** limit, early banner at 200 and predictable wait‑wall—no hidden throttling.
---
## 5 · Success Criteria — Signals We Solve the Problem
* **Performance:** P95 scan < 5 s on first pass; `< 1 s` for warm delta scans.
* **Compatibility:** SBOMs in at least three formats consumed by ≥ 3 downstream tools.
* **Adoption:** ≥ 1 000 reported installs & ≥ 2 000 binary downloads by Q2‑2026.
* **Compliance:** Positive audits referencing CRA / NIST / SLSA readiness.
* **Community:** ≥ 15 first‑time contributors merged per quarter by 2026.
* **Transparency:** 0 support tickets complaining about “mystery throttling”.
---
## 6 · Non‑Goals (2025‑2027)
* Multi‑tenant SaaS offering.
* Automatic “fix‑PR” generation (left to ecosystem).
* Windows container **scanning** (Windows *agents* are on the 12‑month roadmap).
---
## 7 · Stakeholder Pain‑Point Recap
| Persona | Pain Today | Stella Ops Solution |
|---------|------------|---------------------|
| **Dev** | “My CI fails for 45 s on every push.” | < 5 s initial, < 1 s warm scans. |
| **Sec‑Ops** | Separate tools for SBOM, policy, and audit. | Unified UI + YAML / Rego policies with history. |
| **Infra** | Internet‑blocked site; no public pulls allowed. | Offline compose bundle + internal registry. |
| **Compliance** | Need CRA‑ready provenance by 2026. | Future `StellaOpsAttestor` SLSA + Rekor integration. |
| **Budget owner** | Fears hidden overage charges in “free” tiers. | Transparent {{ quota_token }} scans/day limit, visible in UI/API. |
---
*Last updated: 14 Jul 2025 (sync with free‑tier quota rev 2.0).*

156
docs/03_QUICKSTART.md
View File

@@ -1,156 +0,0 @@
# Five‑Minute Quick‑Start ⚡
Run your first container scan locally
> **Heads‑up** – the public α `v0.1.0` image drops **late 2025**.
> Once it is published as
> `registry.stella-ops.org/stella-ops/stella-ops:0.1.0‑alpha`
> every command on this page works without changes.
---
## 0 · What you need 🔧
| Requirement | Minimum | Notes |
|-------------|---------|-------|
| OS | Ubuntu 22.04 • Alma 9 | x86‑64 or arm64 |
| Docker | Engine 25 • Compose v2 | `docker -v` |
| CPU / RAM | 2 vCPU / 2 GiB | Dev‑laptop baseline |
| Disk | 10 GiB SSD | SBOM cache |
> **Tip –** If you already have Redis & MongoDB, skip the infra
> compose file and point Stella Ops at those hosts via `.env`.
---
## 1 · Fetch the signed Compose bundles 📦
```bash
# Infrastructure (Redis + MongoDB)
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml.sig
# Core scanner stack
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml.sig
# Verify signatures (supply‑chain 101)
cosign verify-blob --key https://stella-ops.org/keys/cosign.pub \
--signature docker-compose.infrastructure.yml.sig docker-compose.infrastructure.yml
cosign verify-blob --key https://stella-ops.org/keys/cosign.pub \
--signature docker-compose.stella-ops.yml.sig docker-compose.stella-ops.yml
````
---
## 2 · Create `.env` 🗝️
```bash
# ─── Identity (shows in reports) ───────────────────────────
STELLA_OPS_COMPANY_NAME="Acme Corp"
STELLA_OPS_ISSUER_EMAIL="ops@acme.example"
STELLA_OPS_DEFAULT_ADMIN_USERNAME="admin"
STELLA_OPS_DEFAULT_ADMIN_PASSWORD="changeme!"
STELLA_OPS_DEFAULT_JWT="" # or load it later with
# docker --env-file .env compose -f docker-compose.stella-ops.yml exec stella set-jwt <JWT_FROM_EMAIL>
# ─── Database secrets ──────────────────────────────────────
MONGO_INITDB_ROOT_USERNAME=stella_admin
MONGO_INITDB_ROOT_PASSWORD=$(openssl rand -base64 18)
MONGO_URL=mongodb
REDIS_PASSWORD=$(openssl rand -base64 18)
REDIS_URL=redis
```
---
## 3 · Start the supporting services 🗄️
```bash
docker compose --env-file .env -f docker-compose.infrastructure.yml pull
docker compose --env-file .env -f docker-compose.infrastructure.yml up -d
```
---
## 4 · Launch Stella Ops 🚀
```bash
docker compose --env-file .env -f docker-compose.stella-ops.yml pull
docker compose --env-file .env -f docker-compose.stella-ops.yml up -d
```
*Point your browser at* **`https://<host>:8443`** – the certificate is
self‑signed in the alpha.
Default credentials: **`admin / changeme`** (rotate immediately!).
---
## 5 · Run a scan 🔍
```bash
docker compose --env-file .env -f docker-compose.stella-ops.yml \
exec stella-ops stella scan alpine:3.20
```
* First scan downloads CVE feeds (\~ 50 MB).
* Warm scans finish in **≈ 5 s** on a 4‑vCPU host thanks to the Δ‑SBOM engine.
---
## 6 · Reload or add a token later 🔄
```bash
# After adding STELLA_JWT to .env …
docker compose --env-file .env -f docker-compose.stella-ops.yml \
exec stella-ops stella jwt <JWT_FROM_EMAIL>
```
*Anonymous mode* → **{{ quota_anon }} scans/day**
*Token mode* → **{{ quota_token }} scans/day**
At **10 % of the daily max** a polite reminder appears; after {{ quota_token }} the server applies a **soft 5 s back‑off** and may return **429 + Retry‑After** until the daily reset.
---
## 7 · Typical next steps ➡️
| Task | Where to look |
| ---------------------------------------- | ------------------------------------------------------------------- |
| CI pipelines (GitHub / GitLab / Jenkins) | [`docs/ci/`](ci/) |
| Air‑gapped install | [Offline Update Kit](10_OFFLINE_KIT.md) |
| Feature overview | [20\_FEATURES.md](20_FEATURES.md) |
| Governance & licence | [`LICENSE.md`](LICENSE.md) • [`11_GOVERNANCE.md`](11_GOVERNANCE.md) |
---
## 8 · Uninstall / cleanup 🧹
```bash
docker compose --env-file .env -f docker-compose.stella-ops.yml down -v
docker compose --env-file .env -f docker-compose.infrastructure.yml down -v
rm compose-*.yml compose-*.yml.sig .env
```
---
### Licence & provenance 📜
Stella Ops is **AGPL‑3.0‑or‑later**. Every release ships:
* **Cosign‑signed** container images
* A full **SPDX 2.3** SBOM
```bash
cosign verify \
--key https://stella-ops.org/keys/cosign.pub \
registry.stella-ops.org/stella-ops/stella-ops:<VERSION>
```
---
© 2025‑2026 Stella Ops – free / libre / open‑source.

2
docs/04_FEATURE_MATRIX.md
View File

@@ -1,6 +1,8 @@
# 4 · Feature Matrix — **Stella Ops**
*(rev 2.0 · 14 Jul 2025)*
> **Looking for a quick read?** Check [`key-features.md`](key-features.md) for the short capability cards; this matrix keeps full tier-by-tier detail.
| Category | Capability | Free Tier (≤ 333 scans / day) | Community Plug‑in | Commercial Add‑On | Notes / ETA |
| ---------------------- | ------------------------------------- | ----------------------------- | ----------------- | ------------------- | ------------------------------------------ |
| **SBOM Ingestion** | Trivy‑JSON, SPDX‑JSON, CycloneDX‑JSON | ✅ | — | — | Auto‑detect on upload |

6
docs/05_SYSTEM_REQUIREMENTS_SPEC.md
View File

@@ -11,17 +11,17 @@ Stella Ops · self‑hosted supply‑chain‑security platform
## 1 · Purpose & Scope
This SRS defines everything the **v0.8‑beta** release of _Stella Ops_ must do, **including the Free‑tier daily quota of {{ quota_token }} SBOM scans per token**.
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
* [02_WHY.md](02_WHY.md) – market gap & problem statement
* [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
* [08_MODULE_SPECIFICATIONS.md](08_MODULE_SPECIFICATIONS.md) – component APIs & plug‑in contracts
* [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
---

2
docs/07_HIGH_LEVEL_ARCHITECTURE.md
View File

@@ -1,5 +1,7 @@
# High‑Level Architecture — **Stella Ops** (Consolidated • 2025Q4)
> **Want the 10-minute tour?** See [`high-level-architecture.md`](high-level-architecture.md); this file retains the exhaustive reference.
> **Purpose.** A complete, implementation‑ready map of Stella Ops: product vision, all runtime components, trust boundaries, tokens/licensing, control/data flows, storage, APIs, security, scale, DevOps, and verification logic.
> **Scope.** This file **replaces** the separate `components.md`; all component details now live here.

2
docs/10_OFFLINE_KIT.md
View File

@@ -82,7 +82,7 @@ store as `STELLA_JWT` in **`.env`**.
| **v0.4 RC (Q3 2026)** | LDAP/AD SSO • registry scanner GA |
| **v1.0 GA (Q4 2026)** | Custom TLS/crypto adaptors (**incl. SM2**)—enabled where law or security requires it |
Full details live in the public [Road‑map](../roadmap/README.md).
Full details live in the public [Road‑map](05_ROADMAP.md).
---

4
docs/11_GOVERNANCE.md
View File

@@ -49,7 +49,7 @@ Approval is recorded via Git forge review or a signed commit trailer
* 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](../roadmap/README.md).
* Release cadence is fixed – see [public Road‑map](05_ROADMAP.md).
* Security fixes may create out‑of‑band `x.y.z‑hotfix` tags.
---
@@ -59,7 +59,7 @@ Approval is recorded via Git forge review or a signed commit trailer
| Situation | Escalation |
|-----------|------------|
| Technical deadlock | **Maintainer Summit** (recorded & published) |
| Security bug | Follow [Security Policy](../security/01_SECURITY_POLICY.md) |
| Security bug | Follow [Security Policy](13_SECURITY_POLICY.md) |
| Code of Conduct violation | See `12_CODE_OF_CONDUCT.md` escalation ladder |
---

2
docs/12_CODE_OF_CONDUCT.md
View File

@@ -31,7 +31,7 @@ If anything here conflicts with the upstream covenant, *our additions win*.
| Channel | When to use |
|---------|-------------|
| `conduct@stella-ops.org` (PGP key [`keys/#pgp`](../keys/#pgp)) | **Primary, confidential** – anything from micro‑aggressions to serious harassment |
| `conduct@stella-ops.org` (PGP key [`keys/#pgp`](https://stella-ops.org/keys/#pgp)) | **Primary, confidential** – anything from micro‑aggressions to serious harassment |
| Matrix `/msg @coc-bot:libera.chat` | Quick, in‑chat nudge for minor issues |
| Public issue with label `coc` | Transparency preferred and **you feel safe** doing so |

2
docs/12_PERFORMANCE_WORKBOOK.md
View File

@@ -143,7 +143,7 @@ P99 = 48 ms. Meets 50 ms gate.
## 8 Trend Snapshot
![Perf trend spark‑line placeholder](perf‑trend.svg)
> _Perf trend spark‑line screenshot pending upload._
> **Grafana/Alerting** – Import `docs/modules/scanner/operations/analyzers-grafana-dashboard.json` and point it at the Prometheus datasource storing `scanner_analyzer_bench_*` metrics. Configure an alert on `scanner_analyzer_bench_regression_ratio` ≥ 1.20 (default limit); the bundled Stat panel surfaces breached scenarios (non-zero values). On-call runbook: `docs/modules/scanner/operations/analyzers.md`.

6
docs/13_SECURITY_POLICY.md
View File

@@ -21,7 +21,7 @@ Pre‑GA lines receive **critical** and **high**‑severity fixes only.
| Channel | PGP‑encrypted? | Target SLA |
|---------|---------------|-----------|
| `security@stella-ops.org` | **Yes** – PGP key: [`/keys/#pgp`](../keys/#pgp) | 72 h acknowledgement |
| `security@stella-ops.org` | **Yes** – PGP key: [`/keys/#pgp`](https://stella-ops.org/keys/#pgp) | 72 h acknowledgement |
| Matrix DM → `@sec‑bot:libera.chat` | Optional | 72 h acknowledgement |
| Public issue with label `security` | No (for non‑confidential flaws) | 7 d acknowledgement |
@@ -65,8 +65,8 @@ We aim for **30 days** from report to release for critical/high issues; medium
| Purpose | Fingerprint | Where to fetch |
|---------|-------------|----------------|
| **PGP (sec‑team)** | `3A5C ​71F3 ​... ​7D9B` | [`/keys/#pgp`](../keys/#pgp) |
| **Cosign release key** | `AB12 ... EF90` | [`/keys/#cosign`](../keys/#cosign) |
| **PGP (sec‑team)** | `3A5C ​71F3 ​... ​7D9B` | [`/keys/#pgp`](https://stella-ops.org/keys/#pgp) |
| **Cosign release key** | `AB12 ... EF90` | [`/keys/#cosign`](https://stella-ops.org/keys/#cosign) |
Verify all downloads (TLS 1.3 by default; 1.2 allowed only via a custom TLS provider such as GOST):

173
docs/README.md
View File

@@ -1,157 +1,38 @@
# Stella Ops
# Stella Ops
> **Self‑hosted, SBOM‑first DevSecOps platform – offline‑friendly, AGPL‑3.0, free up to {{ quota_token }} scans per UTC day (soft delay only, never blocks).**
> Stella Ops is the sovereign, SBOM‑first security platform that proves every container decision with deterministic scans, explainable policy verdicts, and offline‑ready provenance.
Stella Ops lets you discover container vulnerabilities in **< 5 s** without sending a single byte outside your network.
Everything here is open‑source and versioned — when you check out a git tag, the docs match the code you are running.
- **Sovereign by design** – bring your own trust roots, vulnerability advisory sources, VEX sources, regional crypto, and Offline Update Kits that never phone home.
- **Deterministic + replayable** – every scan can be reproduced bit‑for‑bit with DSSE + OpenVEX evidence.
- **Actionable signal** – lattice logic ranks exploitability, and the policy engine lets you tailor VEX handling, muting, and expiration rules for your environment.
---
**Proof points:** SBOM dependency and vulnerability dependency cartographing work, deterministic replay manifests, lattice policy UI with OpenVEX, and post‑quantum trust packs ready for regulated sectors.
## 🚀 Start here (first 60 minutes)
## Choose Your Path
| Step | What you will learn | Doc |
|------|--------------------|-----|
| 1 ️⃣ | 90‑second elevator pitch & pillars | **[What Is Stella Ops?](01_WHAT_IS_IT.md)** |
| 2 ️⃣ | Pain points it solves | **[Why Does It Exist?](02_WHY.md)** |
| 3 ️⃣ | Install & run a scan in 10 min | **[Install Guide](21_INSTALL_GUIDE.md)** |
| 4 ️⃣ | Components & data‑flow | **[High‑Level Architecture](07_HIGH_LEVEL_ARCHITECTURE.md)** |
| 5 ️⃣ | Integrate the CLI / REST API | **[API & CLI Reference](09_API_CLI_REFERENCE.md)** |
| 6 ️⃣ | Vocabulary used throughout the docs | **[Glossary](14_GLOSSARY_OF_TERMS.md)** |
| If you want to… | Open this | Read time |
|-----------------|-----------|-----------|
| Understand the promise and pain we solve | `overview.md` | ≈ 2 min |
| Run a first scan and see the CLI | `quickstart.md` | ≈ 5 min |
| Browse key capabilities at a glance | `key-features.md` | ≈ 3 min |
| Check architecture, road to production, or evaluate fit | See “Dig deeper” below | ≤ 30 min curated set |
---
## Explore the Essentials
## 📚 Complete Table of Contents
1. **Value in context** – [Overview](overview.md) compresses the “Why” + “What” stories and shows how Stella Ops stands apart.
2. **Try it fast** – [Quickstart](quickstart.md) walks through fetching the signed bundles, configuring `.env`, and verifying the first scan.
3. **Feature confidence** – [Key Features](key-features.md) gives five capability cards covering Delta SBOM, VEX‑first policy, Sovereign crypto, Deterministic replay, and Transparent quotas.
4. **Up‑next checkpoints** – [Evaluation checklist](evaluate/checklist.md) helps teams plan Day‑0 to Day‑30 adoption milestones.
<details>
<summary>Click to expand the full docs index</summary>
## Dig Deeper (curated reading)
### Overview
- **01 – [What Is Stella Ops?](01_WHAT_IS_IT.md)**
- **02 – [Why Does It Exist?](02_WHY.md)**
- **03 – [Vision & Road‑map](03_VISION.md)**
- **04 – [Feature Matrix](04_FEATURE_MATRIX.md)**
- **Install & operations:** [Installation guide](21_INSTALL_GUIDE.md), [Offline Update Kit](24_OFFLINE_KIT.md), [Security hardening](17_SECURITY_HARDENING_GUIDE.md).
- **Architecture & modules:** [High‑level architecture](high-level-architecture.md), [Module dossiers](modules/platform/architecture-overview.md), [Strategic differentiators](moat.md).
- **Policy & governance:** [Policy templates](60_POLICY_TEMPLATES.md), [Legal & quota FAQ](29_LEGAL_FAQ_QUOTA.md), [Governance charter](11_GOVERNANCE.md).
- **UI & glossary:** [Console guide](15_UI_GUIDE.md), [Accessibility](accessibility.md), [Glossary](14_GLOSSARY_OF_TERMS.md).
- **Technical documentation:** [Full technical index](technical/README.md) for architecture, APIs, module dossiers, and operations playbooks.
- **FAQs & readiness:** [FAQ matrix](23_FAQ_MATRIX.md), [Roadmap (external)](https://stella-ops.org/roadmap/), [Release engineering playbook](13_RELEASE_ENGINEERING_PLAYBOOK.md).
### Reference & concepts
- **05 – [System Requirements Specification](05_SYSTEM_REQUIREMENTS_SPEC.md)**
- **07 – [High‑Level Architecture](07_HIGH_LEVEL_ARCHITECTURE.md)**
- **08 – [Architecture Decision Records](adr/index.md)**
- **08 – Module Architecture Dossiers**
- [Architecture Overview](modules/platform/architecture-overview.md)
- [Scanner](modules/scanner/architecture.md)
- [Concelier](modules/concelier/architecture.md)
- [Excititor](modules/excititor/architecture.md)
- [Excititor Mirrors](modules/excititor/mirrors.md)
- [Signer](modules/signer/architecture.md)
- [Attestor](modules/attestor/architecture.md)
- [Authority](modules/authority/architecture.md)
- [Policy Engine](modules/policy/architecture.md)
- [Notify](modules/notify/architecture.md)
- [Scheduler](modules/scheduler/architecture.md)
- [CLI](modules/cli/architecture.md)
- [Web UI](modules/ui/architecture.md)
- [Zastava Runtime](modules/zastava/architecture.md)
- [Release & Operations](modules/devops/architecture.md)
- **09 – [API & CLI Reference](09_API_CLI_REFERENCE.md)**
- **10 – [Plug‑in SDK Guide](10_PLUGIN_SDK_GUIDE.md)**
- **10 – [Concelier CLI Quickstart](10_CONCELIER_CLI_QUICKSTART.md)**
- **10 – [BuildX Generator Quickstart](dev/BUILDX_PLUGIN_QUICKSTART.md)**
- **10 – [Scanner Cache Configuration](dev/SCANNER_CACHE_CONFIGURATION.md)**
- **30 – [Excititor Connector Packaging Guide](dev/30_EXCITITOR_CONNECTOR_GUIDE.md)**
- **31 – [Aggregation-Only Contract Reference](ingestion/aggregation-only-contract.md)**
- **31 – [Advisory Observations & Linksets](advisories/aggregation.md)**
- **31 – [VEX Observations & Linksets](vex/aggregation.md)**
- **32 – [Entry-Point Detection Playbook](modules/scanner/operations/entrypoint.md)**
- **30 – Developer Templates**
- [Excititor Connector Skeleton](dev/templates/excititor-connector/)
- **11 – [Authority Service](11_AUTHORITY.md)**
- **11 – [Data Schemas](11_DATA_SCHEMAS.md)**
- **12 – [Performance Workbook](12_PERFORMANCE_WORKBOOK.md)**
- **13 – [Release‑Engineering Playbook](13_RELEASE_ENGINEERING_PLAYBOOK.md)**
- **20 – [CLI AOC Commands Reference](modules/cli/guides/cli-reference.md)**
- **20 – [Console CLI Parity Matrix](cli-vs-ui-parity.md)**
- **60 – [Policy Engine Overview](policy/overview.md)**
- **61 – [Policy DSL Grammar](policy/dsl.md)**
- **62 – [Policy Lifecycle & Approvals](policy/lifecycle.md)**
- **63 – [Policy Runs & Orchestration](policy/runs.md)**
- **64 – [Policy Exception Effects](policy/exception-effects.md)**
- **65 – [Policy Engine REST API](api/policy.md)**
- **66 – [Policy CLI Guide](modules/cli/guides/policy.md)**
- **67 – [Policy Editor Workspace](ui/policy-editor.md)**
- **68 – [Policy Observability](observability/policy.md)**
- **69 – [Console Observability](observability/ui-telemetry.md)**
- **70 – [Policy Governance & Least Privilege](security/policy-governance.md)**
- **70a – [Policy Gateway](policy/gateway.md)**
- **71 – [Policy Examples](examples/policies/README.md)**
- **72 – [Policy FAQ](faq/policy-faq.md)**
- **73 – [Policy Run DTOs](../src/Scheduler/__Libraries/StellaOps.Scheduler.Models/docs/SCHED-MODELS-20-001-POLICY-RUNS.md)**
- **30 – [Fixture Maintenance](dev/fixtures.md)**
- **74 – [Export Center Overview](modules/export-center/overview.md)**
- **75 – [Export Center Architecture](modules/export-center/architecture.md)**
- **76 – [Export Center Profiles](modules/export-center/profiles.md)**
- **77 – [Export Center API Reference](modules/export-center/api.md)**
- **78 – [Export Center CLI Guide](modules/export-center/cli.md)**
- **79 – [Export Center Trivy Adapters](modules/export-center/trivy-adapter.md)**
- **80 – [Export Center Mirror Bundles](modules/export-center/mirror-bundles.md)**
- **81 – [Export Center Provenance & Signing](modules/export-center/provenance-and-signing.md)**
Need more? The full documentation tree – ADRs, per‑module operations, schemas, developer references – stays untouched under the existing directories (`modules/`, `api/`, `dev/`, `ops/`), ready when you are.
### User & operator guides
- **14 – [Glossary](14_GLOSSARY_OF_TERMS.md)**
- **15 – [UI Guide](15_UI_GUIDE.md)**
- **16 – [Console AOC Dashboard](ui/console.md)**
- **16 – [Console Accessibility Guide](accessibility.md)**
- **17 – [Security Hardening Guide](17_SECURITY_HARDENING_GUIDE.md)**
- **17 – [Console Security Posture](security/console-security.md)**
- **18 – [Coding Standards](18_CODING_STANDARDS.md)**
- **19 – [Test‑Suite Overview](19_TEST_SUITE_OVERVIEW.md)**
- **21 – [Install Guide](21_INSTALL_GUIDE.md)**
- **21 – [Docker Install Recipes](install/docker.md)**
- **22 – [CI/CD Recipes Library](ci/20_CI_RECIPES.md)**
- **23 – [FAQ](23_FAQ_MATRIX.md)**
- **24 – [Offline Update Kit Admin Guide](24_OFFLINE_KIT.md)**
- **25 – [Mirror Operations Runbook](ops/concelier-mirror-operations.md)**
- **26 – [Concelier Apple Connector Operations](ops/concelier-apple-operations.md)**
- **27 – [Authority Key Rotation Playbook](ops/authority-key-rotation.md)**
- **28 – [Concelier CCCS Connector Operations](ops/concelier-cccs-operations.md)**
- **29 – [Concelier CISA ICS Connector Operations](ops/concelier-icscisa-operations.md)**
- **30 – [Concelier CERT-Bund Connector Operations](ops/concelier-certbund-operations.md)**
- **31 – [Concelier MSRC Connector – AAD Onboarding](ops/concelier-msrc-operations.md)**
- **32 – [Scanner Analyzer Bench Operations](ops/scanner-analyzers-operations.md)**
- **33 – [Scanner Artifact Store Migration](ops/scanner-rustfs-migration.md)**
- **34 – [Zastava Runtime Operations Runbook](ops/zastava-runtime-operations.md)**
- **35 – [Launch Readiness Checklist](ops/launch-readiness.md)**
- **36 – [Launch Cutover Runbook](ops/launch-cutover.md)**
- **37 – [Registry Token Service](ops/registry-token-service.md)**
- **37 – [Deployment Upgrade & Rollback Runbook](ops/deployment-upgrade-runbook.md)**
- **38 – [Policy Schema Export Automation](devops/policy-schema-export.md)**
- **40 – [Observability Guide (AOC)](observability/observability.md)**
- **41 – [Telemetry Collector Deployment](ops/telemetry-collector.md)**
- **42 – [Telemetry Storage Deployment](ops/telemetry-storage.md)**
- **43 – [Authority Scopes & Tenancy](security/authority-scopes.md)**
- **44 – [Container Deployment (AOC)](deploy/containers.md)**
- **45 – [Export Center Operations Runbook](operations/export-runbook.md)**
### Notifications Studio
- **81 – [Notifications Overview](notifications/overview.md)**
- **82 – [Notifications Architecture](notifications/architecture.md)**
- **83 – [Notifications Rules](notifications/rules.md)**
- **84 – [Notifications Templates](notifications/templates.md)**
- **85 – [Notifications Digests](notifications/digests.md)**
### Legal & licence
- **32 – [Legal & Quota FAQ](29_LEGAL_FAQ_QUOTA.md)**
</details>
---
## 🧹 Backlog hygiene
> Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
- **Aggregation-Only Contract (AOC).** Ingestion services aggregate and link facts only—derived precedence, severity, and safe-fix hints live in Policy overlays and dedicated explorers. Review [`implplan/AGENTS.md`](implplan/AGENTS.md) and the AOC guardrails in [`aoc/aoc-guardrails.md`](aoc/aoc-guardrails.md).
- **Cartographer owns graphs.** SBOM Service emits projections/events; Cartographer (`CARTO-GRAPH-21-00x`) builds graph storage, overlays, and tiles. See `modules/concelier/architecture.md` (Cartographer handshake section) for handoff boundaries.
- **Notifier replaces legacy Notify.** Sprint‑15 `StellaOps.Notify.*` tasks are frozen; use the Notifications Studio/Notifier backlogs (`NOTIFY-SVC-38..40`, `WEB-NOTIFY-3x-00x`, `CLI-NOTIFY-3x-00x`).
- **Dedicated services for Vuln & Policy.** Vuln Explorer work flows through `src/VulnExplorer/StellaOps.VulnExplorer.Api`/Console/CLI (Sprint 29); gateway routes proxy only. Policy Engine remains the sole source for precedence/suppression overlays.
- **Cleanup log.** The backlog consolidation summary lives in [`backlog/2025-10-cleanup.md`](backlog/2025-10-cleanup.md).
© 2025 Stella Ops contributors – licensed AGPL‑3.0‑or‑later
© 2025 Stella Ops contributors – AGPL‑3.0‑or‑later

88
docs/TASKS.completed.md Normal file
View File

@@ -0,0 +1,88 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-VISITOR-30-001 | DONE (2025-10-30) | Docs Guild | — | Reorganize visitor-facing documentation (README, overview, quickstart, key features) for rapid evaluation flow. | ✅ New visitor doc stack published; ✅ README links updated; ✅ Legacy pages slotted into deeper-read tier. |
| DOC7.README-INDEX | DONE (2025-10-17) | Docs Guild | — | Refresh index docs (docs/README.md + root README) after architecture dossier split and Offline Kit overhaul. | ✅ ToC reflects new component architecture docs; ✅ root README highlights updated doc set; ✅ Offline Kit guide linked correctly. |
| DOC4.AUTH-PDG | DONE (2025-10-19) | Docs Guild, Plugin Team | PLG6.DOC | Copy-edit `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md`, export lifecycle diagram, add LDAP RFC cross-link. | ✅ PR merged with polish; ✅ Diagram committed; ✅ Slack handoff posted. |
| DOC1.AUTH | DONE (2025-10-12) | Docs Guild, Authority Core | CORE5B.DOC | Draft `docs/11_AUTHORITY.md` covering architecture, configuration, bootstrap flows. | ✅ Architecture + config sections approved by Core; ✅ Samples reference latest options; ✅ Offline note added. |
| DOC3.Concelier-Authority | DONE (2025-10-12) | Docs Guild, DevEx | FSR4 | Polish operator/runbook sections (DOC3/DOC5) to document Concelier authority rollout, bypass logging, and enforcement checklist. | ✅ DOC3/DOC5 updated with audit runbook references; ✅ enforcement deadline highlighted; ✅ Docs guild sign-off. |
| DOC5.Concelier-Runbook | DONE (2025-10-12) | Docs Guild | DOC3.Concelier-Authority | Produce dedicated Concelier authority audit runbook covering log fields, monitoring recommendations, and troubleshooting steps. | ✅ Runbook published; ✅ linked from DOC3/DOC5; ✅ alerting guidance included. |
| FEEDDOCS-DOCS-05-001 | DONE (2025-10-11) | Docs Guild | FEEDMERGE-ENGINE-04-001, FEEDMERGE-ENGINE-04-002 | Publish Concelier conflict resolution runbook covering precedence workflow, merge-event auditing, and Sprint 3 metrics. | ✅ `docs/modules/concelier/operations/conflict-resolution.md` committed; ✅ metrics/log tables align with latest merge code; ✅ Ops alert guidance handed to Concelier team. |
| FEEDDOCS-DOCS-05-002 | DONE (2025-10-16) | Docs Guild, Concelier Ops | FEEDDOCS-DOCS-05-001 | Ops sign-off captured: conflict runbook circulated, alert thresholds tuned, and rollout decisions documented in change log. | ✅ Ops review recorded; ✅ alert thresholds finalised using `docs/modules/concelier/operations/authority-audit-runbook.md`; ✅ change-log entry linked from runbook once GHSA/NVD/OSV regression fixtures land. |
| DOCS-ADR-09-001 | DONE (2025-10-19) | Docs Guild, DevEx | — | Establish ADR process (`docs/adr/0000-template.md`) and document usage guidelines. | Template published; README snippet linking ADR process; announcement posted (`docs/updates/2025-10-18-docs-guild.md`). |
| DOCS-EVENTS-09-002 | DONE (2025-10-19) | Docs Guild, Platform Events | SCANNER-EVENTS-15-201 | Publish event schema catalog (`docs/events/`) for `scanner.report.ready@1`, `scheduler.rescan.delta@1`, `attestor.logged@1`. | Schemas validated (Ajv CI hooked); docs/events/README summarises usage; Platform Events notified via `docs/updates/2025-10-18-docs-guild.md`. |
| DOCS-EVENTS-09-003 | DONE (2025-10-19) | Docs Guild | DOCS-EVENTS-09-002 | Add human-readable envelope field references and canonical payload samples for published events, including offline validation workflow. | Tables explain common headers/payload segments; versioned sample payloads committed; README links to validation instructions and samples. |
| DOCS-EVENTS-09-004 | DONE (2025-10-19) | Docs Guild, Scanner WebService | SCANNER-EVENTS-15-201 | Refresh scanner event docs to mirror DSSE-backed report fields, document `scanner.scan.completed`, and capture canonical sample validation. | Schemas updated for new payload shape; README references DSSE reuse and validation test; samples align with emitted events. |
| PLATFORM-EVENTS-09-401 | DONE (2025-10-21) | Platform Events Guild | DOCS-EVENTS-09-003 | Embed canonical event samples into contract/integration tests and ensure CI validates payloads against published schemas. | Notify models tests now run schema validation against `docs/events/*.json`, event schemas allow optional `attributes`, and docs capture the new validation workflow. |
| RUNTIME-GUILD-09-402 | DONE (2025-10-19) | Runtime Guild | SCANNER-POLICY-09-107 | Confirm Scanner WebService surfaces `quietedFindingCount` and progress hints to runtime consumers; document readiness checklist. | Runtime verification run captures enriched payload; checklist/doc updates merged; stakeholders acknowledge availability. |
| DOCS-CONCELIER-07-201 | DONE (2025-10-22) | Docs Guild, Concelier WebService | FEEDWEB-DOCS-01-001 | Final editorial review and publish pass for Concelier authority toggle documentation (Quickstart + operator guide). | Review feedback resolved, publish PR merged, release notes updated with documentation pointer. |
| DOCS-RUNTIME-17-004 | DONE (2025-10-26) | Docs Guild, Runtime Guild | SCANNER-EMIT-17-701, ZASTAVA-OBS-17-005, DEVOPS-REL-17-002 | Document build-id workflows: SBOM exposure, runtime event payloads (`process.buildId`), Scanner `/policy/runtime` response (`buildIds` list), debug-store layout, and operator guidance for symbol retrieval. | Architecture + operator docs updated with build-id sections (Observer, Scanner, CLI), examples show `readelf` output + debuginfod usage, references linked from Offline Kit/Release guides + CLI help. |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-AOC-19-001 | DONE (2025-10-26) | Docs Guild, Concelier Guild | CONCELIER-WEB-AOC-19-001, EXCITITOR-WEB-AOC-19-001 | Author `/docs/ingestion/aggregation-only-contract.md` covering philosophy, invariants, schemas, error codes, migration, observability, and security checklist. | New doc published with compliance checklist; cross-links from existing docs added. |
| DOCS-AOC-19-002 | DONE (2025-10-26) | Docs Guild, Architecture Guild | DOCS-AOC-19-001 | Update `/docs/modules/platform/architecture-overview.md` to include AOC boundary, raw stores, and sequence diagram (fetch → guard → raw insert → policy evaluation). | Overview doc updated with diagrams/text; lint passes; stakeholders sign off. |
| DOCS-AOC-19-003 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-AOC-19-003 | Refresh `/docs/modules/policy/architecture.md` clarifying ingestion boundary, raw inputs, and policy-only derived data. | Doc highlights raw-only ingestion contract, updated diagrams merge, compliance checklist added. |
| DOCS-AOC-19-004 | DONE (2025-10-26) | Docs Guild, UI Guild | UI-AOC-19-001 | Extend `/docs/ui/console.md` with Sources dashboard tiles, violation drill-down workflow, and verification action. | UI doc updated with screenshots/flow descriptions, compliance checklist appended. |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-POLICY-20-001 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-ENGINE-20-000 | Author `/docs/policy/overview.md` covering concepts, inputs/outputs, determinism, and compliance checklist. | Doc published with diagrams + glossary; lint passes; checklist included. |
| DOCS-POLICY-20-002 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-ENGINE-20-001 | Write `/docs/policy/dsl.md` with grammar, built-ins, examples, anti-patterns. | DSL doc includes grammar tables, examples, compliance checklist; validated against parser tests. |
| DOCS-POLICY-20-003 | DONE (2025-10-26) | Docs Guild, Authority Core | AUTH-POLICY-20-001 | Publish `/docs/policy/lifecycle.md` describing draft→approve workflow, roles, audit, compliance list. | Lifecycle doc linked from UI/CLI help; approvals roles documented; checklist appended. |
| DOCS-POLICY-20-004 | DONE (2025-10-26) | Docs Guild, Scheduler Guild | SCHED-MODELS-20-001 | Create `/docs/policy/runs.md` detailing run modes, incremental mechanics, cursors, replay. | Run doc includes sequence diagrams + compliance checklist; cross-links to scheduler docs. |
| DOCS-POLICY-20-005 | DONE (2025-10-26) | Docs Guild, BE-Base Platform Guild | WEB-POLICY-20-001 | Draft `/docs/api/policy.md` describing endpoints, schemas, error codes. | API doc validated against OpenAPI; examples included; checklist appended. |
| DOCS-POLICY-20-006 | DONE (2025-10-26) | Docs Guild, DevEx/CLI Guild | CLI-POLICY-20-002 | Produce `/docs/modules/cli/guides/policy.md` with command usage, exit codes, JSON output contracts. | CLI doc includes examples, exit codes, compliance checklist. |
| DOCS-POLICY-20-007 | DONE (2025-10-26) | Docs Guild, UI Guild | UI-POLICY-20-001 | Document `/docs/ui/policy-editor.md` covering editor, simulation, diff workflows, approvals. | UI doc includes screenshots/placeholders, accessibility notes, compliance checklist. |
| DOCS-POLICY-20-008 | DONE (2025-10-26) | Docs Guild, Architecture Guild | POLICY-ENGINE-20-003 | Write `/docs/modules/policy/architecture.md` (new epic content) with sequence diagrams, selection strategy, schema. | Architecture doc merged with diagrams; compliance checklist appended; references updated. |
| DOCS-POLICY-20-009 | DONE (2025-10-26) | Docs Guild, Observability Guild | POLICY-ENGINE-20-007 | Add `/docs/observability/policy.md` for metrics/traces/logs, sample dashboards. | Observability doc includes metrics tables, dashboard screenshots, checklist. |
| DOCS-POLICY-20-010 | DONE (2025-10-26) | Docs Guild, Security Guild | AUTH-POLICY-20-002 | Publish `/docs/security/policy-governance.md` covering scopes, approvals, tenancy, least privilege. | Security doc merged; compliance checklist appended; reviewed by Security Guild. |
| DOCS-POLICY-20-011 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-ENGINE-20-001 | Populate `/docs/examples/policies/` with baseline/serverless/internal-only samples and commentary. | Example policies committed with explanations; lint passes; compliance checklist per file. |
| DOCS-POLICY-20-012 | DONE (2025-10-26) | Docs Guild, Support Guild | WEB-POLICY-20-003 | Draft `/docs/faq/policy-faq.md` addressing common pitfalls, VEX conflicts, determinism issues. | FAQ published with Q/A entries, cross-links, compliance checklist. |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-CONSOLE-23-001 | DONE (2025-10-26) | Docs Guild, Console Guild | CONSOLE-CORE-23-004 | Publish `/docs/ui/console-overview.md` covering IA, tenant model, global filters, and AOC alignment with compliance checklist. | Doc merged with diagrams + overview tables; checklist appended; Console Guild sign-off. |
| DOCS-CONSOLE-23-002 | DONE (2025-10-26) | Docs Guild, Console Guild | DOCS-CONSOLE-23-001 | Author `/docs/ui/navigation.md` detailing routes, breadcrumbs, keyboard shortcuts, deep links, and tenant context switching. | Navigation doc merged with shortcut tables and screenshots; accessibility checklist satisfied. |
| DOCS-CONSOLE-23-003 | DONE (2025-10-26) | Docs Guild, SBOM Service Guild, Console Guild | SBOM-CONSOLE-23-001, CONSOLE-FEAT-23-102 | Document `/docs/ui/sbom-explorer.md` (catalog, detail, graph overlays, exports) including compliance checklist and performance tips. | Doc merged with annotated screenshots, export instructions, and overlay examples; checklist appended. |
| DOCS-CONSOLE-23-004 | DONE (2025-10-26) | Docs Guild, Concelier Guild, Excititor Guild | CONCELIER-CONSOLE-23-001, EXCITITOR-CONSOLE-23-001 | Produce `/docs/ui/advisories-and-vex.md` explaining aggregation-not-merge, conflict indicators, raw viewers, and provenance banners. | Doc merged; raw JSON examples included; compliance checklist complete. |
| DOCS-CONSOLE-23-005 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-CONSOLE-23-001, CONSOLE-FEAT-23-104 | Write `/docs/ui/findings.md` describing filters, saved views, explain drawer, exports, and CLI parity callouts. | Doc merged with filter matrix + explain walkthrough; checklist appended. |
| DOCS-CONSOLE-23-006 | DONE (2025-10-26) | Docs Guild, Policy Guild, Product Ops | POLICY-CONSOLE-23-002, CONSOLE-FEAT-23-105 | Publish `/docs/ui/policies.md` with editor, simulation, approvals, compliance checklist, and RBAC mapping. | Doc merged; Monaco screenshots + simulation diff examples included; approval flow described; checklist appended. |
| DOCS-CONSOLE-23-007 | DONE (2025-10-26) | Docs Guild, Scheduler Guild | SCHED-CONSOLE-23-001, CONSOLE-FEAT-23-106 | Document `/docs/ui/runs.md` covering queues, live progress, diffs, retries, evidence downloads, and troubleshooting. | Doc merged with SSE troubleshooting, metrics references, compliance checklist. |
| DOCS-CONSOLE-23-008 | DONE (2025-10-26) | Docs Guild, Authority Guild | AUTH-CONSOLE-23-002, CONSOLE-FEAT-23-108 | Draft `/docs/ui/admin.md` describing users/roles, tenants, tokens, integrations, fresh-auth prompts, and RBAC mapping. | Doc merged with tables for scopes vs roles, screenshots, compliance checklist. |
| DOCS-CONSOLE-23-009 | DONE (2025-10-27) | Docs Guild, DevOps Guild | DOWNLOADS-CONSOLE-23-001, CONSOLE-FEAT-23-109 | Publish `/docs/ui/downloads.md` listing product images, commands, offline instructions, parity with CLI, and compliance checklist. | Doc merged; manifest sample included; copy-to-clipboard guidance documented; checklist complete. |
| DOCS-CONSOLE-23-010 | DONE (2025-10-27) | Docs Guild, Deployment Guild, Console Guild | DEVOPS-CONSOLE-23-002, CONSOLE-REL-23-301 | Write `/docs/deploy/console.md` (Helm, ingress, TLS, CSP, env vars, health checks) with compliance checklist. | Deploy doc merged; templates validated; CSP guidance included; checklist appended. |
| DOCS-CONSOLE-23-011 | DONE (2025-10-28) | Docs Guild, Deployment Guild | DOCS-CONSOLE-23-010 | Update `/docs/install/docker.md` to cover Console image, Compose/Helm usage, offline tarballs, parity with CLI. | Doc updated with new sections; commands validated; compliance checklist appended. |
| DOCS-CONSOLE-23-012 | DONE (2025-10-28) | Docs Guild, Security Guild | AUTH-CONSOLE-23-003, WEB-CONSOLE-23-002 | Publish `/docs/security/console-security.md` detailing OIDC flows, scopes, CSP, fresh-auth, evidence handling, and compliance checklist. | Security doc merged; threat model notes included; checklist appended. |
| DOCS-CONSOLE-23-013 | DONE (2025-10-28) | Docs Guild, Observability Guild | TELEMETRY-CONSOLE-23-001, CONSOLE-QA-23-403 | Write `/docs/observability/ui-telemetry.md` cataloguing metrics/logs/traces, dashboards, alerts, and feature flags. | Doc merged with instrumentation tables, dashboard screenshots, checklist appended. |
| DOCS-CONSOLE-23-014 | DONE (2025-10-28) | Docs Guild, Console Guild, CLI Guild | CONSOLE-DOC-23-502 | Maintain `/docs/cli-vs-ui-parity.md` matrix and integrate CI check guidance. | Matrix published with parity status, CI workflow documented, compliance checklist appended. |
| DOCS-CONSOLE-23-017 | DONE (2025-10-27) | Docs Guild, Console Guild | CONSOLE-FEAT-23-101..109 | Create `/docs/examples/ui-tours.md` providing triage, audit, policy rollout walkthroughs with annotated screenshots and GIFs. | UI tours doc merged; capture instructions + asset placeholders committed; compliance checklist appended. |
| DOCS-CONSOLE-23-018 | DONE (2025-10-27) | Docs Guild, Security Guild | DOCS-CONSOLE-23-012 | Execute console security compliance checklist and capture Security Guild sign-off in Sprint 23 log. | Checklist completed; findings addressed or tickets filed; sign-off noted in updates file. |
| DOCS-LNM-22-006 | DONE (2025-10-27) | Docs Guild, Architecture Guild | CONCELIER-LNM-21-001..005, EXCITITOR-LNM-21-001..005 | Refresh `/docs/modules/concelier/architecture.md` and `/docs/modules/excititor/architecture.md` describing observation/linkset pipelines and event contracts. | Architecture docs updated with observation/linkset flow + event tables; revisit once service implementations land. |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-EXC-25-004 | DONE (2025-10-27) | Docs Guild, Policy Guild | POLICY-ENGINE-70-001 | Document `/docs/policy/exception-effects.md` explaining evaluation order, conflicts, simulation. | Doc merged; tests cross-referenced; checklist appended. |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-EXPORT-35-001 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-001..006 | Author `/docs/modules/export-center/overview.md` covering purpose, profiles, security, AOC alignment, surfaces, ending with imposed rule statement. | Doc merged with diagrams/examples; imposed rule line present; index updated. |
| DOCS-EXPORT-35-002 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-002..005 | Publish `/docs/modules/export-center/architecture.md` describing planner, adapters, manifests, signing, distribution flows, restating imposed rule. | Architecture doc merged; sequence diagrams included; rule statement appended. |
| DOCS-EXPORT-35-003 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-003..004 | Publish `/docs/modules/export-center/profiles.md` detailing schema fields, examples, compatibility, and imposed rule reminder. | Profiles doc merged; JSON schemas linked; imposed rule noted. |
| DOCS-EXPORT-36-004 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-36-001..004, WEB-EXPORT-36-001 | Publish `/docs/modules/export-center/api.md` covering endpoints, payloads, errors, and mention imposed rule. | API doc merged; examples validated; rule included. |
| DOCS-EXPORT-36-005 | DONE (2025-10-29) | Docs Guild | CLI-EXPORT-35-001, CLI-EXPORT-36-001 | Publish `/docs/modules/export-center/cli.md` with command reference, CI scripts, verification steps, restating imposed rule. | CLI doc merged; script snippets tested; rule appended. |
| DOCS-EXPORT-36-006 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-36-001, DEVOPS-EXPORT-36-001 | Publish `/docs/modules/export-center/trivy-adapter.md` covering field mappings, compatibility matrix, and imposed rule reminder. | Doc merged; mapping tables validated; rule included. |
| DOCS-EXPORT-37-001 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-37-001, DEVOPS-EXPORT-37-001 | Publish `/docs/modules/export-center/mirror-bundles.md` describing filesystem/OCI layouts, delta/encryption, import guide, ending with imposed rule. | Doc merged; diagrams provided; verification steps tested; rule stated. |
| DOCS-EXPORT-37-002 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-005, EXPORT-SVC-37-002 | Publish `/docs/modules/export-center/provenance-and-signing.md` detailing manifests, attestation flow, verification, reiterating imposed rule. | Doc merged; signature examples validated; rule appended. |
| DOCS-EXPORT-37-003 | DONE (2025-10-29) | Docs Guild | DEVOPS-EXPORT-37-001 | Publish `/docs/operations/export-runbook.md` covering failures, tuning, capacity planning, with imposed rule reminder. | Runbook merged; procedures validated; rule included. |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-NOTIFY-38-001 | DONE (2025-10-29) | Docs Guild, Notifications Service Guild | NOTIFY-SVC-38-001..004 | Publish `/docs/notifications/overview.md` and `/docs/notifications/architecture.md`, each ending with imposed rule reminder. | Docs merged; diagrams verified; imposed rule appended. |
| DOCS-NOTIFY-39-002 | DONE (2025-10-29) | Docs Guild, Notifications Service Guild | NOTIFY-SVC-39-001..004 | Publish `/docs/notifications/rules.md`, `/docs/notifications/templates.md`, `/docs/notifications/digests.md` with examples and imposed rule line. | Docs merged; examples validated; imposed rule appended. |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-PACKS-43-001 | DONE (2025-10-27) | Docs Guild, Task Runner Guild | PACKS-REG-42-001, TASKRUN-42-001 | Publish `/docs/task-packs/spec.md`, `/docs/task-packs/authoring-guide.md`, `/docs/task-packs/registry.md`, `/docs/task-packs/runbook.md`, `/docs/security/pack-signing-and-rbac.md`, `/docs/operations/cli-release-and-packaging.md` with imposed rule statements. | Docs merged; tutorials validated; imposed rule appended; cross-links added. |

81
docs/TASKS.md
View File

@@ -1,24 +1,9 @@
# Docs Guild Task Board (UTC 2025-10-10)
> Blocked: waiting on telemetry core deliverable (TELEMETRY-OBS-50-001) to finalise architecture details and diagrams.
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOC7.README-INDEX | DONE (2025-10-17) | Docs Guild | — | Refresh index docs (docs/README.md + root README) after architecture dossier split and Offline Kit overhaul. | ✅ ToC reflects new component architecture docs; ✅ root README highlights updated doc set; ✅ Offline Kit guide linked correctly. |
| DOC4.AUTH-PDG | DONE (2025-10-19) | Docs Guild, Plugin Team | PLG6.DOC | Copy-edit `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md`, export lifecycle diagram, add LDAP RFC cross-link. | ✅ PR merged with polish; ✅ Diagram committed; ✅ Slack handoff posted. |
| DOC1.AUTH | DONE (2025-10-12) | Docs Guild, Authority Core | CORE5B.DOC | Draft `docs/11_AUTHORITY.md` covering architecture, configuration, bootstrap flows. | ✅ Architecture + config sections approved by Core; ✅ Samples reference latest options; ✅ Offline note added. |
| DOC3.Concelier-Authority | DONE (2025-10-12) | Docs Guild, DevEx | FSR4 | Polish operator/runbook sections (DOC3/DOC5) to document Concelier authority rollout, bypass logging, and enforcement checklist. | ✅ DOC3/DOC5 updated with audit runbook references; ✅ enforcement deadline highlighted; ✅ Docs guild sign-off. |
| DOC5.Concelier-Runbook | DONE (2025-10-12) | Docs Guild | DOC3.Concelier-Authority | Produce dedicated Concelier authority audit runbook covering log fields, monitoring recommendations, and troubleshooting steps. | ✅ Runbook published; ✅ linked from DOC3/DOC5; ✅ alerting guidance included. |
| FEEDDOCS-DOCS-05-001 | DONE (2025-10-11) | Docs Guild | FEEDMERGE-ENGINE-04-001, FEEDMERGE-ENGINE-04-002 | Publish Concelier conflict resolution runbook covering precedence workflow, merge-event auditing, and Sprint 3 metrics. | ✅ `docs/modules/concelier/operations/conflict-resolution.md` committed; ✅ metrics/log tables align with latest merge code; ✅ Ops alert guidance handed to Concelier team. |
| FEEDDOCS-DOCS-05-002 | DONE (2025-10-16) | Docs Guild, Concelier Ops | FEEDDOCS-DOCS-05-001 | Ops sign-off captured: conflict runbook circulated, alert thresholds tuned, and rollout decisions documented in change log. | ✅ Ops review recorded; ✅ alert thresholds finalised using `docs/modules/concelier/operations/authority-audit-runbook.md`; ✅ change-log entry linked from runbook once GHSA/NVD/OSV regression fixtures land. |
| DOCS-ADR-09-001 | DONE (2025-10-19) | Docs Guild, DevEx | — | Establish ADR process (`docs/adr/0000-template.md`) and document usage guidelines. | Template published; README snippet linking ADR process; announcement posted (`docs/updates/2025-10-18-docs-guild.md`). |
| DOCS-EVENTS-09-002 | DONE (2025-10-19) | Docs Guild, Platform Events | SCANNER-EVENTS-15-201 | Publish event schema catalog (`docs/events/`) for `scanner.report.ready@1`, `scheduler.rescan.delta@1`, `attestor.logged@1`. | Schemas validated (Ajv CI hooked); docs/events/README summarises usage; Platform Events notified via `docs/updates/2025-10-18-docs-guild.md`. |
| DOCS-EVENTS-09-003 | DONE (2025-10-19) | Docs Guild | DOCS-EVENTS-09-002 | Add human-readable envelope field references and canonical payload samples for published events, including offline validation workflow. | Tables explain common headers/payload segments; versioned sample payloads committed; README links to validation instructions and samples. |
| DOCS-EVENTS-09-004 | DONE (2025-10-19) | Docs Guild, Scanner WebService | SCANNER-EVENTS-15-201 | Refresh scanner event docs to mirror DSSE-backed report fields, document `scanner.scan.completed`, and capture canonical sample validation. | Schemas updated for new payload shape; README references DSSE reuse and validation test; samples align with emitted events. |
| PLATFORM-EVENTS-09-401 | DONE (2025-10-21) | Platform Events Guild | DOCS-EVENTS-09-003 | Embed canonical event samples into contract/integration tests and ensure CI validates payloads against published schemas. | Notify models tests now run schema validation against `docs/events/*.json`, event schemas allow optional `attributes`, and docs capture the new validation workflow. |
| RUNTIME-GUILD-09-402 | DONE (2025-10-19) | Runtime Guild | SCANNER-POLICY-09-107 | Confirm Scanner WebService surfaces `quietedFindingCount` and progress hints to runtime consumers; document readiness checklist. | Runtime verification run captures enriched payload; checklist/doc updates merged; stakeholders acknowledge availability. |
| DOCS-CONCELIER-07-201 | DONE (2025-10-22) | Docs Guild, Concelier WebService | FEEDWEB-DOCS-01-001 | Final editorial review and publish pass for Concelier authority toggle documentation (Quickstart + operator guide). | Review feedback resolved, publish PR merged, release notes updated with documentation pointer. |
| DOCS-RUNTIME-17-004 | DONE (2025-10-26) | Docs Guild, Runtime Guild | SCANNER-EMIT-17-701, ZASTAVA-OBS-17-005, DEVOPS-REL-17-002 | Document build-id workflows: SBOM exposure, runtime event payloads (`process.buildId`), Scanner `/policy/runtime` response (`buildIds` list), debug-store layout, and operator guidance for symbol retrieval. | Architecture + operator docs updated with build-id sections (Observer, Scanner, CLI), examples show `readelf` output + debuginfod usage, references linked from Offline Kit/Release guides + CLI help. |
| DOCS-OBS-50-001 | BLOCKED (2025-10-26) | Docs Guild, Observability Guild | TELEMETRY-OBS-50-001 | Publish `/docs/observability/overview.md` introducing scope, imposed rule banner, architecture diagram, and tenant guarantees. | Doc merged with imposed rule banner; diagram committed; cross-links to telemetry stack + evidence locker docs. |
> Blocked: waiting on telemetry core deliverable (TELEMETRY-OBS-50-001) to finalise architecture details and diagrams.
| DOCS-OBS-50-002 | TODO | Docs Guild, Security Guild | TELEMETRY-OBS-50-002 | Author `/docs/observability/telemetry-standards.md` detailing common fields, scrubbing policy, sampling defaults, and redaction override procedure. | Doc merged; imposed rule banner present; examples validated with telemetry fixtures; security review sign-off captured. |
| DOCS-OBS-50-003 | TODO | Docs Guild, Observability Guild | TELEMETRY-OBS-50-001 | Create `/docs/observability/logging.md` covering structured log schema, dos/don'ts, tenant isolation, and copyable examples. | Doc merged with banner; sample logs redacted; lint passes; linked from coding standards. |
| DOCS-OBS-50-004 | TODO | Docs Guild, Observability Guild | TELEMETRY-OBS-50-002 | Draft `/docs/observability/tracing.md` explaining context propagation, async linking, CLI header usage, and sampling strategies. | Doc merged; imposed rule banner included; diagrams updated; references to CLI/Console features added. |
@@ -33,17 +18,6 @@
| DOCS-CLI-OBS-52-001 | TODO | Docs Guild, DevEx/CLI Guild | CLI-OBS-52-001 | Create `/docs/modules/cli/guides/observability.md` detailing `stella obs` commands, examples, exit codes, imposed rule banner, and scripting tips. | Doc merged; examples tested; banner included; CLI parity matrix updated. |
| DOCS-CLI-FORENSICS-53-001 | TODO | Docs Guild, DevEx/CLI Guild | CLI-FORENSICS-54-001 | Publish `/docs/modules/cli/guides/forensics.md` for snapshot/verify/attest commands with sample outputs, imposed rule banner, and offline workflows. | Doc merged; sample bundles verified; banner present; offline notes cross-linked. |
| DOCS-RUNBOOK-55-001 | TODO | Docs Guild, Ops Guild | DEVOPS-OBS-55-001, WEB-OBS-55-001 | Author `/docs/runbooks/incidents.md` describing incident mode activation, escalation steps, retention impact, verification checklist, and imposed rule banner. | Doc merged; runbook rehearsed; banner included; linked from alerts. |
| DOCS-AOC-19-001 | DONE (2025-10-26) | Docs Guild, Concelier Guild | CONCELIER-WEB-AOC-19-001, EXCITITOR-WEB-AOC-19-001 | Author `/docs/ingestion/aggregation-only-contract.md` covering philosophy, invariants, schemas, error codes, migration, observability, and security checklist. | New doc published with compliance checklist; cross-links from existing docs added. |
| DOCS-AOC-19-002 | DONE (2025-10-26) | Docs Guild, Architecture Guild | DOCS-AOC-19-001 | Update `/docs/modules/platform/architecture-overview.md` to include AOC boundary, raw stores, and sequence diagram (fetch → guard → raw insert → policy evaluation). | Overview doc updated with diagrams/text; lint passes; stakeholders sign off. |
| DOCS-AOC-19-003 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-AOC-19-003 | Refresh `/docs/modules/policy/architecture.md` clarifying ingestion boundary, raw inputs, and policy-only derived data. | Doc highlights raw-only ingestion contract, updated diagrams merge, compliance checklist added. |
| DOCS-AOC-19-004 | DONE (2025-10-26) | Docs Guild, UI Guild | UI-AOC-19-001 | Extend `/docs/ui/console.md` with Sources dashboard tiles, violation drill-down workflow, and verification action. | UI doc updated with screenshots/flow descriptions, compliance checklist appended. |
> DOCS-AOC-19-004: Architecture overview & policy-engine updates landed 2025-10-26; incorporate the new AOC boundary diagrams and metrics references.
| DOCS-AOC-19-005 | DONE (2025-10-26) | Docs Guild, CLI Guild | CLI-AOC-19-003 | Update `/docs/modules/cli/guides/cli-reference.md` with `stella sources ingest --dry-run` and `stella aoc verify` usage, exit codes, and offline notes. | CLI reference + quickstart sections updated; examples validated; compliance checklist added. |
> DOCS-AOC-19-005: New ingestion reference + architecture overview published 2025-10-26; ensure CLI docs link to both and surface AOC exit codes mapping.
| DOCS-AOC-19-006 | DONE (2025-10-26) | Docs Guild, Observability Guild | CONCELIER-WEB-AOC-19-002, EXCITITOR-WEB-AOC-19-002 | Document new metrics/traces/log keys in `/docs/observability/observability.md`. | Observability doc lists new metrics/traces/log fields; dashboards referenced; compliance checklist appended. |
| DOCS-AOC-19-007 | DONE (2025-10-26) | Docs Guild, Authority Core | AUTH-AOC-19-001 | Update `/docs/security/authority-scopes.md` with new ingestion scopes and tenancy enforcement notes. | Doc reflects new scopes, sample policies updated, compliance checklist added. |
| DOCS-AOC-19-008 | DONE (2025-10-26) | Docs Guild, DevOps Guild | DEVOPS-AOC-19-002 | Refresh `/docs/deploy/containers.md` to cover validator enablement, guard env flags, and read-only verify user. | Deploy doc updated; offline kit section mentions validator scripts; compliance checklist appended. |
| DOCS-AOC-19-009 | DONE (2025-10-26) | Docs Guild, Authority Core | AUTH-AOC-19-001 | Update AOC docs/samples to reflect new `advisory:*`, `vex:*`, and `aoc:verify` scopes. | Docs reference new scopes, samples aligned, compliance checklist updated. |
## Air-Gapped Mode (Epic 16)
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
@@ -106,18 +80,6 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-POLICY-20-001 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-ENGINE-20-000 | Author `/docs/policy/overview.md` covering concepts, inputs/outputs, determinism, and compliance checklist. | Doc published with diagrams + glossary; lint passes; checklist included. |
| DOCS-POLICY-20-002 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-ENGINE-20-001 | Write `/docs/policy/dsl.md` with grammar, built-ins, examples, anti-patterns. | DSL doc includes grammar tables, examples, compliance checklist; validated against parser tests. |
| DOCS-POLICY-20-003 | DONE (2025-10-26) | Docs Guild, Authority Core | AUTH-POLICY-20-001 | Publish `/docs/policy/lifecycle.md` describing draft→approve workflow, roles, audit, compliance list. | Lifecycle doc linked from UI/CLI help; approvals roles documented; checklist appended. |
| DOCS-POLICY-20-004 | DONE (2025-10-26) | Docs Guild, Scheduler Guild | SCHED-MODELS-20-001 | Create `/docs/policy/runs.md` detailing run modes, incremental mechanics, cursors, replay. | Run doc includes sequence diagrams + compliance checklist; cross-links to scheduler docs. |
| DOCS-POLICY-20-005 | DONE (2025-10-26) | Docs Guild, BE-Base Platform Guild | WEB-POLICY-20-001 | Draft `/docs/api/policy.md` describing endpoints, schemas, error codes. | API doc validated against OpenAPI; examples included; checklist appended. |
| DOCS-POLICY-20-006 | DONE (2025-10-26) | Docs Guild, DevEx/CLI Guild | CLI-POLICY-20-002 | Produce `/docs/modules/cli/guides/policy.md` with command usage, exit codes, JSON output contracts. | CLI doc includes examples, exit codes, compliance checklist. |
| DOCS-POLICY-20-007 | DONE (2025-10-26) | Docs Guild, UI Guild | UI-POLICY-20-001 | Document `/docs/ui/policy-editor.md` covering editor, simulation, diff workflows, approvals. | UI doc includes screenshots/placeholders, accessibility notes, compliance checklist. |
| DOCS-POLICY-20-008 | DONE (2025-10-26) | Docs Guild, Architecture Guild | POLICY-ENGINE-20-003 | Write `/docs/modules/policy/architecture.md` (new epic content) with sequence diagrams, selection strategy, schema. | Architecture doc merged with diagrams; compliance checklist appended; references updated. |
| DOCS-POLICY-20-009 | DONE (2025-10-26) | Docs Guild, Observability Guild | POLICY-ENGINE-20-007 | Add `/docs/observability/policy.md` for metrics/traces/logs, sample dashboards. | Observability doc includes metrics tables, dashboard screenshots, checklist. |
| DOCS-POLICY-20-010 | DONE (2025-10-26) | Docs Guild, Security Guild | AUTH-POLICY-20-002 | Publish `/docs/security/policy-governance.md` covering scopes, approvals, tenancy, least privilege. | Security doc merged; compliance checklist appended; reviewed by Security Guild. |
| DOCS-POLICY-20-011 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-ENGINE-20-001 | Populate `/docs/examples/policies/` with baseline/serverless/internal-only samples and commentary. | Example policies committed with explanations; lint passes; compliance checklist per file. |
| DOCS-POLICY-20-012 | DONE (2025-10-26) | Docs Guild, Support Guild | WEB-POLICY-20-003 | Draft `/docs/faq/policy-faq.md` addressing common pitfalls, VEX conflicts, determinism issues. | FAQ published with Q/A entries, cross-links, compliance checklist. |
## Graph Explorer v1
@@ -140,30 +102,12 @@
## StellaOps Console (Sprint 23)
> 2025-10-28: Install Docker guide references pending CLI commands (`stella downloads manifest`, `stella downloads mirror`, `stella console status`). Update once CLI parity lands.
> 2025-10-28: Added guide covering keyboard matrix, screen reader behaviour, colour/focus tokens, testing workflow, offline guidance, and compliance checklist.
> Follow-up: align diagrams/examples after `CONCELIER-LNM-21` & `EXCITITOR-LNM-21` work merges (currently TODO).
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-CONSOLE-23-001 | DONE (2025-10-26) | Docs Guild, Console Guild | CONSOLE-CORE-23-004 | Publish `/docs/ui/console-overview.md` covering IA, tenant model, global filters, and AOC alignment with compliance checklist. | Doc merged with diagrams + overview tables; checklist appended; Console Guild sign-off. |
| DOCS-CONSOLE-23-002 | DONE (2025-10-26) | Docs Guild, Console Guild | DOCS-CONSOLE-23-001 | Author `/docs/ui/navigation.md` detailing routes, breadcrumbs, keyboard shortcuts, deep links, and tenant context switching. | Navigation doc merged with shortcut tables and screenshots; accessibility checklist satisfied. |
| DOCS-CONSOLE-23-003 | DONE (2025-10-26) | Docs Guild, SBOM Service Guild, Console Guild | SBOM-CONSOLE-23-001, CONSOLE-FEAT-23-102 | Document `/docs/ui/sbom-explorer.md` (catalog, detail, graph overlays, exports) including compliance checklist and performance tips. | Doc merged with annotated screenshots, export instructions, and overlay examples; checklist appended. |
| DOCS-CONSOLE-23-004 | DONE (2025-10-26) | Docs Guild, Concelier Guild, Excititor Guild | CONCELIER-CONSOLE-23-001, EXCITITOR-CONSOLE-23-001 | Produce `/docs/ui/advisories-and-vex.md` explaining aggregation-not-merge, conflict indicators, raw viewers, and provenance banners. | Doc merged; raw JSON examples included; compliance checklist complete. |
| DOCS-CONSOLE-23-005 | DONE (2025-10-26) | Docs Guild, Policy Guild | POLICY-CONSOLE-23-001, CONSOLE-FEAT-23-104 | Write `/docs/ui/findings.md` describing filters, saved views, explain drawer, exports, and CLI parity callouts. | Doc merged with filter matrix + explain walkthrough; checklist appended. |
| DOCS-CONSOLE-23-006 | DONE (2025-10-26) | Docs Guild, Policy Guild, Product Ops | POLICY-CONSOLE-23-002, CONSOLE-FEAT-23-105 | Publish `/docs/ui/policies.md` with editor, simulation, approvals, compliance checklist, and RBAC mapping. | Doc merged; Monaco screenshots + simulation diff examples included; approval flow described; checklist appended. |
| DOCS-CONSOLE-23-007 | DONE (2025-10-26) | Docs Guild, Scheduler Guild | SCHED-CONSOLE-23-001, CONSOLE-FEAT-23-106 | Document `/docs/ui/runs.md` covering queues, live progress, diffs, retries, evidence downloads, and troubleshooting. | Doc merged with SSE troubleshooting, metrics references, compliance checklist. |
| DOCS-CONSOLE-23-008 | DONE (2025-10-26) | Docs Guild, Authority Guild | AUTH-CONSOLE-23-002, CONSOLE-FEAT-23-108 | Draft `/docs/ui/admin.md` describing users/roles, tenants, tokens, integrations, fresh-auth prompts, and RBAC mapping. | Doc merged with tables for scopes vs roles, screenshots, compliance checklist. |
| DOCS-CONSOLE-23-009 | DONE (2025-10-27) | Docs Guild, DevOps Guild | DOWNLOADS-CONSOLE-23-001, CONSOLE-FEAT-23-109 | Publish `/docs/ui/downloads.md` listing product images, commands, offline instructions, parity with CLI, and compliance checklist. | Doc merged; manifest sample included; copy-to-clipboard guidance documented; checklist complete. |
| DOCS-CONSOLE-23-010 | DONE (2025-10-27) | Docs Guild, Deployment Guild, Console Guild | DEVOPS-CONSOLE-23-002, CONSOLE-REL-23-301 | Write `/docs/deploy/console.md` (Helm, ingress, TLS, CSP, env vars, health checks) with compliance checklist. | Deploy doc merged; templates validated; CSP guidance included; checklist appended. |
| DOCS-CONSOLE-23-011 | DONE (2025-10-28) | Docs Guild, Deployment Guild | DOCS-CONSOLE-23-010 | Update `/docs/install/docker.md` to cover Console image, Compose/Helm usage, offline tarballs, parity with CLI. | Doc updated with new sections; commands validated; compliance checklist appended. |
| DOCS-CONSOLE-23-012 | DONE (2025-10-28) | Docs Guild, Security Guild | AUTH-CONSOLE-23-003, WEB-CONSOLE-23-002 | Publish `/docs/security/console-security.md` detailing OIDC flows, scopes, CSP, fresh-auth, evidence handling, and compliance checklist. | Security doc merged; threat model notes included; checklist appended. |
| DOCS-CONSOLE-23-013 | DONE (2025-10-28) | Docs Guild, Observability Guild | TELEMETRY-CONSOLE-23-001, CONSOLE-QA-23-403 | Write `/docs/observability/ui-telemetry.md` cataloguing metrics/logs/traces, dashboards, alerts, and feature flags. | Doc merged with instrumentation tables, dashboard screenshots, checklist appended. |
| DOCS-CONSOLE-23-014 | DONE (2025-10-28) | Docs Guild, Console Guild, CLI Guild | CONSOLE-DOC-23-502 | Maintain `/docs/cli-vs-ui-parity.md` matrix and integrate CI check guidance. | Matrix published with parity status, CI workflow documented, compliance checklist appended. |
> 2025-10-28: Install Docker guide references pending CLI commands (`stella downloads manifest`, `stella downloads mirror`, `stella console status`). Update once CLI parity lands.
| DOCS-CONSOLE-23-015 | DONE (2025-10-27) | Docs Guild, Architecture Guild | CONSOLE-CORE-23-001, WEB-CONSOLE-23-001 | Produce `/docs/modules/ui/console-architecture.md` describing frontend packages, data flow diagrams, SSE design, performance budgets. | Architecture doc merged with diagrams + compliance checklist; reviewers approve. |
| DOCS-CONSOLE-23-016 | DONE (2025-10-28) | Docs Guild, Accessibility Guild | CONSOLE-QA-23-402, CONSOLE-FEAT-23-102 | Refresh `/docs/accessibility.md` with Console-specific keyboard flows, color tokens, testing tools, and compliance checklist updates. | Accessibility doc updated; audits referenced; checklist appended. |
> 2025-10-28: Added guide covering keyboard matrix, screen reader behaviour, colour/focus tokens, testing workflow, offline guidance, and compliance checklist.
| DOCS-CONSOLE-23-017 | DONE (2025-10-27) | Docs Guild, Console Guild | CONSOLE-FEAT-23-101..109 | Create `/docs/examples/ui-tours.md` providing triage, audit, policy rollout walkthroughs with annotated screenshots and GIFs. | UI tours doc merged; capture instructions + asset placeholders committed; compliance checklist appended. |
| DOCS-CONSOLE-23-018 | DONE (2025-10-27) | Docs Guild, Security Guild | DOCS-CONSOLE-23-012 | Execute console security compliance checklist and capture Security Guild sign-off in Sprint 23 log. | Checklist completed; findings addressed or tickets filed; sign-off noted in updates file. |
| DOCS-LNM-22-006 | DONE (2025-10-27) | Docs Guild, Architecture Guild | CONCELIER-LNM-21-001..005, EXCITITOR-LNM-21-001..005 | Refresh `/docs/modules/concelier/architecture.md` and `/docs/modules/excititor/architecture.md` describing observation/linkset pipelines and event contracts. | Architecture docs updated with observation/linkset flow + event tables; revisit once service implementations land. |
> Follow-up: align diagrams/examples after `CONCELIER-LNM-21` & `EXCITITOR-LNM-21` work merges (currently TODO).
| DOCS-LNM-22-007 | TODO | Docs Guild, Observability Guild | CONCELIER-LNM-21-005, EXCITITOR-LNM-21-005, DEVOPS-LNM-22-002 | Publish `/docs/observability/aggregation.md` with metrics/traces/logs/SLOs. | Observability doc merged; dashboards referenced; checklist appended. |
| DOCS-LNM-22-008 | TODO | Docs Guild, DevOps Guild | MERGE-LNM-21-001, CONCELIER-LNM-21-102 | Write `/docs/migration/no-merge.md` describing migration plan, backfill steps, rollback, feature flags. | Migration doc approved by stakeholders; checklist appended. |
@@ -201,7 +145,6 @@
| DOCS-EXC-25-001 | TODO | Docs Guild, Governance Guild | WEB-EXC-25-001 | Author `/docs/governance/exceptions.md` covering lifecycle, scope patterns, examples, compliance checklist. | Doc merged; reviewers sign off; checklist included. |
| DOCS-EXC-25-002 | TODO | Docs Guild, Authority Core | AUTH-EXC-25-001 | Publish `/docs/governance/approvals-and-routing.md` detailing roles, routing matrix, MFA rules, audit trails. | Doc merged; routing examples validated; checklist appended. |
| DOCS-EXC-25-003 | TODO | Docs Guild, BE-Base Platform Guild | WEB-EXC-25-001..003 | Create `/docs/api/exceptions.md` with endpoints, payloads, errors, idempotency notes. | API doc aligned with OpenAPI; examples tested; checklist appended. |
| DOCS-EXC-25-004 | DONE (2025-10-27) | Docs Guild, Policy Guild | POLICY-ENGINE-70-001 | Document `/docs/policy/exception-effects.md` explaining evaluation order, conflicts, simulation. | Doc merged; tests cross-referenced; checklist appended. |
| DOCS-EXC-25-005 | TODO | Docs Guild, UI Guild | UI-EXC-25-001..004 | Write `/docs/ui/exception-center.md` with UI walkthrough, badges, accessibility, shortcuts. | Doc merged with screenshots; accessibility checklist completed. |
| DOCS-EXC-25-006 | TODO | Docs Guild, DevEx/CLI Guild | CLI-EXC-25-001..002 | Update `/docs/modules/cli/guides/exceptions.md` covering command usage and exit codes. | CLI doc updated; examples validated; checklist appended. |
| DOCS-EXC-25-007 | TODO | Docs Guild, DevOps Guild | SCHED-WORKER-25-101, DEVOPS-GRAPH-24-003 | Publish `/docs/migration/exception-governance.md` describing cutover from legacy suppressions, notifications, rollback. | Migration doc approved; checklist included. |
@@ -229,15 +172,6 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-EXPORT-35-001 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-001..006 | Author `/docs/modules/export-center/overview.md` covering purpose, profiles, security, AOC alignment, surfaces, ending with imposed rule statement. | Doc merged with diagrams/examples; imposed rule line present; index updated. |
| DOCS-EXPORT-35-002 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-002..005 | Publish `/docs/modules/export-center/architecture.md` describing planner, adapters, manifests, signing, distribution flows, restating imposed rule. | Architecture doc merged; sequence diagrams included; rule statement appended. |
| DOCS-EXPORT-35-003 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-003..004 | Publish `/docs/modules/export-center/profiles.md` detailing schema fields, examples, compatibility, and imposed rule reminder. | Profiles doc merged; JSON schemas linked; imposed rule noted. |
| DOCS-EXPORT-36-004 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-36-001..004, WEB-EXPORT-36-001 | Publish `/docs/modules/export-center/api.md` covering endpoints, payloads, errors, and mention imposed rule. | API doc merged; examples validated; rule included. |
| DOCS-EXPORT-36-005 | DONE (2025-10-29) | Docs Guild | CLI-EXPORT-35-001, CLI-EXPORT-36-001 | Publish `/docs/modules/export-center/cli.md` with command reference, CI scripts, verification steps, restating imposed rule. | CLI doc merged; script snippets tested; rule appended. |
| DOCS-EXPORT-36-006 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-36-001, DEVOPS-EXPORT-36-001 | Publish `/docs/modules/export-center/trivy-adapter.md` covering field mappings, compatibility matrix, and imposed rule reminder. | Doc merged; mapping tables validated; rule included. |
| DOCS-EXPORT-37-001 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-37-001, DEVOPS-EXPORT-37-001 | Publish `/docs/modules/export-center/mirror-bundles.md` describing filesystem/OCI layouts, delta/encryption, import guide, ending with imposed rule. | Doc merged; diagrams provided; verification steps tested; rule stated. |
| DOCS-EXPORT-37-002 | DONE (2025-10-29) | Docs Guild | EXPORT-SVC-35-005, EXPORT-SVC-37-002 | Publish `/docs/modules/export-center/provenance-and-signing.md` detailing manifests, attestation flow, verification, reiterating imposed rule. | Doc merged; signature examples validated; rule appended. |
| DOCS-EXPORT-37-003 | DONE (2025-10-29) | Docs Guild | DEVOPS-EXPORT-37-001 | Publish `/docs/operations/export-runbook.md` covering failures, tuning, capacity planning, with imposed rule reminder. | Runbook merged; procedures validated; rule included. |
| DOCS-EXPORT-37-004 | TODO | Docs Guild | AUTH-EXPORT-37-001, EXPORT-SVC-37-002 | Publish `/docs/security/export-hardening.md` outlining RBAC, tenancy, encryption, redaction, restating imposed rule. | Security doc merged; checklist updated; rule appended. |
| DOCS-EXPORT-37-101 | TODO | Docs Guild, DevEx/CLI Guild | CLI-EXPORT-37-001 | Refresh CLI verification sections once `stella export verify` lands (flags, exit codes, samples). | `docs/modules/export-center/cli.md` & `docs/modules/export-center/provenance-and-signing.md` updated with final command syntax; examples tested; rule reminder retained. |
| DOCS-EXPORT-37-102 | TODO | Docs Guild, DevOps Guild | DEVOPS-EXPORT-37-001 | Embed export dashboards/alerts references into provenance/runbook docs after Grafana work ships. | Docs updated with dashboard IDs/alert notes; update logged; rule reminder present. |
@@ -353,8 +287,6 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DOCS-NOTIFY-38-001 | DONE (2025-10-29) | Docs Guild, Notifications Service Guild | NOTIFY-SVC-38-001..004 | Publish `/docs/notifications/overview.md` and `/docs/notifications/architecture.md`, each ending with imposed rule reminder. | Docs merged; diagrams verified; imposed rule appended. |
| DOCS-NOTIFY-39-002 | DONE (2025-10-29) | Docs Guild, Notifications Service Guild | NOTIFY-SVC-39-001..004 | Publish `/docs/notifications/rules.md`, `/docs/notifications/templates.md`, `/docs/notifications/digests.md` with examples and imposed rule line. | Docs merged; examples validated; imposed rule appended. |
| DOCS-NOTIFY-40-001 | TODO | Docs Guild, Security Guild | AUTH-NOTIFY-38-001, NOTIFY-SVC-40-001..004 | Publish `/docs/notifications/channels.md`, `/docs/notifications/escalations.md`, `/docs/notifications/api.md`, `/docs/operations/notifier-runbook.md`, `/docs/security/notifications-hardening.md`; each ends with imposed rule line. | Docs merged; accessibility checks passed; imposed rule appended. |
## CLI Parity & Task Packs
@@ -363,7 +295,6 @@
|----|--------|----------|------------|-------------|---------------|
| DOCS-CLI-41-001 | TODO | Docs Guild, DevEx/CLI Guild | CLI-CORE-41-001 | Publish `/docs/modules/cli/guides/overview.md`, `/docs/modules/cli/guides/configuration.md`, `/docs/modules/cli/guides/output-and-exit-codes.md` with imposed rule statements. | Docs merged; examples verified; imposed rule appended. |
| DOCS-CLI-42-001 | TODO | Docs Guild | DOCS-CLI-41-001, CLI-PARITY-41-001 | Publish `/docs/modules/cli/guides/parity-matrix.md` and command guides under `/docs/modules/cli/guides/commands/*.md` (policy, sbom, vuln, vex, advisory, export, orchestrator, notify, aoc, auth). | Guides merged; parity automation documented; imposed rule appended. |
| DOCS-PACKS-43-001 | DONE (2025-10-27) | Docs Guild, Task Runner Guild | PACKS-REG-42-001, TASKRUN-42-001 | Publish `/docs/task-packs/spec.md`, `/docs/task-packs/authoring-guide.md`, `/docs/task-packs/registry.md`, `/docs/task-packs/runbook.md`, `/docs/security/pack-signing-and-rbac.md`, `/docs/operations/cli-release-and-packaging.md` with imposed rule statements. | Docs merged; tutorials validated; imposed rule appended; cross-links added. |
## Containerized Distribution (Epic 13)

111
docs/aoc/guard-library.md Normal file
View File

@@ -0,0 +1,111 @@
# Aggregation-Only Guard Library Reference
> **Packages:** `StellaOps.Aoc`, `StellaOps.Aoc.AspNetCore`
> **Related tasks:** `WEB-AOC-19-001`, `WEB-AOC-19-003`, `DEVOPS-AOC-19-001`
> **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
should use the guard whenever raw advisory or VEX payloads are accepted so that
forbidden fields are rejected long before they reach MongoDB.
## Packages
### `StellaOps.Aoc`
- `IAocGuard` / `AocWriteGuard` — validate JSON payloads and emit `AocGuardResult`.
- `AocGuardOptions` — toggles for signature enforcement, tenant requirements, and required top-level fields.
- `AocViolation` / `AocViolationCode` — structured violations surfaced to callers.
- `ServiceCollectionExtensions.AddAocGuard()` — DI helper that registers the singleton guard.
- `AocGuardExtensions.ValidateOrThrow()` — throws `AocGuardException` when validation fails.
### `StellaOps.Aoc.AspNetCore`
- `AocGuardEndpointFilter<TRequest>` — Minimal API endpoint filter that evaluates request payloads through the guard before invoking handlers.
- `AocHttpResults.Problem()` — Produces a RFC 7807 payload that includes violation codes, suitable for API responses.
## Minimal API integration
```csharp
using StellaOps.Aoc;
using StellaOps.Aoc.AspNetCore.Routing;
using StellaOps.Aoc.AspNetCore.Results;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAocGuard();
builder.Services.Configure<AocGuardOptions>(options =>
{
options.RequireSignatureMetadata = true;
options.RequireTenant = true;
});
var app = builder.Build();
app.MapPost("/ingest", async (IngestionRequest request, IAocGuard guard, ILogger<Program> logger) =>
{
// additional application logic
return Results.Accepted();
})
.AddEndpointFilter(new AocGuardEndpointFilter<IngestionRequest>(
request => new object?[] { request.Payload },
serializerOptions: null,
guardOptions: null))
.ProducesProblem(StatusCodes.Status400BadRequest)
.WithTags("AOC");
app.UseExceptionHandler(errorApp =>
{
errorApp.Run(async context =>
{
var exceptionHandler = context.Features.Get<IExceptionHandlerFeature>();
if (exceptionHandler?.Error is AocGuardException guardException)
{
var result = AocHttpResults.Problem(context, guardException);
await result.ExecuteAsync(context);
return;
}
context.Response.StatusCode = StatusCodes.Status500InternalServerError;
});
});
```
Key points:
- Register the guard singleton before wiring repositories or worker services.
- Use `AocGuardEndpointFilter<TRequest>` to protect Minimal API endpoints. The `payloadSelector`
can yield multiple payloads (e.g. batch ingestion) and the filter will validate each one.
- Wrap guard exceptions with `AocHttpResults.Problem` to ensure clients receive machine-readables codes (`ERR_AOC_00x`).
## Worker / repository usage
Inject `IAocGuard` (or a module-specific wrapper such as `IVexRawWriteGuard`) anywhere documents
are persisted. Call `ValidateOrThrow` before writes to guarantee fail-fast behaviour, for example:
```csharp
public sealed class AdvisoryRawRepository
{
private readonly IAocGuard _guard;
public AdvisoryRawRepository(IAocGuard guard) => _guard = guard;
public Task WriteAsync(JsonDocument document, CancellationToken cancellationToken)
{
_guard.ValidateOrThrow(document.RootElement);
// proceed with storage logic
}
}
```
## Configuration tips
- Adjust `AocGuardOptions.RequiredTopLevelFields` when staging new schema changes. All configured names are case-insensitive.
- Set `RequireSignatureMetadata = false` for legacy feeds that do not provide signature envelopes yet; track the waiver in the module backlog.
- Use module-specific wrappers (`AddConcelierAocGuards`, `AddExcititorAocGuards`) to combine guard registration with domain exceptions and metrics.
## Testing guidance
- Unit-test guard behaviour with fixture payloads (see `src/Aoc/__Tests`).
- Service-level tests should assert that ingestion endpoints return `ERR_AOC_*` codes via `AocHttpResults`.
- CI must run `stella aoc verify` once CLI support lands (`DEVOPS-AOC-19-002`).
- Roslyn analyzer enforcement (`WEB-AOC-19-003`) will ensure the guard is registered; keep services wired through the shared extensions to prepare for that gate.
For questions or updates, coordinate with the BE‑Base Platform guild and reference `WEB-AOC-19-001`.

2
docs/backlog/2025-10-cleanup.md
View File

@@ -6,7 +6,7 @@ This note captures the Sprint backlog hygiene pass applied on 26 October 2025. T
- **Console replaces legacy Angular UI.** Sprint 13 UI tasks (`UI-SCANS-13-002`, `UI-VEX-13-003`, `UI-ADMIN-13-004`, `UI-SCHED-13-005`) are retired. Console Sprint 23 (`CONSOLE-CORE-23-001..005`, `CONSOLE-FEAT-23-101..109`, `CONSOLE-REL-23-301..303`) owns the experience.
- **Policy CLI runtime verbs consolidated.** `CLI-RUNTIME-13-005` is superseded by `CLI-POLICY-20-002` and Policy Studio flows (`CLI-POLICY-27-00x`).
- **Notifier supersedes legacy Notify.* modules.** All Sprint 15 `StellaOps.Notify.*` tasks are archived. Replacement work lives in Notifications Studio / Notifier Sprints 38–40 (`NOTIFY-SVC-38-00x`, `NOTIFY-SVC-39-00x`, `NOTIFY-SVC-40-00x`, plus `WEB/CLI-NOTIFY-3x-00x`).
- **Cartographer owns graph construction.** `SBOM-GRAPH-24-00{1..4}` tasks are deleted from SBOM Service; Cartographer backlog (`CARTO-GRAPH-21-001..009`) covers graph storage, overlays, and tiling.
- **Graph platform realigned.** Cartographer backlog items are archived; Graph Indexer + Graph API own graph storage, overlays, and explorer flows. Update open work to reference `GRAPH-*` tasks and the governance note in `docs/devops/contracts-and-rules.md`.
- **Dedicated Vuln Explorer service.** Gateway/UI/CLI entries that attempted to inline Vuln Explorer logic (`WEB-GRAPH-24-003`, `UI-GRAPH-24-005`, `CLI-VULN-24-003`) now defer to Sprint 29 Vuln Explorer (`VULN-API-29-00x`, `CONSOLE-VULN-29-00x`, `CLI-VULN-29-00x`).
- **AOC enforcement.** Ingestion-layer tasks attempting to compute derived severity/safe-fix metadata (`CONCELIER-VULN-29-003`, `EXCITITOR-VULN-29-003`) were removed; the Policy Engine overlay backlog (`POLICY-ENGINE-29-001..003`) is the canonical home.
- **CI/Offline adjustments.** `DEVOPS-UI-13-006` and `DEVOPS-OFFLINE-18-003` moved under Console release tasks (`CONSOLE-QA-23-401`, `DEVOPS-CONSOLE-23-001`, `CONSOLE-REL-23-302`).

2
docs/dev/cartographer-graph-handshake.md
View File

@@ -1,5 +1,7 @@
# Cartographer Graph Handshake Plan
> **Archived (2025-10-30).** Cartographer has been retired in favour of the Graph Indexer + Graph API platform (see `docs/devops/contracts-and-rules.md`). Keep this document only for historical reference; new work must reference `GRAPH-*` tasks and the Graph module docs.
_Status: 2025-10-29_
## Why this exists

24
docs/devops/contracts-and-rules.md Normal file
View File

@@ -0,0 +1,24 @@
# DevOps Governance Rules Anchor (Sprint 33)
> **Scope** · Exit deliverable for `DEVOPS-RULES-33-001`
> **Audience** · DevOps Guild, Platform leads, service owners
> **Related** · `ops/devops/TASKS.md`, `docs/backlog/2025-10-cleanup.md`, `docs/modules/platform/architecture-overview.md`
This note consolidates the platform governance rules ratified on 30 October 2025.
Each rule captures intent, affected surfaces, enforcement actions, and references to the
source-of-truth backlogs so that subsequent sprints do not re‑introduce conflicting work.
| Rule | Intent & Rationale | Enforcement & Ownership | Follow-ups |
|------|--------------------|-------------------------|------------|
| **Gateway is a proxy only; Policy Engine owns overlays/simulations.** | Keep Gateway thin and deterministic: it authenticates, authorises, and forwards requests. All overlay composition, simulation, and policy evaluation stays inside Policy Engine so we avoid duplicated logic and time-of-check drift. | *Owners:* BE‑Base Platform Guild + Policy Engine Guild. <br/>*Enforcement:* Gateway PR reviews block embedded overlay code, new endpoints require `Policy Engine` contracts, CI parity checks compare Gateway ↔ Policy overlay schemas. | - Update open tasks referencing “gateway overlay” work to point at `POLICY-ENGINE-20-00x`.<br/>- Close or rewrite backlog items `WEB-POLICY-20-00x` that attempted to compute overlays in Gateway. |
| **AOC ingestion is canonical-only; no merges at ingest.** | Concelier/Excititor persist upstream truth plus provenance. Derived severity, merges, or dedupe belong to downstream Policy workflows. This keeps ingestion auditable and replayable. | *Owners:* Concelier & Excititor guilds, DevOps Guild for CI pipelines. <br/>*Enforcement:* `StellaOps.Aoc` guard library, Mongo validators, Roslyn analyzer backlog (`WEB-AOC-19-003`), CI job `stella aoc verify`. | - Ensure ingestion tasks reference the guard library (`StellaOps.Aoc`).<br/>- Retire legacy tasks that still mention merge-at-ingest (see backlog cleanup note). |
| **Single graph platform: Graph Indexer + Graph API (Cartographer retired).** | Replace the historical Cartographer service with the Graph Indexer + Graph API pairing so graph storage, overlays, and explorer flows share one platform. | *Owners:* Graph Platform Guild, Scheduler Guild, DevOps Guild. <br/>*Enforcement:* New graph work lands in `docs/modules/graph/**` and `src/Graph/**`. Gateway/UI/CLI tickets reference the Graph API endpoints only. | - Archive Cartographer handshake docs and mark Cartographer backlog items as historical.<br/>- Update Scheduler/SBOM/Console tickets to depend on `GRAPH-*` IDs instead of `CARTO-*`. |
## Tracking & documentation
- ✅ Rules recorded in `docs/implplan/SPRINTS.md` (Sprint 33) and `ops/devops/TASKS.md`.
- ✅ Repository-wide references to “Cartographer as active platform” updated (see backlog note amendment and doc banner).
- ✅ Changelog entry (`docs/updates/2025-10-30-devops-governance.md`) captures reviewer acknowledgement.
Future adjustments to these rules must update this file and reference `DEVOPS-RULES-33-001`
when proposing changes so the DevOps Guild can track history.

38
docs/evaluate/checklist.md Normal file
View File

@@ -0,0 +1,38 @@
# Evaluation Checklist – 30-Day Adoption Plan
## Day 0–1: Kick the Tires
- [ ] Follow the [Quickstart](../quickstart.md) to run the first scan and confirm quota headers (`X-Stella-Quota-Remaining`).
- [ ] Capture the deterministic replay bundle (`stella replay export`) to verify SRM evidence.
- [ ] Log into the Console, review the explain trace for the latest scan, and test policy waiver creation.
## Day 2–7: Prove Fit
- [ ] Import the [Offline Update Kit](../24_OFFLINE_KIT.md) and confirm feeds refresh with no Internet access.
- [ ] Apply a sovereign CryptoProfile matching your regulatory environment (FIPS, eIDAS, GOST, SM).
- [ ] Run policy simulations with your SBOMs using `stella policy simulate --input <sbom>`; log explain outcomes for review.
- [ ] Validate attestation workflows by exporting DSSE bundles and replaying them on a secondary host.
## Day 8–14: Integrate
- [ ] Wire the CLI into CI/CD to gate images using exit codes and `X-Stella-Quota-Remaining` telemetry.
- [ ] Configure `StellaOps.Notify` with at least one channel (email/webhook) and confirm digest delivery.
- [ ] Map existing advisory/VEX sources to Concelier connectors; note any feeds requiring custom plug-ins.
- [ ] Review `StellaOps.Policy.Engine` audit logs to ensure waiver ownership and expiry meet governance needs.
## Day 15–30: Harden & Measure
- [ ] Follow the [Security Hardening Guide](../17_SECURITY_HARDENING_GUIDE.md) to rotate keys and enable mTLS across modules.
- [ ] Enable observability pipelines (metrics + OpenTelemetry) to capture scan throughput and policy outcomes.
- [ ] Run performance checks against the [Performance Workbook](../12_PERFORMANCE_WORKBOOK.md) targets; note P95 latencies.
- [ ] Document operational runbooks (install, upgrade, rollback) referencing [Release Engineering Playbook](../13_RELEASE_ENGINEERING_PLAYBOOK.md).
## Decision Gates
| Question | Evidence to collect | Source |
|----------|--------------------|--------|
| Can we operate fully offline? | Offline kit import logs, quota JWT validation without Internet | Quickstart, Offline Kit guide |
| Are findings explainable and reproducible? | SRM replay results, policy explain traces | Key features, Policy Engine UI |
| Does it meet regional compliance? | CryptoProfile application, Attestor/Rekor mirror configuration | Sovereign crypto docs, Attestor guide |
**Next step:** once the checklist is green, plan production rollout with module-specific architecture docs under `docs/modules/`.

2
docs/events/README.md
View File

@@ -35,7 +35,7 @@ Additive payload changes (new optional fields) can stay within the same version.
| `payload` | `object` | Event-specific body; schemas embed the canonical report and DSSE envelope. |
| `attributes` | `object` | Optional metadata bag (`string` keys/values) for downstream correlation. |
For Scanner orchestrator events, `links` include console and API deep links (`ui`, `report`, and `policy`) plus an optional `attestation` URL when a DSSE envelope is present. See [`orchestrator-scanner-events.md`](orchestrator-scanner-events.md) for details.
For Scanner orchestrator events, `links` include console and API deep links (`report.ui`, `report.api`, etc.) plus optional attestation references when a DSSE envelope is present. See [`orchestrator-scanner-events.md`](orchestrator-scanner-events.md) for details.
### Legacy Redis envelope
| Field | Type | Notes |

12
docs/events/orchestrator-scanner-events.md
View File

@@ -35,10 +35,12 @@ Emitted once a signed report is persisted and attested. Payload highlights:
- `reportId` / `scanId` — identifiers for the persisted report and originating scan. Until Scan IDs are surfaced by the API, `scanId` mirrors `reportId` so downstream correlators can stabilise on a single key.
- **Attributes:** `reportId`, `policyRevisionId`, `policyDigest`, `verdict` — pre-sorted for deterministic routing.
- **Links:**
- `ui` → `/ui/reports/{reportId}` on the current host.
- `report` → `{apiBasePath}/{reportsSegment}/{reportId}` (defaults to `/api/v1/reports/{reportId}`).
- `policy` → `{apiBasePath}/{policySegment}/revisions/{revisionId}` when a revision is present.
- `attestation` → `/ui/attestations/{reportId}` when a DSSE envelope is included.
- `report.ui` → `/ui/reports/{reportId}` on the current host.
- `report.api` → `{apiBasePath}/{reportsSegment}/{reportId}` (defaults to `/api/v1/reports/{reportId}`).
- `policy.ui` → `/ui/policy/revisions/{revisionId}` when a revision is present.
- `policy.api` → `{apiBasePath}/{policySegment}/revisions/{revisionId}` when a revision is present.
- `attestation.ui` → `/ui/attestations/{reportId}` when a DSSE envelope is included.
- `attestation.api` → `{apiBasePath}/{reportsSegment}/{reportId}/attestation` when a DSSE envelope is included.
- `imageDigest` — OCI image digest associated with the analysis.
- `generatedAt` — report generation timestamp (ISO-8601 UTC).
- `verdict` — `pass`, `warn`, or `fail` after policy evaluation.
@@ -59,7 +61,7 @@ Emitted after scan execution finishes (success or policy failure). Payload highl
- `reportId` / `scanId` / `imageDigest` — identifiers mirroring the report-ready event. As with the report-ready payload, `scanId` currently mirrors `reportId` as a temporary shim.
- **Attributes:** `reportId`, `policyRevisionId`, `policyDigest`, `verdict`.
- **Links:** same as above (`ui`, `report`, `policy`) with `attestation` populated when DSSE metadata exists.
- **Links:** same as above (`report.*`, `policy.*`) with `attestation.*` populated when DSSE metadata exists.
- `verdict`, `summary`, `delta`, `policy` — same semantics as above.
- `findings` — array of surfaced findings with `id`, `severity`, optional `cve`, `purl`, and `reachability`.
- `links`, `dsse`, `report` — same structure as §2.1 (allows Notifier to reuse signatures).

16
docs/events/samples/scanner.event.report.ready@1.sample.json
View File

@@ -46,10 +46,18 @@
"revisionId": "rev-42"
},
"links": {
"ui": "https://scanner.example/ui/reports/report-abc",
"report": "https://scanner.example/api/v1/reports/report-abc",
"policy": "https://scanner.example/api/v1/policy/revisions/rev-42",
"attestation": "https://scanner.example/ui/attestations/report-abc"
"report": {
"ui": "https://scanner.example/ui/reports/report-abc",
"api": "https://scanner.example/api/v1/reports/report-abc"
},
"policy": {
"ui": "https://scanner.example/ui/policy/revisions/rev-42",
"api": "https://scanner.example/api/v1/policy/revisions/rev-42"
},
"attestation": {
"ui": "https://scanner.example/ui/attestations/report-abc",
"api": "https://scanner.example/api/v1/reports/report-abc/attestation"
}
},
"dsse": {
"payloadType": "application/vnd.stellaops.report+json",

16
docs/events/samples/scanner.event.scan.completed@1.sample.json
View File

@@ -52,10 +52,18 @@
}
],
"links": {
"ui": "https://scanner.example/ui/reports/report-abc",
"report": "https://scanner.example/api/v1/reports/report-abc",
"policy": "https://scanner.example/api/v1/policy/revisions/rev-42",
"attestation": "https://scanner.example/ui/attestations/report-abc"
"report": {
"ui": "https://scanner.example/ui/reports/report-abc",
"api": "https://scanner.example/api/v1/reports/report-abc"
},
"policy": {
"ui": "https://scanner.example/ui/policy/revisions/rev-42",
"api": "https://scanner.example/api/v1/policy/revisions/rev-42"
},
"attestation": {
"ui": "https://scanner.example/ui/attestations/report-abc",
"api": "https://scanner.example/api/v1/reports/report-abc/attestation"
}
},
"dsse": {
"payloadType": "application/vnd.stellaops.report+json",

17
docs/events/scanner.event.report.ready@1.json
View File

@@ -126,10 +126,9 @@
"type": "object",
"additionalProperties": false,
"properties": {
"ui": {"type": "string", "format": "uri"},
"report": {"type": "string", "format": "uri"},
"policy": {"type": "string", "format": "uri"},
"attestation": {"type": "string", "format": "uri"}
"report": {"$ref": "#/definitions/linkTarget"},
"policy": {"$ref": "#/definitions/linkTarget"},
"attestation": {"$ref": "#/definitions/linkTarget"}
}
},
"dsse": {
@@ -161,4 +160,14 @@
}
}
}
"definitions": {
"linkTarget": {
"type": "object",
"additionalProperties": false,
"properties": {
"ui": {"type": "string", "format": "uri"},
"api": {"type": "string", "format": "uri"}
}
}
}
}

17
docs/events/scanner.event.scan.completed@1.json
View File

@@ -136,10 +136,9 @@
"type": "object",
"additionalProperties": false,
"properties": {
"ui": {"type": "string", "format": "uri"},
"report": {"type": "string", "format": "uri"},
"policy": {"type": "string", "format": "uri"},
"attestation": {"type": "string", "format": "uri"}
"report": {"$ref": "#/definitions/linkTarget"},
"policy": {"$ref": "#/definitions/linkTarget"},
"attestation": {"$ref": "#/definitions/linkTarget"}
}
},
"dsse": {
@@ -171,4 +170,14 @@
}
}
}
"definitions": {
"linkTarget": {
"type": "object",
"additionalProperties": false,
"properties": {
"ui": {"type": "string", "format": "uri"},
"api": {"type": "string", "format": "uri"}
}
}
}
}

30
docs/examples/ui-tours.md
View File

@@ -40,14 +40,10 @@ These tours stitch together the primary Console workspaces so trainers can deliv
8. **Wrap with CLI:** Pop terminal and run `stella findings explain --policy <id> --finding <key> --format markdown` to show reproducibility.
### 2.3 Capture checklist
- `docs/assets/ui/tours/triage-step-01.png` — dashboard ticker highlighting new criticals.
![Tour A – dashboard criticals](../assets/ui/tours/triage-step-01.png)
- `docs/assets/ui/tours/triage-step-03.png` — filter tray with severity/time window applied.
![Tour A – filter tray](../assets/ui/tours/triage-step-03.png)
- `docs/assets/ui/tours/triage-step-04.png` — explain drawer evidence tab.
![Tour A – explain drawer evidence](../assets/ui/tours/triage-step-04.png)
- `docs/assets/ui/tours/triage-flow.gif` — 20 s screen recording of steps 1–5 with annotations.
![Tour A – walkthrough GIF](../assets/ui/tours/triage-flow.gif)
- `docs/assets/ui/tours/triage-step-01.png` — dashboard ticker highlighting new criticals. *(capture pending)*
- `docs/assets/ui/tours/triage-step-03.png` — filter tray with severity/time window applied. *(capture pending)*
- `docs/assets/ui/tours/triage-step-04.png` — explain drawer evidence tab. *(capture pending)*
- `docs/assets/ui/tours/triage-flow.gif` — 20 s screen recording of steps 1–5 with annotations. *(capture pending)*
### 2.4 Talking points & callouts
- Call out Aggregation-Only boundaries: findings reference Concelier/Excititor provenance, UI stays read-only.
@@ -78,12 +74,9 @@ These tours stitch together the primary Console workspaces so trainers can deliv
8. **CLI parity close-out:** Run `stella downloads manifest --channel stable` to mirror UI manifest retrieval. Confirm digests match.
### 3.3 Capture checklist
- `docs/assets/ui/tours/audit-step-02.png` — manifest verification banner (green).
![Tour B – manifest verification](../assets/ui/tours/audit-step-02.png)
- `docs/assets/ui/tours/audit-step-05.png` — exports tab showing evidence bundle ready.
![Tour B – exports tab](../assets/ui/tours/audit-step-05.png)
- `docs/assets/ui/tours/audit-flow.gif` — 25 s capture from manifest view through export download.
![Tour B – walkthrough GIF](../assets/ui/tours/audit-flow.gif)
- `docs/assets/ui/tours/audit-step-02.png` — manifest verification banner (green). *(capture pending)*
- `docs/assets/ui/tours/audit-step-05.png` — exports tab showing evidence bundle ready. *(capture pending)*
- `docs/assets/ui/tours/audit-flow.gif` — 25 s capture from manifest view through export download. *(capture pending)*
### 3.4 Talking points & callouts
- Stress deterministic manifests and Cosign signatures; reference deployment doc for TLS/CSP alignment.
@@ -114,12 +107,9 @@ These tours stitch together the primary Console workspaces so trainers can deliv
8. **Publish CLI parity:** Execute `stella policy promote --policy <id> --revision <rev> --run-mode full` to reinforce reproducibility.
### 4.3 Capture checklist
- `docs/assets/ui/tours/policy-step-02.png` — editor checklist with lint/simulation statuses.
![Tour C – editor checklist](../assets/ui/tours/policy-step-02.png)
- `docs/assets/ui/tours/policy-step-04.png` — simulation diff comparing Active vs Staged.
![Tour C – simulation diff](../assets/ui/tours/policy-step-04.png)
- `docs/assets/ui/tours/policy-flow.gif` — 30 s clip from draft view through promotion confirmation.
![Tour C – walkthrough GIF](../assets/ui/tours/policy-flow.gif)
- `docs/assets/ui/tours/policy-step-02.png` — editor checklist with lint/simulation statuses. *(capture pending)*
- `docs/assets/ui/tours/policy-step-04.png` — simulation diff comparing Active vs Staged. *(capture pending)*
- `docs/assets/ui/tours/policy-flow.gif` — 30 s clip from draft view through promotion confirmation. *(capture pending)*
### 4.4 Talking points & callouts
- Stress governance: approvals logged with correlation IDs, fresh-auth enforced.

2
docs/faq/policy-faq.md
View File

@@ -1,6 +1,6 @@
# Policy Engine FAQ
Answers to questions that Support, Ops, and Policy Guild teams receive most frequently. Pair this FAQ with the [Policy Lifecycle](../policy/lifecycle.md), [Runs](../policy/runs.md), and [CLI guide](../cli/policy.md) for deeper explanations.
Answers to questions that Support, Ops, and Policy Guild teams receive most frequently. Pair this FAQ with the [Policy Lifecycle](../policy/lifecycle.md), [Runs](../policy/runs.md), and [CLI guide](../modules/cli/guides/policy.md) for deeper explanations.
---

49
docs/high-level-architecture.md Normal file
View File

@@ -0,0 +1,49 @@
# High-Level Architecture – 10-Minute Tour
```
Build → Sign → Store → Scan → Policy → Attest → Notify/Export
```
## 1. Guiding Principles
- **SBOM-first everything:** scanners prefer CycloneDX/SPDX inputs and only unpack images when SBOMs are absent.
- **Restart-time plug-ins:** analyzers, exporters, and connectors are loaded at startup, keeping runtime surfaces predictable.
- **Sovereign posture:** all services tolerate zero outbound traffic; Offline Update Kits mirror feeds and trust roots.
## 2. System Map
| Tier | Services | Key responsibilities |
|------|----------|----------------------|
| **Edge / Identity** | `StellaOps.Authority` | Issues short-lived OpToks (DPoP + mTLS), exposes OIDC device-code + auth-code flows, rotates JWKS. |
| **Scan & attest** | `StellaOps.Scanner` (API + Worker), `StellaOps.Signer`, `StellaOps.Attestor` | Accept SBOMs/images, drive analyzers, produce DSSE/SRM bundles, optionally log to Rekor mirror. |
| **Evidence graph** | `StellaOps.Concelier`, `StellaOps.Excititor`, `StellaOps.Policy.Engine` | Ingest advisories/VEX, correlate linksets, run lattice policy and VEX-first decisioning. |
| **Experience** | `StellaOps.UI`, `StellaOps.Cli`, `StellaOps.Notify`, `StellaOps.ExportCenter` | Surface findings, automate policy workflows, deliver notifications, package offline mirrors. |
| **Data plane** | MongoDB, Redis, RustFS/object storage, NATS/Redis Streams | Deterministic storage, counters, queue orchestration, Delta SBOM cache. |
## 3. Request Lifecycle
1. **Evidence enters** via Concelier and Excititor connectors (Aggregation-Only Contract).
2. **SBOM arrives** from CLI/CI, Scanner deduplicates layers and enqueues work.
3. **Analyzer bundle** runs inside Worker, streams SRM events, stores SBOM fragments in content-addressed cache.
4. **Policy Engine** merges advisories, VEX, and SBOM inventory, applies lattice logic, emits explain trace.
5. **Signer + Attestor** wrap results into DSSE, optionally record to Rekor, and hand proof bundles to Export Center.
6. **UI/CLI** surface findings, quotas, and replay manifests; Notify pushes channel-specific digests.
## 4. Extension Points
- **Scanner analyzers** (`plugins/scanner/**`): ship restart-time plug-ins with deterministic manifests.
- **Concelier connectors** (`src/Concelier/__Libraries/**`): fetch advisories, adhere to Aggregation-Only Contract.
- **Policy packs**: upload YAML/Rego bundles with fixtures; simulation endpoints test impacts before promotion.
- **Crypto profiles**: import trust-root packs to align with regional signature mandates.
## 5. Sovereign & Offline Considerations
- **Offline Update Kit** carries vulnerability feeds, container images (x86-64 + arm64), Cosign signatures, and detatched JWS manifests.
- **Transparency mirrors**: Attestor caches Rekor proofs; mirrors can be deployed on-prem for DSSE verification.
- **Quota enforcement** uses Redis counters with local JWT validation, so no central service is required.
## 6. Where to Learn More
- Deep dive per module in `docs/modules/<module>/architecture.md`.
- Study strategic themes in [moat.md](moat.md).
- Review API and CLI contracts in [09_API_CLI_REFERENCE.md](09_API_CLI_REFERENCE.md).

2
docs/implplan/SPRINTS.md
View File

@@ -492,7 +492,7 @@ This file describe implementation of Stella Ops (docs/README.md). Implementation
| Sprint 33 | Orchestrator Dashboard | docs/TASKS.md | TODO | Docs Guild | DOCS-ORCH-33-001 | Author `/docs/orchestrator/api.md` with endpoints, WebSocket events, error codes, and imposed rule reminder. |
| Sprint 33 | Orchestrator Dashboard | docs/TASKS.md | TODO | Docs Guild | DOCS-ORCH-33-002 | Author `/docs/orchestrator/console.md` covering screens, accessibility, and live updates. |
| Sprint 33 | Orchestrator Dashboard | docs/TASKS.md | TODO | Docs Guild | DOCS-ORCH-33-003 | Author `/docs/orchestrator/cli.md` with command reference, examples, and exit codes. |
| Sprint 33 | Governance & Rules | ops/devops/TASKS.md | DOING (2025-10-26) | DevOps Guild, Platform Leads | DEVOPS-RULES-33-001 | Contracts & Rules anchor (gateway proxy-only; Policy Engine overlays/simulations; AOC ingestion canonicalization; Graph Indexer + Graph API as sole platform). |
| Sprint 33 | Governance & Rules | ops/devops/TASKS.md | REVIEW (2025-10-30) | DevOps Guild, Platform Leads | DEVOPS-RULES-33-001 | Contracts & Rules anchor (gateway proxy-only; Policy Engine overlays/simulations; AOC ingestion canonicalization; Graph Indexer + Graph API as sole platform). |
| Sprint 33 | Orchestrator Dashboard | ops/devops/TASKS.md | TODO | DevOps Guild | DEVOPS-ORCH-33-001 | Publish Grafana dashboards for rate-limit/backpressure/error clustering and configure alert rules with runbooks. |
| Sprint 33 | Orchestrator Dashboard | src/Authority/StellaOps.Authority/TASKS.md | TODO | Authority Core & Security Guild | AUTH-ORCH-33-001 | Add `Orch.Operator` role, control action scopes, and enforce reason/ticket field capture. |
| Sprint 33 | Orchestrator Dashboard | src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md | TODO | Concelier Core Guild | CONCELIER-ORCH-33-001 | Wire orchestrator control hooks (pause, throttle, retry) into Concelier workers with safe checkpoints. |

2
docs/ingestion/aggregation-only-contract.md
View File

@@ -7,7 +7,7 @@
- Defines the canonical behaviour for `advisory_raw` and `vex_raw` collections and the linkset hints they may emit.
- Applies to every ingestion runtime (`StellaOps.Concelier.*`, `StellaOps.Excititor.*`), the Authority scopes that guard them, and the DevOps/QA surfaces that verify compliance.
- Complements the high-level architecture in [Concelier](../modules/concelier/architecture.md) and Authority enforcement documented in [Authority Architecture](../modules/authority/architecture.md).
- Paired guidance: see the guard-rail checkpoints in [AOC Guardrails](../aoc/aoc-guardrails.md) and CLI usage that will land in `/docs/modules/cli/guides/` as part of Sprint 19 follow-up.
- Paired guidance: see the guard-rail checkpoints in [AOC Guardrails](../aoc/aoc-guardrails.md), the implementation reference in [AOC Guard Library](../aoc/guard-library.md), and CLI usage that will land in `/docs/modules/cli/guides/` as part of Sprint 19 follow-up.
## 2. Philosophy and Goals

33
docs/key-features.md Normal file
View File

@@ -0,0 +1,33 @@
# Key Features – Capability Cards
Each card is a fast read pairing the headline capability with the evidence that backs it and why it matters day to day.
## 1. Delta SBOM Engine
- **What it is:** Layer-aware ingestion keeps the SBOM catalog content-addressed; rescans only fetch new layers and update dependency/vulnerability cartographs.
- **Evidence:** Deterministic Replay Manifest (SRM) captures the exact analyzer inputs/outputs per layer.
- **Why it matters:** Warm scans drop below one second, so CI/CD pipelines stay fast even under the free-tier quota.
## 2. Lattice Policy + OpenVEX
- **What it is:** Policy engine merges SBOM, advisories, VEX, and waivers through lattice logic that prioritises exploitability.
- **Evidence:** OpenVEX is treated as first-class input; the policy UI renders explain traces, while custom rule packs let teams automate muting, expirations, and non-VEX alert logic.
- **Why it matters:** Teams can distinguish exploitable risk from noise, tune the experience beyond VEX statements, and prove why a deployment was blocked or allowed.
## 3. Sovereign Crypto Profiles
- **What it is:** Bring-your-own trust bundles that switch signing algorithms (FIPS, eIDAS, GOST, SM) without code changes.
- **Evidence:** Crypto profiles travel with Offline Update Kits and post-quantum trust packs, keeping signatures verifiable in regulated sectors.
- **Why it matters:** You meet regional crypto requirements while keeping provenance attestations consistent across tenants.
## 4. Deterministic Replay & Evidence Bundles
- **What it is:** Every scan produces a DSSE + SRM bundle that can be replayed with `stella replay`.
- **Evidence:** Replay manifests capture analyzer versions, lattice state, and attestations in content-addressed storage for audit trails.
- **Why it matters:** Auditors and incident responders can re-run a historical scan and trust the findings were not tampered with.
## 5. Transparent Quotas & Offline Operations
- **What it is:** Redis-backed counters surface `{{ quota_token }}` scans/day via headers, UI banners, and `/quota` API; Offline Update Kits mirror feeds.
- **Evidence:** Quota tokens verify locally using bundled public keys, and Offline Update Kits include mirrored advisories, SBOM feeds, and VEX sources.
- **Why it matters:** You stay within predictable limits, avoid surprise throttling, and operate entirely offline when needed.
### Explore Further
- Walk the first deployment in [quickstart.md](quickstart.md).
- Dive into architectural flows in [high-level-architecture.md](high-level-architecture.md).
- Need detailed matrices? The legacy [feature matrix](04_FEATURE_MATRIX.md) and [vision](03_VISION.md) remain available for deep dives.

4
docs/modules/authority/operations/backup-restore.md
View File

@@ -80,12 +80,12 @@
docker compose up -d
curl -fsS http://localhost:8080/health
```
6. **Validate JWKS and tokens:** call `/jwks` and issue a short-lived token via the CLI to confirm key material matches expectations. If the restored environment requires a fresh signing key, follow the rotation SOP in [`docs/11_AUTHORITY.md`](../11_AUTHORITY.md) using `ops/authority/key-rotation.sh` to invoke `/internal/signing/rotate`.
6. **Validate JWKS and tokens:** call `/jwks` and issue a short-lived token via the CLI to confirm key material matches expectations. If the restored environment requires a fresh signing key, follow the rotation SOP in [`docs/11_AUTHORITY.md`](../../../11_AUTHORITY.md) using `ops/authority/key-rotation.sh` to invoke `/internal/signing/rotate`.
## Disaster Recovery Notes
- **Air-gapped replication:** replicate archives via the Offline Update Kit transport channels; never attach USB devices without scanning.
- **Retention:** maintain 30 daily snapshots + 12 monthly archival copies. Rotate encryption keys annually.
- **Key compromise:** if signing keys are suspected compromised, restore from the latest clean backup, rotate via OPS3 (see `ops/authority/key-rotation.sh` and `docs/11_AUTHORITY.md`), and publish a revocation notice.
- **Key compromise:** if signing keys are suspected compromised, restore from the latest clean backup, rotate via OPS3 (see `ops/authority/key-rotation.sh` and [`docs/11_AUTHORITY.md`](../../../11_AUTHORITY.md)), and publish a revocation notice.
- **Mongo version:** keep dump/restore images pinned to the deployment version (compose uses `mongo:7`). Driver 3.5.0 requires MongoDB **4.2+**—clusters still on 4.0 must be upgraded before restore, and future driver releases will drop 4.0 entirely. citeturn1open1
## Verification Checklist

6
docs/modules/cli/guides/cli-reference.md
View File

@@ -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](../../platform/architecture-overview.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](../../../ingestion/aggregation-only-contract.md) and the [architecture overview](../architecture.md). They consume Authority-issued tokens with tenant scopes and never mutate ingestion stores.
---
@@ -285,9 +285,9 @@ Additional notes:
## 5 · Related references
- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md)
- [Aggregation-Only Contract reference](../../../ingestion/aggregation-only-contract.md)
- [Architecture overview](../../platform/architecture-overview.md)
- [Console AOC dashboard](../../ui/console.md)
- [Console AOC dashboard](../../../ui/console.md)
- [Authority scopes](../../authority/architecture.md)
---

2
docs/modules/platform/architecture-overview.md
View File

@@ -147,7 +147,7 @@ sequenceDiagram
- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md)
- [Concelier architecture](../concelier/architecture.md)
- [Excititor architecture](../excititor/architecture.md)
- [Policy Engine architecture](policy-engine.md)
- [Policy Engine architecture](../policy/architecture.md)
- [Authority service](../authority/architecture.md)
- [Observability standards (upcoming)](../../observability/policy.md) – interim reference for telemetry naming.

2
docs/modules/telemetry/operations/collector.md
View File

@@ -39,7 +39,7 @@ docker compose -f docker-compose.telemetry-storage.yaml up -d
python ../../ops/devops/telemetry/smoke_otel_collector.py --host localhost
```
The smoke test posts sample traces, metrics, and logs and verifies that the collector increments the `otelcol_receiver_accepted_*` counters exposed via the Prometheus exporter. The storage overlay gives you a local Prometheus/Tempo/Loki stack to confirm end-to-end wiring. The same client certificate can be used by local services to weave traces together. See [`Telemetry Storage Deployment`](telemetry-storage.md) for the storage configuration guidelines used in staging/production.
The smoke test posts sample traces, metrics, and logs and verifies that the collector increments the `otelcol_receiver_accepted_*` counters exposed via the Prometheus exporter. The storage overlay gives you a local Prometheus/Tempo/Loki stack to confirm end-to-end wiring. The same client certificate can be used by local services to weave traces together. See [`Telemetry Storage Deployment`](storage.md) for the storage configuration guidelines used in staging/production.
---

2
docs/modules/telemetry/operations/storage.md
View File

@@ -27,6 +27,7 @@ cd deploy/compose
docker compose -f docker-compose.telemetry.yaml up -d
docker compose -f docker-compose.telemetry-storage.yaml up -d
python ../../ops/devops/telemetry/smoke_otel_collector.py --host localhost
python ../../ops/devops/telemetry/validate_storage_stack.py
```
Configuration files live in `deploy/telemetry/storage/`. Adjust the overrides before shipping to staging/production.
@@ -160,6 +161,7 @@ Provision the following secrets/configs (names can be overridden via Helm values
- [ ] Prometheus scrape succeeds (`curl -sk --cert client.crt --key client.key https://collector:9464`).
- [ ] Tempo and Loki report tenant activity (`/api/status`).
- [ ] Retention policy tested by uploading sample data and verifying expiry.
- [ ] `python ops/devops/telemetry/validate_storage_stack.py` passes before committing updated configs.
- [ ] Alerts wired into SLO evaluator (DEVOPS-OBS-51-001).
- [ ] Component rule packs imported (e.g. `docs/modules/scheduler/operations/worker-prometheus-rules.yaml`).

2
docs/notifications/overview.md
View File

@@ -55,7 +55,7 @@ The Notify WebService fronts worker state with REST APIs used by the UI and CLI.
| Step | Goal | Reference |
|------|------|-----------|
| 1 | Deploy Notify WebService + Worker with Mongo and Redis | [`modules/notify/architecture.md`](../modules/notify/architecture.md#1-runtime-shape--projects) |
| 2 | Register OAuth clients/scopes in Authority | [`etc/authority.yaml.sample`](../etc/authority.yaml.sample) |
| 2 | Register OAuth clients/scopes in Authority | [`etc/authority.yaml.sample`](../../etc/authority.yaml.sample) |
| 3 | Install channel plug-ins and capture secret references | [`plugins/notify`](../../plugins) |
| 4 | Create a tenant rule and test preview | [`POST /channels/{id}/test`](../modules/notify/architecture.md#8-external-apis-webservice) |
| 5 | Inspect deliveries and digests | `/api/v1/notify/deliveries`, `/api/v1/notify/digests` |

4
docs/observability/observability.md
View File

@@ -120,10 +120,10 @@ Update `docs/assets/dashboards/` with screenshots when Grafana capture pipeline
- [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md)
- [Architecture overview](../modules/platform/architecture-overview.md)
- [Console AOC dashboard](../ui/console.md)
- [CLI AOC commands](../cli/cli-reference.md)
- [CLI AOC commands](../modules/cli/guides/cli-reference.md)
- [Concelier architecture](../modules/concelier/architecture.md)
- [Excititor architecture](../modules/excititor/architecture.md)
- [Scheduler Worker observability guide](../ops/scheduler-worker-operations.md)
- [Scheduler Worker observability guide](../modules/scheduler/operations/worker.md)
---

39
docs/overview.md Normal file
View File

@@ -0,0 +1,39 @@
# Stella Ops – 2‑Minute Overview
## The Problem We Solve
- **Supply-chain attacks exploded 742 % in three years;** regulated teams still need to scan hundreds of containers a day while disconnected from the public Internet.
- **Existing scanners trade freedom for SaaS:** no offline feeds, hidden quotas, noisy results that lack exploitability context.
- **Audit fatigue is real:** Policy decisions are opaque, replaying scans is guesswork, and trust hinges on external transparency logs you do not control.
## The Promise
Stella Ops delivers **deterministic, sovereign container security** that works the same online or fully air-gapped:
1. **Deterministic replay manifests** (SRM) prove every scan result, so auditors can rerun evidence and see the exact same outcome.
2. **Lattice policy engine + OpenVEX** keeps findings explainable; exploitability, attestation, and waivers merge into one verdict.
3. **Sovereign crypto profiles** let you anchor signatures to eIDAS, FIPS, GOST, or SM roots, mirror your feeds, and keep Sigstore-compatible transparency logs offline.
## Core Capability Clusters
| Cluster | What you get | Why it matters |
|---------|--------------|----------------|
| **SBOM-first scanning** | Delta-layer SBOM cache, sub‑5 s warm scans, Trivy/CycloneDX/SPDX ingestion + dependency cartographing | Speeds repeat scans 10× and keeps SBOMs the source of truth |
| **Explainable policy** | OpenVEX + lattice logic, policy engine for custom rule packs, waiver expirations | Reduces alert fatigue, supports alert muting beyond VEX, and shows why a finding blocks deploy |
| **Attestation & provenance** | DSSE bundles, optional Rekor mirror, DSSE → CLI/UI exports | Lets you prove integrity without relying on external services |
| **Offline operations** | Offline Update Kit bundles, mirrored feeds, quota tokens verified locally | Works for sovereign clouds, SCIFs, and heavily regulated sectors |
| **Governance & observability** | Structured audit trails, quota transparency, per-tenant metrics | Keeps compliance teams and operators in sync without extra tooling |
## Who Benefits
| Persona | Outcome in week one |
|---------|--------------------|
| **Security engineering** | Deterministic replay + explain traces | cuts review time, keeps waivers honest |
| **Platform / SRE** | Fast scans, local registry, no Internet dependency | fits pipelines and air-gapped staging |
| **Compliance & risk** | Signed SBOMs, provable quotas, legal/attestation docs | supports audits without custom tooling |
## Where to Go Next
- 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).

93
docs/quickstart.md Normal file
View File

@@ -0,0 +1,93 @@
# Quickstart – First Scan in Five Minutes
> **Status:** public α image ships late 2025 (`registry.stella-ops.org/stella-ops/stella-ops:0.1.0-alpha`). Commands below are ready the moment the tag lands.
## 0. Prerequisites (1 min)
| Requirement | Minimum | Notes |
|-------------|---------|-------|
| OS | Ubuntu 22.04 LTS / Alma 9 | x86‑64 or arm64 |
| Docker | Engine 25 + Compose v2 | `docker -v` |
| Resources | 2 vCPU / 2 GiB RAM / 10 GiB SSD | Fits developer laptops |
| TLS trust | Built-in self-signed or your own certs | Replace `/certs` before production |
Keep Redis and MongoDB bundled unless you already operate managed instances.
## 1. Download the signed bundles (1 min)
```bash
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml
curl -LO https://get.stella-ops.org/docker-compose.infrastructure.yml.sig
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml
curl -LO https://get.stella-ops.org/docker-compose.stella-ops.yml.sig
cosign verify-blob \
--key https://stella-ops.org/keys/cosign.pub \
--signature docker-compose.infrastructure.yml.sig \
docker-compose.infrastructure.yml
cosign verify-blob \
--key https://stella-ops.org/keys/cosign.pub \
--signature docker-compose.stella-ops.yml.sig \
docker-compose.stella-ops.yml
```
*Air-gapped?* The [Offline Update Kit](24_OFFLINE_KIT.md) ships these files plus feeds and plug-ins.
## 2. Configure `.env` (1 min)
Create `.env` with the essentials:
```dotenv
STELLA_OPS_COMPANY_NAME="Acme Corp"
STELLA_OPS_DEFAULT_ADMIN_USERNAME="admin"
STELLA_OPS_DEFAULT_ADMIN_PASSWORD="change-me!"
MONGO_INITDB_ROOT_USERNAME=stella_admin
MONGO_INITDB_ROOT_PASSWORD=$(openssl rand -base64 18)
MONGO_URL=mongodb
REDIS_PASSWORD=$(openssl rand -base64 18)
REDIS_URL=redis
```
Use existing Redis/Mongo endpoints by setting `MONGO_URL` and `REDIS_URL`. Keep credentials scoped to Stella Ops; Redis counters enforce the transparent quota (`{{ quota_token }}` scans/day).
## 3. Launch services (1 min)
```bash
docker compose --env-file .env -f docker-compose.infrastructure.yml up -d
docker compose --env-file .env -f docker-compose.stella-ops.yml up -d
```
- `StellaOps.Authority` issues short-lived OpToks for CLI/UI.
- `StellaOps.Scanner` hosts `/scan`, queues work to Workers.
- `StellaOps.Policy.Engine` and `StellaOps.Concelier` start with seeded policies, feeds sync in the background.
## 4. Run your first scan (1 min)
```bash
stella auth login --device-code
stella scan image \
--image registry.stella-ops.org/demo/juice-shop:latest \
--sbom-type cyclonedx-json
```
- Expect `<5 s` warm scans once the Delta SBOM cache is primed.
- CLI exits non-zero if lattice policy blocks the image; use `stella policy explain --last` for context.
- Headers `X-Stella-Quota-Remaining` and the UI banner keep quota usage transparent.
## 5. Verify & explore (1 min)
- Check the Console (`https://localhost:8443`) to view findings, VEX evidence, and deterministic replay manifests.
- Export the DSSE bundle: `stella export run --format dsse`.
- Capture evidence for audit: `stella attest bundle --output demo.dsse.json`.
### Sovereign mode in one click
- Import the Offline Update Kit (`stella offline-kit import ./stella-ouk-2025-alpha.tar.gz`) to replace every external feed.
- Apply a CryptoProfile (`stella authority crypto apply ./profiles/fips.yaml`) to swap signing algorithms without rebuilding.
### Next steps
- 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).

2
docs/security/authority-scopes.md
View File

@@ -241,7 +241,7 @@ clients:
- [Concelier architecture](../modules/concelier/architecture.md)
- [Excititor architecture](../modules/excititor/architecture.md)
- [Policy governance](policy-governance.md)
- [Authority key rotation playbook](../ops/authority-key-rotation.md)
- [Authority key rotation playbook](../modules/authority/operations/key-rotation.md)
---

17
docs/technical/README.md Normal file
View File

@@ -0,0 +1,17 @@
# Technical Documentation Index
> Use this hub when you need the full implementation detail: architecture blueprints, data contracts, developer guides, and operations playbooks. Each section below links to the canonical sources already living in `docs/**`.
## Sections
- [Strategy & Core Specs](strategy/README.md)
- [Platform Architecture & Module Dossiers](architecture/README.md)
- [Component map](architecture/component-map.md)
- [Interfaces, Contracts & Schemas](interfaces/README.md)
- [Development Guides & Tooling](development/README.md)
- [Operations, Deployment & Offline](operations/README.md)
- [Observability, Notifications & Telemetry](observability/README.md)
- [Security, Risk & Governance](security/README.md)
- [Process, Coordination & Change Logs](process/README.md)
---
Need a doc that is missing here? Raise an entry in `docs/TASKS.md` so the index stays complete.

44
docs/technical/architecture/README.md Normal file
View File

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

77
docs/technical/architecture/component-map.md Normal file
View File

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

33
docs/technical/development/README.md Normal file
View File

@@ -0,0 +1,33 @@
# Development Guides & Tooling
Resources for contributors building features, plug-ins, connectors, and tests.
## Engineering Standards & Quality
- [../18_CODING_STANDARDS.md](../../18_CODING_STANDARDS.md) – language guidelines, project layout, review expectations.
- [../19_TEST_SUITE_OVERVIEW.md](../../19_TEST_SUITE_OVERVIEW.md) – unit, integration, golden, and determinism test strategy.
- [../12_PERFORMANCE_WORKBOOK.md](../../12_PERFORMANCE_WORKBOOK.md) – benchmark targets and reference rigs.
- [../cli-vs-ui-parity.md](../../cli-vs-ui-parity.md) – CLI vs Console feature parity tracking.
- [../scanner-core-contracts.md](../../scanner-core-contracts.md) – DTO fixtures consumed by tests.
## Plug-ins, Connectors & Extensions
- [../10_PLUGIN_SDK_GUIDE.md](../../10_PLUGIN_SDK_GUIDE.md) – plug-in lifecycle, manifests, packaging.
- [../10_CONCELIER_CLI_QUICKSTART.md](../../10_CONCELIER_CLI_QUICKSTART.md) – local Concelier + CLI workflow for advisory ingestion.
- Developer guides under [../dev/](../../dev/):
- Connector playbooks (`30_EXCITITOR_CONNECTOR_GUIDE.md`, `30_VEXER_CONNECTOR_GUIDE.md`, `concelier-connector-research-20251011.md`, `kisa_connector_notes.md`).
- Authority and DPoP guidance (`31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md`, `authority-dpop-mtls-plan.md`, `authority-plugin-di-coordination.md`, `authority-rate-limit-tuning-outline.md`, `32_AUTH_CLIENT_GUIDE.md`).
- Analyzer and cache configuration (`SCANNER_CACHE_CONFIGURATION.md`, `java-analyzer-observation-plan.md`, `EXCITITOR_STATEMENT_BACKFILL.md`).
- Normalisation & merge references (`aoc-normalization-removal-notes.md`, `merge_semver_playbook.md`, `normalized-rule-recipes.md`, `normalized_versions_rollout.md`).
- Operational templates and fixtures (`templates/`, `fixtures.md`).
- Mongo/Cartographer details (`mongo_indices.md`, `cartographer-graph-handshake.md`).
## CLI, SDKs & Automation
- [../09_API_CLI_REFERENCE.md](../../09_API_CLI_REFERENCE.md) – authoritative CLI commands and flags (use for scripting).
- [../api/sdk-openapi-program.md](../../api/sdk-openapi-program.md) – guidance for downstream SDK generation.
- [../policy/gateway.md](../../policy/gateway.md) & [../policy/dsl.md](../../policy/dsl.md) – foundations for automating policy programs.
## Scaffolding & Examples
- [../examples/policies/README.md](../../examples/policies/README.md) – sample policy bundles.
- [../examples/ui-tours.md](../../examples/ui-tours.md) and [../assets/ui/tours/README.md](../../assets/ui/tours/README.md) – console tour authoring guides.
- [../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.

48
docs/technical/interfaces/README.md Normal file
View File

@@ -0,0 +1,48 @@
# Interfaces, Contracts & Schemas
Specifications covering APIs, data contracts, event envelopes, and enforcement models.
## External & Internal APIs
- [../09_API_CLI_REFERENCE.md](../../09_API_CLI_REFERENCE.md) – canonical REST and CLI surface (scan, policy, auth, health).
- [../api/policy.md](../../api/policy.md) – Policy Engine REST endpoints.
- Module APIs: see relevant module architecture docs (e.g., [../../modules/export-center/api.md](../../modules/export-center/api.md)).
## Policy & Decisioning
- [../policy/overview.md](../../policy/overview.md) – Policy Engine fundamentals.
- [../policy/dsl.md](../../policy/dsl.md) – `stella-dsl@1` grammar.
- [../policy/lifecycle.md](../../policy/lifecycle.md) – creation, promotion, approval flows.
- [../policy/runs.md](../../policy/runs.md) – execution orchestrations.
- [../policy/exception-effects.md](../../policy/exception-effects.md) – waiver semantics.
- [../policy/gateway.md](../../policy/gateway.md) – gateway service contract.
- [../60_POLICY_TEMPLATES.md](../../60_POLICY_TEMPLATES.md) – YAML/Rego samples.
## Data Schemas & Storage Contracts
- [../11_DATA_SCHEMAS.md](../../11_DATA_SCHEMAS.md) – MongoDB/Redis/document shapes.
- JSON schemas under [../schemas/](../../schemas/) – policy diff, explain trace, run request, run status, preview sample, report sample.
- [../../modules/scanner/architecture.md](../../modules/scanner/architecture.md) – SBOM cache and scan job contracts.
- [../../scanner-core-contracts.md](../../scanner-core-contracts.md) – shared scanner DTOs.
## Events & Messaging
- [../events/README.md](../../events/README.md) – event catalogue (`scanner.scan.completed@1`, `scheduler.rescan.delta@1`, etc.).
- Payload schemas in [../events/*.json](../../events/) and samples in [../events/samples/](../../events/samples/).
- [../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.
- [../aoc/aoc-guardrails.md](../../aoc/aoc-guardrails.md) – guardrails checklist.
- [../advisories/aggregation.md](../../advisories/aggregation.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.
## Identity, Quota & Licence Enforcement
- [../license-jwt-quota.md](../../license-jwt-quota.md) – offline quota token design.
- [../30_QUOTA_ENFORCEMENT_FLOW1.md](../../30_QUOTA_ENFORCEMENT_FLOW1.md) – enforcement sequence diagram.
- [../33_333_QUOTA_OVERVIEW.md](../../33_333_QUOTA_OVERVIEW.md) – free tier policy.
- [../30_QUOTA_ENFORCEMENT_FLOW1.md](../../30_QUOTA_ENFORCEMENT_FLOW1.md) and [../33_333_QUOTA_OVERVIEW.md](../../33_333_QUOTA_OVERVIEW.md) – pair with [../29_LEGAL_FAQ_QUOTA.md](../../29_LEGAL_FAQ_QUOTA.md) for legal framing.
- [../../modules/authority/architecture.md](../../modules/authority/architecture.md) – OpTok issuance & validation contracts.
- [../../modules/registry/architecture.md](../../modules/registry/architecture.md) – token service scope and audit requirements.
## Transparency & Attestation
- [../../modules/attestor/architecture.md](../../modules/attestor/architecture.md) – DSSE/Rekor bundle contracts.
- [../../modules/signer/architecture.md](../../modules/signer/architecture.md) – signing workflow contracts.
- [../../modules/export-center/provenance-and-signing.md](../../modules/export-center/provenance-and-signing.md) – export bundle evidence artefacts.

29
docs/technical/observability/README.md Normal file
View File

@@ -0,0 +1,29 @@
# Observability, Notifications & Telemetry
Guides for capturing metrics, logs, traces, and delivering notifications.
## Observability Stack
- [../observability/observability.md](../../observability/observability.md) – AOC observability overview.
- [../observability/policy.md](../../observability/policy.md) – policy-specific telemetry guidance.
- [../observability/ui-telemetry.md](../../observability/ui-telemetry.md) – UI instrumentation and SSE tracing.
- Telemetry module docs: [../../modules/telemetry/architecture.md](../../modules/telemetry/architecture.md), [../../modules/telemetry/implementation_plan.md](../../modules/telemetry/implementation_plan.md), [../../modules/telemetry/operations/collector.md](../../modules/telemetry/operations/collector.md), [../../modules/telemetry/operations/storage.md](../../modules/telemetry/operations/storage.md).
- Authority / Scanner dashboards: see respective module `operations/*.json` and Grafana runbooks.
## Events & Streaming
- [../events/README.md](../../events/README.md) – canonical event definitions.
- Payload schemas (JSON): [../events/scanner.scan.completed@1.json](../../events/scanner.scan.completed@1.json), [../events/scanner.report.ready@1.json](../../events/scanner.report.ready@1.json), [../events/scheduler.rescan.delta@1.json](../../events/scheduler.rescan.delta@1.json), [../events/attestor.logged@1.json](../../events/attestor.logged@1.json), etc.
- [../events/samples/](../../events/samples/) – sample payloads with validation workflow.
- [../../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/architecture.md](../../modules/notify/architecture.md) & [../../modules/notify/implementation_plan.md](../../modules/notify/implementation_plan.md) – implementation detail.
## Metrics & Dashboards
- Scanner analyzers dashboard: [../../modules/scanner/operations/analyzers-grafana-dashboard.json](../../modules/scanner/operations/analyzers-grafana-dashboard.json).
- Scheduler worker dashboards & alert rules: [../../modules/scheduler/operations/worker-grafana-dashboard.json](../../modules/scheduler/operations/worker-grafana-dashboard.json), [../../modules/scheduler/operations/worker-prometheus-rules.yaml](../../modules/scheduler/operations/worker-prometheus-rules.yaml).
- Authority monitoring: [../../modules/authority/operations/monitoring.md](../../modules/authority/operations/monitoring.md).
- DevOps observability tasks: see [../../modules/devops/architecture.md](../../modules/devops/architecture.md) and runbooks.

47
docs/technical/operations/README.md Normal file
View File

@@ -0,0 +1,47 @@
# Operations, Deployment & Offline
Deployment, runtime operations, and air-gap playbooks for running Stella Ops in production.
## 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.
- [../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.
- [../artifacts/bom-index/README.md](../../artifacts/bom-index/README.md) – BOM index artifact layout for Offline Kit exports.
## Offline & Sovereign Operations
- [../quickstart.md](../../quickstart.md) – 5-minute path to first scan (useful for smoke testing installs).
- [../10_OFFLINE_KIT.md](../../10_OFFLINE_KIT.md) & [../24_OFFLINE_KIT.md](../../24_OFFLINE_KIT.md) – bundle contents, import/export workflow.
- [../airgap/airgap-mode.md](../../airgap/airgap-mode.md) – configuration for sealed environments.
- [../license-jwt-quota.md](../../license-jwt-quota.md) – offline quota token lifecycle.
- [../10_CONCELIER_CLI_QUICKSTART.md](../../10_CONCELIER_CLI_QUICKSTART.md) – workstation ingest/export workflow (operators).
## Hardening & Governance
- [../17_SECURITY_HARDENING_GUIDE.md](../../17_SECURITY_HARDENING_GUIDE.md) – platform hardening checklist.
- [../accessibility.md](../../accessibility.md) – accessibility checklist for console deployments.
- [../security/console-security.md](../../security/console-security.md) – console-specific controls.
- [../security/authority-scopes.md](../../security/authority-scopes.md) – Authority scope model.
- [../security/rate-limits.md](../../security/rate-limits.md) – throttling policy reference.
- [../security/policy-governance.md](../../security/policy-governance.md) – policy governance guardrails.
- [../security/audit-events.md](../../security/audit-events.md) – audit event catalogue.
- [../security/revocation-bundle.md](../../security/revocation-bundle.md) & [../security/revocation-bundle-example.json](../../security/revocation-bundle-example.json) – revocation workflow.
- [../security/password-hashing.md](../../security/password-hashing.md) – credential storage details.
## 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).
- Observability operations: [../observability/observability.md](../../observability/observability.md), [../observability/ui-telemetry.md](../../observability/ui-telemetry.md).
## DevOps & Release Automation
- [../devops/policy-schema-export.md](../../devops/policy-schema-export.md) – policy schema export automation.
- [../modules/devops/runbooks/launch-readiness.md](../../modules/devops/runbooks/launch-readiness.md), [../modules/devops/runbooks/launch-cutover.md](../../modules/devops/runbooks/launch-cutover.md), [../modules/devops/runbooks/deployment-upgrade.md](../../modules/devops/runbooks/deployment-upgrade.md), [../modules/devops/runbooks/nuget-preview-bootstrap.md](../../modules/devops/runbooks/nuget-preview-bootstrap.md).
- [../modules/registry/operations/token-service.md](../../modules/registry/operations/token-service.md) – registry token runbook.
- [../modules/concelier/operations/mirror.md](../../modules/concelier/operations/mirror.md) – mirror operations.
- [../modules/concelier/operations/connectors/](../../modules/concelier/operations/connectors/) – connector-specific procedures (ACSC, CCCS, CERT-Bund, etc.).
- [../modules/authority/operations/](../../modules/authority/operations/) – key rotation, monitoring, backup/restore.
- [../modules/scanner/operations/](../../modules/scanner/operations/) – analyzer management, entrypoint guides, RustFS migration.
- [../modules/scheduler/operations/](../../modules/scheduler/operations/) – worker dashboards, Prometheus rules.
- [../modules/telemetry/operations/](../../modules/telemetry/operations/) – collector/storage deployment.

25
docs/technical/process/README.md Normal file
View File

@@ -0,0 +1,25 @@
# Process, Coordination & Change Logs
Use these artefacts to understand team ownership, active workstreams, and historical updates.
## Ownership & Roles
- [../AGENTS.md](../../AGENTS.md) – global agent/role definitions.
- Module ownership: each directory under [../modules/](../../modules/) includes `AGENTS.md`, `TASKS.md`, and `README.md` describing responsibilities.
## Work Tracking
- [../TASKS.md](../../TASKS.md) – Docs Guild task board.
- Sprint plans and historical boards: [../implplan/SPRINTS.md](../../implplan/SPRINTS.md), [../implplan/SPRINTS_PRIOR_20251028.md](../../implplan/SPRINTS_PRIOR_20251028.md), [../implplan/SPRINTS_PRIOR_20251027.md](../../implplan/SPRINTS_PRIOR_20251027.md), [../implplan/SPRINTS_PRIOR_20251025.md](../../implplan/SPRINTS_PRIOR_20251025.md), [../implplan/SPRINTS_PRIOR_20251021.md](../../implplan/SPRINTS_PRIOR_20251021.md), [../implplan/SPRINTS_PRIOR_20251019.md](../../implplan/SPRINTS_PRIOR_20251019.md).
- Execution plan: [../implplan/EXECPLAN.md](../../implplan/EXECPLAN.md).
- Backlog hygiene and consolidation notes: [../backlog/](../../backlog/).
- Task packs and reusable templates: [../task-packs/](../../task-packs/).
## 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/).
- Examples and golden data: [../examples/](../../examples/), [../events/samples/](../../events/samples/).
## Supporting References
- Risk & governance: [../risk/risk-profiles.md](../../risk/risk-profiles.md), [../security/policy-governance.md](../../security/policy-governance.md).
- Observability/process integration: [../events/orchestrator-scanner-events.md](../../events/orchestrator-scanner-events.md), [../events/README.md](../../events/README.md).

35
docs/technical/security/README.md Normal file
View File

@@ -0,0 +1,35 @@
# Security, Risk & Governance
Authoritative sources for threat models, governance, compliance, and security operations.
## Policies & Governance
- [../13_SECURITY_POLICY.md](../../13_SECURITY_POLICY.md) – responsible disclosure, support windows.
- [../11_GOVERNANCE.md](../../11_GOVERNANCE.md) – project governance charter.
- [../12_CODE_OF_CONDUCT.md](../../12_CODE_OF_CONDUCT.md) – community expectations.
- [../17_SECURITY_HARDENING_GUIDE.md](../../17_SECURITY_HARDENING_GUIDE.md) – deployment hardening steps.
- [../security/policy-governance.md](../../security/policy-governance.md) – policy governance specifics.
- [../29_LEGAL_FAQ_QUOTA.md](../../29_LEGAL_FAQ_QUOTA.md) – legal interpretation of quota.
- [../33_333_QUOTA_OVERVIEW.md](../../33_333_QUOTA_OVERVIEW.md) – quota policy reference.
- [../risk/risk-profiles.md](../../risk/risk-profiles.md) – organisational risk personas.
## Threat Models & Security Architecture
- [../security/authority-threat-model.md](../../security/authority-threat-model.md) – Authority service threat analysis.
- [../security/authority-scopes.md](../../security/authority-scopes.md) – scope model.
- [../security/console-security.md](../../security/console-security.md) – Console posture guidance.
- [../security/pack-signing-and-rbac.md](../../security/pack-signing-and-rbac.md) – pack signing, RBAC guardrails.
- [../security/policy-governance.md](../../security/policy-governance.md) – policy governance controls.
- [../security/rate-limits.md](../../security/rate-limits.md) – rate limiting behaviour.
- [../security/password-hashing.md](../../security/password-hashing.md) – credential storage.
## Audit, Revocation & Compliance
- [../security/audit-events.md](../../security/audit-events.md) – audit event taxonomy.
- [../security/revocation-bundle.md](../../security/revocation-bundle.md) & [../security/revocation-bundle-example.json](../../security/revocation-bundle-example.json) – revocation process.
- [../license-jwt-quota.md](../../license-jwt-quota.md) – licence/quota enforcement controls.
- [../30_QUOTA_ENFORCEMENT_FLOW1.md](../../30_QUOTA_ENFORCEMENT_FLOW1.md) – quota enforcement sequence.
- [../10_OFFLINE_KIT.md](../../10_OFFLINE_KIT.md) & [../24_OFFLINE_KIT.md](../../24_OFFLINE_KIT.md) – tamper-evident offline artefacts.
- [../security/](../../security/) – browse for additional deep dives (audit, scopes, rate limits).
## 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.

22
docs/technical/strategy/README.md Normal file
View File

@@ -0,0 +1,22 @@
# Strategy & Core Specifications
Foundational references that describe Stella Ops’ goals, scope, and differentiators.
- [../03_VISION.md](../../03_VISION.md) – north-star, KPIs, quarterly themes.
- [../04_FEATURE_MATRIX.md](../../04_FEATURE_MATRIX.md) – capability matrix by tier (free, community, commercial).
- [../05_SYSTEM_REQUIREMENTS_SPEC.md](../../05_SYSTEM_REQUIREMENTS_SPEC.md) – functional and non-functional requirements for the `v0.1.0-alpha` release (quota, scanning, policy, SLAs).
- [../40_ARCHITECTURE_OVERVIEW.md](../../40_ARCHITECTURE_OVERVIEW.md) – guiding principles and platform-level design rationale.
- [../moat.md](../../moat.md) – differentiating workstreams (deterministic replay, lattice policy, sovereign crypto readiness, attestation graph).
- [../05_ROADMAP.md](../../05_ROADMAP.md) – legacy pointer to the public web roadmap (kept for historical links).
- [../33_333_QUOTA_OVERVIEW.md](../../33_333_QUOTA_OVERVIEW.md) – free tier policy framing.
- [../29_LEGAL_FAQ_QUOTA.md](../../29_LEGAL_FAQ_QUOTA.md) – legal interpretation of quota enforcement under AGPL-3.0.
- [../13_SECURITY_POLICY.md](../../13_SECURITY_POLICY.md) – responsible disclosure support window and release line commitments.
- [../14_GLOSSARY_OF_TERMS.md](../../14_GLOSSARY_OF_TERMS.md) – canonical vocabulary used across documentation.
- [../15_UI_GUIDE.md](../../15_UI_GUIDE.md) – UX overview for stakeholders evaluating the console.
- [../23_FAQ_MATRIX.md](../../23_FAQ_MATRIX.md) – stakeholder FAQ.
## Related Concepts
- [../33_333_QUOTA_OVERVIEW.md](../../33_333_QUOTA_OVERVIEW.md) and [../30_QUOTA_ENFORCEMENT_FLOW1.md](../../30_QUOTA_ENFORCEMENT_FLOW1.md) align business policy with enforcement diagrams.
- [../license-jwt-quota.md](../../license-jwt-quota.md) – offline licensing narrative for quota tokens.
- [../moat.md](../../moat.md) – includes procurement-grade trust statement blueprint.
- [../10_OFFLINE_KIT.md](../../10_OFFLINE_KIT.md) & [../24_OFFLINE_KIT.md](../../24_OFFLINE_KIT.md) – strategic offline story (also referenced in Operations).

9
docs/ui/admin.md
View File

@@ -138,10 +138,10 @@ Audit entries appear for every user/token change. CLI parity: `stella auth token
## 11. Screenshot coordination
- Placeholders:
- `![Admin tenants placeholder](../assets/ui/admin/tenants-placeholder.png)`
- `![Admin roles placeholder](../assets/ui/admin/roles-placeholder.png)`
- `![Admin tokens placeholder](../assets/ui/admin/tokens-placeholder.png)`
- Placeholders (captures pending upload):
- `docs/assets/ui/admin/tenants-placeholder.png`
- `docs/assets/ui/admin/roles-placeholder.png`
- `docs/assets/ui/admin/tokens-placeholder.png`
- Capture real screenshots with Authority Guild once Sprint 23 UI is final (tracked in `#console-screenshots`, 2025-10-26 entry). Provide both light and dark theme variants.
---
@@ -171,4 +171,3 @@ Audit entries appear for every user/token change. CLI parity: `stella auth token
---
*Last updated: 2025-10-26 (Sprint 23).*

7
docs/ui/advisories-and-vex.md
View File

@@ -163,9 +163,9 @@ All raw views are read-only to maintain Aggregation-Only guarantees.
## 13. Screenshot coordination
- Placeholders:
- `![Advisory grid placeholder](../assets/ui/advisories/grid-placeholder.png)`
- `![VEX consensus placeholder](../assets/ui/advisories/vex-placeholder.png)`
- Placeholders (captures pending upload):
- `docs/assets/ui/advisories/grid-placeholder.png`
- `docs/assets/ui/advisories/vex-placeholder.png`
- Coordinate with Console Guild to capture updated screenshots (dark and light themes) once Sprint 23 build candidate is tagged. Tracking in Slack channel `#console-screenshots` (entry 2025-10-26).
---
@@ -196,4 +196,3 @@ All raw views are read-only to maintain Aggregation-Only guarantees.
---
*Last updated: 2025-10-26 (Sprint 23).*

7
docs/ui/findings.md
View File

@@ -143,9 +143,9 @@ Explain drawer includes copy-to-clipboard buttons for rule chain and evidence JS
## 10. Screenshot coordination
- Placeholders:
- `![Findings grid placeholder](../assets/ui/findings/grid-placeholder.png)`
- `![Explain drawer placeholder](../assets/ui/findings/explain-placeholder.png)`
- Placeholders (captures pending upload):
- `docs/assets/ui/findings/grid-placeholder.png`
- `docs/assets/ui/findings/explain-placeholder.png`
- Coordinate with Console Guild (Slack `#console-screenshots`, entry 2025-10-26) to capture updated light and dark theme shots before release.
---
@@ -176,4 +176,3 @@ Explain drawer includes copy-to-clipboard buttons for rule chain and evidence JS
---
*Last updated: 2025-10-26 (Sprint 23).*

6
docs/ui/policies.md
View File

@@ -158,9 +158,9 @@ UI disables controls not allowed by current scope and surfaces tooltip with requ
## 12. Screenshot coordination
- Placeholders:
- `![Policy list placeholder](../assets/ui/policies/list-placeholder.png)`
- `![Policy approval placeholder](../assets/ui/policies/approval-placeholder.png)`
- `![Simulation diff placeholder](../assets/ui/policies/simulation-placeholder.png)`
- `docs/assets/ui/policies/list-placeholder.png` (capture pending)
- `docs/assets/ui/policies/approval-placeholder.png` (capture pending)
- `docs/assets/ui/policies/simulation-placeholder.png` (capture pending)
- Coordinate with Console Guild via `#console-screenshots` (entry 2025-10-26) to replace placeholders once UI captures are ready (light and dark themes).
---

2
docs/ui/policy-editor.md
View File

@@ -46,7 +46,7 @@ The Policy Editor is the primary Console workspace for composing, simulating, an
- *Explain Explorer* (optional drawer for findings)
- **Right rail:** context cards for VEX providers, policy metadata, quick links to CLI/API docs.
> Placeholder screenshot: `![Policy editor workspace](../assets/policy-editor/workspace.png)` (add after UI team captures latest build).
> Placeholder screenshot: `docs/assets/policy-editor/workspace.png` (pending upload after UI team captures latest build).
---

4
docs/ui/runs.md
View File

@@ -134,8 +134,8 @@ Sections:
## 11. Screenshot coordination
- Placeholders:
- `![Runs dashboard placeholder](../assets/ui/runs/dashboard-placeholder.png)`
- `![Run detail placeholder](../assets/ui/runs/detail-placeholder.png)`
- `docs/assets/ui/runs/dashboard-placeholder.png` (capture pending)
- `docs/assets/ui/runs/detail-placeholder.png` (capture pending)
- Coordinate with Scheduler Guild for updated screenshots after Sprint 23 UI stabilises (tracked in `#console-screenshots`, entry 2025-10-26).
---

4
docs/ui/sbom-explorer.md
View File

@@ -161,8 +161,8 @@ Saved views store combinations of these filters and expose command palette short
## 10. Screenshot coordination
- Placeholder images:
- `![SBOM catalog view placeholder](../assets/ui/sbom/catalog-placeholder.png)`
- `![Overlay graph placeholder](../assets/ui/sbom/overlay-placeholder.png)`
- `docs/assets/ui/sbom/catalog-placeholder.png` (capture pending)
- `docs/assets/ui/sbom/overlay-placeholder.png` (capture pending)
- Coordinate with Console Guild to capture updated screenshots (dark and light theme) once Sprint 23 UI stabilises. Track follow-up in Console Guild thread `#console-screenshots` dated 2025-10-26.
---

4
docs/updates/2025-10-27-task-packs-docs.md
View File

@@ -6,10 +6,10 @@
- `/docs/task-packs/registry.md`
- `/docs/task-packs/runbook.md`
- `/docs/security/pack-signing-and-rbac.md`
- `/docs/operations/cli-release-and-packaging.md`
- `/docs/modules/cli/operations/release-and-packaging.md`
- Each doc includes imposed-rule reminder, compliance checklist, and cross-links to Task Runner, Packs Registry, CLI release tasks.
- Created asset staging instructions at `docs/assets/ui/tours/README.md` (shared with CLI enablement).
- Circulated spec + authoring guide links to Task Runner, Packs Registry, Authority, and DevOps guild channels for technical review (2025-10-27). Target follow-up review once CLI parity tasks (`CLI-PACKS-42-001`, `CLI-PACKS-43-001`) land; tentative sync held for 2025-11-03 (Docs Guild to confirm).
- Sprint tracker `DOCS-PACKS-43-001` marked DOING→DONE; follow-up reviews scheduled with Task Runner and Security guilds.
Artifacts: [Spec](../task-packs/spec.md), [Authoring guide](../task-packs/authoring-guide.md), [Registry](../task-packs/registry.md), [Runbook](../task-packs/runbook.md), [Signing/RBAC](../security/pack-signing-and-rbac.md), [CLI release runbook](../operations/cli-release-and-packaging.md).
Artifacts: [Spec](../task-packs/spec.md), [Authoring guide](../task-packs/authoring-guide.md), [Registry](../task-packs/registry.md), [Runbook](../task-packs/runbook.md), [Signing/RBAC](../security/pack-signing-and-rbac.md), [CLI release runbook](../modules/cli/operations/release-and-packaging.md).

17
docs/updates/2025-10-30-devops-governance.md Normal file
View File

@@ -0,0 +1,17 @@
# 30 Oct 2025 — Governance rules anchor consolidated
**What changed**
- Published `docs/devops/contracts-and-rules.md` capturing the Sprint 33 governance rules:
1. API Gateway remains a proxy; Policy Engine composes overlays/simulations.
2. AOC ingestion persists upstream truth only (no merge/deduplicate logic).
3. Graph platform standardised on Graph Indexer + Graph API (Cartographer retired).
- Updated backlog hygiene note (`docs/backlog/2025-10-cleanup.md`) and archived the Cartographer handshake plan to point at the new graph platform.
- Logged the rules in `ops/devops/TASKS.md` and `docs/implplan/SPRINTS.md`, removing duplicate references to Cartographer as an active service.
**Reviewers / acknowledgements**
- Platform Leads (DevOps + Graph) confirmed the retirement of Cartographer in favour of Graph Indexer + Graph API.
- Policy Engine Guild acknowledged the proxy-only Gateway posture and downstream overlay ownership.
See `DEVOPS-RULES-33-001` for the owning task.

1
etc/authority.yaml
View File

@@ -23,6 +23,7 @@ signing:
keyPath: "../certificates/authority-signing-dev.pem"
algorithm: "ES256"
keySource: "file"
jwksCacheLifetime: "00:05:00"
bootstrap:
enabled: false

1
etc/authority.yaml.sample
View File

@@ -30,6 +30,7 @@ signing:
keyPath: "../certificates/authority-signing-2025-dev.pem"
algorithm: "ES256"
keySource: "file"
jwksCacheLifetime: "00:05:00"
# provider: "default"
additionalKeys:
- keyId: "authority-signing-dev"

5
ops/authority/TASKS.completed.md Normal file
View File

@@ -0,0 +1,5 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
| OPS3.KEY-ROTATION | DONE (2025-10-12) | DevOps Crew, Authority Core | CORE10.JWKS | Implement key rotation tooling + pipeline hook once rotating JWKS lands. Document SOP and secret handling. | ✅ CLI/script rotates keys + updates JWKS; ✅ Pipeline job documented; ✅ docs/ops runbook updated. |

1
ops/authority/TASKS.md
View File

@@ -3,4 +3,3 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| OPS3.KEY-ROTATION | DONE (2025-10-12) | DevOps Crew, Authority Core | CORE10.JWKS | Implement key rotation tooling + pipeline hook once rotating JWKS lands. Document SOP and secret handling. | ✅ CLI/script rotates keys + updates JWKS; ✅ Pipeline job documented; ✅ docs/ops runbook updated. |

5
ops/deployment/TASKS.completed.md Normal file
View File

@@ -0,0 +1,5 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-OPS-14-003 | DONE (2025-10-26) | Deployment Guild | DEVOPS-REL-14-001 | Document and script upgrade/rollback flows, channel management, and compatibility matrices per architecture. | Helm/Compose guides updated with digest pinning, automated checks committed, rollback drill recorded. |

1
ops/deployment/TASKS.md
View File

@@ -2,7 +2,6 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-OPS-14-003 | DONE (2025-10-26) | Deployment Guild | DEVOPS-REL-14-001 | Document and script upgrade/rollback flows, channel management, and compatibility matrices per architecture. | Helm/Compose guides updated with digest pinning, automated checks committed, rollback drill recorded. |
| DOWNLOADS-CONSOLE-23-001 | TODO | Deployment Guild, DevOps Guild | DEVOPS-CONSOLE-23-002 | Maintain signed downloads manifest pipeline (images, Helm, offline bundles), publish JSON under `deploy/downloads/manifest.json`, and document sync cadence for Console + docs parity. | Pipeline generates signed manifest with checksums, automated PR updates manifest, docs updated with sync workflow, parity check in CI passes. |
| DEPLOY-NOTIFY-38-001 | BLOCKED (2025-10-29) | Deployment Guild, DevOps Guild | NOTIFY-SVC-38-001..004 | Package notifier API/worker Helm overlays (email/chat/webhook), secrets templates, rollout guide. | Overlays committed; smoke deploy executed; rollback steps recorded; secrets templates provided. |
| DEPLOY-POLICY-27-001 | TODO | Deployment Guild, Policy Registry Guild | REGISTRY-API-27-001, DEVOPS-POLICY-27-003 | Produce Helm/Compose overlays for Policy Registry + simulation workers, including Mongo migrations, object storage buckets, signing key secrets, and tenancy defaults. | Overlays committed with deterministic digests; install docs updated; smoke deploy validated in staging. |

27
ops/devops/TASKS.completed.md Normal file
View File

@@ -0,0 +1,27 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-HELM-09-001 | DONE | DevOps Guild | SCANNER-WEB-09-101 | Create Helm/Compose environment profiles (dev, staging, airgap) with deterministic digests. | Profiles committed under `deploy/`; docs updated; CI smoke deploy passes. |
| DEVOPS-SCANNER-09-204 | DONE (2025-10-21) | DevOps Guild, Scanner WebService Guild | SCANNER-EVENTS-15-201 | Surface `SCANNER__EVENTS__*` environment variables across docker-compose (dev/stage/airgap) and Helm values, defaulting to share the Redis queue DSN. | Compose/Helm configs ship enabled Redis event publishing with documented overrides; lint jobs updated; docs cross-link to new knobs. |
| DEVOPS-SCANNER-09-205 | DONE (2025-10-21) | DevOps Guild, Notify Guild | DEVOPS-SCANNER-09-204 | Add Notify smoke stage that tails the Redis stream and asserts `scanner.report.ready`/`scanner.scan.completed` reach Notify WebService in staging. | CI job reads Redis stream during scanner smoke deploy, confirms Notify ingestion via API, alerts on failure. |
| DEVOPS-PERF-10-001 | DONE | DevOps Guild | BENCH-SCANNER-10-001 | Add perf smoke job (SBOM compose <5 s target) to CI. | CI job runs sample build verifying <5 s; alerts configured. |
| DEVOPS-PERF-10-002 | DONE (2025-10-23) | DevOps Guild | BENCH-SCANNER-10-002 | Publish analyzer bench metrics to Grafana/perf workbook and alarm on ≥20 % regressions. | CI exports JSON for dashboards; Grafana panel wired; Ops on-call doc updated with alert hook. |
| DEVOPS-REL-14-001 | DONE (2025-10-26) | DevOps Guild | SIGNER-API-11-101, ATTESTOR-API-11-201 | Deterministic build/release pipeline with SBOM/provenance, signing, manifest generation. | CI pipeline produces signed images + SBOM/attestations, manifests published with verified hashes, docs updated. |
| DEVOPS-REL-14-004 | DONE (2025-10-26) | DevOps Guild, Scanner Guild | DEVOPS-REL-14-001, SCANNER-ANALYZERS-LANG-10-309P | Extend release/offline smoke jobs to exercise the Python analyzer plug-in (warm/cold scans, determinism, signature checks). | Release/Offline pipelines run Python analyzer smoke suite; alerts hooked; docs updated with new coverage matrix. |
| DEVOPS-REL-17-002 | DONE (2025-10-26) | DevOps Guild | DEVOPS-REL-14-001, SCANNER-EMIT-17-701 | Persist stripped-debug artifacts organised by GNU build-id and bundle them into release/offline kits with checksum manifests. | CI job writes `.debug` files under `artifacts/debug/.build-id/`, manifest + checksums published, offline kit includes cache, smoke job proves symbol lookup via build-id. |
| DEVOPS-MIRROR-08-001 | DONE (2025-10-19) | DevOps Guild | DEVOPS-REL-14-001 | Stand up managed mirror profiles for `*.stella-ops.org` (Concelier/Excititor), including Helm/Compose overlays, multi-tenant secrets, CDN caching, and sync documentation. | Infra overlays committed, CI smoke deploy hits mirror endpoints, runbooks published for downstream sync and quota management. |
| DEVOPS-POLICY-20-001 | DONE (2025-10-26) | DevOps Guild, Policy Guild | POLICY-ENGINE-20-001 | Integrate DSL linting in CI (parser/compile) to block invalid policies; add pipeline step compiling sample policies. | CI fails on syntax errors; lint logs surfaced; docs updated with pipeline instructions. |
| DEVOPS-POLICY-20-003 | DONE (2025-10-26) | DevOps Guild, QA Guild | DEVOPS-POLICY-20-001, POLICY-ENGINE-20-005 | Determinism CI: run Policy Engine twice with identical inputs and diff outputs to guard non-determinism. | CI job compares outputs, fails on differences, logs stored; documentation updated. |
| DEVOPS-POLICY-20-004 | DONE (2025-10-27) | DevOps Guild, Scheduler Guild, CLI Guild | SCHED-MODELS-20-001, CLI-POLICY-20-002 | Automate policy schema exports: generate JSON Schema from `PolicyRun*` DTOs during CI, publish artefacts, and emit change alerts for CLI consumers (Slack + changelog). | CI stage outputs versioned schema files, uploads artefacts, notifies #policy-engine channel on change; docs/CLI references updated. |
| DEVOPS-OBS-50-001 | DONE (2025-10-26) | DevOps Guild, Observability Guild | TELEMETRY-OBS-50-001 | Deliver default OpenTelemetry collector deployment (Compose/Helm manifests), OTLP ingestion endpoints, and secure pipeline (authN, mTLS, tenant partitioning). Provide smoke test verifying traces/logs/metrics ingestion. | Collector manifests committed; smoke test green; docs updated; imposed rule banner reminder noted. |
| DEVOPS-OBS-50-003 | DONE (2025-10-26) | DevOps Guild, Offline Kit Guild | DEVOPS-OBS-50-001 | Package telemetry stack configs for air-gapped installs (Offline Kit bundle, documented overrides, sample values) and automate checksum/signature generation. | Offline bundle includes collector+storage configs; checksums published; docs cross-linked; imposed rule annotation recorded. |
| DEVOPS-LAUNCH-18-100 | DONE (2025-10-26) | DevOps Guild | - | Finalise production environment footprint (clusters, secrets, network overlays) for full-platform go-live. | IaC/compose overlays committed, secrets placeholders documented, dry-run deploy succeeds in staging. |
| DEVOPS-CONSOLE-23-002 | TODO | DevOps Guild, Console Guild | DEVOPS-CONSOLE-23-001, CONSOLE-REL-23-301 | Produce `stella-console` container build + Helm chart overlays with deterministic digests, SBOM/provenance artefacts, and offline bundle packaging scripts. | Container published to registry mirror, Helm values committed, SBOM/attestations generated, offline kit job passes smoke test, docs updated. |
| DEVOPS-LAUNCH-18-100 | DONE (2025-10-26) | DevOps Guild | - | Finalise production environment footprint (clusters, secrets, network overlays) for full-platform go-live. | IaC/compose overlays committed, secrets placeholders documented, dry-run deploy succeeds in staging. |
| DEVOPS-LAUNCH-18-900 | DONE (2025-10-26) | DevOps Guild, Module Leads | Wave 0 completion | Collect “full implementation” sign-off from module owners and consolidate launch readiness checklist. | Sign-off record stored under `docs/modules/devops/runbooks/launch-readiness.md`; outstanding gaps triaged; checklist approved. |
| DEVOPS-LAUNCH-18-001 | DONE (2025-10-26) | DevOps Guild | DEVOPS-LAUNCH-18-100, DEVOPS-LAUNCH-18-900 | Production launch cutover rehearsal and runbook publication. | `docs/modules/devops/runbooks/launch-cutover.md` drafted, rehearsal executed with rollback drill, approvals captured. |
| DEVOPS-NUGET-13-001 | DONE (2025-10-25) | DevOps Guild, Platform Leads | DEVOPS-REL-14-001 | Add .NET 10 preview feeds / local mirrors so `Microsoft.Extensions.*` 10.0 preview packages restore offline; refresh restore docs. | NuGet.config maps preview feeds (or local mirrored packages), `dotnet restore` succeeds for Excititor/Concelier solutions without ad-hoc feed edits, docs updated for offline bootstrap. |
| DEVOPS-NUGET-13-002 | DONE (2025-10-26) | DevOps Guild | DEVOPS-NUGET-13-001 | Ensure all solutions/projects prefer `local-nuget` before public sources and document restore order validation. | `NuGet.config` and solution-level configs resolve from `local-nuget` first; automated check verifies priority; docs updated for restore ordering. |
| DEVOPS-NUGET-13-003 | DONE (2025-10-26) | DevOps Guild, Platform Leads | DEVOPS-NUGET-13-002 | Sweep `Microsoft.*` NuGet dependencies pinned to 8.* and upgrade to latest .NET 10 equivalents (or .NET 9 when 10 unavailable), updating restore guidance. | Dependency audit shows no 8.* `Microsoft.*` packages remaining; CI builds green; changelog/doc sections capture upgrade rationale. |

24
ops/devops/TASKS.md
View File

@@ -4,15 +4,11 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-RULES-33-001 | DOING (2025-10-26) | DevOps Guild, Platform Leads | — | Contracts & Rules anchor:<br>• Gateway proxies only; Policy Engine composes overlays/simulations.<br>• AOC ingestion cannot merge; only lossless canonicalization.<br>• One graph platform: Graph Indexer + Graph API. Cartographer retired. | Rules posted in SPRINTS/TASKS; duplicates cleaned per guidance; reviewers acknowledge in changelog. |
| DEVOPS-RULES-33-001 | REVIEW (2025-10-30) | DevOps Guild, Platform Leads | — | Contracts & Rules anchor:<br>• Gateway proxies only; Policy Engine composes overlays/simulations.<br>• AOC ingestion cannot merge; only lossless canonicalization.<br>• One graph platform: Graph Indexer + Graph API. Cartographer retired. | Rules posted in SPRINTS/TASKS; duplicates cleaned per guidance; reviewers acknowledge in changelog. |
> 2025-10-30: Published governance anchor (`docs/devops/contracts-and-rules.md`), archived Cartographer plan, and logged reviewer acknowledgement in `docs/updates/2025-10-30-devops-governance.md`.
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-HELM-09-001 | DONE | DevOps Guild | SCANNER-WEB-09-101 | Create Helm/Compose environment profiles (dev, staging, airgap) with deterministic digests. | Profiles committed under `deploy/`; docs updated; CI smoke deploy passes. |
| DEVOPS-SCANNER-09-204 | DONE (2025-10-21) | DevOps Guild, Scanner WebService Guild | SCANNER-EVENTS-15-201 | Surface `SCANNER__EVENTS__*` environment variables across docker-compose (dev/stage/airgap) and Helm values, defaulting to share the Redis queue DSN. | Compose/Helm configs ship enabled Redis event publishing with documented overrides; lint jobs updated; docs cross-link to new knobs. |
| DEVOPS-SCANNER-09-205 | DONE (2025-10-21) | DevOps Guild, Notify Guild | DEVOPS-SCANNER-09-204 | Add Notify smoke stage that tails the Redis stream and asserts `scanner.report.ready`/`scanner.scan.completed` reach Notify WebService in staging. | CI job reads Redis stream during scanner smoke deploy, confirms Notify ingestion via API, alerts on failure. |
| DEVOPS-PERF-10-001 | DONE | DevOps Guild | BENCH-SCANNER-10-001 | Add perf smoke job (SBOM compose <5 s target) to CI. | CI job runs sample build verifying <5 s; alerts configured. |
| DEVOPS-PERF-10-002 | DONE (2025-10-23) | DevOps Guild | BENCH-SCANNER-10-002 | Publish analyzer bench metrics to Grafana/perf workbook and alarm on ≥20 % regressions. | CI exports JSON for dashboards; Grafana panel wired; Ops on-call doc updated with alert hook. |
| DEVOPS-AOC-19-001 | BLOCKED (2025-10-26) | DevOps Guild, Platform Guild | WEB-AOC-19-003 | Integrate the AOC Roslyn analyzer and guard tests into CI, failing builds when ingestion projects attempt banned writes. | Analyzer runs in PR/CI pipelines, results surfaced in build summary, docs updated under `docs/modules/devops/runbooks/ci-aoc.md`. |
> Docs hand-off (2025-10-26): see `docs/ingestion/aggregation-only-contract.md` §5, `docs/modules/platform/architecture-overview.md`, and `docs/modules/cli/guides/cli-reference.md` for guard + verifier expectations.
| DEVOPS-AOC-19-002 | BLOCKED (2025-10-26) | DevOps Guild | CLI-AOC-19-002, CONCELIER-WEB-AOC-19-004, EXCITITOR-WEB-AOC-19-004 | Add pipeline stage executing `stella aoc verify --since` against seeded Mongo snapshots for Concelier + Excititor, publishing violation report artefacts. | Stage runs on main/nightly, fails on violations, artifacts retained, runbook documented. |
@@ -20,10 +16,9 @@
| DEVOPS-AOC-19-003 | BLOCKED (2025-10-26) | DevOps Guild, QA Guild | CONCELIER-WEB-AOC-19-003, EXCITITOR-WEB-AOC-19-003 | Enforce unit test coverage thresholds for AOC guard suites and ensure coverage exported to dashboards. | Coverage report includes guard projects, threshold gate passes/fails as expected, dashboards refreshed with new metrics. |
> Blocked: guard coverage suites and exporter hooks pending in Concelier/Excititor (CONCELIER-WEB-AOC-19-003, EXCITITOR-WEB-AOC-19-003).
| DEVOPS-AOC-19-101 | TODO (2025-10-28) | DevOps Guild, Concelier Storage Guild | CONCELIER-STORE-AOC-19-002 | Draft supersedes backfill rollout (freeze window, dry-run steps, rollback) once advisory_raw idempotency index passes staging verification. | Runbook committed in `docs/deploy/containers.md` + Offline Kit notes, staging rehearsal scheduled with dependencies captured in SPRINTS. |
| DEVOPS-OBS-50-001 | DONE (2025-10-26) | DevOps Guild, Observability Guild | TELEMETRY-OBS-50-001 | Deliver default OpenTelemetry collector deployment (Compose/Helm manifests), OTLP ingestion endpoints, and secure pipeline (authN, mTLS, tenant partitioning). Provide smoke test verifying traces/logs/metrics ingestion. | Collector manifests committed; smoke test green; docs updated; imposed rule banner reminder noted. |
| DEVOPS-OBS-50-002 | DOING (2025-10-26) | DevOps Guild, Security Guild | DEVOPS-OBS-50-001, TELEMETRY-OBS-51-002 | Stand up multi-tenant storage backends (Prometheus, Tempo/Jaeger, Loki) with retention policies, tenant isolation, and redaction guard rails. Integrate with Authority scopes for read paths. | Storage stack deployed with auth; retention configured; integration tests verify tenant isolation; runbook drafted. |
> Coordination started with Observability Guild (2025-10-26) to schedule staging rollout and provision service accounts. Staging bootstrap commands and secret names documented in `docs/modules/telemetry/operations/storage.md`.
| DEVOPS-OBS-50-003 | DONE (2025-10-26) | DevOps Guild, Offline Kit Guild | DEVOPS-OBS-50-001 | Package telemetry stack configs for air-gapped installs (Offline Kit bundle, documented overrides, sample values) and automate checksum/signature generation. | Offline bundle includes collector+storage configs; checksums published; docs cross-linked; imposed rule annotation recorded. |
> 2025-10-30: Added static validator `ops/devops/telemetry/validate_storage_stack.py` and updated storage runbook to require it alongside TLS/tenant setup.
| DEVOPS-OBS-51-001 | TODO | DevOps Guild, Observability Guild | WEB-OBS-51-001, DEVOPS-OBS-50-001 | Implement SLO evaluator service (burn rate calculators, webhook emitters), Grafana dashboards, and alert routing to Notifier. Provide Terraform/Helm automation. | Dashboards live; evaluator emits webhooks; alert runbook referenced; staging alert fired in test. |
| DEVOPS-OBS-52-001 | TODO | DevOps Guild, Timeline Indexer Guild | TIMELINE-OBS-52-002 | Configure streaming pipeline (NATS/Redis/Kafka) with retention, partitioning, and backpressure tuning for timeline events; add CI validation of schema + rate caps. | Pipeline deployed; load test meets SLA; schema validation job passes; documentation updated. |
| DEVOPS-OBS-53-001 | TODO | DevOps Guild, Evidence Locker Guild | EVID-OBS-53-001 | Provision object storage with WORM/retention options (S3 Object Lock / MinIO immutability), legal hold automation, and backup/restore scripts for evidence locker. | Storage configured with WORM; legal hold script documented; backup test performed; runbook updated. |
@@ -40,29 +35,16 @@
| DEVOPS-AIRGAP-57-002 | TODO | DevOps Guild, Authority Guild | AUTH-OBS-50-001 | Configure sealed-mode CI tests that run services with sealed flag and ensure no egress occurs (iptables + mock DNS). | CI suite fails on attempted egress; reports remediation; documentation updated. |
| DEVOPS-AIRGAP-58-001 | TODO | DevOps Guild, Notifications Guild | NOTIFY-AIRGAP-56-002 | Provide local SMTP/syslog container templates and health checks for sealed environments; integrate into Bootstrap Pack. | Templates deployed successfully; health checks in CI; docs updated. |
| DEVOPS-AIRGAP-58-002 | TODO | DevOps Guild, Observability Guild | DEVOPS-AIRGAP-56-001, DEVOPS-OBS-51-001 | Ship sealed-mode observability stack (Prometheus/Grafana/Tempo/Loki) pre-configured with offline dashboards and no remote exporters. | Stack boots offline; dashboards available; verification script confirms zero egress. |
| DEVOPS-REL-14-001 | DONE (2025-10-26) | DevOps Guild | SIGNER-API-11-101, ATTESTOR-API-11-201 | Deterministic build/release pipeline with SBOM/provenance, signing, manifest generation. | CI pipeline produces signed images + SBOM/attestations, manifests published with verified hashes, docs updated. |
| DEVOPS-REL-14-004 | DONE (2025-10-26) | DevOps Guild, Scanner Guild | DEVOPS-REL-14-001, SCANNER-ANALYZERS-LANG-10-309P | Extend release/offline smoke jobs to exercise the Python analyzer plug-in (warm/cold scans, determinism, signature checks). | Release/Offline pipelines run Python analyzer smoke suite; alerts hooked; docs updated with new coverage matrix. |
| DEVOPS-REL-17-002 | DONE (2025-10-26) | DevOps Guild | DEVOPS-REL-14-001, SCANNER-EMIT-17-701 | Persist stripped-debug artifacts organised by GNU build-id and bundle them into release/offline kits with checksum manifests. | CI job writes `.debug` files under `artifacts/debug/.build-id/`, manifest + checksums published, offline kit includes cache, smoke job proves symbol lookup via build-id. |
| DEVOPS-REL-17-004 | BLOCKED (2025-10-26) | DevOps Guild | DEVOPS-REL-17-002 | Ensure release workflow publishes `out/release/debug` (build-id tree + manifest) and fails when symbols are missing. | Release job emits debug artefacts, `mirror_debug_store.py` summary committed, warning cleared from build logs, docs updated. |
| DEVOPS-MIRROR-08-001 | DONE (2025-10-19) | DevOps Guild | DEVOPS-REL-14-001 | Stand up managed mirror profiles for `*.stella-ops.org` (Concelier/Excititor), including Helm/Compose overlays, multi-tenant secrets, CDN caching, and sync documentation. | Infra overlays committed, CI smoke deploy hits mirror endpoints, runbooks published for downstream sync and quota management. |
> Note (2025-10-26, BLOCKED): IdentityModel.Tokens patched for logging 9.x, but release bundle still fails because Docker cannot stream multi-arch build context (`unix:///var/run/docker.sock` unavailable, EOF during copy). Retry once docker daemon/socket is healthy; until then `out/release/debug` cannot be generated.
| DEVOPS-CONSOLE-23-001 | BLOCKED (2025-10-26) | DevOps Guild, Console Guild | CONSOLE-CORE-23-001 | Add console CI workflow (pnpm cache, lint, type-check, unit, Storybook a11y, Playwright, Lighthouse) with offline runners and artifact retention for screenshots/reports. | Workflow runs on PR & main, caches reduce install time, failing checks block merges, artifacts uploaded for triage, docs updated. |
> Blocked: Console workspace and package scripts (CONSOLE-CORE-23-001..005) are not yet present; CI cannot execute pnpm/Playwright/Lighthouse until the Next.js app lands.
| DEVOPS-CONSOLE-23-002 | TODO | DevOps Guild, Console Guild | DEVOPS-CONSOLE-23-001, CONSOLE-REL-23-301 | Produce `stella-console` container build + Helm chart overlays with deterministic digests, SBOM/provenance artefacts, and offline bundle packaging scripts. | Container published to registry mirror, Helm values committed, SBOM/attestations generated, offline kit job passes smoke test, docs updated. |
| DEVOPS-LAUNCH-18-100 | DONE (2025-10-26) | DevOps Guild | - | Finalise production environment footprint (clusters, secrets, network overlays) for full-platform go-live. | IaC/compose overlays committed, secrets placeholders documented, dry-run deploy succeeds in staging. |
| DEVOPS-LAUNCH-18-900 | DONE (2025-10-26) | DevOps Guild, Module Leads | Wave 0 completion | Collect “full implementation” sign-off from module owners and consolidate launch readiness checklist. | Sign-off record stored under `docs/modules/devops/runbooks/launch-readiness.md`; outstanding gaps triaged; checklist approved. |
| DEVOPS-LAUNCH-18-001 | DONE (2025-10-26) | DevOps Guild | DEVOPS-LAUNCH-18-100, DEVOPS-LAUNCH-18-900 | Production launch cutover rehearsal and runbook publication. | `docs/modules/devops/runbooks/launch-cutover.md` drafted, rehearsal executed with rollback drill, approvals captured. |
| DEVOPS-NUGET-13-001 | DONE (2025-10-25) | DevOps Guild, Platform Leads | DEVOPS-REL-14-001 | Add .NET 10 preview feeds / local mirrors so `Microsoft.Extensions.*` 10.0 preview packages restore offline; refresh restore docs. | NuGet.config maps preview feeds (or local mirrored packages), `dotnet restore` succeeds for Excititor/Concelier solutions without ad-hoc feed edits, docs updated for offline bootstrap. |
| DEVOPS-NUGET-13-002 | DONE (2025-10-26) | DevOps Guild | DEVOPS-NUGET-13-001 | Ensure all solutions/projects prefer `local-nuget` before public sources and document restore order validation. | `NuGet.config` and solution-level configs resolve from `local-nuget` first; automated check verifies priority; docs updated for restore ordering. |
| DEVOPS-NUGET-13-003 | DONE (2025-10-26) | DevOps Guild, Platform Leads | DEVOPS-NUGET-13-002 | Sweep `Microsoft.*` NuGet dependencies pinned to 8.* and upgrade to latest .NET 10 equivalents (or .NET 9 when 10 unavailable), updating restore guidance. | Dependency audit shows no 8.* `Microsoft.*` packages remaining; CI builds green; changelog/doc sections capture upgrade rationale. |
## Policy Engine v2
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-POLICY-20-001 | DONE (2025-10-26) | DevOps Guild, Policy Guild | POLICY-ENGINE-20-001 | Integrate DSL linting in CI (parser/compile) to block invalid policies; add pipeline step compiling sample policies. | CI fails on syntax errors; lint logs surfaced; docs updated with pipeline instructions. |
| DEVOPS-POLICY-20-003 | DONE (2025-10-26) | DevOps Guild, QA Guild | DEVOPS-POLICY-20-001, POLICY-ENGINE-20-005 | Determinism CI: run Policy Engine twice with identical inputs and diff outputs to guard non-determinism. | CI job compares outputs, fails on differences, logs stored; documentation updated. |
| DEVOPS-POLICY-20-004 | DONE (2025-10-27) | DevOps Guild, Scheduler Guild, CLI Guild | SCHED-MODELS-20-001, CLI-POLICY-20-002 | Automate policy schema exports: generate JSON Schema from `PolicyRun*` DTOs during CI, publish artefacts, and emit change alerts for CLI consumers (Slack + changelog). | CI stage outputs versioned schema files, uploads artefacts, notifies #policy-engine channel on change; docs/CLI references updated. |
> 2025-10-27: `.gitea/workflows/build-test-deploy.yml` publishes the `policy-schema-exports` artefact under `artifacts/policy-schemas/<commit>/` and posts Slack diffs via `POLICY_ENGINE_SCHEMA_WEBHOOK`; diff stored as `policy-schema-diff.patch`.
## Graph Explorer v1

83
ops/devops/telemetry/validate_storage_stack.py Normal file
View File

@@ -0,0 +1,83 @@
#!/usr/bin/env python3
"""
Static validation for the telemetry storage stack configuration.
Checks the Prometheus, Tempo, and Loki configuration snippets to ensure:
- mutual TLS is enabled end-to-end
- tenant override files are referenced
- multitenancy flags are set
- retention/limit defaults exist for __default__ tenant entries
This script is intended to back `DEVOPS-OBS-50-002` and can run in CI
before publishing bundles or rolling out staging updates.
"""
from __future__ import annotations
import sys
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[3]
PROMETHEUS_PATH = REPO_ROOT / "deploy/telemetry/storage/prometheus.yaml"
TEMPO_PATH = REPO_ROOT / "deploy/telemetry/storage/tempo.yaml"
LOKI_PATH = REPO_ROOT / "deploy/telemetry/storage/loki.yaml"
TEMPO_OVERRIDES_PATH = REPO_ROOT / "deploy/telemetry/storage/tenants/tempo-overrides.yaml"
LOKI_OVERRIDES_PATH = REPO_ROOT / "deploy/telemetry/storage/tenants/loki-overrides.yaml"
def read(path: Path) -> str:
if not path.exists():
raise FileNotFoundError(f"Required configuration file missing: {path}")
return path.read_text(encoding="utf-8")
def assert_contains(haystack: str, needle: str, path: Path) -> None:
if needle not in haystack:
raise AssertionError(f"{path} is missing required snippet: {needle!r}")
def validate_prometheus() -> None:
content = read(PROMETHEUS_PATH)
assert_contains(content, "tls_config:", PROMETHEUS_PATH)
assert_contains(content, "ca_file:", PROMETHEUS_PATH)
assert_contains(content, "cert_file:", PROMETHEUS_PATH)
assert_contains(content, "key_file:", PROMETHEUS_PATH)
assert_contains(content, "authorization:", PROMETHEUS_PATH)
assert_contains(content, "credentials_file:", PROMETHEUS_PATH)
def validate_tempo() -> None:
content = read(TEMPO_PATH)
assert_contains(content, "multitenancy_enabled: true", TEMPO_PATH)
assert_contains(content, "require_client_cert: true", TEMPO_PATH)
assert_contains(content, "per_tenant_override_config", TEMPO_PATH)
overrides = read(TEMPO_OVERRIDES_PATH)
assert_contains(overrides, "__default__", TEMPO_OVERRIDES_PATH)
assert_contains(overrides, "traces_per_second_limit", TEMPO_OVERRIDES_PATH)
assert_contains(overrides, "max_bytes_per_trace", TEMPO_OVERRIDES_PATH)
def validate_loki() -> None:
content = read(LOKI_PATH)
assert_contains(content, "auth_enabled: true", LOKI_PATH)
assert_contains(content, "per_tenant_override_config", LOKI_PATH)
overrides = read(LOKI_OVERRIDES_PATH)
assert_contains(overrides, "__default__", LOKI_OVERRIDES_PATH)
assert_contains(overrides, "retention_period", LOKI_OVERRIDES_PATH)
def main() -> int:
try:
validate_prometheus()
validate_tempo()
validate_loki()
except (AssertionError, FileNotFoundError) as exc:
print(f"[❌] telemetry storage validation failed: {exc}", file=sys.stderr)
return 1
print("[✓] telemetry storage configuration meets multi-tenant guard rails.")
return 0
if __name__ == "__main__":
sys.exit(main())

5
ops/licensing/TASKS.completed.md Normal file
View File

@@ -0,0 +1,5 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-LIC-14-004 | DONE (2025-10-26) | Licensing Guild | AUTH-MTLS-11-002 | Implement registry token service tied to Authority (DPoP/mTLS), plan gating, revocation handling, and monitoring per architecture. | Token service issues scoped tokens, revocation tested, monitoring dashboards in place, docs updated. |

1
ops/licensing/TASKS.md
View File

@@ -2,4 +2,3 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-LIC-14-004 | DONE (2025-10-26) | Licensing Guild | AUTH-MTLS-11-002 | Implement registry token service tied to Authority (DPoP/mTLS), plan gating, revocation handling, and monitoring per architecture. | Token service issues scoped tokens, revocation tested, monitoring dashboards in place, docs updated. |

8
ops/offline-kit/TASKS.completed.md Normal file
View File

@@ -0,0 +1,8 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-OFFLINE-14-002 | DONE (2025-10-26) | Offline Kit Guild | DEVOPS-REL-14-001 | Build offline kit packaging workflow (artifact bundling, manifest generation, signature verification). | Offline tarball generated with manifest + checksums + signatures; `ops/offline-kit/run-python-analyzer-smoke.sh` invoked as part of packaging; `debug/.build-id` tree mirrored from release output; import script verifies integrity; docs updated. |
| DEVOPS-OFFLINE-18-004 | DONE (2025-10-22) | Offline Kit Guild, Scanner Guild | DEVOPS-OFFLINE-18-003, SCANNER-ANALYZERS-LANG-10-309G | Rebuild Offline Kit bundle with Go analyzer plug-in and updated manifest/signature set. | Kit tarball includes Go analyzer artifacts; manifest/signature refreshed; verification steps executed and logged; docs updated with new bundle version. |
| DEVOPS-OFFLINE-18-005 | DONE (2025-10-26) | Offline Kit Guild, Scanner Guild | DEVOPS-REL-14-004, SCANNER-ANALYZERS-LANG-10-309P | Repackage Offline Kit with Python analyzer plug-in artefacts and refreshed manifest/signature set. | Kit tarball includes Python analyzer DLL/PDB/manifest; signature + manifest updated; Offline Kit guide references Python coverage; smoke import validated. |
| DEVOPS-OFFLINE-17-003 | DONE (2025-10-26) | Offline Kit Guild, DevOps Guild | DEVOPS-REL-17-002 | Mirror release debug-store artefacts ( `.build-id/` tree and `debug-manifest.json`) into Offline Kit packaging and document import validation. | Offline kit archives `debug/.build-id/` with manifest/sha256, docs cover symbol lookup workflow, smoke job confirms build-id lookup succeeds on air-gapped install. |

4
ops/offline-kit/TASKS.md
View File

@@ -2,13 +2,9 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| DEVOPS-OFFLINE-14-002 | DONE (2025-10-26) | Offline Kit Guild | DEVOPS-REL-14-001 | Build offline kit packaging workflow (artifact bundling, manifest generation, signature verification). | Offline tarball generated with manifest + checksums + signatures; `ops/offline-kit/run-python-analyzer-smoke.sh` invoked as part of packaging; `debug/.build-id` tree mirrored from release output; import script verifies integrity; docs updated. |
| DEVOPS-OFFLINE-18-004 | DONE (2025-10-22) | Offline Kit Guild, Scanner Guild | DEVOPS-OFFLINE-18-003, SCANNER-ANALYZERS-LANG-10-309G | Rebuild Offline Kit bundle with Go analyzer plug-in and updated manifest/signature set. | Kit tarball includes Go analyzer artifacts; manifest/signature refreshed; verification steps executed and logged; docs updated with new bundle version. |
| DEVOPS-OFFLINE-18-005 | DONE (2025-10-26) | Offline Kit Guild, Scanner Guild | DEVOPS-REL-14-004, SCANNER-ANALYZERS-LANG-10-309P | Repackage Offline Kit with Python analyzer plug-in artefacts and refreshed manifest/signature set. | Kit tarball includes Python analyzer DLL/PDB/manifest; signature + manifest updated; Offline Kit guide references Python coverage; smoke import validated. |
| DEVOPS-OFFLINE-34-006 | TODO | Offline Kit Guild, Orchestrator Service Guild | ORCH-SVC-34-004, DEPLOY-ORCH-34-001 | Bundle orchestrator service container, worker SDK samples, Postgres snapshot, and dashboards into Offline Kit with manifest/signature updates. | Offline kit contains orchestrator assets; manifest/signature validated; docs updated with air-gapped install steps; smoke import executed. |
| DEVOPS-OFFLINE-37-001 | TODO | Offline Kit Guild, Exporter Service Guild | EXPORT-SVC-37-001..004, DEPLOY-EXPORT-36-001 | Export Center offline bundles + verification tooling (mirror artefacts, verification CLI, manifest/signature refresh, air-gap import script). | Offline kit includes export bundles/tools; verification script passes; manifest/signature updated; docs detail import workflow. |
| DEVOPS-OFFLINE-37-002 | TODO | Offline Kit Guild, Notifications Service Guild | NOTIFY-SVC-40-001..004, WEB-NOTIFY-40-001 | Notifier offline packs (sample configs, template/digest packs, dry-run harness) with integrity checks and operator docs. | Offline kit ships notifier assets with checksums; dry-run harness validated; docs outline sealed/connected install steps. |
| CLI-PACKS-43-002 | TODO | Offline Kit Guild, Packs Registry Guild | PACKS-REG-42-001, DEPLOY-PACKS-43-001 | Bundle Task Pack samples, registry mirror seeds, Task Runner configs, and CLI binaries with checksums into Offline Kit. | Offline kit includes packs registry mirror, Task Runner configs, CLI binaries; manifest/signature updated; docs describe air-gapped execution. |
| OFFLINE-CONTAINERS-46-001 | TODO | Offline Kit Guild, Deployment Guild | DEVOPS-CONTAINERS-46-001, DEPLOY-AIRGAP-46-001 | Include container air-gap bundle, verification docs, and mirrored registry instructions inside Offline Kit. | Offline kit ships bundle + how-to; verification steps validated; manifest/signature updated; imposed rule noted. |
| DEVOPS-OFFLINE-17-003 | DONE (2025-10-26) | Offline Kit Guild, DevOps Guild | DEVOPS-REL-17-002 | Mirror release debug-store artefacts ( `.build-id/` tree and `debug-manifest.json`) into Offline Kit packaging and document import validation. | Offline kit archives `debug/.build-id/` with manifest/sha256, docs cover symbol lookup workflow, smoke job confirms build-id lookup succeeds on air-gapped install. |
| DEVOPS-OFFLINE-17-004 | BLOCKED (2025-10-26) | Offline Kit Guild, DevOps Guild | DEVOPS-REL-17-002 | Execute `mirror_debug_store.py` after the next release pipeline emits `out/release/debug`, verify manifest hashes, and archive `metadata/debug-store.json` with the kit. | Debug store mirrored post-release, manifest SHA validated, summary committed alongside Offline Kit bundle evidence. ⏳ Blocked until the release pipeline publishes the next `out/release/debug` tree; rerun the mirroring script as part of that pipeline. |

8
samples/TASKS.completed.md Normal file
View File

@@ -0,0 +1,8 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| SAMPLES-10-001 | DONE | Samples Guild, Scanner Team | SCANNER-EMIT-10-605 | Curate sample images (nginx, alpine+busybox, distroless+go, .NET AOT, python venv, npm monorepo) with expected SBOM/BOM-Index sidecars. | Samples committed under `samples/`; golden SBOM/BOM-Index files present; documented usage. |
| SAMPLES-13-004 | DONE (2025-10-23) | Samples Guild, Policy Guild | POLICY-CORE-09-006, UI-POLICY-13-007 | Add policy preview/report fixtures showing confidence bands and unknown-age tags. | Confidence sample (`samples/policy/policy-preview-unknown.json`) reviewed, documented usage in UI dev guide, ajv validation hook updated. |
| SAMPLES-POLICY-20-001 | DONE (2025-10-26) | Samples Guild, Policy Guild | POLICY-ENGINE-20-002, DOCS-POLICY-20-011 | Create sample policies (`baseline.pol`, `serverless.pol`, `internal-only.pol`) with annotated SBOM/advisory fixtures. | Samples stored under `samples/policy/`; README documents usage; tests validate deterministic outputs. |
| SAMPLES-POLICY-20-002 | DONE (2025-10-26) | Samples Guild, UI Guild | UI-POLICY-20-002 | Produce simulation diff fixtures (before/after JSON) for UI/CLI tests. | Fixtures committed with schema validation; referenced by UI+CLI tests; docs cross-link. |

4
samples/TASKS.md
View File

@@ -2,15 +2,11 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| SAMPLES-10-001 | DONE | Samples Guild, Scanner Team | SCANNER-EMIT-10-605 | Curate sample images (nginx, alpine+busybox, distroless+go, .NET AOT, python venv, npm monorepo) with expected SBOM/BOM-Index sidecars. | Samples committed under `samples/`; golden SBOM/BOM-Index files present; documented usage. |
| SAMPLES-13-004 | DONE (2025-10-23) | Samples Guild, Policy Guild | POLICY-CORE-09-006, UI-POLICY-13-007 | Add policy preview/report fixtures showing confidence bands and unknown-age tags. | Confidence sample (`samples/policy/policy-preview-unknown.json`) reviewed, documented usage in UI dev guide, ajv validation hook updated. |
## Policy Engine v2
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| SAMPLES-POLICY-20-001 | DONE (2025-10-26) | Samples Guild, Policy Guild | POLICY-ENGINE-20-002, DOCS-POLICY-20-011 | Create sample policies (`baseline.pol`, `serverless.pol`, `internal-only.pol`) with annotated SBOM/advisory fixtures. | Samples stored under `samples/policy/`; README documents usage; tests validate deterministic outputs. |
| SAMPLES-POLICY-20-002 | DONE (2025-10-26) | Samples Guild, UI Guild | UI-POLICY-20-002 | Produce simulation diff fixtures (before/after JSON) for UI/CLI tests. | Fixtures committed with schema validation; referenced by UI+CLI tests; docs cross-link. |
## Graph Explorer v1

65
samples/api/reports/report-sample.dsse.json
View File

@@ -1,58 +1,11 @@
{
"report": {
"reportId": "report-3def5f362aa475ef14b6",
"imageDigest": "sha256:deadbeef",
"generatedAt": "2025-10-19T08:28:09.3699267+00:00",
"verdict": "blocked",
"policy": {
"revisionId": "rev-1",
"digest": "27d2ec2b34feedc304fc564d252ecee1c8fa14ea581a5ff5c1ea8963313d5c8d"
},
"summary": {
"total": 1,
"blocked": 1,
"warned": 0,
"ignored": 0,
"quieted": 1
},
"verdicts": [
{
"findingId": "finding-1",
"status": "Blocked",
"ruleName": "Block Critical",
"ruleAction": "Block",
"score": 40.5,
"configVersion": "1.0",
"inputs": {
"reachabilityWeight": 0.45,
"baseScore": 40.5,
"severityWeight": 90,
"trustWeight": 1,
"trustWeight.NVD": 1,
"reachability.runtime": 0.45,
"unknownConfidence": 0.52,
"unknownAgeDays": 4
},
"quietedBy": "policy/quiet-critical-runtime",
"quiet": true,
"unknownConfidence": 0.52,
"confidenceBand": "medium",
"unknownAgeDays": 4,
"sourceTrust": "NVD",
"reachability": "runtime"
}
],
"issues": []
},
"dsse": {
"payloadType": "application/vnd.stellaops.report+json",
"payload": "eyJyZXBvcnRJZCI6InJlcG9ydC0zZGVmNWYzNjJhYTQ3NWVmMTRiNiIsImltYWdlRGlnZXN0Ijoic2hhMjU2OmRlYWRiZWVmIiwiZ2VuZXJhdGVkQXQiOiIyMDI1LTEwLTE5VDA4OjI4OjA5LjM2OTkyNjcrMDA6MDAiLCJ2ZXJkaWN0IjoiYmxvY2tlZCIsInBvbGljeSI6eyJyZXZpc2lvbklkIjoicmV2LTEiLCJkaWdlc3QiOiIyN2QyZWMyYjM0ZmVlZGMzMDRmYzU2NGQyNTJlY2VlMWM4ZmExNGVhNTgxYTVmZjVjMWVhODk2MzMxM2Q1YzhkIn0sInN1bW1hcnkiOnsidG90YWwiOjEsImJsb2NrZWQiOjEsIndhcm5lZCI6MCwiaWdub3JlZCI6MCwicXVpZXRlZCI6MX0sInZlcmRpY3RzIjpbeyJmaW5kaW5nSWQiOiJmaW5kaW5nLTEiLCJzdGF0dXMiOiJCbG9ja2VkIiwicnVsZU5hbWUiOiJCbG9jayBDcml0aWNhbCIsInJ1bGVBY3Rpb24iOiJCbG9jayIsInNjb3JlIjo0MC41LCJjb25maWdWZXJzaW9uIjoiMS4wIiwiaW5wdXRzIjp7InJlYWNoYWJpbGl0eVdlaWdodCI6MC40NSwiYmFzZVNjb3JlIjo0MC41LCJzZXZlcml0eVdlaWdodCI6OTAsInRydXN0V2VpZ2h0IjoxLCJ0cnVzdFdlaWdodC5OVkQiOjEsInJlYWNoYWJpbGl0eS5ydW50aW1lIjowLjQ1LCJ1bmtub3duQ29uZmlkZW5jZSI6MC41MiwidW5rbm93bkFnZURheXMiOjR9LCJxdWlldGVkQnkiOiJwb2xpY3kvcXVpZXQtY3JpdGljYWwtcnVudGltZSIsInF1aWV0Ijp0cnVlLCJ1bmtub3duQ29uZmlkZW5jZSI6MC41MiwiY29uZmlkZW5jZUJhbmQiOiJtZWRpdW0iLCJ1bmtub3duQWdlRGF5cyI6NCwic291cmNlVHJ1c3QiOiJOVkQiLCJyZWFjaGFiaWxpdHkiOiJydW50aW1lIn1dLCJpc3N1ZXMiOltdfQ==",
"signatures": [
{
"keyId": "scanner-report-signing",
"algorithm": "hs256",
"signature": "s3qnWeRsYs+QA/nO84Us8G2xjZcvphc2P7KnOdTVwQs="
}
]
}
"payloadType": "application/vnd.stellaops.report+json",
"payload": "eyJyZXBvcnRJZCI6InJlcG9ydC1hYmMiLCJpbWFnZURpZ2VzdCI6InNoYTI1NjpmZWVkZmFjZSIsImdlbmVyYXRlZEF0IjoiMjAyNS0xMC0xOVQxMjozNDo1NiswMDowMCIsInZlcmRpY3QiOiJibG9ja2VkIiwicG9saWN5Ijp7InJldmlzaW9uSWQiOiJyZXYtNDIiLCJkaWdlc3QiOiJkaWdlc3QtMTIzIn0sInN1bW1hcnkiOnsidG90YWwiOjEsImJsb2NrZWQiOjEsIndhcm5lZCI6MCwiaWdub3JlZCI6MCwicXVpZXRlZCI6MH0sInZlcmRpY3RzIjpbeyJmaW5kaW5nSWQiOiJmaW5kaW5nLTEiLCJzdGF0dXMiOiJCbG9ja2VkIiwic2NvcmUiOjQ3LjUsInNvdXJjZVRydXN0IjoiTlZEIiwicmVhY2hhYmlsaXR5IjoicnVudGltZSJ9XSwiaXNzdWVzIjpbXX0=",
"signatures": [
{
"keyId": "test-key",
"algorithm": "hs256",
"signature": "signature-value"
}
]
}

95
src/Aoc/__Libraries/StellaOps.Aoc.AspNetCore/Results/AocHttpResults.cs Normal file
View File

@@ -0,0 +1,95 @@
using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Http;
using HttpResults = Microsoft.AspNetCore.Http.Results;
using StellaOps.Aoc;
namespace StellaOps.Aoc.AspNetCore.Results;
/// <summary>
/// Helpers for emitting Aggregation-Only Contract error responses.
/// </summary>
public static class AocHttpResults
{
private const string DefaultProblemType = "https://stella-ops.org/problems/aoc-violation";
/// <summary>
/// Converts an <see cref="AocGuardException"/> into a RFC 7807 problem response.
/// </summary>
/// <param name="httpContext">The current HTTP context.</param>
/// <param name="exception">The guard exception.</param>
/// <param name="title">Optional problem title.</param>
/// <param name="detail">Optional problem detail.</param>
/// <param name="type">Optional problem type URI.</param>
/// <param name="status">Optional HTTP status code override.</param>
/// <param name="extensions">Optional extension payload merged with guard details.</param>
/// <returns>An HTTP result representing the problem response.</returns>
public static IResult Problem(
HttpContext httpContext,
AocGuardException exception,
string? title = null,
string? detail = null,
string? type = null,
int? status = null,
IDictionary<string, object?>? extensions = null)
{
if (httpContext is null)
{
throw new ArgumentNullException(nameof(httpContext));
}
if (exception is null)
{
throw new ArgumentNullException(nameof(exception));
}
var primaryCode = exception.Result.Violations.IsDefaultOrEmpty
? "ERR_AOC_000"
: exception.Result.Violations[0].ErrorCode;
var violationPayload = exception.Result.Violations
.Select(v => new Dictionary<string, object?>(StringComparer.Ordinal)
{
["code"] = v.ErrorCode,
["path"] = v.Path,
["message"] = v.Message
})
.ToArray();
var extensionPayload = new Dictionary<string, object?>(StringComparer.Ordinal)
{
["code"] = primaryCode,
["violations"] = violationPayload
};
if (extensions is not null)
{
foreach (var kvp in extensions)
{
extensionPayload[kvp.Key] = kvp.Value;
}
}
var statusCode = status ?? MapErrorCodeToStatus(primaryCode);
var problemType = type ?? DefaultProblemType;
var problemDetail = detail ?? $"AOC guard rejected the request with {primaryCode}.";
var problemTitle = title ?? "Aggregation-Only Contract violation";
return HttpResults.Problem(
statusCode: statusCode,
title: problemTitle,
detail: problemDetail,
type: problemType,
extensions: extensionPayload);
}
private static int MapErrorCodeToStatus(string errorCode) => errorCode switch
{
"ERR_AOC_003" => StatusCodes.Status409Conflict,
"ERR_AOC_004" => StatusCodes.Status422UnprocessableEntity,
"ERR_AOC_005" => StatusCodes.Status422UnprocessableEntity,
"ERR_AOC_006" => StatusCodes.Status403Forbidden,
_ => StatusCodes.Status400BadRequest,
};
}

91
src/Aoc/__Libraries/StellaOps.Aoc.AspNetCore/Routing/AocGuardEndpointFilter.cs Normal file
View File

@@ -0,0 +1,91 @@
using System;
using System.Collections.Generic;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using StellaOps.Aoc;
namespace StellaOps.Aoc.AspNetCore.Routing;
public sealed class AocGuardEndpointFilter<TRequest> : IEndpointFilter
{
private readonly Func<TRequest, IEnumerable<object?>> _payloadSelector;
private readonly JsonSerializerOptions _serializerOptions;
private readonly AocGuardOptions? _guardOptions;
public AocGuardEndpointFilter(
Func<TRequest, IEnumerable<object?>> payloadSelector,
JsonSerializerOptions? serializerOptions,
AocGuardOptions? guardOptions)
{
_payloadSelector = payloadSelector ?? throw new ArgumentNullException(nameof(payloadSelector));
_serializerOptions = serializerOptions ?? new JsonSerializerOptions(JsonSerializerDefaults.Web);
_guardOptions = guardOptions;
}
public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
{
if (context is null)
{
throw new ArgumentNullException(nameof(context));
}
if (TryGetArgument(context, out var request))
{
var payloads = _payloadSelector(request);
if (payloads is not null)
{
var guard = context.HttpContext.RequestServices.GetRequiredService<IAocGuard>();
var options = ResolveOptions(context.HttpContext.RequestServices);
foreach (var payload in payloads)
{
if (payload is null)
{
continue;
}
JsonElement element = payload switch
{
JsonElement jsonElement => jsonElement,
JsonDocument jsonDocument => jsonDocument.RootElement,
_ => JsonSerializer.SerializeToElement(payload, _serializerOptions)
};
guard.ValidateOrThrow(element, options);
}
}
}
return await next(context).ConfigureAwait(false);
}
private AocGuardOptions ResolveOptions(IServiceProvider services)
{
if (_guardOptions is not null)
{
return _guardOptions;
}
var options = services.GetService<IOptions<AocGuardOptions>>();
return options?.Value ?? AocGuardOptions.Default;
}
private static bool TryGetArgument(EndpointFilterInvocationContext context, out TRequest argument)
{
for (var i = 0; i < context.Arguments.Count; i++)
{
if (context.Arguments[i] is TRequest typedArgument)
{
argument = typedArgument;
return true;
}
}
argument = default!;
return false;
}
}

14
src/Aoc/__Libraries/StellaOps.Aoc.AspNetCore/StellaOps.Aoc.AspNetCore.csproj Normal file
View File

@@ -0,0 +1,14 @@
<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\StellaOps.Aoc\StellaOps.Aoc.csproj" />
</ItemGroup>
</Project>

49
src/Aoc/__Tests/StellaOps.Aoc.AspNetCore.Tests/AocHttpResultsTests.cs Normal file
View File

@@ -0,0 +1,49 @@
using System.Collections.Immutable;
using System.IO;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using StellaOps.Aoc;
using StellaOps.Aoc.AspNetCore.Results;
namespace StellaOps.Aoc.AspNetCore.Tests;
public sealed class AocHttpResultsTests
{
[Fact]
public async Task Problem_WritesProblemDetails_WithGuardViolations()
{
// Arrange
var violations = ImmutableArray.Create(
AocViolation.Create(AocViolationCode.MissingProvenance, "/upstream", "Missing upstream"),
AocViolation.Create(AocViolationCode.ForbiddenField, "/severity", "Forbidden"));
var result = AocGuardResult.FromViolations(violations);
var exception = new AocGuardException(result);
var context = new DefaultHttpContext();
context.Response.Body = new MemoryStream();
var services = new ServiceCollection();
services.AddLogging();
services.AddProblemDetails();
context.RequestServices = services.BuildServiceProvider();
// Act
var problem = AocHttpResults.Problem(context, exception);
await problem.ExecuteAsync(context);
context.Response.Body.Seek(0, SeekOrigin.Begin);
using var document = await JsonDocument.ParseAsync(context.Response.Body, cancellationToken: TestContext.Current.CancellationToken);
var root = document.RootElement;
// Assert
Assert.Equal(StatusCodes.Status422UnprocessableEntity, context.Response.StatusCode);
Assert.Equal("Aggregation-Only Contract violation", root.GetProperty("title").GetString());
Assert.Equal("ERR_AOC_004", root.GetProperty("code").GetString());
var violationsJson = root.GetProperty("violations");
Assert.Equal(2, violationsJson.GetArrayLength());
Assert.Equal("ERR_AOC_004", violationsJson[0].GetProperty("code").GetString());
Assert.Equal("/upstream", violationsJson[0].GetProperty("path").GetString());
}
}

32
src/Aoc/__Tests/StellaOps.Aoc.AspNetCore.Tests/StellaOps.Aoc.AspNetCore.Tests.csproj Normal file
View File

@@ -0,0 +1,32 @@
<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>preview</LangVersion>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<IsPackable>false</IsPackable>
<UseConcelierTestInfra>false</UseConcelierTestInfra>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
<PackageReference Include="xunit.v3" Version="3.0.0" />
<PackageReference Include="xunit.runner.visualstudio" Version="3.1.3" />
</ItemGroup>
<ItemGroup>
<Using Include="Xunit" />
</ItemGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\__Libraries\StellaOps.Aoc.AspNetCore\StellaOps.Aoc.AspNetCore.csproj" />
</ItemGroup>
</Project>

7
src/Attestor/StellaOps.Attestor/TASKS.completed.md Normal file
View File

@@ -0,0 +1,7 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| ATTESTOR-API-11-201 | DONE (2025-10-19) | Attestor Guild | — | `/rekor/entries` submission pipeline with dedupe, proof acquisition, and persistence. | ✅ `POST /api/v1/rekor/entries` enforces mTLS + Authority OpTok, validates DSSE bundles, and handles dual-log preferences.<br>✅ Redis/Mongo idempotency returns existing UUID on duplicate `bundleSha256` without re-submitting to Rekor.<br>✅ Rekor driver fetches inclusion proofs (or schedules async fetch) and persists canonical entry/proof metadata.<br>✅ Optional archive path stores DSSE/proof bundles to MinIO/S3; integration tests cover success/pending/error flows. |
| ATTESTOR-VERIFY-11-202 | DONE (2025-10-19) | Attestor Guild | — | `/rekor/verify` + retrieval endpoints validating signatures and Merkle proofs. | ✅ `GET /api/v1/rekor/entries/{uuid}` surfaces cached entries with optional backend refresh and handles not-found/refresh flows.<br>✅ `POST /api/v1/rekor/verify` accepts UUID, bundle, or artifact hash inputs; verifies DSSE signatures, Merkle proofs, and checkpoint anchors.<br>✅ Verification output returns `{ok, uuid, index, logURL, checkedAt}` with failure diagnostics for invalid proofs.<br>✅ Unit/integration tests exercise cache hits, backend refresh, invalid bundle/proof scenarios, and checkpoint trust anchor enforcement. |
| ATTESTOR-OBS-11-203 | DONE (2025-10-19) | Attestor Guild | — | Telemetry, alerting, mTLS hardening, and archive workflow for Attestor. | ✅ Structured logs, metrics, and optional traces record submission latency, proof fetch outcomes, verification results, and Rekor error buckets with correlation IDs.<br>✅ mTLS enforcement hardened (peer allowlist, SAN checks, rate limiting) and documented; TLS settings audited for modern ciphers only.<br>✅ Alerting/dashboard pack covers error rates, proof backlog, Redis/Mongo health, and archive job failures; runbook updated.<br>✅ Archive workflow includes retention policy jobs, failure alerts, and periodic verification of stored bundles and proofs. |

3
src/Attestor/StellaOps.Attestor/TASKS.md
View File

@@ -2,9 +2,6 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| ATTESTOR-API-11-201 | DONE (2025-10-19) | Attestor Guild | — | `/rekor/entries` submission pipeline with dedupe, proof acquisition, and persistence. | ✅ `POST /api/v1/rekor/entries` enforces mTLS + Authority OpTok, validates DSSE bundles, and handles dual-log preferences.<br>✅ Redis/Mongo idempotency returns existing UUID on duplicate `bundleSha256` without re-submitting to Rekor.<br>✅ Rekor driver fetches inclusion proofs (or schedules async fetch) and persists canonical entry/proof metadata.<br>✅ Optional archive path stores DSSE/proof bundles to MinIO/S3; integration tests cover success/pending/error flows. |
| ATTESTOR-VERIFY-11-202 | DONE (2025-10-19) | Attestor Guild | — | `/rekor/verify` + retrieval endpoints validating signatures and Merkle proofs. | ✅ `GET /api/v1/rekor/entries/{uuid}` surfaces cached entries with optional backend refresh and handles not-found/refresh flows.<br>✅ `POST /api/v1/rekor/verify` accepts UUID, bundle, or artifact hash inputs; verifies DSSE signatures, Merkle proofs, and checkpoint anchors.<br>✅ Verification output returns `{ok, uuid, index, logURL, checkedAt}` with failure diagnostics for invalid proofs.<br>✅ Unit/integration tests exercise cache hits, backend refresh, invalid bundle/proof scenarios, and checkpoint trust anchor enforcement. |
| ATTESTOR-OBS-11-203 | DONE (2025-10-19) | Attestor Guild | — | Telemetry, alerting, mTLS hardening, and archive workflow for Attestor. | ✅ Structured logs, metrics, and optional traces record submission latency, proof fetch outcomes, verification results, and Rekor error buckets with correlation IDs.<br>✅ mTLS enforcement hardened (peer allowlist, SAN checks, rate limiting) and documented; TLS settings audited for modern ciphers only.<br>✅ Alerting/dashboard pack covers error rates, proof backlog, Redis/Mongo health, and archive job failures; runbook updated.<br>✅ Archive workflow includes retention policy jobs, failure alerts, and periodic verification of stored bundles and proofs. |
> Remark (2025-10-19): Wave 0 prerequisites reviewed (none outstanding); ATTESTOR-API-11-201, ATTESTOR-VERIFY-11-202, and ATTESTOR-OBS-11-203 tracked as DOING per Wave 0A kickoff.
> Remark (2025-10-19): Dual-log submissions, signature/proof verification, and observability hardening landed; attestor endpoints now rate-limited per client with correlation-ID logging and updated docs/tests.

689
src/Authority/StellaOps.Api.OpenApi/authority/openapi.yaml Normal file
View File

@@ -0,0 +1,689 @@
openapi: 3.1.0
info:
title: StellaOps Authority Authentication API
summary: Token issuance, introspection, revocation, and key discovery endpoints exposed by the Authority service.
description: |
The Authority service issues OAuth 2.1 access tokens for StellaOps components, enforcing tenant and scope
restrictions configured per client. This specification describes the authentication surface only; domain APIs
are documented by their owning services.
version: 0.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
servers:
- url: https://authority.stellaops.local
description: Example Authority deployment
tags:
- name: Authentication
description: OAuth 2.1 token exchange, introspection, and revocation flows.
- name: Keys
description: JSON Web Key Set discovery.
components:
securitySchemes:
ClientSecretBasic:
type: http
scheme: basic
description: HTTP Basic authentication with `client_id` and `client_secret`.
OAuthPassword:
type: oauth2
description: Resource owner password exchange for Authority-managed identities.
flows:
password:
tokenUrl: /token
refreshUrl: /token
scopes:
advisory:ingest: Submit advisory ingestion payloads.
advisory:read: Read advisory ingestion data.
aoc:verify: Execute Aggregation-Only Contract verification workflows.
authority.audit.read: Read Authority audit logs.
authority.clients.manage: Manage Authority client registrations.
authority.users.manage: Manage Authority users.
authority:tenants.read: Read the Authority tenant catalog.
concelier.jobs.trigger: Trigger Concelier aggregation jobs.
concelier.merge: Manage Concelier merge operations.
effective:write: Write effective findings (Policy Engine service identity only).
email: Access email claim data.
exceptions:approve: Approve exception workflows.
findings:read: Read effective findings emitted by Policy Engine.
graph:export: Export graph artefacts.
graph:read: Read graph explorer data.
graph:simulate: Run graph what-if simulations.
graph:write: Enqueue or mutate graph build jobs.
offline_access: Request refresh tokens for offline access.
openid: Request OpenID Connect identity tokens.
orch:operate: Execute privileged Orchestrator control actions.
orch:read: Read Orchestrator job state.
policy:author: Author Policy Studio drafts and workspaces.
policy:activate: Activate policy revisions.
policy:approve: Approve or reject policy drafts.
policy:audit: Inspect Policy Studio audit history.
policy:edit: Edit policy definitions.
policy:operate: Operate Policy Studio promotions and runs.
policy:read: Read policy definitions and metadata.
policy:run: Trigger policy executions.
policy:submit: Submit policy drafts for review.
policy:review: Review Policy Studio drafts and leave feedback.
policy:simulate: Execute Policy Studio simulations.
policy:write: Create or update policy drafts.
profile: Access profile claim data.
signals:admin: Administer Signals ingestion and routing settings.
signals:read: Read Signals events and state.
signals:write: Publish Signals events or mutate state.
stellaops.bypass: Bypass trust boundary protections (restricted identities only).
ui.read: Read Console UX resources.
vex:ingest: Submit VEX ingestion payloads.
vex:read: Read VEX ingestion data.
vuln:read: Read vulnerability permalinks and overlays.
authorizationCode:
authorizationUrl: /authorize
tokenUrl: /token
refreshUrl: /token
scopes:
advisory:ingest: Submit advisory ingestion payloads.
advisory:read: Read advisory ingestion data.
aoc:verify: Execute Aggregation-Only Contract verification workflows.
authority.audit.read: Read Authority audit logs.
authority.clients.manage: Manage Authority client registrations.
authority.users.manage: Manage Authority users.
authority:tenants.read: Read the Authority tenant catalog.
concelier.jobs.trigger: Trigger Concelier aggregation jobs.
concelier.merge: Manage Concelier merge operations.
effective:write: Write effective findings (Policy Engine service identity only).
email: Access email claim data.
exceptions:approve: Approve exception workflows.
findings:read: Read effective findings emitted by Policy Engine.
graph:export: Export graph artefacts.
graph:read: Read graph explorer data.
graph:simulate: Run graph what-if simulations.
graph:write: Enqueue or mutate graph build jobs.
offline_access: Request refresh tokens for offline access.
openid: Request OpenID Connect identity tokens.
orch:operate: Execute privileged Orchestrator control actions.
orch:read: Read Orchestrator job state.
policy:author: Author Policy Studio drafts and workspaces.
policy:activate: Activate policy revisions.
policy:approve: Approve or reject policy drafts.
policy:audit: Inspect Policy Studio audit history.
policy:edit: Edit policy definitions.
policy:operate: Operate Policy Studio promotions and runs.
policy:read: Read policy definitions and metadata.
policy:run: Trigger policy executions.
policy:submit: Submit policy drafts for review.
policy:review: Review Policy Studio drafts and leave feedback.
policy:simulate: Execute Policy Studio simulations.
policy:write: Create or update policy drafts.
profile: Access profile claim data.
signals:admin: Administer Signals ingestion and routing settings.
signals:read: Read Signals events and state.
signals:write: Publish Signals events or mutate state.
stellaops.bypass: Bypass trust boundary protections (restricted identities only).
ui.read: Read Console UX resources.
vex:ingest: Submit VEX ingestion payloads.
vex:read: Read VEX ingestion data.
vuln:read: Read vulnerability permalinks and overlays.
OAuthClientCredentials:
type: oauth2
description: Client credential exchange for machine-to-machine identities.
flows:
clientCredentials:
tokenUrl: /token
scopes:
advisory:ingest: Submit advisory ingestion payloads.
advisory:read: Read advisory ingestion data.
aoc:verify: Execute Aggregation-Only Contract verification workflows.
authority.audit.read: Read Authority audit logs.
authority.clients.manage: Manage Authority client registrations.
authority.users.manage: Manage Authority users.
authority:tenants.read: Read the Authority tenant catalog.
concelier.jobs.trigger: Trigger Concelier aggregation jobs.
concelier.merge: Manage Concelier merge operations.
effective:write: Write effective findings (Policy Engine service identity only).
email: Access email claim data.
exceptions:approve: Approve exception workflows.
findings:read: Read effective findings emitted by Policy Engine.
graph:export: Export graph artefacts.
graph:read: Read graph explorer data.
graph:simulate: Run graph what-if simulations.
graph:write: Enqueue or mutate graph build jobs.
offline_access: Request refresh tokens for offline access.
openid: Request OpenID Connect identity tokens.
orch:operate: Execute privileged Orchestrator control actions.
orch:read: Read Orchestrator job state.
policy:author: Author Policy Studio drafts and workspaces.
policy:activate: Activate policy revisions.
policy:approve: Approve or reject policy drafts.
policy:audit: Inspect Policy Studio audit history.
policy:edit: Edit policy definitions.
policy:operate: Operate Policy Studio promotions and runs.
policy:read: Read policy definitions and metadata.
policy:run: Trigger policy executions.
policy:submit: Submit policy drafts for review.
policy:review: Review Policy Studio drafts and leave feedback.
policy:simulate: Execute Policy Studio simulations.
policy:write: Create or update policy drafts.
profile: Access profile claim data.
signals:admin: Administer Signals ingestion and routing settings.
signals:read: Read Signals events and state.
signals:write: Publish Signals events or mutate state.
stellaops.bypass: Bypass trust boundary protections (restricted identities only).
ui.read: Read Console UX resources.
vex:ingest: Submit VEX ingestion payloads.
vex:read: Read VEX ingestion data.
vuln:read: Read vulnerability permalinks and overlays.
schemas:
TokenResponse:
type: object
description: OAuth 2.1 bearer token response.
properties:
access_token:
type: string
description: Access token encoded as JWT.
token_type:
type: string
description: Token type indicator. Always `Bearer`.
expires_in:
type: integer
description: Lifetime of the access token, in seconds.
minimum: 1
refresh_token:
type: string
description: Refresh token issued when the grant allows offline access.
scope:
type: string
description: Space-delimited scopes granted in the response.
id_token:
type: string
description: ID token issued for authorization-code flows.
required:
- access_token
- token_type
- expires_in
OAuthErrorResponse:
type: object
description: RFC 6749 compliant error envelope.
properties:
error:
type: string
description: Machine-readable error code.
error_description:
type: string
description: Human-readable error description.
error_uri:
type: string
format: uri
description: Link to documentation about the error.
required:
- error
PasswordGrantRequest:
type: object
required:
- grant_type
- client_id
- username
- password
properties:
grant_type:
type: string
const: password
client_id:
type: string
description: Registered client identifier. May also be supplied via HTTP Basic auth.
client_secret:
type: string
description: Client secret. Required for confidential clients when not using HTTP Basic auth.
scope:
type: string
description: Space-delimited scopes being requested.
username:
type: string
description: Resource owner username.
password:
type: string
description: Resource owner password.
authority_provider:
type: string
description: Optional identity provider hint. Required when multiple password-capable providers are registered.
description: Form-encoded payload for password grant exchange.
ClientCredentialsGrantRequest:
type: object
required:
- grant_type
- client_id
properties:
grant_type:
type: string
const: client_credentials
client_id:
type: string
description: Registered client identifier. May also be supplied via HTTP Basic auth.
client_secret:
type: string
description: Client secret. Required for confidential clients when not using HTTP Basic auth.
scope:
type: string
description: Space-delimited scopes being requested.
authority_provider:
type: string
description: Optional identity provider hint for plugin-backed clients.
operator_reason:
type: string
description: Required when requesting `orch:operate`; explains the operator action.
maxLength: 256
operator_ticket:
type: string
description: Required when requesting `orch:operate`; tracks the external change ticket or incident.
maxLength: 128
description: Form-encoded payload for client credentials exchange.
RefreshTokenGrantRequest:
type: object
required:
- grant_type
- refresh_token
properties:
grant_type:
type: string
const: refresh_token
client_id:
type: string
description: Registered client identifier. May also be supplied via HTTP Basic auth.
client_secret:
type: string
description: Client secret. Required for confidential clients when not using HTTP Basic auth.
refresh_token:
type: string
description: Previously issued refresh token.
scope:
type: string
description: Optional scope list to narrow the requested access.
description: Form-encoded payload for refresh token exchange.
RevocationRequest:
type: object
required:
- token
properties:
token:
type: string
description: Token value or token identifier to revoke.
token_type_hint:
type: string
description: Optional token type hint (`access_token` or `refresh_token`).
description: Form-encoded payload for token revocation.
IntrospectionRequest:
type: object
required:
- token
properties:
token:
type: string
description: Token value whose state should be introspected.
token_type_hint:
type: string
description: Optional token type hint (`access_token` or `refresh_token`).
description: Form-encoded payload for token introspection.
IntrospectionResponse:
type: object
description: Active token descriptor compliant with RFC 7662.
properties:
active:
type: boolean
description: Indicates whether the token is currently active.
scope:
type: string
description: Space-delimited list of scopes granted to the token.
client_id:
type: string
description: Client identifier associated with the token.
sub:
type: string
description: Subject identifier when the token represents an end-user.
username:
type: string
description: Preferred username associated with the subject.
token_type:
type: string
description: Type of the token (e.g., `Bearer`).
exp:
type: integer
description: Expiration timestamp (seconds since UNIX epoch).
iat:
type: integer
description: Issued-at timestamp (seconds since UNIX epoch).
nbf:
type: integer
description: Not-before timestamp (seconds since UNIX epoch).
aud:
type: array
description: Audience values associated with the token.
items:
type: string
iss:
type: string
description: Issuer identifier.
jti:
type: string
description: JWT identifier corresponding to the token.
tenant:
type: string
description: Tenant associated with the token, when assigned.
confirmation:
type: object
description: Sender-constrained confirmation data (e.g., mTLS thumbprint, DPoP JWK thumbprint).
required:
- active
JwksDocument:
type: object
description: JSON Web Key Set published by the Authority.
properties:
keys:
type: array
items:
$ref: '#/components/schemas/Jwk'
required:
- keys
Jwk:
type: object
description: Public key material for token signature validation.
properties:
kid:
type: string
description: Key identifier.
kty:
type: string
description: Key type (e.g., `EC`, `RSA`).
use:
type: string
description: Intended key use (`sig`).
alg:
type: string
description: Signing algorithm (e.g., `ES384`).
crv:
type: string
description: Elliptic curve identifier when applicable.
x:
type: string
description: X coordinate for EC keys.
y:
type: string
description: Y coordinate for EC keys.
status:
type: string
description: Operational status metadata for the key (e.g., `active`, `retiring`).
paths:
/token:
post:
tags:
- Authentication
summary: Exchange credentials for tokens
description: |
Issues OAuth 2.1 bearer tokens for StellaOps clients. Supports password, client credentials,
authorization-code, device, and refresh token grants. Confidential clients must authenticate using
HTTP Basic auth or `client_secret` form fields.
security:
- ClientSecretBasic: []
- {}
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- $ref: '#/components/schemas/PasswordGrantRequest'
- $ref: '#/components/schemas/ClientCredentialsGrantRequest'
- $ref: '#/components/schemas/RefreshTokenGrantRequest'
encoding:
authority_provider:
style: form
explode: false
examples:
passwordGrant:
summary: Password grant for tenant-scoped ingestion bot
value:
grant_type: password
client_id: ingest-cli
client_secret: s3cr3t
username: ingest-bot
password: pa55w0rd!
scope: advisory:ingest vex:ingest
authority_provider: primary-directory
authorizationCode:
summary: Authorization code exchange for Console UI session
value:
grant_type: authorization_code
client_id: console-ui
code: 2Lba1WtwPLfZ2b0Z9uPrsQ
redirect_uri: https://console.stellaops.local/auth/callback
code_verifier: g3ZnL91QJ6i4zO_86oI4CDnZ7gS0bSeK
clientCredentials:
summary: Client credentials exchange for Policy Engine
value:
grant_type: client_credentials
client_id: policy-engine
client_secret: 9c39f602-2f2b-4f29
scope: effective:write findings:read
operator_reason: Deploying policy change 1234
operator_ticket: CHG-004211
refreshToken:
summary: Refresh token rotation for console session
value:
grant_type: refresh_token
client_id: console-ui
refresh_token: 0.rg9pVlsGzXE8Q
responses:
'200':
description: Token exchange succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
examples:
passwordGrant:
summary: Password grant success response
value:
access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
token_type: Bearer
expires_in: 3600
refresh_token: OxGdVtZJ-mk49cFd38uRUw
scope: advisory:ingest vex:ingest
clientCredentials:
summary: Client credentials success response
value:
access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
token_type: Bearer
expires_in: 900
scope: effective:write findings:read
authorizationCode:
summary: Authorization code success response
value:
access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
token_type: Bearer
expires_in: 900
refresh_token: VxKpc9Vj9QjYV6gLrhQHTw
scope: ui.read authority:tenants.read
id_token: eyJhbGciOiJFUzM4NCIsImtpZCI6ImNvbnNvbGUifQ...
'400':
description: Malformed request, unsupported grant type, or invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthErrorResponse'
examples:
invalidProvider:
summary: Unknown identity provider hint
value:
error: invalid_request
error_description: "Unknown identity provider 'legacy-directory'."
invalidScope:
summary: Scope not permitted for client
value:
error: invalid_scope
error_description: Scope 'effective:write' is not permitted for this client.
'401':
description: Client authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthErrorResponse'
examples:
badClientSecret:
summary: Invalid client secret
value:
error: invalid_client
error_description: Client authentication failed.
/revoke:
post:
tags:
- Authentication
summary: Revoke an access or refresh token
security:
- ClientSecretBasic: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RevocationRequest'
examples:
revokeRefreshToken:
summary: Revoke refresh token after logout
value:
token: 0.rg9pVlsGzXE8Q
token_type_hint: refresh_token
responses:
'200':
description: Token revoked or already invalid. The response body is intentionally blank.
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthErrorResponse'
examples:
missingToken:
summary: Token parameter omitted
value:
error: invalid_request
error_description: The revocation request is missing the token parameter.
'401':
description: Client authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthErrorResponse'
examples:
badClientSecret:
summary: Invalid client credentials
value:
error: invalid_client
error_description: Client authentication failed.
/introspect:
post:
tags:
- Authentication
summary: Introspect token state
description: Returns the active status and claims for a given token. Requires a privileged client.
security:
- ClientSecretBasic: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/IntrospectionRequest'
examples:
introspectToken:
summary: Validate an access token issued to Orchestrator
value:
token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
token_type_hint: access_token
responses:
'200':
description: Token state evaluated.
content:
application/json:
schema:
$ref: '#/components/schemas/IntrospectionResponse'
examples:
activeToken:
summary: Active token response
value:
active: true
scope: orch:operate orch:read
client_id: orch-control
sub: operator-7f12
username: ops.engineer@tenant.example
token_type: Bearer
exp: 1761628800
iat: 1761625200
nbf: 1761625200
iss: https://authority.stellaops.local
aud:
- https://orch.stellaops.local
jti: 01J8KYRAMG7FWBPRRV5XG20T7S
tenant: tenant-alpha
confirmation:
mtls_thumbprint: 079871b8c9a0f2e6
inactiveToken:
summary: Revoked token response
value:
active: false
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthErrorResponse'
examples:
missingToken:
summary: Token missing
value:
error: invalid_request
error_description: token parameter is required.
'401':
description: Client authentication failed or client lacks introspection permission.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthErrorResponse'
examples:
unauthorizedClient:
summary: Client not allowed to introspect tokens
value:
error: invalid_client
error_description: Client authentication failed.
/jwks:
get:
tags:
- Keys
summary: Retrieve signing keys
description: Returns the JSON Web Key Set used to validate Authority-issued tokens.
responses:
'200':
description: JWKS document.
headers:
Cache-Control:
schema:
type: string
description: Standard caching headers apply; keys rotate infrequently.
content:
application/json:
schema:
$ref: '#/components/schemas/JwksDocument'
examples:
ecKeySet:
summary: EC signing keys
value:
keys:
- kid: auth-tokens-es384-202510
kty: EC
use: sig
alg: ES384
crv: P-384
x: 7UchU5R77LtChrJx6uWg9mYjFvV6RIpSgZPDIj7d1q0
y: v98nHe8a7mGZ9Fn1t4Jp9PTJv1ma35QPmhUrE4pH7H0
status: active
- kid: auth-tokens-es384-202409
kty: EC
use: sig
alg: ES384
crv: P-384
x: hjdKc0r8jvVHJ7S9mP0y0mU9bqN7v5PxS21SwclTzfc
y: yk6J3pz4TUpymN4mG-6th3dYvJ5N1lQvDK0PLuFv3Pg
status: retiring

10
src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsClaimTypes.cs
View File

@@ -55,6 +55,16 @@ public static class StellaOpsClaimTypes
/// </summary>
public const string IdentityProvider = "stellaops:idp";
/// <summary>
/// Operator reason supplied when issuing orchestrator control tokens.
/// </summary>
public const string OperatorReason = "stellaops:operator_reason";
/// <summary>
/// Operator ticket supplied when issuing orchestrator control tokens.
/// </summary>
public const string OperatorTicket = "stellaops:operator_ticket";
/// <summary>
/// Session identifier claim (<c>sid</c>).
/// </summary>

8
src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.completed.md Normal file
View File

@@ -0,0 +1,8 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| PLG6.DOC | DONE (2025-10-11) | BE-Auth Plugin, Docs Guild | PLG1–PLG5 | Final polish + diagrams for plugin developer guide (AUTHPLUG-DOCS-01-001). | Docs team delivers copy-edit + exported diagrams; PR merged. |
| SEC1.PLG | DONE (2025-10-11) | Security Guild, BE-Auth Plugin | SEC1.A (StellaOps.Cryptography) | Swap Standard plugin hashing to Argon2id via `StellaOps.Cryptography` abstractions; keep PBKDF2 verification for legacy. | ✅ `StandardUserCredentialStore` uses `ICryptoProvider` to hash/check; ✅ Transparent rehash on success; ✅ Unit tests cover tamper + legacy rehash. |
| SEC1.OPT | DONE (2025-10-11) | Security Guild | SEC1.PLG | Expose password hashing knobs in `StandardPluginOptions` (`memoryKiB`, `iterations`, `parallelism`, `algorithm`) with validation. | ✅ Options bound from YAML; ✅ Invalid configs throw; ✅ Docs include tuning guidance. |
| SEC4.PLG | DONE (2025-10-12) | Security Guild | SEC4.A (revocation schema) | Provide plugin hooks so revoked users/clients write reasons for revocation bundle export. | ✅ Revocation exporter consumes plugin data; ✅ Tests cover revoked user/client output. |

4
src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md
View File

@@ -2,12 +2,8 @@
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| PLG6.DOC | DONE (2025-10-11) | BE-Auth Plugin, Docs Guild | PLG1–PLG5 | Final polish + diagrams for plugin developer guide (AUTHPLUG-DOCS-01-001). | Docs team delivers copy-edit + exported diagrams; PR merged. |
| SEC1.PLG | DONE (2025-10-11) | Security Guild, BE-Auth Plugin | SEC1.A (StellaOps.Cryptography) | Swap Standard plugin hashing to Argon2id via `StellaOps.Cryptography` abstractions; keep PBKDF2 verification for legacy. | ✅ `StandardUserCredentialStore` uses `ICryptoProvider` to hash/check; ✅ Transparent rehash on success; ✅ Unit tests cover tamper + legacy rehash. |
| SEC1.OPT | DONE (2025-10-11) | Security Guild | SEC1.PLG | Expose password hashing knobs in `StandardPluginOptions` (`memoryKiB`, `iterations`, `parallelism`, `algorithm`) with validation. | ✅ Options bound from YAML; ✅ Invalid configs throw; ✅ Docs include tuning guidance. |
| SEC2.PLG | BLOCKED (2025-10-21) | Security Guild, Storage Guild | SEC2.A (audit contract) | Emit audit events from password verification outcomes and persist via `IAuthorityLoginAttemptStore`. <br>⛔ Waiting on AUTH-DPOP-11-001 / AUTH-MTLS-11-002 / PLUGIN-DI-08-001 to stabilise Authority auth surfaces before final verification + publish. | ✅ Serilog events enriched with subject/client/IP/outcome; ✅ Mongo records written per attempt; ✅ Tests assert success/lockout/failure cases. |
| SEC3.PLG | BLOCKED (2025-10-21) | Security Guild, BE-Auth Plugin | CORE8, SEC3.A (rate limiter) | Ensure lockout responses and rate-limit metadata flow through plugin logs/events (include retry-after). <br>⛔ Pending AUTH-DPOP-11-001 / AUTH-MTLS-11-002 / PLUGIN-DI-08-001 so limiter telemetry contract matches final authority surface. | ✅ Audit record includes retry-after; ✅ Tests confirm lockout + limiter interplay. |
| SEC4.PLG | DONE (2025-10-12) | Security Guild | SEC4.A (revocation schema) | Provide plugin hooks so revoked users/clients write reasons for revocation bundle export. | ✅ Revocation exporter consumes plugin data; ✅ Tests cover revoked user/client output. |
| SEC5.PLG | BLOCKED (2025-10-21) | Security Guild | SEC5.A (threat model) | Address plugin-specific mitigations (bootstrap user handling, password policy docs) in threat model backlog. <br>⛔ Final documentation depends on AUTH-DPOP-11-001 / AUTH-MTLS-11-002 / PLUGIN-DI-08-001 outcomes. | ✅ Threat model lists plugin attack surfaces; ✅ Mitigation items filed. |
| PLG4-6.CAPABILITIES | BLOCKED (2025-10-12) | BE-Auth Plugin, Docs Guild | PLG1–PLG3 | Finalise capability metadata exposure, config validation, and developer guide updates; remaining action is Docs polish/diagram export. | ✅ Capability metadata + validation merged; ✅ Plugin guide updated with final copy & diagrams; ✅ Release notes mention new toggles. <br>⛔ Blocked awaiting Authority rate-limiter stream (CORE8/SEC3) to resume so doc updates reflect final limiter behaviour. |
| PLG7.RFC | REVIEW | BE-Auth Plugin, Security Guild | PLG4 | Socialize LDAP plugin RFC (`docs/rfcs/authority-plugin-ldap.md`) and capture guild feedback. | ✅ Guild review sign-off recorded; ✅ Follow-up issues filed in module boards. |

7
src/Authority/StellaOps.Authority/StellaOps.Authority.Tests/OpenIddict/ClientCredentialsAndTokenHandlersTests.cs
View File

@@ -597,6 +597,13 @@ public class ClientCredentialsHandlersTests
Assert.Equal("resume source after maintenance", reason);
var ticket = Assert.IsType<string>(context.Transaction.Properties[AuthorityOpenIddictConstants.OperatorTicketProperty]);
Assert.Equal("INC-2045", ticket);
var principal = Assert.NotNull(context.Principal);
Assert.Equal("resume source after maintenance", principal.FindFirstValue(StellaOpsClaimTypes.OperatorReason));
Assert.Equal("INC-2045", principal.FindFirstValue(StellaOpsClaimTypes.OperatorTicket));
var scopeClaim = principal.FindFirstValue(StellaOpsClaimTypes.Scope);
Assert.Contains("orch:operate", scopeClaim.Split(' ', StringSplitOptions.RemoveEmptyEntries));
var scopeItems = principal.FindAll(StellaOpsClaimTypes.ScopeItem).Select(claim => claim.Value).ToArray();
Assert.Contains("orch:operate", scopeItems);
}
[Fact]

251
src/Authority/StellaOps.Authority/StellaOps.Authority.Tests/Signing/AuthorityJwksServiceTests.cs Normal file
View File

@@ -0,0 +1,251 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Caching.Memory;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.Time.Testing;
using Microsoft.IdentityModel.Tokens;
using StellaOps.Authority.Signing;
using StellaOps.Configuration;
using StellaOps.Cryptography;
using Xunit;
namespace StellaOps.Authority.Tests.Signing;
public sealed class AuthorityJwksServiceTests
{
[Fact]
public void Get_ReusesCachedResponse_UntilLifetimeExpires()
{
var options = CreateAuthorityOptions();
options.Signing.JwksCacheLifetime = TimeSpan.FromSeconds(10);
var provider = new TestCryptoProvider();
var registry = new TestRegistry(provider);
using var cache = new MemoryCache(new MemoryCacheOptions());
var clock = new FakeTimeProvider(DateTimeOffset.Parse("2025-10-30T12:00:00Z"));
var service = new AuthorityJwksService(
registry,
NullLogger<AuthorityJwksService>.Instance,
cache,
clock,
Options.Create(options));
var first = service.Get();
Assert.Single(first.Response.Keys);
Assert.Equal(1, provider.EnumerationCount);
var second = service.Get();
Assert.Single(second.Response.Keys);
Assert.Equal(first.ETag, second.ETag);
Assert.Equal(1, provider.EnumerationCount);
clock.Advance(TimeSpan.FromSeconds(11));
var third = service.Get();
Assert.Single(third.Response.Keys);
Assert.NotEqual(first.ETag, third.ETag);
Assert.Equal(2, provider.EnumerationCount);
}
[Fact]
public void Invalidate_ForcesRebuildOnNextRequest()
{
var options = CreateAuthorityOptions();
options.Signing.JwksCacheLifetime = TimeSpan.FromMinutes(5);
var provider = new TestCryptoProvider();
var registry = new TestRegistry(provider);
using var cache = new MemoryCache(new MemoryCacheOptions());
var clock = new FakeTimeProvider(DateTimeOffset.Parse("2025-10-30T12:00:00Z"));
var service = new AuthorityJwksService(
registry,
NullLogger<AuthorityJwksService>.Instance,
cache,
clock,
Options.Create(options));
var first = service.Get();
Assert.Equal(1, provider.EnumerationCount);
service.Invalidate();
provider.AddKey("key-2");
var second = service.Get();
Assert.Equal(2, provider.EnumerationCount);
Assert.Equal(2, second.Response.Keys.Count);
Assert.Contains(second.Response.Keys, key => key.Kid == "key-2");
}
private static StellaOpsAuthorityOptions CreateAuthorityOptions()
{
return new StellaOpsAuthorityOptions
{
Issuer = new Uri("https://authority.test"),
Storage =
{
ConnectionString = "mongodb://localhost/test"
},
Signing =
{
Enabled = true,
ActiveKeyId = "key-1",
KeyPath = "key-1.pem",
Algorithm = SignatureAlgorithms.Es256,
KeySource = "file",
Provider = "test"
}
};
}
private sealed class TestRegistry : ICryptoProviderRegistry
{
private readonly IReadOnlyCollection<ICryptoProvider> providers;
public TestRegistry(ICryptoProvider provider)
{
providers = new[] { provider };
}
public IReadOnlyCollection<ICryptoProvider> Providers => providers;
public bool TryResolve(string preferredProvider, out ICryptoProvider provider)
{
provider = providers.First();
return true;
}
public ICryptoProvider ResolveOrThrow(CryptoCapability capability, string algorithmId)
=> providers.First();
public CryptoSignerResolution ResolveSigner(
CryptoCapability capability,
string algorithmId,
CryptoKeyReference keyReference,
string? preferredProvider = null)
{
var provider = providers.First();
return new CryptoSignerResolution(provider.GetSigner(algorithmId, keyReference), provider.Name);
}
}
private sealed class TestCryptoProvider : ICryptoProvider
{
private readonly Dictionary<string, TestKey> keys = new(StringComparer.OrdinalIgnoreCase);
private int counter;
public TestCryptoProvider()
{
AddKey("key-1");
}
public string Name => "test";
public int EnumerationCount => counter;
public bool Supports(CryptoCapability capability, string algorithmId) => true;
public IPasswordHasher GetPasswordHasher(string algorithmId) => throw new NotSupportedException();
public ICryptoSigner GetSigner(string algorithmId, CryptoKeyReference keyReference)
{
if (!keys.TryGetValue(keyReference.KeyId, out var key))
{
throw new InvalidOperationException($"Unknown key {keyReference.KeyId}.");
}
return new TestSigner(keyReference.KeyId, algorithmId, key.Parameters);
}
public void UpsertSigningKey(CryptoSigningKey signingKey)
{
keys[signingKey.Reference.KeyId] = new TestKey(signingKey.Reference.KeyId, signingKey.PublicParameters);
}
public bool RemoveSigningKey(string keyId) => keys.Remove(keyId);
public IReadOnlyCollection<CryptoSigningKey> GetSigningKeys()
{
counter++;
return keys.Values
.Select(static key => key.ToSigningKey())
.ToArray();
}
public void AddKey(string keyId)
{
using var ecdsa = ECDsa.Create(ECCurve.NamedCurves.nistP256);
var parameters = ecdsa.ExportParameters(true);
keys[keyId] = new TestKey(keyId, parameters);
}
private sealed class TestKey
{
public TestKey(string keyId, ECParameters parameters)
{
KeyId = keyId;
Parameters = parameters;
}
public string KeyId { get; }
public ECParameters Parameters { get; }
public CryptoSigningKey ToSigningKey()
{
return new CryptoSigningKey(
new CryptoKeyReference(KeyId, "test"),
SignatureAlgorithms.Es256,
in Parameters,
DateTimeOffset.UtcNow,
metadata: new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase)
{
["status"] = AuthoritySigningKeyStatus.Active
});
}
}
}
private sealed class TestSigner : ICryptoSigner
{
private readonly ECParameters parameters;
public TestSigner(string keyId, string algorithmId, ECParameters parameters)
{
KeyId = keyId;
AlgorithmId = algorithmId;
this.parameters = parameters;
}
public string KeyId { get; }
public string AlgorithmId { get; }
public ValueTask<byte[]> SignAsync(ReadOnlyMemory<byte> data, CancellationToken cancellationToken = default)
=> ValueTask.FromResult(Array.Empty<byte>());
public ValueTask<bool> VerifyAsync(ReadOnlyMemory<byte> data, ReadOnlyMemory<byte> signature, CancellationToken cancellationToken = default)
=> ValueTask.FromResult(false);
public JsonWebKey ExportPublicJsonWebKey()
{
var x = parameters.Q.X is null ? Array.Empty<byte>() : parameters.Q.X;
var y = parameters.Q.Y is null ? Array.Empty<byte>() : parameters.Q.Y;
return new JsonWebKey
{
Kid = KeyId,
Alg = AlgorithmId,
Kty = JsonWebAlgorithmsKeyTypes.EllipticCurve,
Use = JsonWebKeyUseNames.Sig,
Crv = JsonWebKeyECTypes.P256,
X = Base64UrlEncoder.Encode(x),
Y = Base64UrlEncoder.Encode(y)
};
}
}
}

16
src/Authority/StellaOps.Authority/StellaOps.Authority.Tests/Signing/AuthoritySigningKeyManagerTests.cs
View File

@@ -48,8 +48,8 @@ public sealed class AuthoritySigningKeyManagerTests
var manager = provider.GetRequiredService<AuthoritySigningKeyManager>();
var jwksService = provider.GetRequiredService<AuthorityJwksService>();
var initial = jwksService.Build();
var initialKey = Assert.Single(initial.Keys);
var initial = jwksService.Get();
var initialKey = Assert.Single(initial.Response.Keys);
Assert.Equal("key-1", initialKey.Kid);
Assert.Equal(AuthoritySigningKeyStatus.Active, initialKey.Status);
@@ -71,13 +71,13 @@ public sealed class AuthoritySigningKeyManagerTests
Assert.Equal(key1Relative, additional.Path);
Assert.Equal("file", additional.Source);
var afterRotation = jwksService.Build();
Assert.Equal(2, afterRotation.Keys.Count);
var afterRotation = jwksService.Get();
Assert.Equal(2, afterRotation.Response.Keys.Count);
var activeEntry = Assert.Single(afterRotation.Keys, key => key.Status == AuthoritySigningKeyStatus.Active);
var activeEntry = Assert.Single(afterRotation.Response.Keys, key => key.Status == AuthoritySigningKeyStatus.Active);
Assert.Equal("key-2", activeEntry.Kid);
var retiredEntry = Assert.Single(afterRotation.Keys, key => key.Status == AuthoritySigningKeyStatus.Retired);
var retiredEntry = Assert.Single(afterRotation.Response.Keys, key => key.Status == AuthoritySigningKeyStatus.Retired);
Assert.Equal("key-1", retiredEntry.Kid);
}
finally
@@ -100,10 +100,12 @@ public sealed class AuthoritySigningKeyManagerTests
services.AddSingleton<IHostEnvironment>(new TestHostEnvironment(basePath));
services.AddSingleton(options);
services.AddSingleton<IOptions<StellaOpsAuthorityOptions>>(Options.Create(options));
services.AddSingleton(TimeProvider.System);
services.AddMemoryCache();
services.AddStellaOpsCrypto();
services.TryAddEnumerable(ServiceDescriptor.Singleton<IAuthoritySigningKeySource, FileAuthoritySigningKeySource>());
services.AddSingleton<AuthoritySigningKeyManager>();
services.AddSingleton<AuthorityJwksService>();
services.AddSingleton<AuthoritySigningKeyManager>();
return services.BuildServiceProvider();
}

14
src/Authority/StellaOps.Authority/StellaOps.Authority/OpenIddict/Handlers/ClientCredentialsHandlers.cs
View File

@@ -903,6 +903,20 @@ internal sealed class HandleClientCredentialsHandler : IOpenIddictServerHandler<
metadataAccessor.SetProject(project);
activity?.SetTag("authority.project", project);
if (context.Transaction.Properties.TryGetValue(AuthorityOpenIddictConstants.OperatorReasonProperty, out var operatorReasonValue) &&
operatorReasonValue is string operatorReasonValueString &&
!string.IsNullOrWhiteSpace(operatorReasonValueString))
{
identity.SetClaim(StellaOpsClaimTypes.OperatorReason, operatorReasonValueString);
}
if (context.Transaction.Properties.TryGetValue(AuthorityOpenIddictConstants.OperatorTicketProperty, out var operatorTicketValue) &&
operatorTicketValue is string operatorTicketValueString &&
!string.IsNullOrWhiteSpace(operatorTicketValueString))
{
identity.SetClaim(StellaOpsClaimTypes.OperatorTicket, operatorTicketValueString);
}
var (providerHandle, descriptor) = await ResolveProviderAsync(context, document).ConfigureAwait(false);
if (context.IsRejected)
{

22
src/Authority/StellaOps.Authority/StellaOps.Authority/Program.cs
View File

@@ -13,6 +13,7 @@ using Microsoft.Extensions.Options;
using Microsoft.AspNetCore.RateLimiting;
using Microsoft.AspNetCore.Server.Kestrel.Https;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Net.Http.Headers;
using OpenIddict.Abstractions;
using OpenIddict.Server;
using OpenIddict.Server.AspNetCore;
@@ -115,6 +116,7 @@ builder.Services.AddSingleton(authorityOptions);
builder.Services.AddSingleton<IOptions<StellaOpsAuthorityOptions>>(Options.Create(authorityOptions));
builder.Services.AddHttpContextAccessor();
builder.Services.TryAddSingleton<TimeProvider>(_ => TimeProvider.System);
builder.Services.AddMemoryCache();
builder.Services.TryAddSingleton<IAuthorityRateLimiterMetadataAccessor, AuthorityRateLimiterMetadataAccessor>();
builder.Services.TryAddSingleton<IAuthorityRateLimiterPartitionKeyResolver, DefaultAuthorityRateLimiterPartitionKeyResolver>();
builder.Services.AddSingleton<IAuthorityClientCertificateValidator, AuthorityClientCertificateValidator>();
@@ -1293,7 +1295,25 @@ app.MapPost("/permalinks/vuln", async (
.RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.VulnRead))
.WithName("CreateVulnPermalink");
app.MapGet("/jwks", (AuthorityJwksService jwksService) => Results.Ok(jwksService.Build()))
app.MapGet("/jwks", (AuthorityJwksService jwksService, HttpContext context) =>
{
var result = jwksService.Get();
if (context.Request.Headers.TryGetValue(HeaderNames.IfNoneMatch, out var etagValues) &&
etagValues.Contains(result.ETag, StringComparer.Ordinal))
{
context.Response.Headers.CacheControl = result.CacheControl;
context.Response.Headers.ETag = result.ETag;
context.Response.Headers.Expires = result.ExpiresAt.ToString("R", CultureInfo.InvariantCulture);
return Results.StatusCode(StatusCodes.Status304NotModified);
}
context.Response.Headers.CacheControl = result.CacheControl;
context.Response.Headers.ETag = result.ETag;
context.Response.Headers.Expires = result.ExpiresAt.ToString("R", CultureInfo.InvariantCulture);
return Results.Json(result.Response);
})
.WithName("JsonWebKeySet");
// Ensure signing key manager initialises key material on startup.

78
src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/AuthorityJwksService.cs
View File

@@ -1,23 +1,81 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.Caching.Memory;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using StellaOps.Configuration;
using StellaOps.Cryptography;
namespace StellaOps.Authority.Signing;
internal sealed class AuthorityJwksService
{
private const string CacheKey = "authority:jwks:current";
private static readonly JsonSerializerOptions SerializerOptions = new(JsonSerializerDefaults.Web)
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
private readonly ICryptoProviderRegistry registry;
private readonly ILogger<AuthorityJwksService> logger;
private readonly IMemoryCache cache;
private readonly TimeProvider timeProvider;
private readonly StellaOpsAuthorityOptions authorityOptions;
public AuthorityJwksService(ICryptoProviderRegistry registry, ILogger<AuthorityJwksService> logger)
public AuthorityJwksService(
ICryptoProviderRegistry registry,
ILogger<AuthorityJwksService> logger,
IMemoryCache cache,
TimeProvider timeProvider,
IOptions<StellaOpsAuthorityOptions> authorityOptions)
{
this.registry = registry ?? throw new ArgumentNullException(nameof(registry));
this.logger = logger ?? throw new ArgumentNullException(nameof(logger));
this.cache = cache ?? throw new ArgumentNullException(nameof(cache));
this.timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
if (authorityOptions is null)
{
throw new ArgumentNullException(nameof(authorityOptions));
}
this.authorityOptions = authorityOptions.Value ?? throw new ArgumentNullException(nameof(authorityOptions));
}
public AuthorityJwksResponse Build() => new(BuildKeys());
public AuthorityJwksResult Get()
{
if (cache.TryGetValue(CacheKey, out AuthorityJwksCacheEntry? cached) &&
cached is not null &&
cached.ExpiresAt > timeProvider.GetUtcNow())
{
return cached.Result;
}
var response = new AuthorityJwksResponse(BuildKeys());
var etag = ComputeEtag(response);
var signingOptions = authorityOptions.Signing;
var lifetime = signingOptions.JwksCacheLifetime > TimeSpan.Zero
? signingOptions.JwksCacheLifetime
: TimeSpan.FromMinutes(5);
var expires = timeProvider.GetUtcNow().Add(lifetime);
var cacheControl = $"public, max-age={(int)lifetime.TotalSeconds}";
var result = new AuthorityJwksResult(response, etag, expires, cacheControl);
var entry = new AuthorityJwksCacheEntry(result, expires);
cache.Set(CacheKey, entry, expires);
return result;
}
public void Invalidate()
{
cache.Remove(CacheKey);
}
private IReadOnlyCollection<JwksKeyEntry> BuildKeys()
{
@@ -58,12 +116,28 @@ internal sealed class AuthorityJwksService
}
}
keys.Sort(static (left, right) => string.Compare(left.Kid, right.Kid, StringComparison.Ordinal));
return keys;
}
private static string ComputeEtag(AuthorityJwksResponse response)
{
var payload = JsonSerializer.Serialize(response, SerializerOptions);
var hash = SHA256.HashData(Encoding.UTF8.GetBytes(payload));
return $"\"{Convert.ToHexString(hash)}\"";
}
private sealed record AuthorityJwksCacheEntry(AuthorityJwksResult Result, DateTimeOffset ExpiresAt);
}
internal sealed record AuthorityJwksResponse([property: JsonPropertyName("keys")] IReadOnlyCollection<JwksKeyEntry> Keys);
internal sealed record AuthorityJwksResult(
AuthorityJwksResponse Response,
string ETag,
DateTimeOffset ExpiresAt,
string CacheControl);
internal sealed class JwksKeyEntry
{
[JsonPropertyName("kty")]

8
src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/AuthoritySigningKeyManager.cs
View File

@@ -19,13 +19,15 @@ internal sealed class AuthoritySigningKeyManager
private readonly ILogger<AuthoritySigningKeyManager> logger;
private RegisteredSigningKey? activeKey;
private readonly Dictionary<string, RegisteredSigningKey> retiredKeys = new(StringComparer.OrdinalIgnoreCase);
private readonly AuthorityJwksService jwksService;
public AuthoritySigningKeyManager(
ICryptoProviderRegistry registry,
IEnumerable<IAuthoritySigningKeySource> keySources,
IOptions<StellaOpsAuthorityOptions> authorityOptions,
IHostEnvironment environment,
ILogger<AuthoritySigningKeyManager> logger)
ILogger<AuthoritySigningKeyManager> logger,
AuthorityJwksService jwksService)
{
this.registry = registry ?? throw new ArgumentNullException(nameof(registry));
if (keySources is null)
@@ -42,6 +44,7 @@ internal sealed class AuthoritySigningKeyManager
this.authorityOptions = authorityOptions?.Value ?? throw new ArgumentNullException(nameof(authorityOptions));
basePath = environment?.ContentRootPath ?? throw new ArgumentNullException(nameof(environment));
this.logger = logger ?? throw new ArgumentNullException(nameof(logger));
this.jwksService = jwksService ?? throw new ArgumentNullException(nameof(jwksService));
LoadInitialKeys();
}
@@ -122,6 +125,7 @@ internal sealed class AuthoritySigningKeyManager
RemoveAdditionalOption(keyId);
logger.LogInformation("Authority signing key rotated. Active key is now {KeyId} via provider {Provider}.", keyId, provider.Name);
jwksService.Invalidate();
return new SigningRotationResult(
keyId,
@@ -221,6 +225,8 @@ internal sealed class AuthoritySigningKeyManager
logger.LogWarning(ex, "Failed to load retired signing key {KeyId}. It will be ignored for JWKS responses.", keyId);
}
}
jwksService.Invalidate();
}
private void RetireCurrentActive()

31
src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/KmsAuthoritySigningKeySource.cs
View File

@@ -1,3 +1,4 @@
using System;
using System.Collections.Generic;
using StellaOps.Cryptography;
using StellaOps.Cryptography.Kms;
@@ -29,19 +30,18 @@ internal sealed class KmsAuthoritySigningKeySource : IAuthoritySigningKeySource
throw new InvalidOperationException("KMS signing keys require signing.keyPath/location to specify the key identifier.");
}
request.AdditionalMetadata?.TryGetValue(KmsMetadataKeys.Version, out var versionId);
string? versionId = null;
if (request.AdditionalMetadata is not null &&
request.AdditionalMetadata.TryGetValue(KmsMetadataKeys.Version, out var metadataVersion))
{
versionId = metadataVersion;
}
var material = _kmsClient.ExportAsync(keyId, versionId).GetAwaiter().GetResult();
var parameters = new ECParameters
{
Curve = ECCurve.NamedCurves.nistP256,
D = material.D.ToArray(),
Q = new ECPoint
{
X = material.Qx.ToArray(),
Y = material.Qy.ToArray(),
},
};
var publicKey = new byte[material.Qx.Length + material.Qy.Length];
Buffer.BlockCopy(material.Qx, 0, publicKey, 0, material.Qx.Length);
Buffer.BlockCopy(material.Qy, 0, publicKey, material.Qx.Length, material.Qy.Length);
var metadata = new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase)
{
@@ -49,7 +49,14 @@ internal sealed class KmsAuthoritySigningKeySource : IAuthoritySigningKeySource
};
var reference = new CryptoKeyReference(request.KeyId, request.Provider);
return new CryptoSigningKey(reference, material.Algorithm, in parameters, material.CreatedAt, request.ExpiresAt, metadata: metadata);
return new CryptoSigningKey(
reference,
material.Algorithm,
material.D,
material.CreatedAt,
request.ExpiresAt,
publicKey,
metadata: metadata);
}
internal static class KmsMetadataKeys

33
src/Authority/StellaOps.Authority/TASKS.completed.md Normal file
View File

@@ -0,0 +1,33 @@
# Completed Tasks
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|----|--------|----------|------------|-------------|---------------|
| AUTH-AOC-19-001 | DONE (2025-10-26) | Authority Core & Security Guild | — | Introduce scopes `advisory:read`, `advisory:ingest`, `vex:read`, `vex:ingest`, `aoc:verify` with configuration binding, migrations, and offline kit defaults. | Scopes published in metadata/OpenAPI, configuration validates scope lists, tests cover token issuance + enforcement. |
| AUTH-AOC-19-002 | DONE (2025-10-27) | Authority Core & Security Guild | AUTH-AOC-19-001 | Propagate tenant claim + scope enforcement for ingestion identities; ensure cross-tenant writes/read blocked and audit logs capture tenant context. | Tenant claim injected into downstream services; forbidden cross-tenant access rejected; audit/log fixtures updated. |
| AUTH-AOC-22-001 | DONE (2025-10-29) | Authority Core Guild | AUTH-AOC-19-001 | Roll out new advisory/vex ingest/read scopes. | Legacy scopes rejected; metadata/docs/configs updated; integration tests cover advisory/vex scope enforcement for Link-Not-Merge APIs. |
| AUTH-POLICY-20-001 | DONE (2025-10-26) | Authority Core & Security Guild | AUTH-AOC-19-001 | Add scopes `policy:write`, `policy:submit`, `policy:approve`, `policy:run`, `findings:read`, `effective:write` with configuration binding and issuer policy updates. | Scopes available in metadata; token issuance validated; offline kit defaults updated; tests cover scope combinations. |
| AUTH-POLICY-20-002 | DONE (2025-10-26) | Authority Core & Security Guild | AUTH-POLICY-20-001, AUTH-AOC-19-002 | Enforce Policy Engine service identity with `effective:write` and ensure API gateway enforces scopes/tenant claims for new endpoints. | Gateway policies updated; unauthorized requests rejected in tests; audit logs capture scope usage. |
| AUTH-GRAPH-21-001 | DONE (2025-10-26) | Authority Core & Security Guild | AUTH-POLICY-20-001 | Define scopes `graph:write`, `graph:read`, `graph:export`, `graph:simulate`, update metadata/OpenAPI, and add OFFLINE kit defaults. | Scopes exposed via discovery docs; smoke tests ensure enforcement; offline kit updated. |
| AUTH-GRAPH-21-002 | DONE (2025-10-26) | Authority Core & Security Guild | AUTH-GRAPH-21-001, AUTH-AOC-19-002 | Wire gateway enforcement for new graph scopes, Cartographer service identity, and tenant propagation across graph APIs. | Gateway config updated; unauthorized access blocked in integration tests; audit logs include graph scope usage. |
| AUTH-GRAPH-21-003 | DONE (2025-10-26) | Authority Core & Docs Guild | AUTH-GRAPH-21-001 | Update security docs and samples describing graph access roles, least privilege guidance, and service identities. | Docs merged with compliance checklist; examples refreshed; release notes prepared. |
| AUTH-POLICY-23-001 | DONE (2025-10-29) | Authority Core & Security Guild | AUTH-POLICY-20-001 | Introduce fine-grained scopes `policy:read`, `policy:edit`, `policy:approve`, `policy:activate`, `policy:simulate`; update issuer templates and metadata. | Scopes exposed; integration tests confirm enforcement; offline kit updated. |
| AUTH-VULN-24-001 | DONE (2025-10-29) | Authority Core & Security Guild | AUTH-GRAPH-21-001 | Extend scopes to include `vuln:read` and signed permalinks with scoped claims for Vuln Explorer; update metadata. | Scopes published; permalinks validated; integration tests cover RBAC. |
| AUTH-ORCH-32-001 | DONE (2025-10-31) | Authority Core & Security Guild | — | Define `orch:read` scope, register `Orch.Viewer` role, update discovery metadata, and seed offline defaults. | Scope/role available in metadata; integration tests confirm read-only enforcement; offline kit updated. |
| AUTH-CONSOLE-23-001 | DONE (2025-10-29) | Authority Core & Security Guild | AUTH-POLICY-20-001 | Register StellaOps Console confidential client with OIDC PKCE support, short-lived ID/access tokens, `console:*` audience claims, and SPA-friendly refresh (token exchange endpoint). Publish discovery metadata + offline kit defaults. | Client registration committed; configuration templates updated; integration tests validate PKCE + scope issuance; security review recorded. |
| AUTH-POLICY-27-001 | DONE (2025-10-31) | Authority Core & Security Guild | AUTH-POLICY-20-001, AUTH-CONSOLE-23-001 | Define Policy Studio roles (`policy:author`, `policy:review`, `policy:approve`, `policy:operate`, `policy:audit`) with tenant-scoped claims, update issuer metadata, and seed offline kit defaults. | Scopes/roles exposed via discovery docs; tokens issued with correct claims; integration tests cover role combinations; docs updated. |
| AUTH-EXC-25-001 | DONE (2025-10-29) | Authority Core & Security Guild | AUTH-POLICY-23-001 | Introduce exception scopes (`exceptions:read`, `exceptions:write`, `exceptions:approve`) and approval routing configuration with MFA gating. | Scopes published in metadata; routing matrix validated; integration tests enforce scope + MFA rules. |
| AUTH-SIG-26-001 | DONE (2025-10-29) | Authority Core & Security Guild | AUTH-EXC-25-001 | Add `signals:read`, `signals:write`, `signals:admin` scopes, issue `SignalsUploader` role template, and enforce AOC for sensor identities. | Scopes exposed; configuration validated; integration tests ensure RBAC + AOC enforcement. |
| AUTH-EXPORT-35-001 | DONE (2025-10-28) | Authority Core & Security Guild | AUTH-AOC-19-001 | Introduce `Export.Viewer`, `Export.Operator`, `Export.Admin` scopes, configure issuer templates, and update discovery metadata/offline defaults. | Scopes available; metadata updated; tests ensure enforcement; offline kit defaults refreshed. |
| AUTH-EXPORT-37-001 | DONE (2025-10-28) | Authority Core & Security Guild | AUTH-EXPORT-35-001, WEB-EXPORT-37-001 | Enforce admin-only access for scheduling, retention, encryption key references, and verify endpoints with audit reason capture. | Admin scope required; audit logs include reason/ticket; integration tests cover denial cases; docs updated. |
| AUTH-TEN-47-001 | DONE (2025-10-30) | Authority Core & Security Guild | AUTH-AOC-19-001 | Align Authority with OIDC/JWT claims (tenants, projects, scopes), implement JWKS caching/rotation, publish scope grammar, and enforce required claims on tokens. | Tokens include tenant/project claims; JWKS cache validated; docs updated; imposed rule noted.<br>2025-10-30: Introduced in-memory JWKS cache with configurable `signing.jwksCacheLifetime`, emitted cache-control/ETag headers on `/jwks`, invalidated cache on rotations, and expanded docs to detail scope grammar + claim catalogue. |
| AUTH-OAS-61-001 | DONE (2025-10-28) | Authority Core & Security Guild, API Contracts Guild | OAS-61-001 | Document Authority authentication/token endpoints in OAS with scopes, examples, and error envelopes. | Spec complete with security schemes; lint passes. |
| AUTH-AOC-19-003 | DONE (2025-10-27) | Authority Core & Docs Guild | AUTH-AOC-19-001 | Update Authority docs and sample configs to describe new scopes, tenancy enforcement, and verify endpoints. | Docs and examples refreshed; release notes prepared; smoke tests confirm new scopes required. |
| AUTH-AOC-19-004 | DONE (2025-10-31) | Authority Core & Security Guild | AUTH-AOC-19-002 | Enforce AOC scope pairings: require `aoc:verify` alongside advisory/vex read scopes and for any `signals:*` requests; emit deterministic errors and telemetry. | Client/token issuance rejects missing pairings with structured errors; logs/metrics capture violations; tests and docs updated. |
| AUTH-POLICY-20-003 | DONE (2025-10-26) | Authority Core & Docs Guild | AUTH-POLICY-20-001 | Update Authority configuration/docs with policy scopes, service identities, and approval workflows; include compliance checklist. | Docs refreshed; samples updated; release notes prepared; doc lint passes. |
| AUTH-POLICY-23-004 | DONE (2025-10-27) | Authority Core & DevOps Guild | AUTH-POLICY-23-001 | Migrate default Authority client registrations/offline kit templates to the new policy scope set and provide migration guidance for existing tokens. | Updated configs committed (Authority, CLI, CI samples); migration note added to release docs; verification script confirms scopes. |
| AUTH-ORCH-33-001 | DONE (2025-10-30) | Authority Core & Security Guild | AUTH-ORCH-32-001 | Add `Orch.Operator` role/scopes for control actions, require reason/ticket attributes, and update issuer templates. | Operator tokens issued; action endpoints enforce scope + reason; audit logs capture operator info; docs refreshed.<br>2025-10-30: Operator token flow now stamps `stellaops:operator_reason`/`stellaops:operator_ticket` claims, enforces claim presence on issuance, extends audit records, and refreshes config/docs (`authority.yaml`, security guides, CLI prompts). |
| AUTH-CONSOLE-23-002 | DONE (2025-10-31) | Authority Core & Security Guild | AUTH-CONSOLE-23-001, AUTH-AOC-19-002 | Expose tenant catalog, user profile, and token introspection endpoints required by Console (fresh-auth prompts, scope checks); enforce tenant header requirements and audit logging with correlation IDs. | Endpoints ship with RBAC enforcement, audit logs include tenant+scope, integration tests cover unauthorized/tenant-mismatch scenarios. |
| AUTH-CONSOLE-23-003 | DONE (2025-10-31) | Authority Core & Docs Guild | AUTH-CONSOLE-23-001, AUTH-CONSOLE-23-002 | Update security docs/config samples for Console flows (PKCE, tenant badge, fresh-auth for admin actions, session inactivity timeouts) with compliance checklist. | Docs merged, config samples validated, release notes updated, ops runbook references new flows. |
| AUTH-CONSOLE-23-004 | DONE (2025-10-31) | Authority Core & Security Guild | AUTH-CONSOLE-23-003, DOCS-CONSOLE-23-012 | Validate console security guide assumptions (120 s OpTok TTL, 300 s fresh-auth window, scope bundles) against Authority implementation and update configs/audit fixtures if needed. | Confirmation recorded in sprint log; Authority config samples/tests updated when adjustments required; `/fresh-auth` behaviour documented in release notes. |
| AUTH-EXC-25-002 | DONE (2025-10-31) | Authority Core & Docs Guild | AUTH-EXC-25-001 | Update documentation/samples for exception roles, routing matrix, MFA requirements, and audit trail references. | Docs merged with compliance checklist; samples verified. |
| AUTH-OAS-61-002 | DONE (2025-10-28) | Authority Core & Security Guild | AUTH-OAS-61-001 | Implement `/.well-known/openapi` with scope metadata, supported grant types, and build version. | Endpoint deployed; contract tests cover discovery. |

Some files were not shown because too many files have changed in this diff Show More