feat: Document completed tasks for KMS, Cryptography, and Plugin Libraries
- Added detailed task completion records for KMS interface implementation and CLI support for file-based keys. - Documented security enhancements including Argon2id password hashing, audit event contracts, and rate limiting configurations. - Included scoped service support and integration updates for the Plugin platform, ensuring proper DI handling and testing coverage.
This commit is contained in:
master
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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">
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
121
docs/02_WHY.md
@@ -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).*
|
||||
@@ -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.
|
||||
@@ -1,5 +1,7 @@
|
||||
# 4 · Feature Matrix — **Stella Ops**
|
||||
*(rev 2.0 · 14 Jul 2025)*
|
||||
# 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 |
|
||||
| ---------------------- | ------------------------------------- | ----------------------------- | ----------------- | ------------------- | ------------------------------------------ |
|
||||
|
||||
@@ -11,18 +11,18 @@ 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
|
||||
* [09_API_CLI_REFERENCE.md](09_API_CLI_REFERENCE.md) – REST & CLI surface
|
||||
* [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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# High‑Level Architecture — **Stella Ops** (Consolidated • 2025Q4)
|
||||
# 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.
|
||||
|
||||
@@ -79,10 +79,10 @@ store as `STELLA_JWT` in **`.env`**.
|
||||
| ---------------------- | ---------------------------------------- |
|
||||
| **v0.1 α (late 2025)** | Manual OUK import • Zastava beta |
|
||||
| **v0.3 β (Q2 2026)** | Auto‑apply delta patch • nightly re‑scan |
|
||||
| **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).
|
||||
| **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](05_ROADMAP.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -47,20 +47,20 @@ Approval is recorded via Git forge review or a signed commit trailer
|
||||
|
||||
## 4 · Release authority & provenance 🔏
|
||||
|
||||
* Every tag is **co‑signed by at least one Security Maintainer**.
|
||||
* CI emits a **signed SPDX SBOM** + **Cosign provenance**.
|
||||
* Release cadence is fixed – see [public Road‑map](../roadmap/README.md).
|
||||
* Security fixes may create out‑of‑band `x.y.z‑hotfix` tags.
|
||||
* Every tag is **co‑signed by at least one Security Maintainer**.
|
||||
* CI emits a **signed SPDX SBOM** + **Cosign provenance**.
|
||||
* Release cadence is fixed – see [public Road‑map](05_ROADMAP.md).
|
||||
* Security fixes may create out‑of‑band `x.y.z‑hotfix` tags.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Escalation lanes 🚦
|
||||
|
||||
| Situation | Escalation |
|
||||
|-----------|------------|
|
||||
| Technical deadlock | **Maintainer Summit** (recorded & published) |
|
||||
| Security bug | Follow [Security Policy](../security/01_SECURITY_POLICY.md) |
|
||||
| Code of Conduct violation | See `12_CODE_OF_CONDUCT.md` escalation ladder |
|
||||
| Situation | Escalation |
|
||||
|-----------|------------|
|
||||
| Technical deadlock | **Maintainer Summit** (recorded & published) |
|
||||
| Security bug | Follow [Security Policy](13_SECURITY_POLICY.md) |
|
||||
| Code of Conduct violation | See `12_CODE_OF_CONDUCT.md` escalation ladder |
|
||||
|
||||
---
|
||||
|
||||
@@ -90,4 +90,4 @@ section directly.)*
|
||||
| `@alice` | Core scanner • Security | 2025‑04 |
|
||||
| `@bob` | UI • Docs | 2025‑06 |
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -143,7 +143,7 @@ P99 = 48 ms. Meets 50 ms gate.
|
||||
|
||||
## 8 Trend Snapshot
|
||||
|
||||
|
||||
> _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`.
|
||||
|
||||
|
||||
@@ -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
173
docs/README.md
@@ -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
88
docs/TASKS.completed.md
Normal 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. |
|
||||
|
||||
@@ -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
111
docs/aoc/guard-library.md
Normal 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`.
|
||||
@@ -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`).
|
||||
|
||||
@@ -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
24
docs/devops/contracts-and-rules.md
Normal 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
38
docs/evaluate/checklist.md
Normal 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/`.
|
||||
@@ -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 |
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -45,12 +45,20 @@
|
||||
"digest": "digest-123",
|
||||
"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"
|
||||
},
|
||||
"links": {
|
||||
"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",
|
||||
"payload": "eyJyZXBvcnRJZCI6InJlcG9ydC1hYmMiLCJpbWFnZURpZ2VzdCI6InNoYTI1NjpmZWVkZmFjZSIsImdlbmVyYXRlZEF0IjoiMjAyNS0xMC0xOVQxMjozNDo1NiswMDowMCIsInZlcmRpY3QiOiJibG9ja2VkIiwicG9saWN5Ijp7InJldmlzaW9uSWQiOiJyZXYtNDIiLCJkaWdlc3QiOiJkaWdlc3QtMTIzIn0sInN1bW1hcnkiOnsidG90YWwiOjEsImJsb2NrZWQiOjEsIndhcm5lZCI6MCwiaWdub3JlZCI6MCwicXVpZXRlZCI6MH0sInZlcmRpY3RzIjpbeyJmaW5kaW5nSWQiOiJmaW5kaW5nLTEiLCJzdGF0dXMiOiJCbG9ja2VkIiwic2NvcmUiOjQ3LjUsInNvdXJjZVRydXN0IjoiTlZEIiwicmVhY2hhYmlsaXR5IjoicnVudGltZSJ9XSwiaXNzdWVzIjpbXX0=",
|
||||
|
||||
@@ -51,12 +51,20 @@
|
||||
"reachability": "runtime"
|
||||
}
|
||||
],
|
||||
"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"
|
||||
},
|
||||
"links": {
|
||||
"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",
|
||||
"payload": "eyJyZXBvcnRJZCI6InJlcG9ydC1hYmMiLCJpbWFnZURpZ2VzdCI6InNoYTI1NjpmZWVkZmFjZSIsImdlbmVyYXRlZEF0IjoiMjAyNS0xMC0xOVQxMjozNDo1NiswMDowMCIsInZlcmRpY3QiOiJibG9ja2VkIiwicG9saWN5Ijp7InJldmlzaW9uSWQiOiJyZXYtNDIiLCJkaWdlc3QiOiJkaWdlc3QtMTIzIn0sInN1bW1hcnkiOnsidG90YWwiOjEsImJsb2NrZWQiOjEsIndhcm5lZCI6MCwiaWdub3JlZCI6MCwicXVpZXRlZCI6MH0sInZlcmRpY3RzIjpbeyJmaW5kaW5nSWQiOiJmaW5kaW5nLTEiLCJzdGF0dXMiOiJCbG9ja2VkIiwic2NvcmUiOjQ3LjUsInNvdXJjZVRydXN0IjoiTlZEIiwicmVhY2hhYmlsaXR5IjoicnVudGltZSJ9XSwiaXNzdWVzIjpbXX0=",
|
||||
|
||||
@@ -122,16 +122,15 @@
|
||||
"type": "object",
|
||||
"description": "Policy revision metadata surfaced alongside the report."
|
||||
},
|
||||
"links": {
|
||||
"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"}
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"report": {"$ref": "#/definitions/linkTarget"},
|
||||
"policy": {"$ref": "#/definitions/linkTarget"},
|
||||
"attestation": {"$ref": "#/definitions/linkTarget"}
|
||||
}
|
||||
},
|
||||
"dsse": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
@@ -161,4 +160,14 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
"definitions": {
|
||||
"linkTarget": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"ui": {"type": "string", "format": "uri"},
|
||||
"api": {"type": "string", "format": "uri"}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -132,16 +132,15 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"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"}
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"report": {"$ref": "#/definitions/linkTarget"},
|
||||
"policy": {"$ref": "#/definitions/linkTarget"},
|
||||
"attestation": {"$ref": "#/definitions/linkTarget"}
|
||||
}
|
||||
},
|
||||
"dsse": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
@@ -171,4 +170,14 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
"definitions": {
|
||||
"linkTarget": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"ui": {"type": "string", "format": "uri"},
|
||||
"api": {"type": "string", "format": "uri"}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-03.png` — filter tray with severity/time window applied.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-04.png` — explain drawer evidence tab.
|
||||
|
||||
- `docs/assets/ui/tours/triage-flow.gif` — 20 s screen recording of steps 1–5 with annotations.
|
||||
|
||||
- `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).
|
||||
|
||||
- `docs/assets/ui/tours/audit-step-05.png` — exports tab showing evidence bundle ready.
|
||||
|
||||
- `docs/assets/ui/tours/audit-flow.gif` — 25 s capture from manifest view through export download.
|
||||
|
||||
- `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.
|
||||
|
||||
- `docs/assets/ui/tours/policy-step-04.png` — simulation diff comparing Active vs Staged.
|
||||
|
||||
- `docs/assets/ui/tours/policy-flow.gif` — 30 s clip from draft view through promotion confirmation.
|
||||
|
||||
- `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.
|
||||
|
||||
@@ -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
49
docs/high-level-architecture.md
Normal 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).
|
||||
@@ -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. |
|
||||
|
||||
@@ -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
33
docs/key-features.md
Normal 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.
|
||||
@@ -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. citeturn1open1
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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`).
|
||||
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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
39
docs/overview.md
Normal 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
93
docs/quickstart.md
Normal 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).
|
||||
@@ -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
17
docs/technical/README.md
Normal 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
44
docs/technical/architecture/README.md
Normal 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
77
docs/technical/architecture/component-map.md
Normal 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
33
docs/technical/development/README.md
Normal 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
48
docs/technical/interfaces/README.md
Normal 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
29
docs/technical/observability/README.md
Normal 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
47
docs/technical/operations/README.md
Normal 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
25
docs/technical/process/README.md
Normal 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
35
docs/technical/security/README.md
Normal 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
22
docs/technical/strategy/README.md
Normal 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).
|
||||
@@ -138,10 +138,10 @@ Audit entries appear for every user/token change. CLI parity: `stella auth token
|
||||
|
||||
## 11. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- ``
|
||||
- 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).*
|
||||
|
||||
|
||||
@@ -1,199 +1,198 @@
|
||||
# StellaOps Console - Advisories and VEX
|
||||
|
||||
> **Audience:** Console UX team, Concelier and Excititor guilds, support and compliance engineers.
|
||||
> **Scope:** Advisory aggregation UX, VEX consensus display, conflict indicators, raw document viewer, provenance banners, CLI parity, and Aggregation-Only Contract (AOC) guardrails for Sprint 23.
|
||||
|
||||
The Advisories and VEX surfaces expose Concelier and Excititor outputs without mutating the underlying data. Operators can review upstream statements, check consensus summaries, inspect conflicts, and hand off evidence to downstream tooling while staying within the Aggregation-Only Contract.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Routes:**
|
||||
- `/console/advisories` (advisory list and detail)
|
||||
- `/console/vex` (VEX consensus and raw claim explorer)
|
||||
- **Scopes:** `advisory.read` and `vex.read` (base access), `advisory.verify` / `vex.verify` for verification actions, `downloads.read` for evidence exports.
|
||||
- **Feature flags:** `advisoryExplorer.enabled`, `vexExplorer.enabled`, `aggregation.conflictIndicators`.
|
||||
- **Dependencies:** Concelier WebService (aggregation API + delta metrics), Excititor WebService (consensus API + conflict feeds), Policy Engine explain hints (optional link-outs), Authority tenant enforcement.
|
||||
- **Offline behaviour:** Uses Offline Kit snapshots when gateway is in sealed mode; verify buttons queue until connectivity resumes.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------------+
|
||||
| Header: Tenant badge - global filters - status ticker - actions |
|
||||
+---------------------------------------------------------------------+
|
||||
| Left rail: Saved views - provider filters - verification queue |
|
||||
+---------------------------------------------------------------------+
|
||||
| Main split pane |
|
||||
| - Advisories tab (grid + detail drawer) |
|
||||
| - VEX tab (consensus table + claim drawer) |
|
||||
| Tabs remember last active view per tenant. |
|
||||
+---------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The header reuses console-wide context chips (`Tenant`, `Severity`, `Source`, `Time`) and the status ticker that streams Concelier and Excititor deltas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Advisory aggregation view
|
||||
|
||||
| Element | Description |
|
||||
|---------|-------------|
|
||||
| **Grid columns** | Vulnerability key (CVE/GHSA/vendor), Title, Source set, Last merged, Severity badge, KEV flag, Affected product count, Merge hash. |
|
||||
| **Source chips** | Show contributing providers (NVD, Red Hat, Debian, vendor PSIRT). Hover reveals precedence order and timestamps. |
|
||||
| **Severity** | Displays the highest severity declared by any source; tooltip lists per-source severities and vectors. |
|
||||
| **KEV / Exploit status** | Badge highlights known exploited status from Concelier enrichment; links to KEV reference. |
|
||||
| **Merge hash** | Deterministic hash from Concelier `merge_event`. Clicking copies hash and opens provenance banner. |
|
||||
| **Filters** | Vulnerability identifier search, provider multi-select, severity picker, KEV toggle, affected product range slider, time window. |
|
||||
| **List actions** | `Open detail`, `Copy CLI` (`stella advisory show ...`), `Compare sources`, `Queue verify`. |
|
||||
|
||||
The grid virtualises up to 15,000 advisories per tenant. Beyond that, the UI engages server-side pagination with cursor hints supplied by Concelier.
|
||||
|
||||
---
|
||||
|
||||
## 4. Advisory detail drawer
|
||||
|
||||
Sections within the drawer:
|
||||
|
||||
1. **Summary cards** (title, published/modified timestamps, advisory merge hash, total sources, exploited flag).
|
||||
2. **Sources timeline** listing each contributing document with signature status, fetched timestamps, precedence rank, and quick links to raw view.
|
||||
3. **Affected products** table (product key, introduced/fixed, range semantics, distro qualifiers, notes). Column toggles allow switching between SemVer and distro notation.
|
||||
4. **Conflict indicators** show when sources disagree on fixed versions, severity, or affected sets. Each conflict row links to an explainer panel that describes the winning value, losing sources, and precedence rule.
|
||||
5. **References** collapsible list (patches, advisories, exploits).
|
||||
6. **Raw JSON** viewer (read-only) using canonical Concelier payload. Users can copy JSON or download via `GET /console/advisories/raw/{id}`.
|
||||
7. **CLI parity** card with commands:
|
||||
- `stella advisory show --tenant <tenant> --vuln <id>`
|
||||
- `stella advisory sources --tenant <tenant> --vuln <id>`
|
||||
- `stella advisory export --tenant <tenant> --vuln <id> --format cdx-json`
|
||||
|
||||
Provenance banner at the top indicates whether all sources are signed, partially signed, or unsigned, referencing AOC guardrails. Unsigned sources trigger a warning and link to the verification checklist.
|
||||
|
||||
---
|
||||
|
||||
## 5. VEX explorer
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Consensus table** | Rows keyed by `(vulnId, productKey)` with rollup status (affected, not affected, fixed, under investigation), confidence score, provider count, and last evaluation timestamp. |
|
||||
| **Status badges** | Colour-coded (red affected, green not affected, blue fixed, amber under investigation). Tooltips show justification and policy revision used. |
|
||||
| **Provider breakdown** | Hover or expand to see source list with accepted/ignored flag, status, justification code, signature state, weight. |
|
||||
| **Filters** | Product search (PURL), status filter, provider filter, justification codes, confidence threshold slider. |
|
||||
| **Saved views** | Prebuilt presets: `Vendor consensus`, `Distro overrides`, `Conflicts`, `Pending investigation`. |
|
||||
|
||||
---
|
||||
|
||||
## 6. VEX detail drawer
|
||||
|
||||
Tabs within the drawer:
|
||||
|
||||
- **Consensus summary**: Restates rollup status, policy revision, confidence benchmarks, and referencing runs.
|
||||
- **Claims list**: Every raw claim from Excititor with provenance, signature result, justification, supersedes chain, evidence snippets. Claims are grouped by provider tier (vendor, distro, ecosystem, CERT).
|
||||
- **Conflict explainers**: For conflicting claims, shows why a claim was ignored (weight, stale timestamp, failing justification gate). Includes inline diff between competing claims.
|
||||
- **Events**: Timeline of claim arrivals and consensus evaluations with correlation IDs, accessible for debugging.
|
||||
- **Raw JSON**: Canonical `VexClaim` or `VexConsensus` payloads with copy/download. CLI parity callouts:
|
||||
- `stella vex consensus show --tenant <tenant> --vuln <id> --product <purl>`
|
||||
- `stella vex claims show --tenant <tenant> --vuln <id> --provider <provider>`
|
||||
|
||||
---
|
||||
|
||||
## 7. Raw viewers and provenance
|
||||
|
||||
- Raw viewers display canonical payloads with syntax highlighting and copy-as-JSON support.
|
||||
- Provenance banner presents: source URI, document digest, signature status, fetch timestamps, collector version.
|
||||
- Users can open raw documents in a modal that includes:
|
||||
- `sha256` digest with copy button
|
||||
- Signature verification summary (passing keys, missing signatures, errors)
|
||||
- `Download DSSE bundle` button when the document is attested
|
||||
- `Open in logs` link that copies search query (`correlationId=...`) for log aggregation tools.
|
||||
|
||||
All raw views are read-only to maintain Aggregation-Only guarantees.
|
||||
|
||||
---
|
||||
|
||||
## 8. Conflict indicators and aggregation-not-merge UX
|
||||
|
||||
- Concelier retains every source; the UI surfaces conflicts rather than merging them.
|
||||
- Conflict badges appear in grids and detail views when sources disagree on affected ranges, fixed versions, severity, or exploit flags.
|
||||
- Clicking a badge opens the conflict explainer panel (powered by Concelier merge metadata) that lists winning/losing sources, ranks, and reasoning (e.g., "Vendor PSIRT overrides ecosystem advisory").
|
||||
- Excititor conflicts highlight discarded claims with reasons (stale, failing justification, low weight). Operators can override weights downstream via Policy Engine if needed.
|
||||
- UI copy explicitly reminds users that policy decisions happen elsewhere; these views show aggregated facts only.
|
||||
|
||||
---
|
||||
|
||||
## 9. Verification workflows
|
||||
|
||||
- **Run verify** buttons call Concelier or Excititor verification endpoints (`POST /console/advisories/verify`, `POST /console/vex/verify`) scoped by tenant and source filters.
|
||||
- Verification results appear as banners summarising documents checked, signatures verified, and guard violations.
|
||||
- Failed verifications show actionable error IDs (`ERR_AOC_00x`), matching CLI output.
|
||||
- Verification history accessible via the status ticker dropdown; entries include operator, scope, and correlation IDs.
|
||||
|
||||
---
|
||||
|
||||
## 10. Exports and automation
|
||||
|
||||
- Advisory tab exposes export actions: `Download normalized advisory`, `Download affected products CSV`, `Download source bundle` (raw documents packaged with manifest).
|
||||
- VEX tab supports exports for consensus snapshots, raw claims, and provider deltas.
|
||||
- Export manifests include merge hash or consensus digest, tenant ID, timestamp, and signature state.
|
||||
- CLI parity snippets accompany each export (e.g., `stella advisory export`, `stella vex export`).
|
||||
- Automation: copy buttons for webhook subscription (`/downloads/hooks/subscribe`) and ORAS push commands when using remote registries.
|
||||
|
||||
---
|
||||
|
||||
## 11. Observability and SSE updates
|
||||
|
||||
- Status ticker shows ingest lag (`advisory_delta_minutes`, `vex_delta_minutes`), last merge event hash, and verification queue depth.
|
||||
- Advisory and VEX grids refresh via SSE channels; updates animate row badges (new source, conflict resolved).
|
||||
- Metrics surfaced in drawers: ingestion age, signature pass rate, consensus evaluation duration.
|
||||
- Errors display correlation IDs linking to Concelier/Excititor logs.
|
||||
|
||||
---
|
||||
|
||||
## 12. Offline and air-gap behaviour
|
||||
|
||||
- When offline, list views display snapshot badge, staleness timer, and disable real-time verification.
|
||||
- Raw downloads reference local snapshot directories and include checksum instructions.
|
||||
- Exports queue locally; UI offers `Copy to removable media` instructions.
|
||||
- CLI parity switches to offline commands (`--offline`, `--snapshot`).
|
||||
- Tenant picker hides tenants not present in the snapshot to avoid partial data views.
|
||||
|
||||
---
|
||||
|
||||
## 13. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- 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).
|
||||
|
||||
---
|
||||
|
||||
## 14. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - shell, filters, tenant model.
|
||||
- `/docs/ui/navigation.md` - command palette, deep-link schema.
|
||||
- `/docs/ingestion/aggregation-only-contract.md` - AOC guardrails.
|
||||
- `/docs/architecture/CONCELIER.md` - merge rules, provenance.
|
||||
- `/docs/architecture/EXCITITOR.md` - VEX consensus model.
|
||||
- `/docs/security/console-security.md` - scopes, DPoP, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
|
||||
---
|
||||
|
||||
## 15. Compliance checklist
|
||||
|
||||
- [ ] Advisory grid columns, filters, and merge hash behaviour documented.
|
||||
- [ ] VEX consensus view covers status badges, provider breakdown, and filters.
|
||||
- [ ] Raw viewer and provenance banners explained with AOC alignment.
|
||||
- [ ] Conflict indicators and explainers tied to aggregation-not-merge rules.
|
||||
- [ ] Verification workflow and CLI parity documented.
|
||||
- [ ] Offline behaviour and automation paths captured.
|
||||
- [ ] Screenshot placeholders and coordination notes recorded.
|
||||
- [ ] References validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
# StellaOps Console - Advisories and VEX
|
||||
|
||||
> **Audience:** Console UX team, Concelier and Excititor guilds, support and compliance engineers.
|
||||
> **Scope:** Advisory aggregation UX, VEX consensus display, conflict indicators, raw document viewer, provenance banners, CLI parity, and Aggregation-Only Contract (AOC) guardrails for Sprint 23.
|
||||
|
||||
The Advisories and VEX surfaces expose Concelier and Excititor outputs without mutating the underlying data. Operators can review upstream statements, check consensus summaries, inspect conflicts, and hand off evidence to downstream tooling while staying within the Aggregation-Only Contract.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Routes:**
|
||||
- `/console/advisories` (advisory list and detail)
|
||||
- `/console/vex` (VEX consensus and raw claim explorer)
|
||||
- **Scopes:** `advisory.read` and `vex.read` (base access), `advisory.verify` / `vex.verify` for verification actions, `downloads.read` for evidence exports.
|
||||
- **Feature flags:** `advisoryExplorer.enabled`, `vexExplorer.enabled`, `aggregation.conflictIndicators`.
|
||||
- **Dependencies:** Concelier WebService (aggregation API + delta metrics), Excititor WebService (consensus API + conflict feeds), Policy Engine explain hints (optional link-outs), Authority tenant enforcement.
|
||||
- **Offline behaviour:** Uses Offline Kit snapshots when gateway is in sealed mode; verify buttons queue until connectivity resumes.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------------+
|
||||
| Header: Tenant badge - global filters - status ticker - actions |
|
||||
+---------------------------------------------------------------------+
|
||||
| Left rail: Saved views - provider filters - verification queue |
|
||||
+---------------------------------------------------------------------+
|
||||
| Main split pane |
|
||||
| - Advisories tab (grid + detail drawer) |
|
||||
| - VEX tab (consensus table + claim drawer) |
|
||||
| Tabs remember last active view per tenant. |
|
||||
+---------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The header reuses console-wide context chips (`Tenant`, `Severity`, `Source`, `Time`) and the status ticker that streams Concelier and Excititor deltas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Advisory aggregation view
|
||||
|
||||
| Element | Description |
|
||||
|---------|-------------|
|
||||
| **Grid columns** | Vulnerability key (CVE/GHSA/vendor), Title, Source set, Last merged, Severity badge, KEV flag, Affected product count, Merge hash. |
|
||||
| **Source chips** | Show contributing providers (NVD, Red Hat, Debian, vendor PSIRT). Hover reveals precedence order and timestamps. |
|
||||
| **Severity** | Displays the highest severity declared by any source; tooltip lists per-source severities and vectors. |
|
||||
| **KEV / Exploit status** | Badge highlights known exploited status from Concelier enrichment; links to KEV reference. |
|
||||
| **Merge hash** | Deterministic hash from Concelier `merge_event`. Clicking copies hash and opens provenance banner. |
|
||||
| **Filters** | Vulnerability identifier search, provider multi-select, severity picker, KEV toggle, affected product range slider, time window. |
|
||||
| **List actions** | `Open detail`, `Copy CLI` (`stella advisory show ...`), `Compare sources`, `Queue verify`. |
|
||||
|
||||
The grid virtualises up to 15,000 advisories per tenant. Beyond that, the UI engages server-side pagination with cursor hints supplied by Concelier.
|
||||
|
||||
---
|
||||
|
||||
## 4. Advisory detail drawer
|
||||
|
||||
Sections within the drawer:
|
||||
|
||||
1. **Summary cards** (title, published/modified timestamps, advisory merge hash, total sources, exploited flag).
|
||||
2. **Sources timeline** listing each contributing document with signature status, fetched timestamps, precedence rank, and quick links to raw view.
|
||||
3. **Affected products** table (product key, introduced/fixed, range semantics, distro qualifiers, notes). Column toggles allow switching between SemVer and distro notation.
|
||||
4. **Conflict indicators** show when sources disagree on fixed versions, severity, or affected sets. Each conflict row links to an explainer panel that describes the winning value, losing sources, and precedence rule.
|
||||
5. **References** collapsible list (patches, advisories, exploits).
|
||||
6. **Raw JSON** viewer (read-only) using canonical Concelier payload. Users can copy JSON or download via `GET /console/advisories/raw/{id}`.
|
||||
7. **CLI parity** card with commands:
|
||||
- `stella advisory show --tenant <tenant> --vuln <id>`
|
||||
- `stella advisory sources --tenant <tenant> --vuln <id>`
|
||||
- `stella advisory export --tenant <tenant> --vuln <id> --format cdx-json`
|
||||
|
||||
Provenance banner at the top indicates whether all sources are signed, partially signed, or unsigned, referencing AOC guardrails. Unsigned sources trigger a warning and link to the verification checklist.
|
||||
|
||||
---
|
||||
|
||||
## 5. VEX explorer
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Consensus table** | Rows keyed by `(vulnId, productKey)` with rollup status (affected, not affected, fixed, under investigation), confidence score, provider count, and last evaluation timestamp. |
|
||||
| **Status badges** | Colour-coded (red affected, green not affected, blue fixed, amber under investigation). Tooltips show justification and policy revision used. |
|
||||
| **Provider breakdown** | Hover or expand to see source list with accepted/ignored flag, status, justification code, signature state, weight. |
|
||||
| **Filters** | Product search (PURL), status filter, provider filter, justification codes, confidence threshold slider. |
|
||||
| **Saved views** | Prebuilt presets: `Vendor consensus`, `Distro overrides`, `Conflicts`, `Pending investigation`. |
|
||||
|
||||
---
|
||||
|
||||
## 6. VEX detail drawer
|
||||
|
||||
Tabs within the drawer:
|
||||
|
||||
- **Consensus summary**: Restates rollup status, policy revision, confidence benchmarks, and referencing runs.
|
||||
- **Claims list**: Every raw claim from Excititor with provenance, signature result, justification, supersedes chain, evidence snippets. Claims are grouped by provider tier (vendor, distro, ecosystem, CERT).
|
||||
- **Conflict explainers**: For conflicting claims, shows why a claim was ignored (weight, stale timestamp, failing justification gate). Includes inline diff between competing claims.
|
||||
- **Events**: Timeline of claim arrivals and consensus evaluations with correlation IDs, accessible for debugging.
|
||||
- **Raw JSON**: Canonical `VexClaim` or `VexConsensus` payloads with copy/download. CLI parity callouts:
|
||||
- `stella vex consensus show --tenant <tenant> --vuln <id> --product <purl>`
|
||||
- `stella vex claims show --tenant <tenant> --vuln <id> --provider <provider>`
|
||||
|
||||
---
|
||||
|
||||
## 7. Raw viewers and provenance
|
||||
|
||||
- Raw viewers display canonical payloads with syntax highlighting and copy-as-JSON support.
|
||||
- Provenance banner presents: source URI, document digest, signature status, fetch timestamps, collector version.
|
||||
- Users can open raw documents in a modal that includes:
|
||||
- `sha256` digest with copy button
|
||||
- Signature verification summary (passing keys, missing signatures, errors)
|
||||
- `Download DSSE bundle` button when the document is attested
|
||||
- `Open in logs` link that copies search query (`correlationId=...`) for log aggregation tools.
|
||||
|
||||
All raw views are read-only to maintain Aggregation-Only guarantees.
|
||||
|
||||
---
|
||||
|
||||
## 8. Conflict indicators and aggregation-not-merge UX
|
||||
|
||||
- Concelier retains every source; the UI surfaces conflicts rather than merging them.
|
||||
- Conflict badges appear in grids and detail views when sources disagree on affected ranges, fixed versions, severity, or exploit flags.
|
||||
- Clicking a badge opens the conflict explainer panel (powered by Concelier merge metadata) that lists winning/losing sources, ranks, and reasoning (e.g., "Vendor PSIRT overrides ecosystem advisory").
|
||||
- Excititor conflicts highlight discarded claims with reasons (stale, failing justification, low weight). Operators can override weights downstream via Policy Engine if needed.
|
||||
- UI copy explicitly reminds users that policy decisions happen elsewhere; these views show aggregated facts only.
|
||||
|
||||
---
|
||||
|
||||
## 9. Verification workflows
|
||||
|
||||
- **Run verify** buttons call Concelier or Excititor verification endpoints (`POST /console/advisories/verify`, `POST /console/vex/verify`) scoped by tenant and source filters.
|
||||
- Verification results appear as banners summarising documents checked, signatures verified, and guard violations.
|
||||
- Failed verifications show actionable error IDs (`ERR_AOC_00x`), matching CLI output.
|
||||
- Verification history accessible via the status ticker dropdown; entries include operator, scope, and correlation IDs.
|
||||
|
||||
---
|
||||
|
||||
## 10. Exports and automation
|
||||
|
||||
- Advisory tab exposes export actions: `Download normalized advisory`, `Download affected products CSV`, `Download source bundle` (raw documents packaged with manifest).
|
||||
- VEX tab supports exports for consensus snapshots, raw claims, and provider deltas.
|
||||
- Export manifests include merge hash or consensus digest, tenant ID, timestamp, and signature state.
|
||||
- CLI parity snippets accompany each export (e.g., `stella advisory export`, `stella vex export`).
|
||||
- Automation: copy buttons for webhook subscription (`/downloads/hooks/subscribe`) and ORAS push commands when using remote registries.
|
||||
|
||||
---
|
||||
|
||||
## 11. Observability and SSE updates
|
||||
|
||||
- Status ticker shows ingest lag (`advisory_delta_minutes`, `vex_delta_minutes`), last merge event hash, and verification queue depth.
|
||||
- Advisory and VEX grids refresh via SSE channels; updates animate row badges (new source, conflict resolved).
|
||||
- Metrics surfaced in drawers: ingestion age, signature pass rate, consensus evaluation duration.
|
||||
- Errors display correlation IDs linking to Concelier/Excititor logs.
|
||||
|
||||
---
|
||||
|
||||
## 12. Offline and air-gap behaviour
|
||||
|
||||
- When offline, list views display snapshot badge, staleness timer, and disable real-time verification.
|
||||
- Raw downloads reference local snapshot directories and include checksum instructions.
|
||||
- Exports queue locally; UI offers `Copy to removable media` instructions.
|
||||
- CLI parity switches to offline commands (`--offline`, `--snapshot`).
|
||||
- Tenant picker hides tenants not present in the snapshot to avoid partial data views.
|
||||
|
||||
---
|
||||
|
||||
## 13. Screenshot coordination
|
||||
|
||||
- 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).
|
||||
|
||||
---
|
||||
|
||||
## 14. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - shell, filters, tenant model.
|
||||
- `/docs/ui/navigation.md` - command palette, deep-link schema.
|
||||
- `/docs/ingestion/aggregation-only-contract.md` - AOC guardrails.
|
||||
- `/docs/architecture/CONCELIER.md` - merge rules, provenance.
|
||||
- `/docs/architecture/EXCITITOR.md` - VEX consensus model.
|
||||
- `/docs/security/console-security.md` - scopes, DPoP, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
|
||||
---
|
||||
|
||||
## 15. Compliance checklist
|
||||
|
||||
- [ ] Advisory grid columns, filters, and merge hash behaviour documented.
|
||||
- [ ] VEX consensus view covers status badges, provider breakdown, and filters.
|
||||
- [ ] Raw viewer and provenance banners explained with AOC alignment.
|
||||
- [ ] Conflict indicators and explainers tied to aggregation-not-merge rules.
|
||||
- [ ] Verification workflow and CLI parity documented.
|
||||
- [ ] Offline behaviour and automation paths captured.
|
||||
- [ ] Screenshot placeholders and coordination notes recorded.
|
||||
- [ ] References validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
@@ -1,130 +1,130 @@
|
||||
# StellaOps Console – Overview
|
||||
|
||||
> **Audience:** Console product leads, Docs Guild writers, backend/API partners.
|
||||
> **Scope:** Information architecture, tenant scoping, global filters, and Aggregation‑Only Contract (AOC) alignment for the unified StellaOps Console that lands with Sprint 23.
|
||||
|
||||
The StellaOps Console is the single entry point for operators to explore SBOMs, advisories, policies, runs, and administrative surfaces. This overview explains how the console is organised, how users move between tenants, and how shared filters keep data views consistent across modules while respecting AOC boundaries.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Mission & Principles
|
||||
|
||||
- **Deterministic navigation.** Every route is stable and deep-link friendly. URLs carry enough context (tenant, filter tokens, view modes) to let operators resume work without reapplying filters.
|
||||
- **Tenant isolation first.** Any cross-tenant action requires fresh authority, and cross-tenant comparisons are made explicit so users never accidentally mix data sets.
|
||||
- **Aggregation-not-merge UX.** Console surfaces advisory and VEX rollups exactly as produced by Concelier and Excititor—no client-side re-weighting or mutation.
|
||||
- **Offline parity.** Every view has an offline equivalent powered by Offline Kit bundles or cached data, and exposes the staleness budget prominently.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Information Architecture
|
||||
|
||||
### 2.1 Primary navigation
|
||||
|
||||
```
|
||||
Console Root
|
||||
├─ Dashboard # KPIs, alerts, feed age, queue depth
|
||||
├─ Findings # Aggregated vulns + explanations (Policy Engine)
|
||||
├─ SBOM Explorer # Catalog, component graph, overlays
|
||||
├─ Advisories & VEX # Concelier / Excititor aggregation outputs
|
||||
├─ Runs # Scheduler runs, scan evidence, retry controls
|
||||
├─ Policies # Editor, simulations, approvals
|
||||
├─ Downloads # Signed artifacts, Offline Kit parity
|
||||
├─ Admin # Tenants, roles, tokens, integrations
|
||||
└─ Help & Tours # Contextual docs, guided walkthroughs
|
||||
```
|
||||
|
||||
Routes lazy-load feature shells so the UI can grow without increasing first-paint cost. Each feature owns its sub-navigation and exposes a `KeyboardShortcuts` modal describing the available accelerators.
|
||||
|
||||
### 2.2 Shared surfaces
|
||||
|
||||
| Surface | Purpose | Notes |
|
||||
|---------|---------|-------|
|
||||
| **Top bar** | Shows active tenant, environment badge (prod/non-prod), offline status pill, user menu, notifications inbox, and the command palette trigger (`⌘/Ctrl K`). | Offline status turns amber when data staleness exceeds configured thresholds. |
|
||||
| **Global filter tray** | Expands from the right edge (`Shift F`). Hosts universal filters (tenant, time window, tags, severity) that apply across compatible routes. | Filter tray remembers per-tenant presets; stored in IndexedDB (non-sensitive). |
|
||||
| **Context chips** | Display active global filters underneath page titles, with one-click removal (`⌫`). | Chips include the origin (e.g., `Tenant: west-prod`). |
|
||||
| **Status ticker** | SSE-driven strip that surfaces Concelier/Excititor ingestion deltas, scheduler lag, and attestor queue depth. | Pulls from `/console/status` proxy (see WEB-CONSOLE-23-002). |
|
||||
|
||||
---
|
||||
|
||||
## 3 · Tenant Model
|
||||
|
||||
| Aspect | Detail |
|
||||
|--------|--------|
|
||||
| **Tenant sources** | The console obtains the tenant list and metadata from Authority `/v1/tenants` after login. Tenant descriptors include display name, slug, environment tag, and RBAC hints (role mask). |
|
||||
| **Selection workflow** | First visit prompts for a default tenant. Afterwards, the tenant picker (`⌘/Ctrl T`) switches context without full reload, issuing `Authorization` refresh with the new tenant scope. |
|
||||
| **Token handling** | Each tenant change generates a short-lived, DPoP-bound access token (`aud=console`, `tenant=<id>`). Tokens live in memory; metadata persists in `sessionStorage` for reload continuity. |
|
||||
| **Cross-tenant comparisons** | Side-by-side dashboards (Dashboard, Findings, SBOM Explorer) allow multi-tenant comparison only via explicit *"Add tenant"* control. Requests issue parallel API calls with separate tokens; results render in split panes labelled per tenant. |
|
||||
| **Fresh-auth gated actions** | Admin and policy approvals call `Authority /fresh-auth` before executing. UI enforces a 5-minute window; afterwards, actions remain visible but disabled pending re-auth. |
|
||||
| **Audit trail** | Tenant switches emit structured logs (`action=ui.tenant.switch`, `tenantId`, `subject`, `previousTenant`) and appear in Authority audit exports. |
|
||||
|
||||
### 3.1 Offline operation
|
||||
|
||||
In offline or sealed environments, the tenant picker only lists tenants bundled within the Offline Kit snapshot. Switching tenants prompts an "offline snapshot" banner showing the snapshot timestamp. Actions that require round-trips to Authority (fresh-auth, token rotation) show guidance to perform the step on an online bastion and import credentials later.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Global Filters & Context Tokens
|
||||
|
||||
| Filter | Applies To | Source & Behaviour |
|
||||
|--------|------------|--------------------|
|
||||
| **Tenant** | All modules | Primary isolation control. Stored in URL (`?tenant=`) and via `x-tenant-id` header injected by the web proxy. Changes invalidate cached data stores. |
|
||||
| **Time window** | Dashboard, Findings, Advisories & VEX, Runs | Options: `24 h`, `7 d`, `30 d`, custom ISO range. Default aligns with Compliance/Authority reporting window. Shared via query param `since=`/`until=`. |
|
||||
| **Severity / Impact** | Findings, Advisories & VEX, SBOM Explorer overlays | Multi-select (Critical/High/Medium/Low/Informational, plus `Exploited` tag). Values map to Policy Engine impact buckets and Concelier KEV flags. |
|
||||
| **Component tags** | SBOM Explorer, Findings | Tags drawn from SBOM metadata (`component.tags[]`). Includes search-as-you-type with scoped suggestions (package type, supplier, license). |
|
||||
| **Source providers** | Advisories & VEX | Filter by provider IDs (e.g., NVD, GHSA, vendor VEX). Tied to Aggregation-Only provenance; filtering never alters base precedence. |
|
||||
| **Run status** | Runs, Dashboard | States: `queued`, `running`, `completed`, `failed`, `cancelled`. Pulled from Scheduler SSE stream; default shows non-terminal states. |
|
||||
| **Policy view** | Findings, Policies | Toggles between Active policy, Staged policy, and Simulation snapshots. Selecting Simulation requires prior simulation run; console links to create one if absent. |
|
||||
|
||||
Filters emit deterministic tokens placed in the URL hash for copy/paste parity with CLI commands (see `/docs/cli-vs-ui-parity.md`). The console warns when a filter combination has no effect on the current view and offers to reset to defaults.
|
||||
|
||||
### 4.1 Presets & Saved Views
|
||||
|
||||
Users can save a set of global filters as named presets (stored per tenant). Presets show up in the command palette and the dashboard landing cards for quick access (`⌘/Ctrl 1..9`).
|
||||
|
||||
---
|
||||
|
||||
## 5 · Aggregation-Only Alignment
|
||||
|
||||
- **Read-only aggregation.** Pages that list advisories or VEX claims consume the canonical aggregation endpoints (`/console/advisories`, `/console/vex`). They never merge or reconcile records client-side. Instead, they highlight the source lineage and precedence as supplied by Concelier and Excititor.
|
||||
- **Consistency indicators.** Each aggregated item displays source badges, precedence order, and a "last merge event hash" so operators can cross-reference Concelier logs. When a source is missing or stale, the UI surfaces a provenance banner linking to the raw document.
|
||||
- **AOC guardrails.** Workflow actions (e.g., "request verify", "download evidence bundle") route through Concelier WebService guard endpoints that enforce Aggregation-Only rules. UI strings reinforce that policy decisions happen in Policy Engine, not here.
|
||||
- **Audit alignment.** Any cross-navigation from aggregated data into findings or policies preserves the underlying IDs so analysts can track how aggregated data influences policy verdicts without altering the data itself.
|
||||
- **CLI parity.** Inline callouts copy the equivalent `stella` CLI commands, ensuring console users can recreate the exact aggregation query offline.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Performance & Telemetry Anchors
|
||||
|
||||
- Initial boot target: **< 2.5 s** `LargestContentfulPaint` on 4 vCPU air-gapped runner with cached assets.
|
||||
- Route budget: each feature shell must keep first interaction (hydrated data + filters) under **1.5 s** once tokens resolve.
|
||||
- Telemetry: console emits metrics via the `/console/telemetry` batch endpoint—`ui_route_render_seconds`, `ui_filter_apply_total`, `ui_tenant_switch_total`, `ui_offline_banner_seconds`. Logs carry correlation IDs matching backend responses for unified tracing.
|
||||
- Lighthouse CI runs in the console pipeline (see `DEVOPS-CONSOLE-23-001`) and asserts budgets above; failing runs gate releases.
|
||||
|
||||
---
|
||||
|
||||
## 7 · References
|
||||
|
||||
- `/docs/architecture/console.md` – component-level diagrams (pending Sprint 23 task).
|
||||
- `/docs/ui/navigation.md` – detailed routes, breadcrumbs, keyboard shortcuts.
|
||||
- `/docs/ui/downloads.md` – downloads manifest, parity workflows, offline guidance.
|
||||
- `/docs/ui/sbom-explorer.md` – SBOM-specific flows and overlays.
|
||||
- `/docs/ui/advisories-and-vex.md` – aggregation UX details.
|
||||
- `/docs/ui/findings.md` – explain drawer and filter matrix.
|
||||
- `/docs/security/console-security.md` – OIDC, scopes, CSP, evidence handling.
|
||||
- `/docs/cli-vs-ui-parity.md` – CLI equivalents and regression automation.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Compliance Checklist
|
||||
|
||||
- [ ] Tenant picker enforces Authority-issued scopes and logs `ui.tenant.switch`.
|
||||
- [ ] Global filters update URLs/query tokens for deterministic deep links.
|
||||
- [ ] Aggregation views show provenance badges and merge hash indicators.
|
||||
- [ ] CLI parity callouts aligned with `stella` commands for equivalent queries.
|
||||
- [ ] Offline banner tested with Offline Kit snapshot import and documented staleness thresholds.
|
||||
- [ ] Accessibility audit covers global filter tray, tenant picker, and keyboard shortcuts (WCAG 2.2 AA).
|
||||
- [ ] Telemetry and Lighthouse budgets tracked in console CI (`DEVOPS-CONSOLE-23-001`).
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
# StellaOps Console – Overview
|
||||
|
||||
> **Audience:** Console product leads, Docs Guild writers, backend/API partners.
|
||||
> **Scope:** Information architecture, tenant scoping, global filters, and Aggregation‑Only Contract (AOC) alignment for the unified StellaOps Console that lands with Sprint 23.
|
||||
|
||||
The StellaOps Console is the single entry point for operators to explore SBOMs, advisories, policies, runs, and administrative surfaces. This overview explains how the console is organised, how users move between tenants, and how shared filters keep data views consistent across modules while respecting AOC boundaries.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Mission & Principles
|
||||
|
||||
- **Deterministic navigation.** Every route is stable and deep-link friendly. URLs carry enough context (tenant, filter tokens, view modes) to let operators resume work without reapplying filters.
|
||||
- **Tenant isolation first.** Any cross-tenant action requires fresh authority, and cross-tenant comparisons are made explicit so users never accidentally mix data sets.
|
||||
- **Aggregation-not-merge UX.** Console surfaces advisory and VEX rollups exactly as produced by Concelier and Excititor—no client-side re-weighting or mutation.
|
||||
- **Offline parity.** Every view has an offline equivalent powered by Offline Kit bundles or cached data, and exposes the staleness budget prominently.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Information Architecture
|
||||
|
||||
### 2.1 Primary navigation
|
||||
|
||||
```
|
||||
Console Root
|
||||
├─ Dashboard # KPIs, alerts, feed age, queue depth
|
||||
├─ Findings # Aggregated vulns + explanations (Policy Engine)
|
||||
├─ SBOM Explorer # Catalog, component graph, overlays
|
||||
├─ Advisories & VEX # Concelier / Excititor aggregation outputs
|
||||
├─ Runs # Scheduler runs, scan evidence, retry controls
|
||||
├─ Policies # Editor, simulations, approvals
|
||||
├─ Downloads # Signed artifacts, Offline Kit parity
|
||||
├─ Admin # Tenants, roles, tokens, integrations
|
||||
└─ Help & Tours # Contextual docs, guided walkthroughs
|
||||
```
|
||||
|
||||
Routes lazy-load feature shells so the UI can grow without increasing first-paint cost. Each feature owns its sub-navigation and exposes a `KeyboardShortcuts` modal describing the available accelerators.
|
||||
|
||||
### 2.2 Shared surfaces
|
||||
|
||||
| Surface | Purpose | Notes |
|
||||
|---------|---------|-------|
|
||||
| **Top bar** | Shows active tenant, environment badge (prod/non-prod), offline status pill, user menu, notifications inbox, and the command palette trigger (`⌘/Ctrl K`). | Offline status turns amber when data staleness exceeds configured thresholds. |
|
||||
| **Global filter tray** | Expands from the right edge (`Shift F`). Hosts universal filters (tenant, time window, tags, severity) that apply across compatible routes. | Filter tray remembers per-tenant presets; stored in IndexedDB (non-sensitive). |
|
||||
| **Context chips** | Display active global filters underneath page titles, with one-click removal (`⌫`). | Chips include the origin (e.g., `Tenant: west-prod`). |
|
||||
| **Status ticker** | SSE-driven strip that surfaces Concelier/Excititor ingestion deltas, scheduler lag, and attestor queue depth. | Pulls from `/console/status` proxy (see WEB-CONSOLE-23-002). |
|
||||
|
||||
---
|
||||
|
||||
## 3 · Tenant Model
|
||||
|
||||
| Aspect | Detail |
|
||||
|--------|--------|
|
||||
| **Tenant sources** | The console obtains the tenant list and metadata from Authority `/v1/tenants` after login. Tenant descriptors include display name, slug, environment tag, and RBAC hints (role mask). |
|
||||
| **Selection workflow** | First visit prompts for a default tenant. Afterwards, the tenant picker (`⌘/Ctrl T`) switches context without full reload, issuing `Authorization` refresh with the new tenant scope. |
|
||||
| **Token handling** | Each tenant change generates a short-lived, DPoP-bound access token (`aud=console`, `tenant=<id>`). Tokens live in memory; metadata persists in `sessionStorage` for reload continuity. |
|
||||
| **Cross-tenant comparisons** | Side-by-side dashboards (Dashboard, Findings, SBOM Explorer) allow multi-tenant comparison only via explicit *"Add tenant"* control. Requests issue parallel API calls with separate tokens; results render in split panes labelled per tenant. |
|
||||
| **Fresh-auth gated actions** | Admin and policy approvals call `Authority /fresh-auth` before executing. UI enforces a 5-minute window; afterwards, actions remain visible but disabled pending re-auth. |
|
||||
| **Audit trail** | Tenant switches emit structured logs (`action=ui.tenant.switch`, `tenantId`, `subject`, `previousTenant`) and appear in Authority audit exports. |
|
||||
|
||||
### 3.1 Offline operation
|
||||
|
||||
In offline or sealed environments, the tenant picker only lists tenants bundled within the Offline Kit snapshot. Switching tenants prompts an "offline snapshot" banner showing the snapshot timestamp. Actions that require round-trips to Authority (fresh-auth, token rotation) show guidance to perform the step on an online bastion and import credentials later.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Global Filters & Context Tokens
|
||||
|
||||
| Filter | Applies To | Source & Behaviour |
|
||||
|--------|------------|--------------------|
|
||||
| **Tenant** | All modules | Primary isolation control. Stored in URL (`?tenant=`) and via `x-tenant-id` header injected by the web proxy. Changes invalidate cached data stores. |
|
||||
| **Time window** | Dashboard, Findings, Advisories & VEX, Runs | Options: `24 h`, `7 d`, `30 d`, custom ISO range. Default aligns with Compliance/Authority reporting window. Shared via query param `since=`/`until=`. |
|
||||
| **Severity / Impact** | Findings, Advisories & VEX, SBOM Explorer overlays | Multi-select (Critical/High/Medium/Low/Informational, plus `Exploited` tag). Values map to Policy Engine impact buckets and Concelier KEV flags. |
|
||||
| **Component tags** | SBOM Explorer, Findings | Tags drawn from SBOM metadata (`component.tags[]`). Includes search-as-you-type with scoped suggestions (package type, supplier, license). |
|
||||
| **Source providers** | Advisories & VEX | Filter by provider IDs (e.g., NVD, GHSA, vendor VEX). Tied to Aggregation-Only provenance; filtering never alters base precedence. |
|
||||
| **Run status** | Runs, Dashboard | States: `queued`, `running`, `completed`, `failed`, `cancelled`. Pulled from Scheduler SSE stream; default shows non-terminal states. |
|
||||
| **Policy view** | Findings, Policies | Toggles between Active policy, Staged policy, and Simulation snapshots. Selecting Simulation requires prior simulation run; console links to create one if absent. |
|
||||
|
||||
Filters emit deterministic tokens placed in the URL hash for copy/paste parity with CLI commands (see `/docs/cli-vs-ui-parity.md`). The console warns when a filter combination has no effect on the current view and offers to reset to defaults.
|
||||
|
||||
### 4.1 Presets & Saved Views
|
||||
|
||||
Users can save a set of global filters as named presets (stored per tenant). Presets show up in the command palette and the dashboard landing cards for quick access (`⌘/Ctrl 1..9`).
|
||||
|
||||
---
|
||||
|
||||
## 5 · Aggregation-Only Alignment
|
||||
|
||||
- **Read-only aggregation.** Pages that list advisories or VEX claims consume the canonical aggregation endpoints (`/console/advisories`, `/console/vex`). They never merge or reconcile records client-side. Instead, they highlight the source lineage and precedence as supplied by Concelier and Excititor.
|
||||
- **Consistency indicators.** Each aggregated item displays source badges, precedence order, and a "last merge event hash" so operators can cross-reference Concelier logs. When a source is missing or stale, the UI surfaces a provenance banner linking to the raw document.
|
||||
- **AOC guardrails.** Workflow actions (e.g., "request verify", "download evidence bundle") route through Concelier WebService guard endpoints that enforce Aggregation-Only rules. UI strings reinforce that policy decisions happen in Policy Engine, not here.
|
||||
- **Audit alignment.** Any cross-navigation from aggregated data into findings or policies preserves the underlying IDs so analysts can track how aggregated data influences policy verdicts without altering the data itself.
|
||||
- **CLI parity.** Inline callouts copy the equivalent `stella` CLI commands, ensuring console users can recreate the exact aggregation query offline.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Performance & Telemetry Anchors
|
||||
|
||||
- Initial boot target: **< 2.5 s** `LargestContentfulPaint` on 4 vCPU air-gapped runner with cached assets.
|
||||
- Route budget: each feature shell must keep first interaction (hydrated data + filters) under **1.5 s** once tokens resolve.
|
||||
- Telemetry: console emits metrics via the `/console/telemetry` batch endpoint—`ui_route_render_seconds`, `ui_filter_apply_total`, `ui_tenant_switch_total`, `ui_offline_banner_seconds`. Logs carry correlation IDs matching backend responses for unified tracing.
|
||||
- Lighthouse CI runs in the console pipeline (see `DEVOPS-CONSOLE-23-001`) and asserts budgets above; failing runs gate releases.
|
||||
|
||||
---
|
||||
|
||||
## 7 · References
|
||||
|
||||
- `/docs/architecture/console.md` – component-level diagrams (pending Sprint 23 task).
|
||||
- `/docs/ui/navigation.md` – detailed routes, breadcrumbs, keyboard shortcuts.
|
||||
- `/docs/ui/downloads.md` – downloads manifest, parity workflows, offline guidance.
|
||||
- `/docs/ui/sbom-explorer.md` – SBOM-specific flows and overlays.
|
||||
- `/docs/ui/advisories-and-vex.md` – aggregation UX details.
|
||||
- `/docs/ui/findings.md` – explain drawer and filter matrix.
|
||||
- `/docs/security/console-security.md` – OIDC, scopes, CSP, evidence handling.
|
||||
- `/docs/cli-vs-ui-parity.md` – CLI equivalents and regression automation.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Compliance Checklist
|
||||
|
||||
- [ ] Tenant picker enforces Authority-issued scopes and logs `ui.tenant.switch`.
|
||||
- [ ] Global filters update URLs/query tokens for deterministic deep links.
|
||||
- [ ] Aggregation views show provenance badges and merge hash indicators.
|
||||
- [ ] CLI parity callouts aligned with `stella` commands for equivalent queries.
|
||||
- [ ] Offline banner tested with Offline Kit snapshot import and documented staleness thresholds.
|
||||
- [ ] Accessibility audit covers global filter tray, tenant picker, and keyboard shortcuts (WCAG 2.2 AA).
|
||||
- [ ] Telemetry and Lighthouse budgets tracked in console CI (`DEVOPS-CONSOLE-23-001`).
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
@@ -1,212 +1,212 @@
|
||||
# StellaOps Console - Downloads Manager
|
||||
|
||||
> **Audience:** DevOps guild, Console engineers, enablement writers, and operators who promote releases or maintain offline mirrors.
|
||||
> **Scope:** `/console/downloads` workspace covering artifact catalog, signed manifest plumbing, export status handling, CLI parity, automation hooks, and offline guidance (Sprint 23).
|
||||
|
||||
The Downloads workspace centralises every artefact required to deploy or validate StellaOps in connected and air-gapped environments. It keeps Console operators aligned with release engineering by surfacing the signed downloads manifest, live export jobs, parity checks against Offline Kit bundles, and automation hooks that mirror the CLI experience.
|
||||
|
||||
---
|
||||
|
||||
## 1 - Access and prerequisites
|
||||
|
||||
- **Route:** `/console/downloads` (list) with detail drawer `/console/downloads/:artifactId`.
|
||||
- **Scopes:** `downloads.read` (baseline) and `downloads.manage` for cancelling or expiring stale exports. Evidence bundles inherit the originating scope (`runs.read`, `findings.read`, etc.).
|
||||
- **Dependencies:** Web gateway `/console/downloads` API (WEB-CONSOLE-23-005), DevOps manifest pipeline (`deploy/downloads/manifest.json`), Offline Kit metadata (`manifest/offline-manifest.json`), and export orchestrator `/console/exports`.
|
||||
- **Feature flags:** `downloads.workspace.enabled`, `downloads.exportQueue`, `downloads.offlineParity`.
|
||||
- **Tenancy:** Artefacts are tenant-agnostic except evidence bundles, which are tagged with originating tenant and require matching Authority scopes.
|
||||
|
||||
---
|
||||
|
||||
## 2 - Workspace layout
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------+
|
||||
| Header: Snapshot timestamp - Manifest signature status |
|
||||
+---------------------------------------------------------------+
|
||||
| Cards: Latest release - Offline kit parity - Export queue |
|
||||
+---------------------------------------------------------------+
|
||||
| Tabs: Artefacts | Exports | Offline Kits | Webhooks |
|
||||
+---------------------------------------------------------------+
|
||||
| Filter bar: Channel - Kind - Architecture - Scope tags |
|
||||
+---------------------------------------------------------------+
|
||||
| Table (virtualised): Artifact | Channel | Digest | Status |
|
||||
| Detail drawer: Metadata | Commands | Provenance | History |
|
||||
+---------------------------------------------------------------+
|
||||
```
|
||||
|
||||
- **Snapshot banner:** shows `manifest.version`, `generatedAt`, and cosign verification state. If verification fails, the banner turns red and links to troubleshooting guidance.
|
||||
- **Quick actions:** Copy manifest URL, download attestation bundle, trigger parity check, open CLI parity doc (`/docs/cli-vs-ui-parity.md`).
|
||||
- **Filters:** allow narrowing by channel (`edge`, `stable`, `airgap`), artefact kind (`container.image`, `helm.chart`, `compose.bundle`, `offline.bundle`, `export.bundle`), architecture (`linux/amd64`, `linux/arm64`), and scope tags (`console`, `scheduler`, `authority`).
|
||||
|
||||
---
|
||||
|
||||
## 3 - Artefact catalogue
|
||||
|
||||
| Category | Artefacts surfaced | Source | Notes |
|
||||
|----------|-------------------|--------|-------|
|
||||
| **Core containers** | `stellaops/web-ui`, `stellaops/web`, `stellaops/concelier`, `stellaops/excititor`, `stellaops/scanner-*`, `stellaops/authority`, `stellaops/attestor`, `stellaops/scheduler-*` | `deploy/downloads/manifest.json` (`artifacts[].kind = "container.image"`) | Digest-only pulls with copy-to-clipboard `docker pull` and `oras copy` commands; badges show arch availability. |
|
||||
| **Helm charts** | `deploy/helm/stellaops-*.tgz` plus values files | Manifest entries where `kind = "helm.chart"` | Commands reference `helm repo add` (online) and `helm install --values` (offline). UI links to values matrix in `/docs/install/helm-prod.md` when available. |
|
||||
| **Compose bundles** | `deploy/compose/docker-compose.*.yaml`, `.env` seeds | `kind = "compose.bundle"` | Inline diff viewer highlights digest changes vs previous snapshot; `docker compose pull` command copies digest pins. |
|
||||
| **Offline kit** | `stella-ops-offline-kit-<ver>-<channel>.tar.gz` + signatures and manifest | Offline Kit metadata (`manifest/offline-manifest.json`) merged into downloads view | Drawer shows bundle size, signed manifest digest, cosign verification command (mirrors `/docs/24_OFFLINE_KIT.md`). |
|
||||
| **Evidence exports** | Completed jobs from `/console/exports` (findings delta, policy explain, run evidence) | Export orchestrator job queue | Entries expire after retention window; UI exposes `stella runs export` and `stella findings export` parity buttons. |
|
||||
| **Webhooks & parity** | `/downloads/hooks/subscribe` configs, CI parity reports | Manifest extras (`kind = "webhook.config"`, `kind = "parity.report"`) | Operators can download webhook payload templates and review the latest CLI parity check report generated by docs CI. |
|
||||
|
||||
---
|
||||
|
||||
## 4 - Manifest structure
|
||||
|
||||
The DevOps pipeline publishes a deterministic manifest at `deploy/downloads/manifest.json`, signed with the release Cosign key (`DOWNLOADS-CONSOLE-23-001`). The Console fetches it on workspace load and caches it with `If-None-Match` headers to avoid redundant pulls. The manifest schema:
|
||||
|
||||
- **`version`** - monotonically increasing integer tied to pipeline run.
|
||||
- **`generatedAt`** - ISO-8601 UTC timestamp.
|
||||
- **`signature`** - URL to detached Cosign signature (`manifest.json.sig`).
|
||||
- **`artifacts[]`** - ordered list keyed by `id`.
|
||||
|
||||
Each artefact contains:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `id` | Stable identifier (`<type>:<name>:<version>`). |
|
||||
| `kind` | One of `container.image`, `helm.chart`, `compose.bundle`, `offline.bundle`, `export.bundle`, `webhook.config`, `parity.report`. |
|
||||
| `channel` | `edge`, `stable`, or `airgap`. |
|
||||
| `version` | Semantic or calendar version (for containers, matches release manifest). |
|
||||
| `architectures` | Array of supported platforms (empty for arch-agnostic artefacts). |
|
||||
| `digest` | SHA-256 for immutable artefacts; Compose bundles include file hash. |
|
||||
| `sizeBytes` | File size (optional for export bundles that stream). |
|
||||
| `downloadUrl` | HTTPS endpoint (registry, object store, or mirror). |
|
||||
| `signatureUrl` | Detached signature (Cosign, DSSE, or attestation) if available. |
|
||||
| `sbomUrl` | Optional SBOM pointer (CycloneDX JSON). |
|
||||
| `attestationUrl` | Optional in-toto/SLSA attestation. |
|
||||
| `docs` | Array of documentation links (e.g., `/docs/install/docker.md`). |
|
||||
| `tags` | Free-form tags (e.g., `["console","ui","offline"]`). |
|
||||
|
||||
### 4.1 Example excerpt
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 42,
|
||||
"generatedAt": "2025-10-27T04:00:00Z",
|
||||
"signature": "https://downloads.stella-ops.org/manifest/manifest.json.sig",
|
||||
"artifacts": [
|
||||
{
|
||||
"id": "container.image:web-ui:2025.10.0-edge",
|
||||
"kind": "container.image",
|
||||
"channel": "edge",
|
||||
"version": "2025.10.0-edge",
|
||||
"architectures": ["linux/amd64", "linux/arm64"],
|
||||
"digest": "sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
|
||||
"sizeBytes": 187563210,
|
||||
"downloadUrl": "https://registry.stella-ops.org/v2/stellaops/web-ui/manifests/sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
|
||||
"signatureUrl": "https://downloads.stella-ops.org/signatures/web-ui-2025.10.0-edge.cosign.sig",
|
||||
"sbomUrl": "https://downloads.stella-ops.org/sbom/web-ui-2025.10.0-edge.cdx.json",
|
||||
"attestationUrl": "https://downloads.stella-ops.org/attestations/web-ui-2025.10.0-edge.intoto.jsonl",
|
||||
"docs": ["/docs/install/docker.md", "/docs/security/console-security.md"],
|
||||
"tags": ["console", "ui"]
|
||||
},
|
||||
{
|
||||
"id": "offline.bundle:ouk:2025.10.0-edge",
|
||||
"kind": "offline.bundle",
|
||||
"channel": "edge",
|
||||
"version": "2025.10.0-edge",
|
||||
"digest": "sha256:4f7d2f7a8d0cf4b5f3af689f6c74cd213f4c1b3a1d76d24f6f9f3d9075e51f90",
|
||||
"downloadUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz",
|
||||
"signatureUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig",
|
||||
"sbomUrl": "https://downloads.stella-ops.org/offline/offline-manifest-2025.10.0-edge.json",
|
||||
"docs": ["/docs/24_OFFLINE_KIT.md"],
|
||||
"tags": ["offline", "airgap"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Console caches the manifest hash and surfaces differences when a new version lands, helping operators confirm digests drift only when expected.
|
||||
|
||||
---
|
||||
|
||||
## 5 - Download workflows and statuses
|
||||
|
||||
| Status | Applies to | Behaviour |
|
||||
|--------|------------|-----------|
|
||||
| **Ready** | Immutable artefacts (images, Helm/Compose bundles, offline kit) | Commands available immediately. Digest, size, and last verification timestamp display in the table. |
|
||||
| **Pending export** | Async exports queued via `/console/exports` | Shows job owner, scope, and estimated completion time. UI polls every 15 s and updates progress bar. |
|
||||
| **Processing** | Long-running export (evidence bundle, large SBOM) | Drawer shows current stage (`collecting`, `compressing`, `signing`). Operators can cancel if they own the request and hold `downloads.manage`. |
|
||||
| **Delivered** | Completed export within retention window | Provides download links, resume token, and parity snippet for CLI. |
|
||||
| **Expired** | Export past retention or manually expired | Row grays out; clicking opens housekeeping guidance with CLI command to regenerate (`stella runs export --run <id>`). |
|
||||
|
||||
Exports inherit retention defaults defined in policy (`downloads.retentionDays`, min 3, max 30). Operators can override per tenant if they have the appropriate scope.
|
||||
|
||||
---
|
||||
|
||||
## 6 - CLI parity and copy-to-clipboard
|
||||
|
||||
- **Digest pulls:** Each container entry exposes `docker pull <image>@<digest>` and `oras copy <image>@<digest> --to-dir ./downloads` buttons. Commands include architecture hints for multi-platform images.
|
||||
- **Helm/Compose:** Buttons output `helm pull` / `helm install` with the manifest URL and `docker compose --env-file` commands referencing the downloaded bundle.
|
||||
- **Offline kit:** Copy buttons produce the full verification sequence:
|
||||
|
||||
```bash
|
||||
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz
|
||||
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig
|
||||
cosign verify-blob \
|
||||
--key https://stella-ops.org/keys/cosign.pub \
|
||||
--signature stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig \
|
||||
stella-ops-offline-kit-2025.10.0-edge.tar.gz
|
||||
```
|
||||
|
||||
- **Exports:** Drawer lists CLI equivalents (for example, `stella findings export --run <id>`). When the CLI supports resume tokens, the command includes `--resume-token` from the manifest entry.
|
||||
- **Automation:** Webhook tab copies `curl` snippets to subscribe to `/downloads/hooks/subscribe?topic=<artifact>` and includes payload schema for integration tests.
|
||||
|
||||
Parity buttons write commands to the clipboard and display a toast confirming scope hints (for example, `Requires downloads.read + tenant scope`). Accessibility shortcuts (`Shift+D`) trigger the primary copy action for keyboard users.
|
||||
|
||||
---
|
||||
|
||||
## 7 - Offline and air-gap workflow
|
||||
|
||||
- **Manifest sync:** Offline users download `manifest/offline-manifest.json` plus detached JWS and import it via `stella offline kit import`. Console highlights if the offline manifest predates the online manifest by more than 7 days.
|
||||
- **Artefact staging:** The workspace enumerates removable media instructions (export to `./staging/<channel>/`) and warns when artefacts exceed configured media size thresholds.
|
||||
- **Mirrors:** Buttons copy `oras copy` commands that mirror images to an internal registry (`registry.<tenant>.internal`). Operators can toggle `--insecure-policy` if the destination uses custom trust roots.
|
||||
- **Parity checks:** `downloads.offlineParity` flag surfaces the latest parity report verifying that Offline Kit contents match the downloads manifest digests. If diff detected, UI raises a banner linking to remediation steps.
|
||||
- **Audit logging:** Every download command triggered from the UI emits `ui.download.commandCopied` with artifact ID, digest, and tenant. Logs feed the evidence locker so air-gap imports can demonstrate provenance.
|
||||
|
||||
---
|
||||
|
||||
## 8 - Observability and quotas
|
||||
|
||||
| Signal | Source | Description |
|
||||
|--------|--------|-------------|
|
||||
| `ui_download_manifest_refresh_seconds` | Console metrics | Measures time to fetch and verify manifest. Targets < 3 s. |
|
||||
| `ui_download_export_queue_depth` | `/console/downloads` API | Number of pending exports (per tenant). Surfaces as card and Grafana panel. |
|
||||
| `ui_download_command_copied_total` | Console logs | Count of copy actions by artifact type, used to gauge CLI parity adoption. |
|
||||
| `downloads.export.duration` | Export orchestrator | Duration histograms for bundle generation; alerts if P95 > 60 s. |
|
||||
| `downloads.quota.remaining` | Authority quota service | Anonymous users limited to 33 exports/day, verified users 333/day. Banner turns amber at 90 % usage as per platform policy. |
|
||||
|
||||
Telemetry entries include correlation IDs that match backend manifest refresh logs and export job records to keep troubleshooting deterministic.
|
||||
|
||||
---
|
||||
|
||||
## 9 - References
|
||||
|
||||
- `/docs/ui/console-overview.md` - primary shell, tenant controls, SSE ticker.
|
||||
- `/docs/ui/navigation.md` - route ownership and keyboard shortcuts.
|
||||
- `/docs/ui/sbom-explorer.md` - export flows feeding the downloads queue.
|
||||
- `/docs/ui/runs.md` - evidence bundle integration.
|
||||
- `/docs/24_OFFLINE_KIT.md` - offline kit packaging and verification.
|
||||
- `/docs/security/console-security.md` - scopes, CSP, and download token handling.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence checks (pending).
|
||||
- `deploy/releases/*.yaml` - source of container digests mirrored into the manifest.
|
||||
|
||||
---
|
||||
|
||||
## 10 - Compliance checklist
|
||||
|
||||
- [ ] Manifest schema documented (fields, signature, caching) and sample kept current.
|
||||
- [ ] Artefact categories mapped to manifest entries and parity workflows.
|
||||
- [ ] Download statuses, retention, and cancellation rules explained.
|
||||
- [ ] CLI copy-to-clipboard commands mirror console actions with scope hints.
|
||||
- [ ] Offline/air-gap parity workflow, mirror commands, and audit logging captured.
|
||||
- [ ] Observability metrics and quota signalling documented.
|
||||
- [ ] References cross-linked to adjacent docs (navigation, exports, offline kit).
|
||||
- [ ] Accessibility shortcuts and copy-to-clipboard behaviour noted with compliance reminder.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 23).*
|
||||
# StellaOps Console - Downloads Manager
|
||||
|
||||
> **Audience:** DevOps guild, Console engineers, enablement writers, and operators who promote releases or maintain offline mirrors.
|
||||
> **Scope:** `/console/downloads` workspace covering artifact catalog, signed manifest plumbing, export status handling, CLI parity, automation hooks, and offline guidance (Sprint 23).
|
||||
|
||||
The Downloads workspace centralises every artefact required to deploy or validate StellaOps in connected and air-gapped environments. It keeps Console operators aligned with release engineering by surfacing the signed downloads manifest, live export jobs, parity checks against Offline Kit bundles, and automation hooks that mirror the CLI experience.
|
||||
|
||||
---
|
||||
|
||||
## 1 - Access and prerequisites
|
||||
|
||||
- **Route:** `/console/downloads` (list) with detail drawer `/console/downloads/:artifactId`.
|
||||
- **Scopes:** `downloads.read` (baseline) and `downloads.manage` for cancelling or expiring stale exports. Evidence bundles inherit the originating scope (`runs.read`, `findings.read`, etc.).
|
||||
- **Dependencies:** Web gateway `/console/downloads` API (WEB-CONSOLE-23-005), DevOps manifest pipeline (`deploy/downloads/manifest.json`), Offline Kit metadata (`manifest/offline-manifest.json`), and export orchestrator `/console/exports`.
|
||||
- **Feature flags:** `downloads.workspace.enabled`, `downloads.exportQueue`, `downloads.offlineParity`.
|
||||
- **Tenancy:** Artefacts are tenant-agnostic except evidence bundles, which are tagged with originating tenant and require matching Authority scopes.
|
||||
|
||||
---
|
||||
|
||||
## 2 - Workspace layout
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------+
|
||||
| Header: Snapshot timestamp - Manifest signature status |
|
||||
+---------------------------------------------------------------+
|
||||
| Cards: Latest release - Offline kit parity - Export queue |
|
||||
+---------------------------------------------------------------+
|
||||
| Tabs: Artefacts | Exports | Offline Kits | Webhooks |
|
||||
+---------------------------------------------------------------+
|
||||
| Filter bar: Channel - Kind - Architecture - Scope tags |
|
||||
+---------------------------------------------------------------+
|
||||
| Table (virtualised): Artifact | Channel | Digest | Status |
|
||||
| Detail drawer: Metadata | Commands | Provenance | History |
|
||||
+---------------------------------------------------------------+
|
||||
```
|
||||
|
||||
- **Snapshot banner:** shows `manifest.version`, `generatedAt`, and cosign verification state. If verification fails, the banner turns red and links to troubleshooting guidance.
|
||||
- **Quick actions:** Copy manifest URL, download attestation bundle, trigger parity check, open CLI parity doc (`/docs/cli-vs-ui-parity.md`).
|
||||
- **Filters:** allow narrowing by channel (`edge`, `stable`, `airgap`), artefact kind (`container.image`, `helm.chart`, `compose.bundle`, `offline.bundle`, `export.bundle`), architecture (`linux/amd64`, `linux/arm64`), and scope tags (`console`, `scheduler`, `authority`).
|
||||
|
||||
---
|
||||
|
||||
## 3 - Artefact catalogue
|
||||
|
||||
| Category | Artefacts surfaced | Source | Notes |
|
||||
|----------|-------------------|--------|-------|
|
||||
| **Core containers** | `stellaops/web-ui`, `stellaops/web`, `stellaops/concelier`, `stellaops/excititor`, `stellaops/scanner-*`, `stellaops/authority`, `stellaops/attestor`, `stellaops/scheduler-*` | `deploy/downloads/manifest.json` (`artifacts[].kind = "container.image"`) | Digest-only pulls with copy-to-clipboard `docker pull` and `oras copy` commands; badges show arch availability. |
|
||||
| **Helm charts** | `deploy/helm/stellaops-*.tgz` plus values files | Manifest entries where `kind = "helm.chart"` | Commands reference `helm repo add` (online) and `helm install --values` (offline). UI links to values matrix in `/docs/install/helm-prod.md` when available. |
|
||||
| **Compose bundles** | `deploy/compose/docker-compose.*.yaml`, `.env` seeds | `kind = "compose.bundle"` | Inline diff viewer highlights digest changes vs previous snapshot; `docker compose pull` command copies digest pins. |
|
||||
| **Offline kit** | `stella-ops-offline-kit-<ver>-<channel>.tar.gz` + signatures and manifest | Offline Kit metadata (`manifest/offline-manifest.json`) merged into downloads view | Drawer shows bundle size, signed manifest digest, cosign verification command (mirrors `/docs/24_OFFLINE_KIT.md`). |
|
||||
| **Evidence exports** | Completed jobs from `/console/exports` (findings delta, policy explain, run evidence) | Export orchestrator job queue | Entries expire after retention window; UI exposes `stella runs export` and `stella findings export` parity buttons. |
|
||||
| **Webhooks & parity** | `/downloads/hooks/subscribe` configs, CI parity reports | Manifest extras (`kind = "webhook.config"`, `kind = "parity.report"`) | Operators can download webhook payload templates and review the latest CLI parity check report generated by docs CI. |
|
||||
|
||||
---
|
||||
|
||||
## 4 - Manifest structure
|
||||
|
||||
The DevOps pipeline publishes a deterministic manifest at `deploy/downloads/manifest.json`, signed with the release Cosign key (`DOWNLOADS-CONSOLE-23-001`). The Console fetches it on workspace load and caches it with `If-None-Match` headers to avoid redundant pulls. The manifest schema:
|
||||
|
||||
- **`version`** - monotonically increasing integer tied to pipeline run.
|
||||
- **`generatedAt`** - ISO-8601 UTC timestamp.
|
||||
- **`signature`** - URL to detached Cosign signature (`manifest.json.sig`).
|
||||
- **`artifacts[]`** - ordered list keyed by `id`.
|
||||
|
||||
Each artefact contains:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `id` | Stable identifier (`<type>:<name>:<version>`). |
|
||||
| `kind` | One of `container.image`, `helm.chart`, `compose.bundle`, `offline.bundle`, `export.bundle`, `webhook.config`, `parity.report`. |
|
||||
| `channel` | `edge`, `stable`, or `airgap`. |
|
||||
| `version` | Semantic or calendar version (for containers, matches release manifest). |
|
||||
| `architectures` | Array of supported platforms (empty for arch-agnostic artefacts). |
|
||||
| `digest` | SHA-256 for immutable artefacts; Compose bundles include file hash. |
|
||||
| `sizeBytes` | File size (optional for export bundles that stream). |
|
||||
| `downloadUrl` | HTTPS endpoint (registry, object store, or mirror). |
|
||||
| `signatureUrl` | Detached signature (Cosign, DSSE, or attestation) if available. |
|
||||
| `sbomUrl` | Optional SBOM pointer (CycloneDX JSON). |
|
||||
| `attestationUrl` | Optional in-toto/SLSA attestation. |
|
||||
| `docs` | Array of documentation links (e.g., `/docs/install/docker.md`). |
|
||||
| `tags` | Free-form tags (e.g., `["console","ui","offline"]`). |
|
||||
|
||||
### 4.1 Example excerpt
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 42,
|
||||
"generatedAt": "2025-10-27T04:00:00Z",
|
||||
"signature": "https://downloads.stella-ops.org/manifest/manifest.json.sig",
|
||||
"artifacts": [
|
||||
{
|
||||
"id": "container.image:web-ui:2025.10.0-edge",
|
||||
"kind": "container.image",
|
||||
"channel": "edge",
|
||||
"version": "2025.10.0-edge",
|
||||
"architectures": ["linux/amd64", "linux/arm64"],
|
||||
"digest": "sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
|
||||
"sizeBytes": 187563210,
|
||||
"downloadUrl": "https://registry.stella-ops.org/v2/stellaops/web-ui/manifests/sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
|
||||
"signatureUrl": "https://downloads.stella-ops.org/signatures/web-ui-2025.10.0-edge.cosign.sig",
|
||||
"sbomUrl": "https://downloads.stella-ops.org/sbom/web-ui-2025.10.0-edge.cdx.json",
|
||||
"attestationUrl": "https://downloads.stella-ops.org/attestations/web-ui-2025.10.0-edge.intoto.jsonl",
|
||||
"docs": ["/docs/install/docker.md", "/docs/security/console-security.md"],
|
||||
"tags": ["console", "ui"]
|
||||
},
|
||||
{
|
||||
"id": "offline.bundle:ouk:2025.10.0-edge",
|
||||
"kind": "offline.bundle",
|
||||
"channel": "edge",
|
||||
"version": "2025.10.0-edge",
|
||||
"digest": "sha256:4f7d2f7a8d0cf4b5f3af689f6c74cd213f4c1b3a1d76d24f6f9f3d9075e51f90",
|
||||
"downloadUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz",
|
||||
"signatureUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig",
|
||||
"sbomUrl": "https://downloads.stella-ops.org/offline/offline-manifest-2025.10.0-edge.json",
|
||||
"docs": ["/docs/24_OFFLINE_KIT.md"],
|
||||
"tags": ["offline", "airgap"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Console caches the manifest hash and surfaces differences when a new version lands, helping operators confirm digests drift only when expected.
|
||||
|
||||
---
|
||||
|
||||
## 5 - Download workflows and statuses
|
||||
|
||||
| Status | Applies to | Behaviour |
|
||||
|--------|------------|-----------|
|
||||
| **Ready** | Immutable artefacts (images, Helm/Compose bundles, offline kit) | Commands available immediately. Digest, size, and last verification timestamp display in the table. |
|
||||
| **Pending export** | Async exports queued via `/console/exports` | Shows job owner, scope, and estimated completion time. UI polls every 15 s and updates progress bar. |
|
||||
| **Processing** | Long-running export (evidence bundle, large SBOM) | Drawer shows current stage (`collecting`, `compressing`, `signing`). Operators can cancel if they own the request and hold `downloads.manage`. |
|
||||
| **Delivered** | Completed export within retention window | Provides download links, resume token, and parity snippet for CLI. |
|
||||
| **Expired** | Export past retention or manually expired | Row grays out; clicking opens housekeeping guidance with CLI command to regenerate (`stella runs export --run <id>`). |
|
||||
|
||||
Exports inherit retention defaults defined in policy (`downloads.retentionDays`, min 3, max 30). Operators can override per tenant if they have the appropriate scope.
|
||||
|
||||
---
|
||||
|
||||
## 6 - CLI parity and copy-to-clipboard
|
||||
|
||||
- **Digest pulls:** Each container entry exposes `docker pull <image>@<digest>` and `oras copy <image>@<digest> --to-dir ./downloads` buttons. Commands include architecture hints for multi-platform images.
|
||||
- **Helm/Compose:** Buttons output `helm pull` / `helm install` with the manifest URL and `docker compose --env-file` commands referencing the downloaded bundle.
|
||||
- **Offline kit:** Copy buttons produce the full verification sequence:
|
||||
|
||||
```bash
|
||||
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz
|
||||
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig
|
||||
cosign verify-blob \
|
||||
--key https://stella-ops.org/keys/cosign.pub \
|
||||
--signature stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig \
|
||||
stella-ops-offline-kit-2025.10.0-edge.tar.gz
|
||||
```
|
||||
|
||||
- **Exports:** Drawer lists CLI equivalents (for example, `stella findings export --run <id>`). When the CLI supports resume tokens, the command includes `--resume-token` from the manifest entry.
|
||||
- **Automation:** Webhook tab copies `curl` snippets to subscribe to `/downloads/hooks/subscribe?topic=<artifact>` and includes payload schema for integration tests.
|
||||
|
||||
Parity buttons write commands to the clipboard and display a toast confirming scope hints (for example, `Requires downloads.read + tenant scope`). Accessibility shortcuts (`Shift+D`) trigger the primary copy action for keyboard users.
|
||||
|
||||
---
|
||||
|
||||
## 7 - Offline and air-gap workflow
|
||||
|
||||
- **Manifest sync:** Offline users download `manifest/offline-manifest.json` plus detached JWS and import it via `stella offline kit import`. Console highlights if the offline manifest predates the online manifest by more than 7 days.
|
||||
- **Artefact staging:** The workspace enumerates removable media instructions (export to `./staging/<channel>/`) and warns when artefacts exceed configured media size thresholds.
|
||||
- **Mirrors:** Buttons copy `oras copy` commands that mirror images to an internal registry (`registry.<tenant>.internal`). Operators can toggle `--insecure-policy` if the destination uses custom trust roots.
|
||||
- **Parity checks:** `downloads.offlineParity` flag surfaces the latest parity report verifying that Offline Kit contents match the downloads manifest digests. If diff detected, UI raises a banner linking to remediation steps.
|
||||
- **Audit logging:** Every download command triggered from the UI emits `ui.download.commandCopied` with artifact ID, digest, and tenant. Logs feed the evidence locker so air-gap imports can demonstrate provenance.
|
||||
|
||||
---
|
||||
|
||||
## 8 - Observability and quotas
|
||||
|
||||
| Signal | Source | Description |
|
||||
|--------|--------|-------------|
|
||||
| `ui_download_manifest_refresh_seconds` | Console metrics | Measures time to fetch and verify manifest. Targets < 3 s. |
|
||||
| `ui_download_export_queue_depth` | `/console/downloads` API | Number of pending exports (per tenant). Surfaces as card and Grafana panel. |
|
||||
| `ui_download_command_copied_total` | Console logs | Count of copy actions by artifact type, used to gauge CLI parity adoption. |
|
||||
| `downloads.export.duration` | Export orchestrator | Duration histograms for bundle generation; alerts if P95 > 60 s. |
|
||||
| `downloads.quota.remaining` | Authority quota service | Anonymous users limited to 33 exports/day, verified users 333/day. Banner turns amber at 90 % usage as per platform policy. |
|
||||
|
||||
Telemetry entries include correlation IDs that match backend manifest refresh logs and export job records to keep troubleshooting deterministic.
|
||||
|
||||
---
|
||||
|
||||
## 9 - References
|
||||
|
||||
- `/docs/ui/console-overview.md` - primary shell, tenant controls, SSE ticker.
|
||||
- `/docs/ui/navigation.md` - route ownership and keyboard shortcuts.
|
||||
- `/docs/ui/sbom-explorer.md` - export flows feeding the downloads queue.
|
||||
- `/docs/ui/runs.md` - evidence bundle integration.
|
||||
- `/docs/24_OFFLINE_KIT.md` - offline kit packaging and verification.
|
||||
- `/docs/security/console-security.md` - scopes, CSP, and download token handling.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence checks (pending).
|
||||
- `deploy/releases/*.yaml` - source of container digests mirrored into the manifest.
|
||||
|
||||
---
|
||||
|
||||
## 10 - Compliance checklist
|
||||
|
||||
- [ ] Manifest schema documented (fields, signature, caching) and sample kept current.
|
||||
- [ ] Artefact categories mapped to manifest entries and parity workflows.
|
||||
- [ ] Download statuses, retention, and cancellation rules explained.
|
||||
- [ ] CLI copy-to-clipboard commands mirror console actions with scope hints.
|
||||
- [ ] Offline/air-gap parity workflow, mirror commands, and audit logging captured.
|
||||
- [ ] Observability metrics and quota signalling documented.
|
||||
- [ ] References cross-linked to adjacent docs (navigation, exports, offline kit).
|
||||
- [ ] Accessibility shortcuts and copy-to-clipboard behaviour noted with compliance reminder.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 23).*
|
||||
|
||||
@@ -143,9 +143,9 @@ Explain drawer includes copy-to-clipboard buttons for rule chain and evidence JS
|
||||
|
||||
## 10. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- 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).*
|
||||
|
||||
|
||||
@@ -1,163 +1,163 @@
|
||||
# StellaOps Console - Navigation
|
||||
|
||||
> **Audience:** Console UX writers, UI engineers, QA, and enablement teams.
|
||||
> **Scope:** Primary route map, layout conventions, keyboard shortcuts, deep-link patterns, and tenant context switching for the StellaOps Console (Sprint 23).
|
||||
|
||||
The navigation framework keeps Console workflows predictable across tenants and deployment modes. This guide explains how the global shell, feature routes, and context tokens cooperate so operators can jump between findings, SBOMs, advisories, policies, and runs without losing scope.
|
||||
|
||||
---
|
||||
|
||||
## 1. Information Architecture
|
||||
|
||||
### 1.1 Primary routes
|
||||
|
||||
| Route pattern | Module owner | Purpose | Required scopes (minimum) | Core services |
|
||||
|---------------|--------------|---------|---------------------------|---------------|
|
||||
| `/console/dashboard` | Web gateway | Landing KPIs, feed age, queue depth, alerts | `ui.read` | Web, Scheduler WebService, Concelier WebService, Excititor WebService |
|
||||
| `/console/findings` | Policy Engine | Aggregated findings, explain drawer, export | `findings.read` | Policy Engine, Concelier WebService, SBOM Service |
|
||||
| `/console/sbom` | SBOM Service | Catalog view, component graph, overlays | `sbom.read` | SBOM Service, Policy Engine (overlays) |
|
||||
| `/console/advisories` | Concelier | Advisory aggregation with provenance banners | `advisory.read` | Concelier WebService |
|
||||
| `/console/vex` | Excititor | VEX aggregation, consensus, conflicts | `vex.read` | Excititor WebService |
|
||||
| `/console/runs` | Scheduler | Run list, live progress, evidence downloads | `runs.read` | Scheduler WebService, Policy Engine, Scanner WebService |
|
||||
| `/console/policies` | Policy Engine | Editor, simulations, approvals | `policy.read` (read) / `policy.write` (edit) | Policy Engine, Authority |
|
||||
| `/console/downloads` | DevOps | Signed artifacts, Offline Kit parity checklist | `downloads.read` | DevOps manifest API, Offline Kit |
|
||||
| `/console/admin` | Authority | Tenants, roles, tokens, integrations | `ui.admin` (plus scoped `authority:*`) | Authority |
|
||||
| `/console/help` | Docs Guild | Guides, tours, release notes | `ui.read` | Docs static assets |
|
||||
|
||||
### 1.2 Secondary navigation elements
|
||||
|
||||
- **Left rail:** highlights the active top-level route, exposes quick metrics, and shows pinned saved views. Keyboard focus cycles through rail entries with `Tab`/`Shift+Tab`.
|
||||
- **Breadcrumb bar:** renders `Home / Module / Detail` format. Detail crumbs include IDs and titles for shareable context (for example, `Findings / High Severity / CVE-2025-1234`).
|
||||
- **Action shelf:** right-aligned controls for context actions (export, verify, retry). Buttons disable automatically if the current subject lacks the requisite scope.
|
||||
|
||||
---
|
||||
|
||||
## 2. Command Palette and Search
|
||||
|
||||
- **Trigger:** `Ctrl/Cmd + K`. Palette opens in place, keeps focus, and announces results via ARIA live region.
|
||||
- **Capabilities:** jump to routes, saved views, tenants, recent entities (findings, SBOMs, advisories), and command actions (for example, "Start verification", "Open explain drawer").
|
||||
- **Result tokens:** palette entries carry metadata (`type`, `tenant`, `filters`). Selecting an item updates the URL and applies stored filters without a full reload.
|
||||
- **Offline fallback:** in sealed/offline mode, palette restricts actions to cached routes and saved views; remote-only items show a grayed-out badge.
|
||||
|
||||
---
|
||||
|
||||
## 3. Global Filters and Context Chips
|
||||
|
||||
| Control | Shortcut | Persistence | Notes |
|
||||
|---------|----------|-------------|-------|
|
||||
| **Tenant picker** | `Ctrl/Cmd + T` | SessionStorage + URL `tenant` query | Issues fresh Authority token, invalidates caches, emits `ui.tenant.switch` log. |
|
||||
| **Filter tray** | `Shift + F` | IndexedDB (per tenant) + URL query (`since`, `severity`, `tags`, `source`, `status`, `policyView`) | Applies instantly to compatible routes; incompatible filters show a reset suggestion. |
|
||||
| **Component search** | `/` when filters closed | URL `component` query | Context-aware; scopes results to current tenant and module. |
|
||||
| **Time window** | `Ctrl/Cmd + Shift + 1-4` | URL `since`/`until`, palette preset | Mapped to preset windows: 24 h, 7 d, 30 d, custom. |
|
||||
|
||||
Context chips appear beneath page titles summarising active filters (for example, `Tenant: west-prod`, `Severity: Critical+High`, `Time: Last 7 days`). Removing a chip updates the tray and URL atomically.
|
||||
|
||||
---
|
||||
|
||||
## 4. Keyboard Shortcut Matrix
|
||||
|
||||
| Scope | Shortcut (Mac / Windows) | Action | Notes |
|
||||
|-------|--------------------------|--------|-------|
|
||||
| Global | `Cmd+K / Ctrl+K` | Open command palette | Accessible from any route except modal dialogs. |
|
||||
| Global | `Cmd+T / Ctrl+T` | Open tenant switcher | Requires `ui.read`. Confirm selection with `Enter`; `Esc` cancels without switching. |
|
||||
| Global | `Shift+F` | Toggle global filter tray | Focus lands on first filter control. |
|
||||
| Global | `Cmd+1-9 / Ctrl+1-9` | Load saved view preset | Each preset bound per tenant; non-assigned keys show tooltip. |
|
||||
| Global | `?` | Show keyboard reference overlay | Overlay lists context-specific shortcuts; closes with `Esc`. |
|
||||
| Findings module | `Cmd+/ / Ctrl+/` | Focus explain search | Works when explain drawer is open. |
|
||||
| SBOM module | `Cmd+G / Ctrl+G` | Toggle graph overlays | Persists per session. |
|
||||
| Advisories & VEX | `Cmd+Opt+F / Ctrl+Alt+F` | Focus provider filter | Highlights provider chip strip. |
|
||||
| Runs module | `Cmd+R / Ctrl+R` | Refresh SSE snapshot | Schedules soft refresh (no hard reload). |
|
||||
| Policies module | `Cmd+S / Ctrl+S` | Save draft (if edit rights) | Mirrors Policy Editor behaviour. |
|
||||
|
||||
Shortcut handling follows WCAG 2.2 best practices: all accelerators are remappable via Settings -> Accessibility -> Keyboard shortcuts, and the overlay documents platform differences.
|
||||
|
||||
---
|
||||
|
||||
## 5. Deep-Link Patterns
|
||||
|
||||
### 5.1 URL schema
|
||||
|
||||
Console URLs adopt the format:
|
||||
|
||||
```
|
||||
/console/<route>[/:id][/:tab]?tenant=<slug>&since=<iso>&severity=<list>&view=<token>&panel=<drawer>&component=<purl>
|
||||
```
|
||||
|
||||
- **`tenant`** is mandatory and matches Authority slugs (e.g., `acme-prod`).
|
||||
- **`since` / `until`** use ISO-8601 timestamps (UTC). Preset ranges set only `since`; UI computes `until` on load.
|
||||
- **`severity`** accepts comma-separated policy buckets (e.g., `critical,high,kev`).
|
||||
- **`view`** stores module-specific state (e.g., `sbomView=usage`, `findingsPreset=threat-hunting`).
|
||||
- **`panel`** selects drawers or tabs (`panel=explain`, `panel=timeline`).
|
||||
|
||||
### 5.2 Copyable links
|
||||
|
||||
- Share links from the action shelf or context chips; both copy canonical URLs with all active filters.
|
||||
- CLI parity: inline callouts provide `stella` commands derived from the URL parameters to ensure console/CLI equivalence.
|
||||
- Offline note: links copied in sealed mode include the snapshot ID (`snapshot=<hash>`) so recipients know which offline data set to load.
|
||||
|
||||
### 5.3 Examples
|
||||
|
||||
- **`since` / `until`** use ISO-8601 timestamps (UTC). Preset ranges set only `since`; UI computes `until` on load.
|
||||
- **`severity`** accepts comma-separated policy buckets (e.g., `critical,high,kev`).
|
||||
- **`view`** stores module-specific state (e.g., `sbomView=usage`, `findingsPreset=threat-hunting`).
|
||||
- **`panel`** selects drawers or tabs (`panel=explain`, `panel=timeline`).
|
||||
- **`component`** encodes package selection using percent-encoded PURL syntax.
|
||||
- **`snapshot`** appears when copying links offline to reference Offline Kit build hash.
|
||||
@@
|
||||
| Use case | Example URL | Description |
|
||||
|----------|-------------|-------------|
|
||||
| Findings triage | `/console/findings?v=table&severity=critical,high&tenant=west-prod&since=2025-10-20T00:00:00Z` | Opens the findings table limited to critical/high for west-prod, last 7 days. |
|
||||
| SBOM component focus | `/console/sbom/sha256:abcd?tenant=west-prod&component=pkg:npm/react@18.3.0&view=usage` | Deep-links to a specific image digest and highlights an NPM package in Usage view. |
|
||||
| Advisory explain | `/console/advisories?tenant=west-prod&source=nvd&panel=detail&documentId=CVE-2025-1234` | Opens advisory list filtered to NVD and expands CVE detail drawer. |
|
||||
| Run monitor | `/console/runs/42?tenant=west-prod&panel=progress` | Focuses run ID 42 with progress drawer active (SSE stream attached). |
|
||||
|
||||
---
|
||||
|
||||
## 6. Tenant Switching Lifecycle
|
||||
|
||||
1. **Initiate:** User triggers `Ctrl/Cmd + T` or clicks the tenant badge. Switcher modal lists authorised tenants and recent selections.
|
||||
2. **Preview:** Selecting a tenant shows summary (environment, last snapshot, role coverage). The modal flags tenants missing required scopes for the current route.
|
||||
3. **Confirm:** On confirmation, the UI requests a new DPoP-bound access token from Authority (`aud=console`, `tenant=<id>`).
|
||||
4. **Invalidate caches:** Stores keyed by tenant purge automatically; modules emit `tenantChanged` events so in-flight SSE streams reconnect with new headers.
|
||||
5. **Restore state:** Global filters reapply where valid. Incompatible filters (for example, a saved view unavailable in the new tenant) prompt users to pick a fallback.
|
||||
6. **Audit and telemetry:** `ui.tenant.switch` log writes subject, from/to tenant, correlation ID. Metric `ui_tenant_switch_total` increments for observability dashboards.
|
||||
7. **Offline behaviour:** If the target tenant is absent from the offline snapshot, switcher displays guidance to import updated Offline Kit data before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## 7. Breadcrumbs, Tabs, and Focus Management
|
||||
|
||||
- Breadcrumb titles update synchronously with route data loads. When fragments change (for example, selecting a finding), the breadcrumb text updates without pushing a new history entry to keep back/forward predictable.
|
||||
- Detail views rely on accessible tabs (`role="tablist"`) with keyboard support (`ArrowLeft/Right`). Tab selection updates the URL `tab` parameter for deep linking.
|
||||
- Focus management:
|
||||
- Route changes send focus to the primary heading (`h1`) using the live region announcer.
|
||||
- Opening drawers or modals traps focus until closed; ESC returns focus to the triggering element.
|
||||
- Keyboard-only navigation is validated via automated Playwright accessibility checks as part of `DEVOPS-CONSOLE-23-001`.
|
||||
|
||||
---
|
||||
|
||||
## 8. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - structural overview, tenant model, global filters.
|
||||
- `/docs/ui/sbom-explorer.md` - SBOM-specific navigation and graphs (pending).
|
||||
- `/docs/ui/advisories-and-vex.md` - aggregation UX details (pending).
|
||||
- `/docs/ui/findings.md` - findings filters and explain drawer (pending).
|
||||
- `/docs/security/console-security.md` - Authority, scopes, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
- `/docs/accessibility.md` - keyboard remapping, WCAG validation checklists.
|
||||
|
||||
---
|
||||
|
||||
## 9. Compliance Checklist
|
||||
|
||||
- [ ] Route table matches Console build (paths, scopes, owners verified with Console Guild).
|
||||
- [ ] Keyboard shortcut matrix reflects implemented accelerators and accessibility overlay.
|
||||
- [ ] Deep-link examples tested for copy/share parity and CLI alignment.
|
||||
- [ ] Tenant switching flow documents cache invalidation and audit logging.
|
||||
- [ ] Filter tray, command palette, and presets cross-referenced with accessibility guidance.
|
||||
- [ ] Offline/air-gap notes included for palette, tenant switcher, and deep-link metadata.
|
||||
- [ ] Links to dependent docs (`/docs/ui/*`, `/docs/security/*`) validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
# StellaOps Console - Navigation
|
||||
|
||||
> **Audience:** Console UX writers, UI engineers, QA, and enablement teams.
|
||||
> **Scope:** Primary route map, layout conventions, keyboard shortcuts, deep-link patterns, and tenant context switching for the StellaOps Console (Sprint 23).
|
||||
|
||||
The navigation framework keeps Console workflows predictable across tenants and deployment modes. This guide explains how the global shell, feature routes, and context tokens cooperate so operators can jump between findings, SBOMs, advisories, policies, and runs without losing scope.
|
||||
|
||||
---
|
||||
|
||||
## 1. Information Architecture
|
||||
|
||||
### 1.1 Primary routes
|
||||
|
||||
| Route pattern | Module owner | Purpose | Required scopes (minimum) | Core services |
|
||||
|---------------|--------------|---------|---------------------------|---------------|
|
||||
| `/console/dashboard` | Web gateway | Landing KPIs, feed age, queue depth, alerts | `ui.read` | Web, Scheduler WebService, Concelier WebService, Excititor WebService |
|
||||
| `/console/findings` | Policy Engine | Aggregated findings, explain drawer, export | `findings.read` | Policy Engine, Concelier WebService, SBOM Service |
|
||||
| `/console/sbom` | SBOM Service | Catalog view, component graph, overlays | `sbom.read` | SBOM Service, Policy Engine (overlays) |
|
||||
| `/console/advisories` | Concelier | Advisory aggregation with provenance banners | `advisory.read` | Concelier WebService |
|
||||
| `/console/vex` | Excititor | VEX aggregation, consensus, conflicts | `vex.read` | Excititor WebService |
|
||||
| `/console/runs` | Scheduler | Run list, live progress, evidence downloads | `runs.read` | Scheduler WebService, Policy Engine, Scanner WebService |
|
||||
| `/console/policies` | Policy Engine | Editor, simulations, approvals | `policy.read` (read) / `policy.write` (edit) | Policy Engine, Authority |
|
||||
| `/console/downloads` | DevOps | Signed artifacts, Offline Kit parity checklist | `downloads.read` | DevOps manifest API, Offline Kit |
|
||||
| `/console/admin` | Authority | Tenants, roles, tokens, integrations | `ui.admin` (plus scoped `authority:*`) | Authority |
|
||||
| `/console/help` | Docs Guild | Guides, tours, release notes | `ui.read` | Docs static assets |
|
||||
|
||||
### 1.2 Secondary navigation elements
|
||||
|
||||
- **Left rail:** highlights the active top-level route, exposes quick metrics, and shows pinned saved views. Keyboard focus cycles through rail entries with `Tab`/`Shift+Tab`.
|
||||
- **Breadcrumb bar:** renders `Home / Module / Detail` format. Detail crumbs include IDs and titles for shareable context (for example, `Findings / High Severity / CVE-2025-1234`).
|
||||
- **Action shelf:** right-aligned controls for context actions (export, verify, retry). Buttons disable automatically if the current subject lacks the requisite scope.
|
||||
|
||||
---
|
||||
|
||||
## 2. Command Palette and Search
|
||||
|
||||
- **Trigger:** `Ctrl/Cmd + K`. Palette opens in place, keeps focus, and announces results via ARIA live region.
|
||||
- **Capabilities:** jump to routes, saved views, tenants, recent entities (findings, SBOMs, advisories), and command actions (for example, "Start verification", "Open explain drawer").
|
||||
- **Result tokens:** palette entries carry metadata (`type`, `tenant`, `filters`). Selecting an item updates the URL and applies stored filters without a full reload.
|
||||
- **Offline fallback:** in sealed/offline mode, palette restricts actions to cached routes and saved views; remote-only items show a grayed-out badge.
|
||||
|
||||
---
|
||||
|
||||
## 3. Global Filters and Context Chips
|
||||
|
||||
| Control | Shortcut | Persistence | Notes |
|
||||
|---------|----------|-------------|-------|
|
||||
| **Tenant picker** | `Ctrl/Cmd + T` | SessionStorage + URL `tenant` query | Issues fresh Authority token, invalidates caches, emits `ui.tenant.switch` log. |
|
||||
| **Filter tray** | `Shift + F` | IndexedDB (per tenant) + URL query (`since`, `severity`, `tags`, `source`, `status`, `policyView`) | Applies instantly to compatible routes; incompatible filters show a reset suggestion. |
|
||||
| **Component search** | `/` when filters closed | URL `component` query | Context-aware; scopes results to current tenant and module. |
|
||||
| **Time window** | `Ctrl/Cmd + Shift + 1-4` | URL `since`/`until`, palette preset | Mapped to preset windows: 24 h, 7 d, 30 d, custom. |
|
||||
|
||||
Context chips appear beneath page titles summarising active filters (for example, `Tenant: west-prod`, `Severity: Critical+High`, `Time: Last 7 days`). Removing a chip updates the tray and URL atomically.
|
||||
|
||||
---
|
||||
|
||||
## 4. Keyboard Shortcut Matrix
|
||||
|
||||
| Scope | Shortcut (Mac / Windows) | Action | Notes |
|
||||
|-------|--------------------------|--------|-------|
|
||||
| Global | `Cmd+K / Ctrl+K` | Open command palette | Accessible from any route except modal dialogs. |
|
||||
| Global | `Cmd+T / Ctrl+T` | Open tenant switcher | Requires `ui.read`. Confirm selection with `Enter`; `Esc` cancels without switching. |
|
||||
| Global | `Shift+F` | Toggle global filter tray | Focus lands on first filter control. |
|
||||
| Global | `Cmd+1-9 / Ctrl+1-9` | Load saved view preset | Each preset bound per tenant; non-assigned keys show tooltip. |
|
||||
| Global | `?` | Show keyboard reference overlay | Overlay lists context-specific shortcuts; closes with `Esc`. |
|
||||
| Findings module | `Cmd+/ / Ctrl+/` | Focus explain search | Works when explain drawer is open. |
|
||||
| SBOM module | `Cmd+G / Ctrl+G` | Toggle graph overlays | Persists per session. |
|
||||
| Advisories & VEX | `Cmd+Opt+F / Ctrl+Alt+F` | Focus provider filter | Highlights provider chip strip. |
|
||||
| Runs module | `Cmd+R / Ctrl+R` | Refresh SSE snapshot | Schedules soft refresh (no hard reload). |
|
||||
| Policies module | `Cmd+S / Ctrl+S` | Save draft (if edit rights) | Mirrors Policy Editor behaviour. |
|
||||
|
||||
Shortcut handling follows WCAG 2.2 best practices: all accelerators are remappable via Settings -> Accessibility -> Keyboard shortcuts, and the overlay documents platform differences.
|
||||
|
||||
---
|
||||
|
||||
## 5. Deep-Link Patterns
|
||||
|
||||
### 5.1 URL schema
|
||||
|
||||
Console URLs adopt the format:
|
||||
|
||||
```
|
||||
/console/<route>[/:id][/:tab]?tenant=<slug>&since=<iso>&severity=<list>&view=<token>&panel=<drawer>&component=<purl>
|
||||
```
|
||||
|
||||
- **`tenant`** is mandatory and matches Authority slugs (e.g., `acme-prod`).
|
||||
- **`since` / `until`** use ISO-8601 timestamps (UTC). Preset ranges set only `since`; UI computes `until` on load.
|
||||
- **`severity`** accepts comma-separated policy buckets (e.g., `critical,high,kev`).
|
||||
- **`view`** stores module-specific state (e.g., `sbomView=usage`, `findingsPreset=threat-hunting`).
|
||||
- **`panel`** selects drawers or tabs (`panel=explain`, `panel=timeline`).
|
||||
|
||||
### 5.2 Copyable links
|
||||
|
||||
- Share links from the action shelf or context chips; both copy canonical URLs with all active filters.
|
||||
- CLI parity: inline callouts provide `stella` commands derived from the URL parameters to ensure console/CLI equivalence.
|
||||
- Offline note: links copied in sealed mode include the snapshot ID (`snapshot=<hash>`) so recipients know which offline data set to load.
|
||||
|
||||
### 5.3 Examples
|
||||
|
||||
- **`since` / `until`** use ISO-8601 timestamps (UTC). Preset ranges set only `since`; UI computes `until` on load.
|
||||
- **`severity`** accepts comma-separated policy buckets (e.g., `critical,high,kev`).
|
||||
- **`view`** stores module-specific state (e.g., `sbomView=usage`, `findingsPreset=threat-hunting`).
|
||||
- **`panel`** selects drawers or tabs (`panel=explain`, `panel=timeline`).
|
||||
- **`component`** encodes package selection using percent-encoded PURL syntax.
|
||||
- **`snapshot`** appears when copying links offline to reference Offline Kit build hash.
|
||||
@@
|
||||
| Use case | Example URL | Description |
|
||||
|----------|-------------|-------------|
|
||||
| Findings triage | `/console/findings?v=table&severity=critical,high&tenant=west-prod&since=2025-10-20T00:00:00Z` | Opens the findings table limited to critical/high for west-prod, last 7 days. |
|
||||
| SBOM component focus | `/console/sbom/sha256:abcd?tenant=west-prod&component=pkg:npm/react@18.3.0&view=usage` | Deep-links to a specific image digest and highlights an NPM package in Usage view. |
|
||||
| Advisory explain | `/console/advisories?tenant=west-prod&source=nvd&panel=detail&documentId=CVE-2025-1234` | Opens advisory list filtered to NVD and expands CVE detail drawer. |
|
||||
| Run monitor | `/console/runs/42?tenant=west-prod&panel=progress` | Focuses run ID 42 with progress drawer active (SSE stream attached). |
|
||||
|
||||
---
|
||||
|
||||
## 6. Tenant Switching Lifecycle
|
||||
|
||||
1. **Initiate:** User triggers `Ctrl/Cmd + T` or clicks the tenant badge. Switcher modal lists authorised tenants and recent selections.
|
||||
2. **Preview:** Selecting a tenant shows summary (environment, last snapshot, role coverage). The modal flags tenants missing required scopes for the current route.
|
||||
3. **Confirm:** On confirmation, the UI requests a new DPoP-bound access token from Authority (`aud=console`, `tenant=<id>`).
|
||||
4. **Invalidate caches:** Stores keyed by tenant purge automatically; modules emit `tenantChanged` events so in-flight SSE streams reconnect with new headers.
|
||||
5. **Restore state:** Global filters reapply where valid. Incompatible filters (for example, a saved view unavailable in the new tenant) prompt users to pick a fallback.
|
||||
6. **Audit and telemetry:** `ui.tenant.switch` log writes subject, from/to tenant, correlation ID. Metric `ui_tenant_switch_total` increments for observability dashboards.
|
||||
7. **Offline behaviour:** If the target tenant is absent from the offline snapshot, switcher displays guidance to import updated Offline Kit data before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## 7. Breadcrumbs, Tabs, and Focus Management
|
||||
|
||||
- Breadcrumb titles update synchronously with route data loads. When fragments change (for example, selecting a finding), the breadcrumb text updates without pushing a new history entry to keep back/forward predictable.
|
||||
- Detail views rely on accessible tabs (`role="tablist"`) with keyboard support (`ArrowLeft/Right`). Tab selection updates the URL `tab` parameter for deep linking.
|
||||
- Focus management:
|
||||
- Route changes send focus to the primary heading (`h1`) using the live region announcer.
|
||||
- Opening drawers or modals traps focus until closed; ESC returns focus to the triggering element.
|
||||
- Keyboard-only navigation is validated via automated Playwright accessibility checks as part of `DEVOPS-CONSOLE-23-001`.
|
||||
|
||||
---
|
||||
|
||||
## 8. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - structural overview, tenant model, global filters.
|
||||
- `/docs/ui/sbom-explorer.md` - SBOM-specific navigation and graphs (pending).
|
||||
- `/docs/ui/advisories-and-vex.md` - aggregation UX details (pending).
|
||||
- `/docs/ui/findings.md` - findings filters and explain drawer (pending).
|
||||
- `/docs/security/console-security.md` - Authority, scopes, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
- `/docs/accessibility.md` - keyboard remapping, WCAG validation checklists.
|
||||
|
||||
---
|
||||
|
||||
## 9. Compliance Checklist
|
||||
|
||||
- [ ] Route table matches Console build (paths, scopes, owners verified with Console Guild).
|
||||
- [ ] Keyboard shortcut matrix reflects implemented accelerators and accessibility overlay.
|
||||
- [ ] Deep-link examples tested for copy/share parity and CLI alignment.
|
||||
- [ ] Tenant switching flow documents cache invalidation and audit logging.
|
||||
- [ ] Filter tray, command palette, and presets cross-referenced with accessibility guidance.
|
||||
- [ ] Offline/air-gap notes included for palette, tenant switcher, and deep-link metadata.
|
||||
- [ ] Links to dependent docs (`/docs/ui/*`, `/docs/security/*`) validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
@@ -158,9 +158,9 @@ UI disables controls not allowed by current scope and surfaces tooltip with requ
|
||||
## 12. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- ``
|
||||
- `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).
|
||||
|
||||
---
|
||||
|
||||
@@ -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: `` (add after UI team captures latest build).
|
||||
> Placeholder screenshot: `docs/assets/policy-editor/workspace.png` (pending upload after UI team captures latest build).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -134,8 +134,8 @@ Sections:
|
||||
## 11. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- `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).
|
||||
|
||||
---
|
||||
|
||||
@@ -161,8 +161,8 @@ Saved views store combinations of these filters and expose command palette short
|
||||
## 10. Screenshot coordination
|
||||
|
||||
- Placeholder images:
|
||||
- ``
|
||||
- ``
|
||||
- `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.
|
||||
|
||||
---
|
||||
|
||||
@@ -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
17
docs/updates/2025-10-30-devops-governance.md
Normal 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.
|
||||
@@ -17,12 +17,13 @@ storage:
|
||||
databaseName: "stellaops_authority"
|
||||
commandTimeout: "00:00:30"
|
||||
|
||||
signing:
|
||||
enabled: true
|
||||
activeKeyId: "authority-signing-dev"
|
||||
keyPath: "../certificates/authority-signing-dev.pem"
|
||||
algorithm: "ES256"
|
||||
keySource: "file"
|
||||
signing:
|
||||
enabled: true
|
||||
activeKeyId: "authority-signing-dev"
|
||||
keyPath: "../certificates/authority-signing-dev.pem"
|
||||
algorithm: "ES256"
|
||||
keySource: "file"
|
||||
jwksCacheLifetime: "00:05:00"
|
||||
|
||||
bootstrap:
|
||||
enabled: false
|
||||
|
||||
@@ -24,17 +24,18 @@ storage:
|
||||
commandTimeout: "00:00:30"
|
||||
|
||||
# Signing configuration for revocation bundles and JWKS.
|
||||
signing:
|
||||
enabled: true
|
||||
activeKeyId: "authority-signing-2025-dev"
|
||||
keyPath: "../certificates/authority-signing-2025-dev.pem"
|
||||
algorithm: "ES256"
|
||||
keySource: "file"
|
||||
# provider: "default"
|
||||
additionalKeys:
|
||||
- keyId: "authority-signing-dev"
|
||||
path: "../certificates/authority-signing-dev.pem"
|
||||
source: "file"
|
||||
signing:
|
||||
enabled: true
|
||||
activeKeyId: "authority-signing-2025-dev"
|
||||
keyPath: "../certificates/authority-signing-2025-dev.pem"
|
||||
algorithm: "ES256"
|
||||
keySource: "file"
|
||||
jwksCacheLifetime: "00:05:00"
|
||||
# provider: "default"
|
||||
additionalKeys:
|
||||
- keyId: "authority-signing-dev"
|
||||
path: "../certificates/authority-signing-dev.pem"
|
||||
source: "file"
|
||||
# Rotation flow:
|
||||
# 1. Generate a new PEM under ./certificates (e.g. authority-signing-2026-dev.pem).
|
||||
# 2. Trigger the .gitea/workflows/authority-key-rotation.yml workflow (or run
|
||||
|
||||
5
ops/authority/TASKS.completed.md
Normal file
5
ops/authority/TASKS.completed.md
Normal 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. |
|
||||
@@ -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
5
ops/deployment/TASKS.completed.md
Normal 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,8 +1,7 @@
|
||||
# Deployment Task Board
|
||||
|
||||
# Deployment Task Board
|
||||
|
||||
| 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
27
ops/devops/TASKS.completed.md
Normal 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. |
|
||||
@@ -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
83
ops/devops/telemetry/validate_storage_stack.py
Normal 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
5
ops/licensing/TASKS.completed.md
Normal 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,5 +1,4 @@
|
||||
# Licensing Task Board
|
||||
|
||||
| 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. |
|
||||
# Licensing Task Board
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
|
||||
8
ops/offline-kit/TASKS.completed.md
Normal file
8
ops/offline-kit/TASKS.completed.md
Normal 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. |
|
||||
@@ -1,14 +1,10 @@
|
||||
# Offline Kit Task Board
|
||||
|
||||
# Offline Kit Task Board
|
||||
|
||||
| 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
8
samples/TASKS.completed.md
Normal 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. |
|
||||
@@ -1,16 +1,12 @@
|
||||
# Samples Task Board
|
||||
|
||||
| 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 Task Board
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
};
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -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>
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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
7
src/Attestor/StellaOps.Attestor/TASKS.completed.md
Normal 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. |
|
||||
@@ -1,11 +1,8 @@
|
||||
# Attestor Guild Task Board (UTC 2025-10-19)
|
||||
|
||||
| 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. |
|
||||
|
||||
# Attestor Guild Task Board (UTC 2025-10-19)
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
|
||||
> 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
689
src/Authority/StellaOps.Api.OpenApi/authority/openapi.yaml
Normal 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
|
||||
@@ -51,12 +51,22 @@ public static class StellaOpsClaimTypes
|
||||
public const string Audience = "aud";
|
||||
|
||||
/// <summary>
|
||||
/// Identity provider hint for downstream services.
|
||||
/// </summary>
|
||||
public const string IdentityProvider = "stellaops:idp";
|
||||
|
||||
/// <summary>
|
||||
/// Session identifier claim (<c>sid</c>).
|
||||
/// </summary>
|
||||
public const string SessionId = "sid";
|
||||
}
|
||||
/// Identity provider hint for downstream services.
|
||||
/// </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>
|
||||
public const string SessionId = "sid";
|
||||
}
|
||||
|
||||
@@ -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. |
|
||||
@@ -1,20 +1,16 @@
|
||||
# Team 8 / Plugin Standard Backlog (UTC 2025-10-10)
|
||||
|
||||
| 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. |
|
||||
| PLG6.DIAGRAM | TODO | Docs Guild | PLG6.DOC | Export final sequence/component diagrams for the developer guide and add offline-friendly assets under `docs/assets/authority`. | ✅ Mermaid sources committed; ✅ Rendered SVG/PNG linked from Section 2 + Section 9; ✅ Docs build preview shared with Plugin + Docs guilds. |
|
||||
|
||||
> Update statuses to DOING/DONE/BLOCKED as you make progress. Always run `dotnet test` for touched projects before marking DONE.
|
||||
|
||||
> Remark (2025-10-13, PLG6.DOC/PLG6.DIAGRAM): Security Guild delivered `docs/security/rate-limits.md`; Docs team can lift Section 3 (tuning table + alerts) into the developer guide diagrams when rendering assets.
|
||||
|
||||
> Check-in (2025-10-19): Wave 0A dependencies (AUTH-DPOP-11-001, AUTH-MTLS-11-002, PLUGIN-DI-08-001) still open, so SEC2/SEC3/SEC5 remain in progress without new scope until upstream limiter updates land.
|
||||
# Team 8 / Plugin Standard Backlog (UTC 2025-10-10)
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| 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. |
|
||||
| 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. |
|
||||
| PLG6.DIAGRAM | TODO | Docs Guild | PLG6.DOC | Export final sequence/component diagrams for the developer guide and add offline-friendly assets under `docs/assets/authority`. | ✅ Mermaid sources committed; ✅ Rendered SVG/PNG linked from Section 2 + Section 9; ✅ Docs build preview shared with Plugin + Docs guilds. |
|
||||
|
||||
> Update statuses to DOING/DONE/BLOCKED as you make progress. Always run `dotnet test` for touched projects before marking DONE.
|
||||
|
||||
> Remark (2025-10-13, PLG6.DOC/PLG6.DIAGRAM): Security Guild delivered `docs/security/rate-limits.md`; Docs team can lift Section 3 (tuning table + alerts) into the developer guide diagrams when rendering assets.
|
||||
|
||||
> Check-in (2025-10-19): Wave 0A dependencies (AUTH-DPOP-11-001, AUTH-MTLS-11-002, PLUGIN-DI-08-001) still open, so SEC2/SEC3/SEC5 remain in progress without new scope until upstream limiter updates land.
|
||||
|
||||
@@ -593,11 +593,18 @@ public class ClientCredentialsHandlersTests
|
||||
Assert.Equal(new[] { "orch:operate" }, grantedScopes);
|
||||
var tenant = Assert.IsType<string>(context.Transaction.Properties[AuthorityOpenIddictConstants.ClientTenantProperty]);
|
||||
Assert.Equal("tenant-default", tenant);
|
||||
var reason = Assert.IsType<string>(context.Transaction.Properties[AuthorityOpenIddictConstants.OperatorReasonProperty]);
|
||||
Assert.Equal("resume source after maintenance", reason);
|
||||
var ticket = Assert.IsType<string>(context.Transaction.Properties[AuthorityOpenIddictConstants.OperatorTicketProperty]);
|
||||
Assert.Equal("INC-2045", ticket);
|
||||
}
|
||||
var reason = Assert.IsType<string>(context.Transaction.Properties[AuthorityOpenIddictConstants.OperatorReasonProperty]);
|
||||
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]
|
||||
public async Task ValidateClientCredentials_RejectsExportViewer_WhenTenantMissing()
|
||||
|
||||
@@ -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)
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
{
|
||||
|
||||
@@ -4,15 +4,16 @@ using System.Globalization;
|
||||
using System.IO;
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.AspNetCore.Http;
|
||||
using Microsoft.Extensions.Configuration;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Microsoft.Extensions.DependencyInjection.Extensions;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Microsoft.Extensions.Options;
|
||||
using Microsoft.Extensions.Configuration;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Microsoft.Extensions.DependencyInjection.Extensions;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Microsoft.Extensions.Options;
|
||||
using Microsoft.AspNetCore.RateLimiting;
|
||||
using Microsoft.AspNetCore.Server.Kestrel.Https;
|
||||
using Microsoft.Extensions.Logging.Abstractions;
|
||||
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;
|
||||
@@ -111,11 +112,12 @@ if (issuerUri is null)
|
||||
}
|
||||
|
||||
authorityOptions.Issuer = issuerUri;
|
||||
builder.Services.AddSingleton(authorityOptions);
|
||||
builder.Services.AddSingleton<IOptions<StellaOpsAuthorityOptions>>(Options.Create(authorityOptions));
|
||||
builder.Services.AddHttpContextAccessor();
|
||||
builder.Services.TryAddSingleton<TimeProvider>(_ => TimeProvider.System);
|
||||
builder.Services.TryAddSingleton<IAuthorityRateLimiterMetadataAccessor, AuthorityRateLimiterMetadataAccessor>();
|
||||
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,8 +1295,26 @@ app.MapPost("/permalinks/vuln", async (
|
||||
.RequireAuthorization(policy => policy.RequireStellaOpsScopes(StellaOpsScopes.VulnRead))
|
||||
.WithName("CreateVulnPermalink");
|
||||
|
||||
app.MapGet("/jwks", (AuthorityJwksService jwksService) => Results.Ok(jwksService.Build()))
|
||||
.WithName("JsonWebKeySet");
|
||||
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.
|
||||
app.Services.GetRequiredService<AuthoritySigningKeyManager>();
|
||||
|
||||
@@ -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")]
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user