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

Add SBOM, symbols, traces, and VEX files for CVE-2022-21661 SQLi case
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- Created CycloneDX and SPDX SBOM files for both reachable and unreachable images.
- Added symbols.json detailing function entry and sink points in the WordPress code.
- Included runtime traces for function calls in both reachable and unreachable scenarios.
- Developed OpenVEX files indicating vulnerability status and justification for both cases.
- Updated README for evaluator harness to guide integration with scanner output.
This commit is contained in:
master
2025-11-08 20:53:45 +02:00
parent 515975edc5
commit 536f6249a6
837 changed files with 37279 additions and 14675 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/11_AUTHORITY.md
View File

@@ -132,7 +132,7 @@ These registrations are provided as examples in `etc/authority.yaml.sample`. Clo
- **Interactive only.** `policy:publish` and `policy:promote` are restricted to password/device-code flows (Console, CLI) and are rejected when requested via client credentials or app secrets. Tokens inherit the 5-minute fresh-auth window; resource servers reject stale tokens and emit `authority.policy_attestation_validated=false`.
- **Mandatory parameters.** Requests must include:
- `policy_reason` (≤512 chars) — human-readable justification (e.g., “Promote tenant A baseline to production”).
- Authority enforces mTLS bindings on /token, /fresh-auth, and /introspect by comparing the presented TLS client certificate thumbprint against the stored claim. Requests missing a certificate or presenting a different certificate are rejected with , and the counter is incremented for operational alerts.
- `policy_ticket` (≤128 chars) — change request / CAB identifier (e.g., `CR-2025-1102`).
- `policy_digest` — lowercase hex digest (32–128 characters) of the policy bundle being published/promoted.
- **Audit surfaces.** On success, the metadata is copied into the access token (`stellaops:policy_reason`, `stellaops:policy_ticket`, `stellaops:policy_digest`, `stellaops:policy_operation`) and recorded in [`authority.password.grant`] audit events as `policy.*` properties.
@@ -142,6 +142,14 @@ These registrations are provided as examples in `etc/authority.yaml.sample`. Clo
Graph Explorer introduces dedicated scopes: `graph:write` for Cartographer build jobs, `graph:read` for query/read operations, `graph:export` for long-running export downloads, and `graph:simulate` for what-if overlays. Assign only the scopes a client actually needs to preserve least privilege—UI-facing clients should typically request read/export access, while background services (Cartographer, Scheduler) require write privileges.
### Policy activation dual-control
- **Config knobs.** `PolicyEngine.activation.forceTwoPersonApproval` forces every activation to collect two distinct `policy:activate` approvals (first response = `202 pending_second_approval`). `PolicyEngine.activation.defaultRequiresTwoPersonApproval` sets the default when callers omit the flag.
- **Operator choice.** When force is disabled, Console/CLI can opt any revision into dual-control by setting `requiresTwoPersonApproval: true`; the service persists the requirement alongside the revision metadata.
- **Audit coverage.** With `PolicyEngine.activation.emitAuditLogs` (default `true`), every activation emits structured `policy.activation.*` logger scopes (pack id, revision, actor(s), tenant, approval count, comment) so SOC pipelines can diff the two-person trail.
- **Status codes.** First approval on a dual-control revision returns `202 pending_second_approval`; duplicates produce `400 duplicate_approval`; the second distinct actor returns the usual `200 activated`.
#### Least-privilege guidance for graph clients
- **Service identities** – The Cartographer worker should request `graph:write` and `graph:read` only; grant `graph:simulate` exclusively to pipeline automation that invokes Policy Engine overlays on demand. Keep `graph:export` scoped to API gateway components responsible for streaming GraphML/JSONL artifacts. Authority enforces this by rejecting `graph:write` tokens that lack `properties.serviceIdentity: cartographer`.
@@ -356,6 +364,7 @@ exceptions:
| Bootstrap | `bootstrap.apiKey` | Shared secret required for `/internal/*`. | Only required when `bootstrap.enabled` is true. |
### 7.1 Sender-constrained clients (DPoP & mTLS)
> Rollout tracker: see [`docs/security/dpop-mtls-rollout.md`](security/dpop-mtls-rollout.md) for phase gates tied to `AUTH-DPOP-11-001` and `AUTH-MTLS-11-002`.
Authority now understands two flavours of sender-constrained OAuth clients:
@@ -386,6 +395,7 @@ Authority now understands two flavours of sender-constrained OAuth clients:
- Declare client `audiences` in bootstrap manifests or plug-in provisioning metadata; Authority now defaults the token `aud` claim and `resource` indicator from this list, which is also used to trigger nonce enforcement for audiences such as `signer` and `attestor`.
- **Mutual TLS clients** – client registrations may declare an mTLS binding (`senderConstraint: mtls`). When enabled via `security.senderConstraints.mtls`, Authority validates the presented client certificate against stored bindings (`certificateBindings[]`), optional chain verification, and timing windows. Successful requests embed `cnf.x5t#S256` into the access token (and introspection output) so resource servers can enforce the certificate thumbprint.
- `security.senderConstraints.mtls.enforceForAudiences` forces mTLS whenever the requested `aud`/`resource` (or the client's configured audiences) intersect the configured allow-list (default includes `signer`). Clients configured for different sender constraints are rejected early so operator policy remains consistent.
- Authority enforces mTLS bindings on `/token`, `/fresh-auth`, and `/introspect` by comparing the presented TLS client certificate thumbprint against the stored `authority_sender_certificate_hex` claim. Requests missing a certificate or presenting a different certificate are rejected with `invalid_token`, and the `authority_mtls_mismatch_total{reason=...}` counter is incremented for visibility.
- Certificate bindings now act as an allow-list: Authority verifies thumbprint, subject, issuer, serial number, and any declared SAN values against the presented certificate, with rotation grace windows applied to `notBefore/notAfter`. Operators can enforce subject regexes, SAN type allow-lists (`dns`, `uri`, `ip`), trusted certificate authorities, and rotation grace via `security.senderConstraints.mtls.*`.
Both modes persist additional metadata in `authority_tokens`: `senderConstraint` records the enforced policy, while `senderKeyThumbprint` stores the DPoP JWK thumbprint or mTLS certificate hash captured at issuance. Downstream services can rely on these fields (and the corresponding `cnf` claim) when auditing offline copies of the token store.

58
docs/19_TEST_SUITE_OVERVIEW.md
View File

@@ -57,7 +57,62 @@ The script spins up MongoDB/Redis via Testcontainers and requires:
* Docker ≥ 25
* Node 20 (for Jest/Playwright)
---
#### Mongo2Go / OpenSSL shim
Multiple suites (Concelier connectors, Excititor worker/WebService, Scheduler)
fall back to [Mongo2Go](https://github.com/Mongo2Go/Mongo2Go) when a developer
does not have a local `mongod` listening on `127.0.0.1:27017`. Modern distros
ship OpenSSL 3 by default, so you **must** expose the legacy OpenSSL 1.1
libraries that the embedded `mongod` requires:
1. From the repo root, export the provided binaries before running any tests:
```bash
export LD_LIBRARY_PATH="$(pwd)/tests/native/openssl-1.1/linux-x64:${LD_LIBRARY_PATH:-}"
```
2. (Optional) If you only need the shim for a single command, prefix it:
```bash
LD_LIBRARY_PATH="$(pwd)/tests/native/openssl-1.1/linux-x64" \
dotnet test src/Concelier/StellaOps.Concelier.sln --nologo
```
3. CI runners or dev containers should either copy
`tests/native/openssl-1.1/linux-x64/libcrypto.so.1.1` and `libssl.so.1.1`
into a directory that is already on the default library path, or export the
`LD_LIBRARY_PATH` value shown above before invoking `dotnet test`.
The shim lives under `tests/native/openssl-1.1/README.md` with upstream source
and licensing details. When the system already has OpenSSL 1.1 installed you
can skip this step.
#### Local Mongo helper
Some suites (Concelier WebService/Core, Exporter JSON) need a full
`mongod` instance when you want to debug outside of Mongo2Go (for example to
inspect data with `mongosh` or pin a specific server version). A thin wrapper
is available under `tools/mongodb/local-mongo.sh`:
```bash
# download (cached under .cache/mongodb-local) and start a local replica set
tools/mongodb/local-mongo.sh start
# reuse an existing data set
tools/mongodb/local-mongo.sh restart
# stop / clean
tools/mongodb/local-mongo.sh stop
tools/mongodb/local-mongo.sh clean
```
By default the script downloads MongoDB 6.0.16 for Ubuntu 22.04, binds to
`127.0.0.1:27017`, and initialises a single-node replica set called `rs0`. The
current URI is printed on start, e.g.
`mongodb://127.0.0.1:27017/?replicaSet=rs0`, and you can export it before
running `dotnet test` if a suite supports overriding its connection string.
---
### Concelier OSV↔GHSA parity fixtures
@@ -106,4 +161,3 @@ flowchart LR
---
*Last updated {{ "now" | date: "%Y‑%m‑%d" }}*

4
docs/TASKS.md
View File

@@ -8,6 +8,7 @@
| DOCS-REPLAY-185-004 | TODO | Docs Guild, Platform Guild | REPLAY-CORE-185-001 | Expand `docs/replay/DEVS_GUIDE_REPLAY.md` with integration checklist and cross-links to sections 3 & 11 of `docs/replay/DETERMINISTIC_REPLAY.md`. | Guide updated with checklist; references validated; lint passes. |
| DOCS-REPLAY-186-004 | TODO | Docs Guild, Scanner Guild | SCAN-REPLAY-186-001 | Publish `docs/replay/TEST_STRATEGY.md` detailing golden replay, feed drift, and tool upgrade verification steps; link from scanner architecture doc. | New doc merged; links verified; CI scenario notes documented. |
| RUNBOOK-REPLAY-187-004 | TODO | Docs Guild, Ops Guild | EVID-REPLAY-187-001, CLI-REPLAY-187-002 | Create `/docs/runbooks/replay_ops.md` covering retention enforcement, RootPack rotation, offline kit workflows, and verification drills referencing `docs/replay/DETERMINISTIC_REPLAY.md`. | Runbook merged; rehearsal notes captured; cross-links added. |
| DOCS-REACH-201-006 | TODO | Docs Guild | ZASTAVA-REACH-201-001, SCAN-REACH-201-002, SIGNALS-REACH-201-003 | Author reachability doc suite (`docs/signals/reachability.md`, `docs/signals/callgraph-formats.md`, `docs/signals/runtime-facts.md`, CLI/UI appendices) plus embed replay evidence guidance. | Docs merged with imposed rule text; cross-links to Scanner/Zastava/Replay guides validated. |
| 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. |
@@ -304,7 +305,8 @@
> 2025-11-03: DOCS-AIAI-31-002 completed – architecture deep dive documents pipeline, deterministic tooling, caching, profiles, and deployment guidance.
| DOCS-AIAI-31-003 | DONE (2025-11-03) | Docs Guild, Advisory AI Guild | AIAI-31-006 | Write `/docs/advisory-ai/api.md` describing endpoints, schemas, errors, rate limits. | API doc aligned with OpenAPI; examples validated; checklist appended. |
> 2025-11-03: DOCS-AIAI-31-003 completed – `docs/advisory-ai/api.md` covers scopes, request/response schema, rate limits, error codes, observability, offline notes.
| DOCS-AIAI-31-004 | BLOCKED (2025-11-03) | Docs Guild, Console Guild | CONSOLE-VULN-29-001, CONSOLE-VEX-30-001, EXCITITOR-CONSOLE-23-001 | Create `/docs/advisory-ai/console.md` with screenshots, a11y notes, copy-as-ticket instructions. | Doc merged; images stored; checklist appended. |
| DOCS-AIAI-31-004 | DOING (2025-11-07) | Docs Guild, Console Guild | CONSOLE-VULN-29-001, CONSOLE-VEX-30-001, EXCITITOR-CONSOLE-23-001 | Create `/docs/advisory-ai/console.md` with screenshots, a11y notes, copy-as-ticket instructions. | Doc merged; images stored; checklist appended. |
> 2025-11-07: Draft outline committed; waiting on final console endpoints for screenshots + API captures.
> 2025-11-03: BLOCKED – waiting for Console endpoints/widgets (CONSOLE-VULN-29-001, CONSOLE-VEX-30-001, EXCITITOR-CONSOLE-23-001) to land before documenting UI flows.
| DOCS-AIAI-31-005 | BLOCKED (2025-11-03) | Docs Guild, DevEx/CLI Guild | CLI-VULN-29-001, CLI-VEX-30-001, AIAI-31-004C | Publish `/docs/advisory-ai/cli.md` covering commands, exit codes, scripting patterns. | Doc merged; examples tested; checklist appended. |
> 2025-11-03: BLOCKED – awaiting CLI implementation (`stella advise run`) and golden outputs (CLI-VULN-29-001, CLI-VEX-30-001, AIAI-31-004C).

35
docs/advisory-ai/console.md Normal file
View File

@@ -0,0 +1,35 @@
# Advisory AI Console Workflows
_Last updated: 2025-11-07_
This guide documents the forthcoming Advisory AI console experience so that console, docs, and QA guilds share a single reference while the new endpoints finish landing.
## 1. Entry points & navigation
- **Dashboard tile**: `Advisory AI` card on the console overview routes to `/console/vuln/advisory-ai` once CONSOLE-VULN-29-001 ships. The tile must include the current model build stamp and data freshness time.
- **Deep links**: Copy-as-ticket payloads link back into the console using `/console/vex/{statementId}` (CONSOLE-VEX-30-001). Provide fallbacks that open the Evidence modal with a toast if the workspace is still loading.
## 2. Evidence surfacing
| Workflow | Required API | Notes |
| --- | --- | --- |
| Findings overview | `GET /console/vuln/findings` | Must include policy verdict badge, VEX justification summary, and last-seen timestamps. |
| Evidence drawer | `GET /console/vex/statements/{id}` | Stream SSE chunk descriptions so long-form provenance renders progressively. |
| Copy as ticket | `POST /console/vuln/tickets` | Returns signed payload + attachment list for JIRA/ServiceNow templates. |
## 3. Accessibility & offline requirements
- Console screens must pass WCAG 2.2 AA contrast and provide focus order that matches the keyboard shortcuts planned for Advisory AI (see `docs/advisory-ai/overview.md`).
- All screenshots captured for this doc must come from sealed-mode bundles (no external fonts/CDNs). Store them under `docs/assets/advisory-ai/console/` with hashed filenames.
- Modal dialogs need `aria-describedby` attributes referencing the explanation text returned by the API; translation strings must live with existing locale packs.
## 4. Copy-as-ticket guidance
1. Operators select one or more VEX-backed findings.
2. Console renders the sanitized payload (JSON) plus context summary for the receiving system.
3. Users can download the payload or send it via webhook; both flows must log `console.ticket.export` events for audit.
## 5. Open items before publication
- [ ] Replace placeholder API responses with captures from the first merged build of CONSOLE-VULN-29-001 / CONSOLE-VEX-30-001.
- [ ] Capture at least two screenshots (list view + evidence drawer) once UI polish is complete.
- [ ] Verify copy-as-ticket instructions with Support to ensure the payload fields align with existing SOC runbooks.
> Tracking: DOCS-AIAI-31-004 (Docs Guild, Console Guild)
**Reference**: API contracts and sample payloads live in `docs/api/console/workspaces.md` (see `/console/vuln/*` and `/console/vex/*` sections) plus the JSON fixtures under `docs/api/console/samples/`.

5
docs/api/console/samples/vex-statement-sse.ndjson Normal file
View File

@@ -0,0 +1,5 @@
{"event":"statement.created","data":{"statementId":"vex:tenant-default:jwt-auth:5d1a","advisoryId":"CVE-2024-12345","product":"registry.local/ops/auth:2025.10.0","state":"under_investigation","justification":"exploit_observed","sequence":4178,"updatedAt":"2025-11-07T23:10:09Z"}}
{"event":"statement.updated","data":{"statementId":"vex:tenant-default:jwt-auth:5d1a","advisoryId":"CVE-2024-12345","product":"registry.local/ops/auth:2025.10.0","state":"fixed","justification":"solution_available","sequence":4182,"updatedAt":"2025-11-08T11:44:32Z"}}
{"event":"statement.conflict","data":{"statementId":"vex:tenant-default:jwt-auth:5d1a","advisoryId":"CVE-2024-12345","product":"registry.local/ops/auth:2025.10.0","conflictSummary":"Excititor statement GHSA-1111 differs on status","sequence":4183,"updatedAt":"2025-11-08T11:44:59Z"}}
{"event":"statement.updated","data":{"statementId":"vex:tenant-default:jwt-auth:5d1a","advisoryId":"CVE-2024-12345","product":"registry.local/ops/auth:2025.10.0","state":"fixed","justification":"solution_available","sequence":4184,"updatedAt":"2025-11-08T11:45:04Z"}}
{"event":"statement.deleted","data":{"statementId":"vex:tenant-default:legacy:1a2b","advisoryId":"CVE-2023-9999","product":"registry.local/ops/legacy:2024.01.0","sequence":4185,"updatedAt":"2025-11-08T12:01:01Z"}}

84
docs/api/console/samples/vuln-findings-sample.json Normal file
View File

@@ -0,0 +1,84 @@
{
"items": [
{
"findingId": "tenant-default:advisory-ai:sha256:5d1a",
"coordinates": {
"advisoryId": "CVE-2024-12345",
"package": "pkg:npm/jsonwebtoken@9.0.2",
"component": "jwt-auth-service",
"image": "registry.local/ops/auth:2025.10.0"
},
"summary": "jsonwebtoken <10.0.0 allows algorithm downgrade.",
"severity": "high",
"cvss": 8.1,
"kev": true,
"policyBadge": "fail",
"vex": {
"statementId": "vex:tenant-default:jwt-auth:5d1a",
"state": "under_investigation",
"justification": "Advisory AI flagged reachable path via Scheduler run 42."
},
"reachability": {
"status": "reachable",
"lastObserved": "2025-11-07T23:11:04Z",
"signalsVersion": "signals-2025.310.1"
},
"evidence": {
"sbomDigest": "sha256:6c81f2bbd8bd7336f197f3f68fba2f76d7287dd1a5e2a0f0e9f14f23f3c2f917",
"policyRunId": "policy-run::2025-11-07::ca9f",
"attestationId": "dsse://authority/attest/84a2"
},
"timestamps": {
"firstSeen": "2025-10-31T04:22:18Z",
"lastSeen": "2025-11-07T23:16:51Z"
}
},
{
"findingId": "tenant-default:advisory-ai:sha256:9bf4",
"coordinates": {
"advisoryId": "GHSA-xxxx-yyyy-zzzz",
"package": "pkg:docker/library/nginx@1.25.2",
"component": "ingress-gateway",
"image": "registry.local/ops/ingress:2025.09.1"
},
"summary": "Heap overflow in nginx HTTP/3 parsing.",
"severity": "critical",
"cvss": 9.8,
"kev": false,
"policyBadge": "warn",
"vex": {
"statementId": "vex:tenant-default:ingress:9bf4",
"state": "not_affected",
"justification": "component_not_present"
},
"reachability": {
"status": "unknown",
"signalsVersion": "signals-2025.309.0"
},
"evidence": {
"sbomDigest": "sha256:99f1e2a7aa0f7c970dcb6674244f0bfb5f37148e3ee09fd4f925d3358dea2239",
"policyRunId": "policy-run::2025-11-06::b210",
"attestationId": "dsse://authority/attest/1d34"
},
"timestamps": {
"firstSeen": "2025-10-29T18:03:11Z",
"lastSeen": "2025-11-07T10:45:03Z"
}
}
],
"facets": {
"severity": [
{ "value": "critical", "count": 1 },
{ "value": "high", "count": 1 }
],
"policyBadge": [
{ "value": "fail", "count": 1 },
{ "value": "warn", "count": 1 }
],
"reachability": [
{ "value": "reachable", "count": 1 },
{ "value": "unknown", "count": 1 }
]
},
"nextPageToken": "eyJjdXJzb3IiOiJmZjg0NiJ9"
}

311
docs/api/console/workspaces.md Normal file
View File

@@ -0,0 +1,311 @@
# Console Workspaces API
_Tracking: CONSOLE-VULN-29-001, CONSOLE-VEX-30-001, DOCS-AIAI-31-004_
## 1. Goals & Scope
The console workspaces provide read-only aggregates for Advisory AI operators:
- `/console/vuln/*` surfaces tenant-scoped findings annotated with policy verdicts, VEX justifications, Scheduler reachability signals, and Advisory AI rationale.
- `/console/vex/*` streams the underlying VEX statements, conflicts, and justification summaries (with SSE support for live updates).
All endpoints MUST:
1. Remain deterministic offline (stable sort keys, ISO-8601 UTC timestamps, hashed assets).
2. Operate with Authority-issued DPoP or mTLS client credentials that include `console:read` and either `vuln:read` or `vex:read`.
3. Respect tenant isolation – every request carries `X-StellaOps-Tenant`.
## 2. Shared Request/Response Conventions
| Requirement | Description |
| --- | --- |
| Headers | `Authorization: DPoP <token>`, `DPoP: <proof>`, `X-StellaOps-Tenant: <tenantId>`, `Accept: application/json` (or `text/event-stream` for SSE). |
| Pagination | Cursor-based via `pageToken`; defaults to 50 items, max 200. Cursors are opaque, base64url, signed. |
| Sorting | Findings sorted by `(severity desc, exploitScore desc, findingId asc)`. Statements sorted by `(lastUpdated desc, statementId asc)`. |
| Dates | RFC 3339 / ISO-8601 UTC (e.g., `2025-11-08T12:02:11Z`). |
| Determinism | All arrays must be pre-sorted; no server-generated uuids in responses. |
## 3. Vulnerability Workspace (`/console/vuln/*`)
### 3.1 `GET /console/vuln/findings`
Query parameters:
| Parameter | Type | Notes |
| --- | --- | --- |
| `pageToken` | string | Optional cursor from previous response. |
| `pageSize` | int | 1-200, default 50. |
| `severity` | string[] | Accepts `critical`, `high`, `medium`, `low`, `info`. |
| `product` | string[] | SBOM `purl` or image digest anchors. |
| `policyBadge` | string[] | `pass`, `warn`, `fail`, `waived`. |
| `vexState` | string[] | `not_affected`, `fixed`, `under_investigation`, etc. |
| `reachability` | string[] | `reachable`, `unreachable`, `unknown`. |
| `search` | string | Substring match on CVE/GHSA/KEV ID (case-insensitive). |
Response body:
```jsonc
{
"items": [
{
"findingId": "tenant-default:advisory-ai:sha256:5d1a",
"coordinates": {
"advisoryId": "CVE-2024-12345",
"package": "pkg:npm/jsonwebtoken@9.0.2",
"component": "jwt-auth-service",
"image": "registry.local/ops/auth:2025.10.0"
},
"summary": "jsonwebtoken <10.0.0 allows algorithm downgrade.",
"severity": "high",
"cvss": 8.1,
"kev": true,
"policyBadge": "fail",
"vex": {
"statementId": "vex:tenant-default:jwt-auth:5d1a",
"state": "under_investigation",
"justification": "Advisory AI flagged reachable path via Scheduler run 42."
},
"reachability": {
"status": "reachable",
"lastObserved": "2025-11-07T23:11:04Z",
"signalsVersion": "signals-2025.310.1"
},
"evidence": {
"sbomDigest": "sha256:6c81…",
"policyRunId": "policy-run::2025-11-07::ca9f",
"attestationId": "dsse://authority/attest/84a2"
},
"timestamps": {
"firstSeen": "2025-10-31T04:22:18Z",
"lastSeen": "2025-11-07T23:16:51Z"
}
}
],
"facets": {
"severity": [
{ "value": "critical", "count": 2 },
{ "value": "high", "count": 7 }
],
"policyBadge": [
{ "value": "fail", "count": 6 },
{ "value": "warn", "count": 3 },
{ "value": "waived", "count": 1 }
],
"reachability": [
{ "value": "reachable", "count": 5 },
{ "value": "unreachable", "count": 2 },
{ "value": "unknown", "count": 1 }
]
},
"nextPageToken": "eyJjdXJzb3IiOiJmZjg0NiJ9"
}
```
### 3.2 `GET /console/vuln/facets`
Returns the full facet catalog (counts by severity, product, policy badge, VEX state, reachability, KEV flag). Designed for sidebar filters without paging; identical parameter surface as `/findings`.
### 3.3 `GET /console/vuln/{findingId}`
Returns the full finding document, including evidence timeline, policy overlays, and export-ready metadata:
```jsonc
{
"findingId": "tenant-default:advisory-ai:sha256:5d1a",
"details": {
"description": "jsonwebtoken <10.0.0 allows algorithm downgrade.",
"references": [
"https://nvd.nist.gov/vuln/detail/CVE-2024-12345",
"https://github.com/auth0/node-jsonwebtoken/security/advisories/GHSA-45mw-4jw3-g2wg"
],
"exploitAvailability": "known_exploit"
},
"policyBadges": [
{
"policyId": "policy://tenant-default/runtime-hardening",
"verdict": "fail",
"explainUrl": "https://console.local/policy/runs/policy-run::2025-11-07::ca9f"
}
],
"vex": {
"statementId": "vex:tenant-default:jwt-auth:5d1a",
"state": "under_investigation",
"justification": "Runtime telemetry confirmed exploitation path.",
"impactStatement": "Token exchange service remains exposed until patch 2025.11.2.",
"remediations": [
{
"type": "patch",
"description": "Upgrade jwt-auth-service to 2025.11.2.",
"deadline": "2025-11-12T00:00:00Z"
}
]
},
"reachability": {
"status": "reachable",
"callPathSamples": [
"api-gateway -> jwt-auth-service -> jsonwebtoken.verify"
],
"lastUpdated": "2025-11-07T23:11:04Z"
},
"evidence": {
"sbom": {
"digest": "sha256:6c81…",
"componentPath": [
"/src/jwt-auth/package.json",
"/src/jwt-auth/node_modules/jsonwebtoken"
]
},
"attestations": [
{
"type": "scan-report",
"attestationId": "dsse://authority/attest/84a2",
"signer": "attestor@stella-ops.org",
"bundleDigest": "sha256:e2bb…"
}
]
},
"timestamps": {
"firstSeen": "2025-10-31T04:22:18Z",
"lastSeen": "2025-11-07T23:16:51Z",
"vexLastUpdated": "2025-11-07T23:10:09Z"
}
}
```
### 3.4 `POST /console/vuln/tickets`
```jsonc
POST /console/vuln/tickets
{
"tenant": "tenant-default",
"selection": [
"tenant-default:advisory-ai:sha256:5d1a",
"tenant-default:advisory-ai:sha256:9bf4"
],
"targetSystem": "servicenow",
"metadata": {
"assignmentGroup": "runtime-security",
"priority": "P1"
}
}
```
Response:
```jsonc
{
"ticketId": "console-ticket::tenant-default::2025-11-08::00018",
"payload": {
"version": "2025-11-01",
"tenant": "tenant-default",
"findings": [
{ "findingId": "tenant-default:advisory-ai:sha256:5d1a", "severity": "high" },
{ "findingId": "tenant-default:advisory-ai:sha256:9bf4", "severity": "critical" }
],
"policyBadge": "fail",
"vexSummary": "2 reachable findings pending patch.",
"attachments": [
{
"type": "json",
"name": "console-ticket-20251108.json",
"digest": "sha256:1fdd…",
"contentType": "application/json",
"expiresAt": "2025-11-15T00:00:00Z"
}
]
},
"auditEventId": "console.ticket.export::2025-11-08::00018"
}
```
Requests emit `console.ticket.export` audit events (tenant, user, selection counts, target system).
## 4. VEX Workspace (`/console/vex/*`)
### 4.1 `GET /console/vex/statements`
Parameters mirror `/console/vuln/findings` plus:
| Parameter | Type | Notes |
| --- | --- | --- |
| `advisoryId` | string[] | CVE/GHSA/OVAL identifiers. |
| `justification` | string[] | `exploit_observed`, `component_not_present`, etc. |
| `statementType` | string[] | `vex`, `openvex`, `custom`, `advisory_ai`. |
| `prefer` | string | `prefer=stream` enables chunked streaming (NDJSON). |
Response (paged JSON):
```jsonc
{
"items": [
{
"statementId": "vex:tenant-default:jwt-auth:5d1a",
"advisoryId": "CVE-2024-12345",
"product": "registry.local/ops/auth:2025.10.0",
"status": "under_investigation",
"justification": "exploit_observed",
"lastUpdated": "2025-11-07T23:10:09Z",
"source": {
"type": "advisory_ai",
"modelBuild": "aiai-console-2025-10-28",
"confidence": 0.74
},
"links": [
{
"rel": "finding",
"href": "/console/vuln/findings/tenant-default:advisory-ai:sha256:5d1a"
}
]
}
],
"nextPageToken": null
}
```
When `Accept: text/event-stream`, the endpoint emits events (see §4.3) instead of paged JSON.
### 4.2 `GET /console/vex/statements/{statementId}`
Returns the canonical statement plus provenance extracts. SSE clients can call this endpoint when they need full bodies after receiving a summary event.
### 4.3 `GET /console/vex/events` (SSE)
Streams live updates for VEX statements affecting the tenant:
- Event types: `statement.created`, `statement.updated`, `statement.deleted`, `statement.conflict`.
- Fields: `id`, `advisoryId`, `product`, `vexState`, `severityHint`, `policyBadge`, `conflictSummary`, `sequence`.
- Replay: Clients include `Last-Event-ID`; server resumes from sequence.
- Heartbeats every 15 seconds (`event: keepalive`, `data: {}`).
Example event payload:
```jsonc
event: statement.updated
data: {
"statementId": "vex:tenant-default:jwt-auth:5d1a",
"advisoryId": "CVE-2024-12345",
"product": "registry.local/ops/auth:2025.10.0",
"state": "fixed",
"justification": "solution_available",
"sequence": 4182,
"updatedAt": "2025-11-08T11:44:32Z"
}
```
## 5. Signals & Scheduler Integration
- Reachability data is materialized by Scheduler delta jobs (`SCHED-CONSOLE-23-001`). `/console/vuln/findings` should cache the most recent job ID and expose `signalsVersion`.
- VEX justification fields reference Excititor statement IDs; ensure the gateway checks Excititor availability and degrades gracefully (returns `state: unavailable` plus telemetry).
- Scheduler must publish `console.vuln.refresh` events whenever advisory/VEX deltas warrant workspace refresh; console SSE endpoint may piggyback on the same Redis/NATS channel.
## 6. Determinism & Offline Notes
1. All responses are compressible JSON; no CDN fonts/assets referenced.
2. SSE endpoints must tolerate sealed mode by operating on loopback addresses only.
3. `authority-sealed-ci.json` (see DEVOPS-AIRGAP-57-002) is the evidence Authority consumes before enabling these APIs for sealed tenants; console responses echo `sealed: true/false` flags for UI badges.
## 7. Sample Payloads for Docs
- `docs/api/console/samples/vuln-findings-sample.json` – exported via `scripts/generate-console-samples.ts` (placeholder script to be added when backend lands).
- `docs/api/console/samples/vex-statement-sse.ndjson` – contains 5 chronological SSE events for screenshot reproduction.
> Until backend implementations ship, use the examples above to unblock DOCS-AIAI-31-004; replace them with live captures once the gateway endpoints are available in staging.

25
docs/dev/lnm-determinism-tests.md
View File

@@ -18,14 +18,35 @@
- Build linksets from conflicting advisory observations (e.g., differing severity or status flags).
- Confirm conflict markers propagate to `AdvisoryLinkset` outputs and associated metrics/log records.
- Capture deterministic ordering of conflict explanations for evidence exports.
- Coverage landed via `AdvisoryObservationFactoryTests.Create_PreservesRawReferencesForConflictAudits` (raw linkset + attribute parity) and `AdvisoryEventLogTests.AppendAsync_SortsConflictStatementIds` (canonical conflict JSON + stable hashes).
3. **Evidence/export parity**
- Re-run observation/linkset pipelines against identical fixtures and assert resulting evidence manifests hash-identically.
- Track monotonic `supersedes` chains and ensure canonical link records include `PRIMARY` schemes.
- `JsonExportSnapshotBuilderTests.WriteAsync_DifferentInputOrderProducesSameDigest` now proves export bundles remain byte-identical regardless of advisory enumeration order; digest sampling extends `ProducesIdenticalBytesAcrossRuns`.
## Mongo2Go/OpenSSL toolchain
Concelier solution tests (and most connector suites) depend on Mongo2Go’s embedded `mongod`, which is linked against OpenSSL 1.1. The repo already ships the required libraries in `tests/native/openssl-1.1/linux-x64/{libcrypto.so.1.1,libssl.so.1.1}`; use them instead of installing global packages so offline runners stay deterministic.
1. Add the shim to your shell before executing any Mongo-backed suite:
```bash
export LD_LIBRARY_PATH="$(git rev-parse --show-toplevel)/tests/native/openssl-1.1/linux-x64:${LD_LIBRARY_PATH:-}"
```
2. For single commands you can prefix the invocation (handy for CI copy/paste):
```bash
LD_LIBRARY_PATH="$(pwd)/tests/native/openssl-1.1/linux-x64" \
dotnet test src/Concelier/StellaOps.Concelier.sln --nologo
```
3. The shim’s provenance and troubleshooting notes live in `tests/native/openssl-1.1/README.md`; reference it when mirroring the toolchain into air-gapped runners.
## Migration Steps
- [ ] Retire `StellaOps.Concelier.Merge.Tests` determinism suites once observation/linkset equivalents land.
- [ ] Introduce new regression fixtures under `StellaOps.Concelier.Core.Tests` (shared via `StellaOps.Concelier.Testing`).
- [x] Retire `StellaOps.Concelier.Merge.Tests` determinism suites once observation/linkset equivalents land.
- [x] Introduce new regression fixtures under `StellaOps.Concelier.Core.Tests` (shared via `StellaOps.Concelier.Testing`).
- [ ] Wire test helpers to Mongo in-memory harness for end-to-end parity runs.
- [ ] Update documentation (`docs/migration/no-merge.md`) with validation checklist once new tests are green.

1
docs/implplan/SPRINTS.md
View File

@@ -44,6 +44,7 @@ Follow the sprint files below in order. Update task status in both `SPRINTS` and
> 2025-11-03: MERGE-LNM-21-001 marked DONE – published `docs/migration/no-merge.md` with rollout, backfill, validation, and rollback guidance for the LNM cutover.
> 2025-11-04: GRAPH-INDEX-28-011 marked DONE (Graph Indexer Guild) – SBOM ingest DI wiring now emits graph snapshots by default, snapshot root configurable via `STELLAOPS_GRAPH_SNAPSHOT_DIR`, and Graph Indexer tests exercised with Mongo URI guidance.
> 2025-11-06: MERGE-LNM-21-002 remains DOING (BE-Merge) – default-off merge DI + job gating landed, but Concelier WebService ingest/mirror tests are failing; guard and migration fixes pending before completion.
> 2025-11-07: MERGE-LNM-21-002 marked DONE (BE-Merge) – Link-Not-Merge telemetry gaps closed by introducing `StellaOps.Ingestion.Telemetry`, guard metrics/tests updated, and Concelier Exporter JSON + solution smoke suites re-run to cover the new filename normalization.
> 2025-11-06: TASKRUN-43-001 marked DONE (Task Runner Guild) – approvals resume API now requeues packs, plan snapshots persisted, and filesystem artifact uploader stores manifests/files for offline review.
> 2025-11-06: CLI-POLICY-23-005 marked DONE (DevEx/CLI Guild) – policy activate CLI verifies scheduling/approval flow, Spectre console fallbacks emit warnings offline, and full CLI suite passes against local feeds.
> 2025-11-07: DOCS-AIAI-31-007 marked DONE (Docs Guild, Security Guild) – published `/docs/security/assistant-guardrails.md` covering redaction rules, blocked phrases, telemetry, and alert wiring.

43
docs/implplan/SPRINT_100_identity_signing.md
View File

@@ -18,7 +18,8 @@ ATTEST-VERIFY-74-001 | DONE | Emit telemetry (spans/metrics) tagged by subject,
ATTEST-VERIFY-74-002 | DONE (2025-11-01) | Document verification report schema and explainability in `/docs/modules/attestor/workflows.md`. Dependencies: ATTEST-VERIFY-73-001. | Verification Guild, Docs Guild (src/Attestor/StellaOps.Attestor.Verify/TASKS.md)
ATTESTOR-72-001 | DONE | Scaffold service (REST API skeleton, storage interfaces, KMS integration stubs) and DSSE validation pipeline. Dependencies: ATTEST-ENVELOPE-72-001. | Attestor Service Guild (src/Attestor/StellaOps.Attestor/TASKS.md)
ATTESTOR-72-002 | DONE | Implement attestation store (DB tables, object storage integration), CRUD, and indexing strategies. Dependencies: ATTESTOR-72-001. | Attestor Service Guild (src/Attestor/StellaOps.Attestor/TASKS.md)
ATTESTOR-72-003 | BLOCKED | Validate attestation store TTL against production-like Mongo/Redis stack; capture logs and remediation plan. Dependencies: ATTESTOR-72-002. | Attestor Service Guild, QA Guild (src/Attestor/StellaOps.Attestor/TASKS.md)
ATTESTOR-72-003 | DONE (2025-11-03) | Validate attestation store TTL against production-like Mongo/Redis stack; capture logs and remediation plan. Dependencies: ATTESTOR-72-002. | Attestor Service Guild, QA Guild (src/Attestor/StellaOps.Attestor/TASKS.md)
> 2025-11-03: TTL soak tests captured in `docs/modules/attestor/ttl-validation.md`; Mongo/Redis evidence archived for replay.
ATTESTOR-73-001 | DONE (2025-11-01) | Implement signing endpoint with Ed25519/ECDSA support, KMS integration, and audit logging. Dependencies: ATTESTOR-72-002, KMS-72-001. | Attestor Service Guild, KMS Guild (src/Attestor/StellaOps.Attestor/TASKS.md)
@@ -48,8 +49,11 @@ AUTH-AIRGAP-56-001 | DONE (2025-11-04) | Provision new scopes (`airgap:seal`, `a
> 2025-11-04: Verified discovery metadata now advertises the airgap scope trio, `etc/authority.yaml.sample` + offline kit docs ship the new roles, and Authority tests enforce tenant gating for `airgap:*` scopes (`dotnet test` executed).
AUTH-AIRGAP-56-002 | DONE (2025-11-04) | Audit import actions with actor, tenant, bundle ID, and trace ID; expose `/authority/audit/airgap` endpoint. Dependencies: AUTH-AIRGAP-56-001, AIRGAP-IMP-58-001. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-04: `/authority/audit/airgap` minimal APIs persist tenant-scoped records with paging, RBAC checks for `airgap:import`/`airgap:status:read` pass, and Authority integration suite (187 tests) exercised the audit flow.
AUTH-AIRGAP-57-001 | BLOCKED (2025-11-01) | Enforce sealed-mode CI gating by refusing token issuance when declared sealed install lacks sealing confirmation. Dependencies: AUTH-AIRGAP-56-001, DEVOPS-AIRGAP-57-002. | Authority Core & Security Guild, DevOps Guild (src/Authority/StellaOps.Authority/TASKS.md)
AUTH-AIRGAP-57-001 | DOING (2025-11-08) | Enforce sealed-mode CI gating by refusing token issuance when declared sealed install lacks sealing confirmation. Dependencies: AUTH-AIRGAP-56-001, DEVOPS-AIRGAP-57-002. | Authority Core & Security Guild, DevOps Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-01: AUTH-AIRGAP-57-001 blocked pending definition of sealed-confirmation evidence and configuration shape before gating (Authority Core & Security Guild, DevOps Guild).
> 2025-11-08: Flipped to DOING; partnering with DevOps on artifacts so Authority gating tests can consume sealed confirmations once published (target 2025-11-10).
> 2025-11-07: Still waiting on DEVOPS-AIRGAP-57-002 sealed-mode CI suite (`ops/devops/sealed-mode-ci/*`) to publish artefacts so Authority can wire the gating tests.
> 2025-11-08: DevOps sealed-mode CI now uploads `artifacts/sealed-mode-ci/<commit>/authority-sealed-ci.json`; Authority to hook the gating middleware/tests up to that feed next.
AUTH-NOTIFY-38-001 | DONE (2025-11-01) | Define `Notify.Viewer`, `Notify.Operator`, `Notify.Admin` scopes/roles, update discovery metadata, offline defaults, and issuer templates. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-01: AUTH-NOTIFY-38-001 completed—Notify scope catalog, discovery metadata, docs, configuration samples, and service tests updated for new roles.
AUTH-NOTIFY-40-001 | DONE (2025-11-02) | Implement signed ack token key rotation, webhook allowlists, admin-only escalation settings, and audit logging of ack actions. Dependencies: AUTH-NOTIFY-38-001, WEB-NOTIFY-40-001. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
@@ -73,6 +77,7 @@ AUTH-PACKS-41-001 | DONE (2025-11-04) | Define CLI SSO profiles and pack scopes
> 2025-11-04: Verified discovery metadata, OpenAPI, `etc/authority.yaml.sample`, and offline kit docs reflect the packs scope set; Authority suite re-run (`dotnet test`) to confirm tenant gating and policy checks.
> 2025-11-02: Shared OpenSSL 1.1 shim now feeds Mongo2Go for Authority & Signals tests, keeping pack scope regressions and other Mongo flows working on OpenSSL 3 hosts.
AUTH-PACKS-43-001 | BLOCKED (2025-10-27) | Enforce pack signing policies, approval RBAC checks, CLI CI token scopes, and audit logging for approvals. Dependencies: AUTH-PACKS-41-001, TASKRUN-42-001, ORCH-SVC-42-101. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-07: AUTH-PACKS-41-001 + TASKRUN-42-001 are DONE; remaining blocker is ORCH-SVC-42-101 (still TODO) for log streaming/approvals APIs. Not deleted—waiting on Orchestrator to publish contracts.
[Identity & Signing] 100.B) Authority.II
@@ -80,8 +85,17 @@ Depends on: Sprint 100.B - Authority.I
Summary: Identity & Signing focus on Authority (phase II).
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
AUTH-POLICY-23-002 | BLOCKED (2025-10-29) | Implement optional two-person rule for activation: require two distinct `policy:activate` approvals when configured; emit audit logs. Dependencies: AUTH-POLICY-23-001. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
AUTH-POLICY-23-003 | BLOCKED (2025-10-29) | Update documentation and sample configs for policy roles, approval workflow, and signing requirements. Dependencies: AUTH-POLICY-23-001. | Authority Core & Docs Guild (src/Authority/StellaOps.Authority/TASKS.md)
AUTH-POLICY-23-001 | DONE (2025-10-27) | Introduce fine-grained policy scopes (`policy:read`, `policy:author`, `policy:review`, `policy:simulate`, `findings:read`) for CLI/service accounts; update discovery metadata, issuer templates, and offline defaults. Dependencies: AUTH-AOC-19-002. | Authority Core & Docs Guild (src/Authority/StellaOps.Authority/TASKS.md)
AUTH-POLICY-23-002 | DONE (2025-11-08) | Implement optional two-person rule for activation: require two distinct `policy:activate` approvals when configured; emit audit logs. Dependencies: AUTH-POLICY-23-001. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-08: Added Policy Engine activation options (force/default/audit toggles), enforced pending-second-approval responses, and emitted `policy.activation.*` telemetry across auditor logs.
AUTH-POLICY-23-003 | DONE (2025-11-08) | Update documentation and sample configs for policy roles, approval workflow, and signing requirements. Dependencies: AUTH-POLICY-23-001. | Authority Core & Docs Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-08: Documented dual-control activation steps, new `PolicyEngine.activation.*` knobs, sample YAML defaults, and console/operator guidance for audit visibility.
> 2025-11-07: Scope migration (AUTH-POLICY-23-001) shipped; activation guardrail and documentation updates now waiting on pairing.
AUTH-DPOP-11-001 | DOING (2025-11-07) | Enforce DPoP sender constraints for `/token` flows (nonce policies, JKT persistence, structured telemetry) so downstream services can trust `cnf` metadata. Dependencies: AUTH-AOC-19-002. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
AUTH-MTLS-11-002 | DOING (2025-11-07) | Deliver mTLS-bound token issuance/validation (cert thumbprint storage, JWKS rotation hooks) required for high-assurance tenants and plugin mitigations. Dependencies: AUTH-DPOP-11-001. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-07: Authority + DevOps stand-up aligned on a 2025-11-10 delivery target for AUTH-DPOP-11-001 / AUTH-MTLS-11-002 and DEVOPS-AIRGAP-57-002 so plugin security/air-gap gating can flip to DOING immediately after.
> 2025-11-08: Taking ownership to wire certificate thumbprint persistence + audit logging; blocking issues from AUTH-DPOP-11-001 now resolved, so mTLS enforcement can proceed.
> 2025-11-08: `/token`/`/introspect` now enforce TLS certificate matches for mTLS-bound tokens and emit `authority_mtls_mismatch_total` telemetry when rejections occur.
AUTH-POLICY-27-002 | DONE (2025-11-02) | Provide attestation signing service bindings (OIDC token exchange, cosign integration) and enforce publish/promote scope checks, fresh-auth requirements, and audit logging. Dependencies: AUTH-POLICY-27-001, REGISTRY-API-27-007. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
> 2025-11-02: Added interactive-only `policy:publish`/`policy:promote` scopes with metadata requirements (`policy_reason`, `policy_ticket`, `policy_digest`), fresh-auth validation, audit enrichment, and updated config/docs for operators.
AUTH-POLICY-27-003 | DONE (2025-11-04) | Update Authority configuration/docs for Policy Studio roles, signing policies, approval workflows, and CLI integration; include compliance checklist. Dependencies: AUTH-POLICY-27-001, AUTH-POLICY-27-002. | Authority Core & Docs Guild (src/Authority/StellaOps.Authority/TASKS.md)
@@ -100,9 +114,11 @@ AUTH-VULN-29-003 | DONE (2025-11-04) | Update security docs/config samples for V
PLG4-6.CAPABILITIES | BLOCKED (2025-10-12) | Finalise capability metadata exposure, config validation, and developer guide updates; remaining action is Docs polish/diagram export. | BE-Auth Plugin, Docs Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
PLG6.DIAGRAM | TODO | Export final sequence/component diagrams for the developer guide and add offline-friendly assets under `docs/assets/authority`. | Docs Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
PLG7.RFC | REVIEW | Socialize LDAP plugin RFC (`docs/rfcs/authority-plugin-ldap.md`) and capture guild feedback. | BE-Auth Plugin, Security Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
SEC2.PLG | BLOCKED (2025-10-21) | 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. | Security Guild, Storage Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
SEC3.PLG | BLOCKED (2025-10-21) | 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. | Security Guild, BE-Auth Plugin (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
SEC5.PLG | BLOCKED (2025-10-21) | 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. | Security Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
SEC2.PLG | BLOCKED (2025-10-21) | Emit audit events from password verification outcomes and persist via `IAuthorityLoginAttemptStore`. <br>⛔ Waiting on AUTH-DPOP-11-001 / AUTH-MTLS-11-002 to stabilise Authority auth surfaces (PLUGIN-DI-08-001 closed 2025-10-21; re-run once sender constraints land). | Security Guild, Storage Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
SEC3.PLG | BLOCKED (2025-10-21) | 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 already merged, so limiter telemetry just awaits final Authority surface. | Security Guild, BE-Auth Plugin (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
SEC5.PLG | BLOCKED (2025-10-21) | Address plugin-specific mitigations (bootstrap user handling, password policy docs) in threat model backlog. <br>⛔ Final documentation now hinges on AUTH-DPOP-11-001 / AUTH-MTLS-11-002 (PLUGIN-DI-08-001 landed 2025-10-21). | Security Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
> 2025-11-07: Upstream AUTH-DPOP-11-001 / AUTH-MTLS-11-002 now DOING; revisit plugin backlog once sender-constraint hardening lands.
> 2025-11-08: Dependency audit confirmed — AUTH-DPOP-11-001 / AUTH-MTLS-11-002 staffed with 2025-11-10 delivery; no missing SEC2/SEC3/SEC5 subtasks, so these remain BLOCKED only until sender constraints merge.
PLG7.IMPL-001 | DONE (2025-11-03) | Scaffold `StellaOps.Authority.Plugin.Ldap` + tests, bind configuration (client certificate, trust-store, insecure toggle) with validation and docs samples. | BE-Auth Plugin (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
> 2025-11-03: Initial `StellaOps.Authority.Plugin.Ldap` project/tests scaffolded with configuration options + registrar; sample manifest (`etc/authority.plugins/ldap.yaml`) updated to new schema (client certificate, trust store, insecure toggle).
PLG7.IMPL-002 | DONE (2025-11-04) | Implement LDAP credential store with TLS/mutual TLS enforcement, deterministic retry/backoff, and structured logging/metrics. | BE-Auth Plugin, Security Guild (src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/TASKS.md)
@@ -131,7 +147,14 @@ KMS-73-001 | TODO | Add cloud KMS driver (e.g., AWS KMS, GCP KMS) with signing a
KMS-73-002 | TODO | Implement PKCS#11/HSM driver plus FIDO2 signing support for high assurance workflows. Dependencies: KMS-73-001. | KMS Guild (src/__Libraries/StellaOps.Cryptography.Kms/TASKS.md)
[Identity & Signing] 100.E) Deployment
Depends on: Helm base chart scaffolding (HELM-45-001)
Summary: Wire deployment assets so Policy Engine activation guardrails stay deterministic across clusters/offline kits.
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
HELM-45-004 | DONE (2025-11-08) | Mount the new `policy-engine-activation` ConfigMap into the Policy Engine (and Policy Gateway) pods, ensure runtime config loads activation overrides from env/file, and refresh Helm/Compose samples for offline parity. | Deployment Guild, Policy Guild (ops/deployment/TASKS.md)
> 2025-11-08: Helm template now injects the activation ConfigMap for policy-engine/gateway pods, Policy Engine host loads `/config/policy-engine/activation.yaml`, Policy Engine/Gateway tests are green, and CI now runs `helm lint`/`helm template` over every `values*.yaml`.
If all tasks are done - read next sprint section - SPRINT_110_ingestion_evidence.md

31
docs/implplan/SPRINT_110_ingestion_evidence.md
View File

@@ -34,7 +34,9 @@ AIAI-31-004C | DONE (2025-11-06) | Deliver CLI `stella advise run` command, rend
DOCS-AIAI-31-002 | DONE (2025-11-03) | Author `/docs/advisory-ai/architecture.md` detailing RAG pipeline, deterministic tooling, caching, model profiles. Dependencies: AIAI-31-004. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-001 | DONE (2025-11-03) | Publish `/docs/advisory-ai/overview.md` covering capabilities, guardrails, RBAC personas, and offline posture. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-003 | DONE (2025-11-03) | Write `/docs/advisory-ai/api.md` covering endpoints, schemas, errors, rate limits, and imposed-rule banner. Dependencies: DOCS-AIAI-31-002. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-004 | BLOCKED (2025-11-03) | Create `/docs/advisory-ai/console.md` with screenshots, a11y notes, copy-as-ticket instructions. Dependencies: CONSOLE-VULN-29-001, CONSOLE-VEX-30-001, EXCITITOR-CONSOLE-23-001. | Docs Guild, Console Guild (docs/TASKS.md)
DOCS-AIAI-31-004 | DOING (2025-11-07) | Create `/docs/advisory-ai/console.md` with screenshots, a11y notes, copy-as-ticket instructions. Dependencies: CONSOLE-VULN-29-001, CONSOLE-VEX-30-001, EXCITITOR-CONSOLE-23-001. | Docs Guild, Console Guild (docs/TASKS.md)
> 2025-11-07: Draft doc committed (`docs/advisory-ai/console.md`) with workflow outline; screenshots will be added once CONSOLE-VULN-29-001 / CONSOLE-VEX-30-001 ship.
> 2025-11-08: Console endpoints are staffed (CONSOLE-VULN-29-001 / CONSOLE-VEX-30-001 DOING); still waiting on EXCITITOR-CONSOLE-23-001 feeds before capturing screenshots/tests.
DOCS-AIAI-31-005 | BLOCKED (2025-11-03) | Publish `/docs/advisory-ai/cli.md` covering commands, exit codes, scripting patterns. Dependencies: CLI-VULN-29-001, CLI-VEX-30-001, AIAI-31-004C. | Docs Guild, DevEx/CLI Guild (docs/TASKS.md)
DOCS-AIAI-31-006 | BLOCKED (2025-11-03) | Update `/docs/policy/assistant-parameters.md` covering temperature, token limits, ranking weights, TTLs. Dependencies: POLICY-ENGINE-31-001. | Docs Guild, Policy Guild (docs/TASKS.md)
DOCS-AIAI-31-007 | DONE (2025-11-07) | Write `/docs/security/assistant-guardrails.md` detailing redaction, injection defense, logging. Dependencies: AIAI-31-005. | Docs Guild, Security Guild (docs/TASKS.md)
@@ -127,7 +129,7 @@ CONCELIER-OAS-61-001 `Spec coverage` | TODO | Update Concelier OAS with advisory
CONCELIER-OAS-61-002 `Examples library` | TODO | Provide rich examples for advisories, linksets, conflict annotations used by SDK + docs. Dependencies: CONCELIER-OAS-61-001. | Concelier Core Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
CONCELIER-OAS-62-001 `SDK smoke tests` | TODO | Add SDK tests covering advisory search, pagination, and conflict handling; ensure source metadata surfaced. Dependencies: CONCELIER-OAS-61-002. | Concelier Core Guild, SDK Generator Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
CONCELIER-OAS-63-001 `Deprecation headers` | TODO | Implement deprecation header support and timeline events for retiring endpoints. Dependencies: CONCELIER-OAS-62-001. | Concelier Core Guild, API Governance Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
CONCELIER-OBS-50-001 `Telemetry adoption` | TODO | Replace ad-hoc logging with telemetry core across ingestion/linking pipelines; ensure spans/logs include tenant, source vendor, upstream id, content hash, and trace IDs. | Concelier Core Guild, Observability Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
CONCELIER-OBS-50-001 `Telemetry adoption` | DONE (2025-11-07) | Replace ad-hoc logging with telemetry core across ingestion/linking pipelines; ensure spans/logs include tenant, source vendor, upstream id, content hash, and trace IDs. | Concelier Core Guild, Observability Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
CONCELIER-OBS-51-001 `Metrics & SLOs` | TODO | Emit metrics for ingest latency (cold/warm), queue depth, aoc violation rate, and publish SLO burn-rate alerts (ingest P95 <30s cold / <5s warm). Ship dashboards + alert configs. Dependencies: CONCELIER-OBS-50-001. | Concelier Core Guild, DevOps Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
CONCELIER-OBS-52-001 `Timeline events` | TODO | Emit `timeline_event` records for advisory ingest/normalization/linkset creation with provenance, trace IDs, conflict summaries, and evidence placeholders. Dependencies: CONCELIER-OBS-51-001. | Concelier Core Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
CONCELIER-OBS-53-001 `Evidence snapshots` | TODO | Produce advisory evaluation bundle payloads (raw doc, linkset, normalization diff) for evidence locker; ensure Merkle manifests seeded with content hashes. Dependencies: CONCELIER-OBS-52-001. | Concelier Core Guild, Evidence Locker Guild (src/Concelier/__Libraries/StellaOps.Concelier.Core/TASKS.md)
@@ -172,14 +174,17 @@ CONCELIER-WEB-AIRGAP-56-001 `Mirror import APIs` | TODO | Extend ingestion endpo
CONCELIER-WEB-AIRGAP-56-002 `Airgap status surfaces` | TODO | Add staleness metadata and bundle provenance to advisory APIs (`/advisories/observations`, `/advisories/linksets`). Dependencies: CONCELIER-WEB-AIRGAP-56-001. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AIRGAP-57-001 `Error remediation` | TODO | Map sealed-mode violations to `AIRGAP_EGRESS_BLOCKED` responses with user guidance. Dependencies: CONCELIER-WEB-AIRGAP-56-002. | Concelier WebService Guild, AirGap Policy Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AIRGAP-58-001 `Import timeline emission` | TODO | Emit timeline events for bundle ingestion operations with bundle ID, scope, and actor metadata. Dependencies: CONCELIER-WEB-AIRGAP-57-001. | Concelier WebService Guild, AirGap Importer Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AOC-19-002 `AOC observability` | TODO | Emit `ingestion_write_total`, `aoc_violation_total`, latency histograms, and tracing spans (`ingest.fetch/transform/write`, `aoc.guard`). Wire structured logging to include tenant, source vendor, upstream id, and content hash. | Concelier WebService Guild, Observability Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AOC-19-002 `AOC observability` | DONE (2025-11-07) | Emit `ingestion_write_total`, `aoc_violation_total`, latency histograms, and tracing spans (`ingest.fetch/transform/write`, `aoc.guard`). Wire structured logging to include tenant, source vendor, upstream id, and content hash. | Concelier WebService Guild, Observability Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AOC-19-003 `Schema/guard unit tests` | TODO | Add unit tests covering schema validation failures, forbidden field rejections (`ERR_AOC_001/002/006/007`), idempotent upserts, and supersedes chains using deterministic fixtures. Dependencies: CONCELIER-WEB-AOC-19-002. | QA Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AOC-19-004 `End-to-end ingest verification` | TODO | Create integration tests ingesting large advisory batches (cold/warm) validating linkset enrichment, metrics emission, and reproducible outputs. Capture load-test scripts + doc notes for Offline Kit dry runs. Dependencies: CONCELIER-WEB-AOC-19-003. | Concelier WebService Guild, QA Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AOC-19-005 `Chunk evidence regression` | TODO (2025-11-08) | Fix `/advisories/{key}/chunks` fixture seeding so AdvisoryChunksEndpoint tests stop returning 404/not-found when raw documents are pre-populated; ensure the Mongo migration no longer emits “Unable to locate advisory_raw documents” during WebService test boot. Dependencies: CONCELIER-WEB-AOC-19-002. | Concelier WebService Guild, QA Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AOC-19-006 `Allowlist ingest auth parity` | TODO (2025-11-08) | Align WebService auth defaults with the test tokens so the allowlisted tenant can create an advisory before forbidden tenants are rejected in `AdvisoryIngestEndpoint_RejectsTenantOutsideAllowlist`. Dependencies: CONCELIER-WEB-AOC-19-002. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-AOC-19-007 `AOC verify violation codes` | TODO (2025-11-08) | Update AOC verify logic/fixtures so guard failures produce the expected `ERR_AOC_001` payload (current regression returns `ERR_AOC_004`) while keeping mapper/guard parity exercised by the new tests. Dependencies: CONCELIER-WEB-AOC-19-002. | Concelier WebService Guild, QA Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OAS-61-001 `/.well-known/openapi` | DONE (2025-11-02) | Implement discovery endpoint emitting Concelier spec with version metadata and ETag. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OAS-61-002 `Error envelope migration` | TODO | Ensure all API responses use standardized error envelope; update controllers/tests. Dependencies: CONCELIER-WEB-OAS-61-001. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OAS-62-001 `Examples expansion` | TODO | Add curated examples for advisory observations/linksets/conflicts; integrate into dev portal. Dependencies: CONCELIER-WEB-OAS-61-002. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OAS-63-001 `Deprecation headers` | TODO | Add Sunset/Deprecation headers for retiring endpoints and update documentation/notifications. Dependencies: CONCELIER-WEB-OAS-62-001. | Concelier WebService Guild, API Governance Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OBS-50-001 `Telemetry adoption` | TODO | Adopt telemetry core in web service host, ensure ingest + read endpoints emit trace/log fields (`tenant_id`, `route`, `decision_effect`), and add correlation IDs to responses. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OBS-50-001 `Telemetry adoption` | DONE (2025-11-07) | Adopt telemetry core in web service host, ensure ingest + read endpoints emit trace/log fields (`tenant_id`, `route`, `decision_effect`), and add correlation IDs to responses. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OBS-51-001 `Observability APIs` | TODO | Surface ingest health metrics, queue depth, and SLO status via `/obs/concelier/health` endpoint for Console widgets, with caching and tenant partitioning. Dependencies: CONCELIER-WEB-OBS-50-001. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
CONCELIER-WEB-OBS-52-001 `Timeline streaming` | TODO | Provide SSE stream `/obs/concelier/timeline` bridging to Timeline Indexer with paging tokens, guardrails, and audit logging. Dependencies: CONCELIER-WEB-OBS-51-001. | Concelier WebService Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
@@ -194,7 +199,7 @@ CONCELIER-WEB-OBS-54-001 `Attestation exposure` | TODO | Provide `/attestations/
CONCELIER-WEB-OBS-55-001 `Incident mode toggles` | TODO | Implement incident mode toggle endpoints, propagate to orchestrator/locker, and document cooldown/backoff semantics. Dependencies: CONCELIER-WEB-OBS-54-001. | Concelier WebService Guild, DevOps Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
FEEDCONN-CCCS-02-009 Version range provenance (Oct 2025) | BE-Conn-CCCS | **TODO (due 2025-10-21)** – Map CCCS advisories into the new `advisory_observations.affected.versions[]` structure, preserving each upstream range with provenance anchors (`cccs:{serial}:{index}`) and normalized comparison keys. Update mapper tests/fixtures for the Link-Not-Merge schema and verify linkset builders consume the ranges without relying on legacy merge counters.<br>2025-10-29: `docs/dev/normalized-rule-recipes.md` now documents helper snippets for building observation version entries—use them instead of merge-specific builders and refresh fixtures with `UPDATE_CCCS_FIXTURES=1`. | CONCELIER-LNM-21-001 (src/Concelier/__Libraries/StellaOps.Concelier.Connector.Cccs/TASKS.md)
FEEDCONN-CERTBUND-02-010 Version range provenance | BE-Conn-CERTBUND | **TODO (due 2025-10-22)** – Translate `product.Versions` phrases (e.g., `2023.1 bis 2024.2`, `alle`) into comparison helpers for `advisory_observations.affected.versions[]`, capturing provenance (`certbund:{advisoryId}:{vendor}`) and localisation notes. Update mapper/tests for the Link-Not-Merge schema and refresh documentation accordingly. | CONCELIER-LNM-21-001 (src/Concelier/__Libraries/StellaOps.Concelier.Connector.CertBund/TASKS.md)
FEEDCONN-CISCO-02-009 SemVer range provenance | BE-Conn-Cisco | **TODO (due 2025-10-21)** – Emit Cisco SemVer ranges into `advisory_observations.affected.versions[]` with provenance identifiers (`cisco:{productId}`) and deterministic comparison keys. Update mapper/tests for the Link-Not-Merge schema and replace legacy merge counter checks with observation/linkset validation. | CONCELIER-LNM-21-001 (src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Cisco/TASKS.md)
FEEDCONN-CISCO-02-009 SemVer range provenance | BE-Conn-Cisco | **DOING (2025-11-08)** – Emitting Cisco SemVer ranges into `advisory_observations.affected.versions[]` with provenance identifiers (`cisco:{productId}`) and deterministic comparison keys. Updating mapper/tests for the Link-Not-Merge schema and replacing legacy merge counter checks with observation/linkset validation. | CONCELIER-LNM-21-001 (src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Cisco/TASKS.md)
FEEDCONN-ICSCISA-02-012 Version range provenance | BE-Conn-ICS-CISA | **DONE (2025-11-03)** – Promote existing firmware/semver data into `advisory_observations.affected.versions[]` entries with deterministic comparison keys and provenance identifiers (`ics-cisa:{advisoryId}:{product}`). Add regression coverage for mixed firmware strings and raise a Models ticket only when observation schema needs a new comparison helper.<br>2025-10-29: Follow `docs/dev/normalized-rule-recipes.md` §2 to build observation version entries and log failures without invoking the retired merge helpers.<br>2025-11-03: Completed – connector now normalizes semver ranges with provenance notes, RSS fallback content clears the AOC guard, and end-to-end Fetch/Parse/Map integration tests pass. | CONCELIER-LNM-21-001 (src/Concelier/__Libraries/StellaOps.Concelier.Connector.Ics.Cisa/TASKS.md)
FEEDCONN-KISA-02-008 Firmware range provenance | BE-Conn-KISA, Models | **DONE (2025-11-04)** – Define comparison helpers for Hangul-labelled firmware ranges (`XFU 1.0.1.0084 ~ 2.0.1.0034`) and map them into `advisory_observations.affected.versions[]` with provenance tags. Coordinate with Models only if a new comparison scheme is required, then update localisation notes and fixtures for the Link-Not-Merge schema.<br>2025-11-03: Analysis in progress – auditing existing mapper output/fixtures ahead of implementing firmware range normalization and provenance wiring.<br>2025-11-03: SemVer normalization helper wired through `KisaMapper` with provenance slugs + vendor extensions; integration tests updated and green, follow-up capture for additional Hangul exclusivity markers queued before completion.<br>2025-11-03: Extended connector tests to cover single-ended (`이상`, `초과`, `이하`, `미만`) and non-numeric phrases, verifying normalized rule types (`gt`, `gte`, `lt`, `lte`) and fallback behaviour; broader corpus review remains before transitioning to DONE.<br>2025-11-03: Captured the top 10 `detailDos.do?IDX=` pages into `seed-data/kisa/html/` via `scripts/kisa_capture_html.py`; JSON endpoint (`rssDetailData.do?IDX=…`) now returns error pages, so connector updates must parse the embedded HTML or secure authenticated API access before closing.<br>2025-11-04: Fetch + parse pipeline now consumes the HTML detail pages end to end (metadata persisted, DOM parser extracts vendor/product ranges); fixtures/tests operate on the HTML snapshots to guard normalized SemVer + vendor extension expectations and severity extraction. | CONCELIER-LNM-21-001 (src/Concelier/__Libraries/StellaOps.Concelier.Connector.Kisa/TASKS.md)
FEEDCONN-SHARED-STATE-003 Source state seeding helper | Tools Guild, BE-Conn-MSRC | **DONE (2025-11-04)** – Delivered `SourceStateSeeder` CLI + processor APIs, Mongo fixtures, and MSRC runbook updates. Seeds raw docs + cursor state deterministically; tests cover happy/path/idempotent flows (`dotnet test src/Concelier/__Tests/StellaOps.Concelier.Connector.Common.Tests/...` – note: requires `libcrypto.so.1.1` when running Mongo2Go locally). | Tools (src/Concelier/__Libraries/StellaOps.Concelier.Connector.Common/TASKS.md)
@@ -212,7 +217,7 @@ Summary: Ingestion & Evidence focus on Concelier (phase VII).
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
MERGE-LNM-21-002 | DONE (2025-11-07) | Refactor or retire `AdvisoryMergeService` and related pipelines, ensuring callers transition to observation/linkset APIs; add compile-time analyzer preventing merge service usage.<br>2025-11-03: Began dependency audit and call-site inventory ahead of deprecation plan; cataloging service registrations/tests referencing merge APIs.<br>2025-11-05 14:42Z: Drafted `concelier:features:noMergeEnabled` gating, merge job allowlist handling, and deprecation/telemetry changes prior to analyzer rollout.<br>2025-11-06 16:10Z: Landed analyzer project (`CONCELIER0002`), wired into Concelier WebService/tests, and updated docs to direct suppressions through explicit migration notes.<br>2025-11-07 03:25Z: Default-on toggle + job gating surfaced ingestion test brittleness; guard/migration diagnostics capture requests missing `upstream.contentHash`.<br>2025-11-07 19:45Z: Set `ConcelierOptions.Features.NoMergeEnabled` default to `true`, added regression coverage (`Features_NoMergeEnabled_DefaultsToTrue`), and rechecked ingest helpers to carry canonical links. Remote .NET 10 CLI run remains queued for validation. | BE-Merge (src/Concelier/__Libraries/StellaOps.Concelier.Merge/TASKS.md)
MERGE-LNM-21-003 Determinism/test updates | DOING (2025-11-07) | QA Guild, BE-Merge | Replace merge determinism suites with observation/linkset regression tests verifying no data mutation and conflicts remain visible. Dependencies: MERGE-LNM-21-002.<br>2025-11-07: Drafting test migration plan (`docs/dev/lnm-determinism-tests.md`) to map legacy merge fixtures onto observation/linkset pipelines; identifying coverage gaps (conflict surfacing, raw vs canonical parity, hash stability).<br>2025-11-07 20:05Z: Landed `AdvisoryObservationFactoryTests.Create_IsDeterministicAcrossRuns` to cover canonical JSON stability and pruned the old merge determinism integration test. | MERGE-LNM-21-002 (src/Concelier/__Libraries/StellaOps.Concelier.Merge/TASKS.md)
MERGE-LNM-21-003 Determinism/test updates | DONE (2025-11-07) | QA Guild, BE-Merge | Replaced the retired merge determinism harness with observation/linkset/export regressions. `AdvisoryObservationFactoryTests` now assert raw reference parity + conflict notes, `AdvisoryEventLogTests` sort/uniquify conflict statement IDs, and `JsonExportSnapshotBuilderTests` guard digest parity across reordered input. `docs/dev/lnm-determinism-tests.md` checklist updated with the new coverage. | MERGE-LNM-21-002 (src/Concelier/__Libraries/StellaOps.Concelier.Merge/TASKS.md)
WEB-AOC-19-001 (dependency) | DONE (2025-11-07) | Shared guard primitives now enforce the top-level allowlist (`_id`, tenant, source, upstream, content, identifiers, linkset, supersedes, created/ingested timestamps, attributes) and emit the reusable `AocError` payload consumed by HTTP/CLI tooling. Extend `AocGuardOptions.AllowedTopLevelFields` when staging new schema fields to avoid false-positive `ERR_AOC_007` violations. | BE-Base Platform Guild (docs/aoc/guard-library.md, src/Web/StellaOps.Web/TASKS.md)
@@ -278,7 +283,7 @@ EXCITITOR-OAS-61-001 `Spec coverage` | TODO | Update VEX OAS to include observat
EXCITITOR-OAS-61-002 `Example catalog` | TODO | Provide examples for VEX justifications, statuses, conflicts; ensure SDK docs reference them. Dependencies: EXCITITOR-OAS-61-001. | Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core/TASKS.md)
EXCITITOR-OAS-62-001 `SDK smoke tests` | TODO | Add SDK scenarios for VEX observation queries and conflict handling to language smoke suites. Dependencies: EXCITITOR-OAS-61-002. | Excititor Core Guild, SDK Generator Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core/TASKS.md)
EXCITITOR-OAS-63-001 `Deprecation headers` | TODO | Add deprecation metadata and notifications for legacy VEX routes. Dependencies: EXCITITOR-OAS-62-001. | Excititor Core Guild, API Governance Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core/TASKS.md)
EXCITITOR-OBS-50-001 `Telemetry adoption` | TODO | Integrate telemetry core across VEX ingestion/linking, ensuring spans/logs capture tenant, product scope, upstream id, justification hash, and trace IDs. | Excititor Core Guild, Observability Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core/TASKS.md)
EXCITITOR-OBS-50-001 `Telemetry adoption` | DONE (2025-11-07) | Integrate telemetry core across VEX ingestion/linking, ensuring spans/logs capture tenant, product scope, upstream id, justification hash, and trace IDs. | Excititor Core Guild, Observability Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core/TASKS.md)
EXCITITOR-OBS-51-001 `Metrics & SLOs` | TODO | Publish metrics for VEX ingest latency, scope resolution success, conflict rate, signature verification failures. Define SLOs (link latency P95 <30s) and configure burn-rate alerts. Dependencies: EXCITITOR-OBS-50-001. | Excititor Core Guild, DevOps Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core/TASKS.md)
@@ -332,16 +337,16 @@ Summary: Ingestion & Evidence focus on Excititor (phase VI).
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
EXCITITOR-WEB-AIRGAP-58-001 | TODO | Emit timeline events for VEX bundle imports with bundle ID, scope, and actor metadata. Dependencies: EXCITITOR-WEB-AIRGAP-57-001. | Excititor WebService Guild, AirGap Importer Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-001 `Raw VEX ingestion APIs` | TODO | Implement `POST /ingest/vex`, `GET /vex/raw*`, and `POST /aoc/verify` endpoints. Enforce Authority scopes, tenant injection, and guard pipeline to ensure only immutable VEX facts are persisted. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-002 `AOC observability + metrics` | TODO | Export metrics (`ingestion_write_total`, `aoc_violation_total`, signature verification counters) and tracing spans matching Conseiller naming. Ensure structured logging includes tenant, source vendor, upstream id, and content hash. Dependencies: EXCITITOR-WEB-AOC-19-001. | Excititor WebService Guild, Observability Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-003 `Guard + schema test harness` | TODO | Add unit/integration tests for schema validation, forbidden field rejection (`ERR_AOC_001/006/007`), and supersedes behavior using CycloneDX-VEX & CSAF fixtures with deterministic expectations. Dependencies: EXCITITOR-WEB-AOC-19-002. | QA Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-004 `Batch ingest validation` | TODO | Build large fixture ingest covering mixed VEX statuses, verifying raw storage parity, metrics, and CLI `aoc verify` compatibility. Document load test/runbook updates. Dependencies: EXCITITOR-WEB-AOC-19-003. | Excititor WebService Guild, QA Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-001 `Raw VEX ingestion APIs` | DONE (2025-11-08) | Implement `POST /ingest/vex`, `GET /vex/raw*`, and `POST /aoc/verify` endpoints. Enforce Authority scopes, tenant injection, and guard pipeline to ensure only immutable VEX facts are persisted. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-002 `AOC observability + metrics` | DONE (2025-11-08) | Export metrics (`ingestion_write_total`, `aoc_violation_total`, signature verification counters) and tracing spans matching Conseiller naming. Ensure structured logging includes tenant, source vendor, upstream id, and content hash. Dependencies: EXCITITOR-WEB-AOC-19-001. | Excititor WebService Guild, Observability Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-003 `Guard + schema test harness` | DONE (2025-11-08) | Add unit/integration tests for schema validation, forbidden field rejection (`ERR_AOC_001/006/007`), and supersedes behavior using CycloneDX-VEX & CSAF fixtures with deterministic expectations. Dependencies: EXCITITOR-WEB-AOC-19-002. | QA Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-AOC-19-004 `Batch ingest validation` | DONE (2025-11-08) | Build large fixture ingest covering mixed VEX statuses, verifying raw storage parity, metrics, and CLI `aoc verify` compatibility. Document load test/runbook updates. Dependencies: EXCITITOR-WEB-AOC-19-003. | Excititor WebService Guild, QA Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OAS-61-001 | TODO | Implement `/.well-known/openapi` discovery endpoint with spec version metadata. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OAS-61-002 | TODO | Standardize error envelope responses and update controller/unit tests. Dependencies: EXCITITOR-WEB-OAS-61-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OAS-62-001 | TODO | Add curated examples for VEX observation/linkset endpoints and ensure portal displays them. Dependencies: EXCITITOR-WEB-OAS-61-002. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OAS-63-001 | TODO | Emit deprecation headers and update docs for retiring VEX APIs. Dependencies: EXCITITOR-WEB-OAS-62-001. | Excititor WebService Guild, API Governance Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OBS-50-001 `Telemetry adoption` | TODO | Adopt telemetry core for VEX APIs, ensure responses include trace IDs & correlation headers, and update structured logging for read endpoints. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OBS-51-001 `Observability health endpoints` | TODO | Implement `/obs/excititor/health` summarizing ingest/link SLOs, signature failure counts, and conflict trends for Console dashboards. Dependencies: EXCITITOR-WEB-OBS-50-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OBS-50-001 `Telemetry adoption` | DONE (2025-11-07) | Adopt telemetry core for VEX APIs, ensure responses include trace IDs & correlation headers, and update structured logging for read endpoints. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OBS-51-001 `Observability health endpoints` | DONE (2025-11-08) | Implement `/obs/excititor/health` summarizing ingest/link SLOs, signature failure counts, and conflict trends for Console dashboards. Dependencies: EXCITITOR-WEB-OBS-50-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OBS-52-001 `Timeline streaming` | TODO | Provide SSE bridge for VEX timeline events with tenant filters, pagination, and guardrails. Dependencies: EXCITITOR-WEB-OBS-51-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OBS-53-001 `Evidence APIs` | TODO | Expose `/evidence/vex/*` endpoints that fetch locker bundles, enforce scopes, and surface verification metadata. Dependencies: EXCITITOR-WEB-OBS-52-001. | Excititor WebService Guild, Evidence Locker Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)
EXCITITOR-WEB-OBS-54-001 `Attestation APIs` | TODO | Add `/attestations/vex/*` endpoints returning DSSE verification state, builder identity, and chain-of-custody links. Dependencies: EXCITITOR-WEB-OBS-53-001. | Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService/TASKS.md)

8
docs/implplan/SPRINT_120_policy_reasoning.md
View File

@@ -22,8 +22,8 @@ LEDGER-29-001 | DONE (2025-11-03) | Design ledger & projection schemas (tables/i
LEDGER-29-002 | DONE (2025-11-03) | Implement ledger write API (`POST /vuln/ledger/events`) with validation, idempotency, hash chaining, and Merkle root computation job.<br>2025-11-03: Web service + domain scaffolding landed with canonical hashing helpers, in-memory repository, Merkle scheduler stub, request/response contracts, and unit tests covering hashing & conflict flows. Dependencies: LEDGER-29-001. | Findings Ledger Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-003 | DONE (2025-11-03) | Build projector worker that derives `findings_projection` rows from ledger events + policy determinations; ensure idempotent replay keyed by `(tenant,finding_id,policy_version)`. <br>2025-11-03: Postgres projection services landed with replay checkpoints, fixtures, and unit coverage (LEDGER-29-003). Dependencies: LEDGER-29-002. | Findings Ledger Guild, Scheduler Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-004 | DONE (2025-11-04) | Integrate Policy Engine batch evaluation (baseline + simulate) with projector; cache rationale references.<br>2025-11-04: Ledger service now calls `/api/policy/eval/batch` with resilient HttpClient, shared cache, and inline fallback; documentation/config samples updated; ledger tests executed (`dotnet test src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/StellaOps.Findings.Ledger.Tests.csproj --no-restore`). Dependencies: LEDGER-29-003. | Findings Ledger Guild, Policy Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-005 | TODO | Implement workflow mutation handlers (assign, comment, accept-risk, target-fix, verify-fix, reopen) producing ledger events with validation and attachments metadata. Dependencies: LEDGER-29-004. | Findings Ledger Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-006 | TODO | Integrate attachment encryption (KMS envelope), signed URL issuance, CSRF protection hooks for Console. Dependencies: LEDGER-29-005. | Findings Ledger Guild, Security Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-005 | DONE | Implement workflow mutation handlers (assign, comment, accept-risk, target-fix, verify-fix, reopen) producing ledger events with validation and attachments metadata. Dependencies: LEDGER-29-004. | Findings Ledger Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-006 | DONE | Integrate attachment encryption (KMS envelope), signed URL issuance, CSRF protection hooks for Console. Dependencies: LEDGER-29-005. | Findings Ledger Guild, Security Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-007 | TODO | Instrument metrics (`ledger_write_latency`, `projection_lag_seconds`, `ledger_events_total`), structured logs, and Merkle anchoring alerts; publish dashboards. Dependencies: LEDGER-29-006. | Findings Ledger Guild, Observability Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-008 | TODO | Develop unit/property/integration tests, replay/restore tooling, determinism harness, and load tests at 5M findings/tenant. Dependencies: LEDGER-29-007. | Findings Ledger Guild, QA Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
LEDGER-29-009 | TODO | Provide deployment manifests (Helm/Compose), backup/restore guidance, Merkle anchor externalization (optional), and offline kit instructions. Dependencies: LEDGER-29-008. | Findings Ledger Guild, DevOps Guild (src/Findings/StellaOps.Findings.Ledger/TASKS.md)
@@ -106,8 +106,8 @@ POLICY-ENGINE-20-008 | TODO | Add unit/property/golden/perf suites covering poli
POLICY-ENGINE-20-009 | TODO | Define Mongo schemas/indexes for `policies`, `policy_runs`, and `effective_finding_*`; implement migrations and tenant enforcement. Dependencies: POLICY-ENGINE-20-008. | Policy Guild, Storage Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-27-001 | TODO | Extend compile outputs to include rule coverage metadata, symbol table, inline documentation, and rule index for editor autocomplete; persist deterministic hashes. Dependencies: POLICY-ENGINE-20-009. | Policy Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-27-002 | TODO | Enhance simulate endpoints to emit rule firing counts, heatmap aggregates, sampled explain traces with deterministic ordering, and delta summaries for quick/batch sims. Dependencies: POLICY-ENGINE-27-001. | Policy Guild, Observability Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-27-003 | TODO | Implement complexity/time limit enforcement with compiler scoring, configurable thresholds, and structured diagnostics (`ERR_POL_COMPLEXITY`). Dependencies: POLICY-ENGINE-27-002. | Policy Guild, Security Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-27-004 | TODO | Update golden/property tests to cover new coverage metrics, symbol tables, explain traces, and complexity limits; provide fixtures for Registry/Console integration. Dependencies: POLICY-ENGINE-27-003. | Policy Guild, QA Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-27-003 | DONE | Implement complexity/time limit enforcement with compiler scoring, configurable thresholds, and structured diagnostics (`ERR_POL_COMPLEXITY`). Dependencies: POLICY-ENGINE-27-002. | Policy Guild, Security Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-27-004 | DONE | Update golden/property tests to cover new coverage metrics, symbol tables, explain traces, and complexity limits; provide fixtures for Registry/Console integration. Dependencies: POLICY-ENGINE-27-003. | Policy Guild, QA Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-29-001 | TODO | Implement batch evaluation endpoint (`POST /policy/eval/batch`) returning determinations + rationale chain for sets of `(artifact,purl,version,advisory)` tuples; support pagination and cost budgets. Dependencies: POLICY-ENGINE-27-004. | Policy Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)
POLICY-ENGINE-29-002 | TODO | Provide streaming simulation API comparing two policy versions, returning per-finding deltas without writes; align determinism with Vuln Explorer simulation. Dependencies: POLICY-ENGINE-29-001. | Policy Guild, Findings Ledger Guild (src/Policy/StellaOps.Policy.Engine/TASKS.md)

5
docs/implplan/SPRINT_140_runtime_signals.md
View File

@@ -48,7 +48,12 @@ Notes:
- 2025-10-29: JSON parsers for Java/Node.js/Python/Go implemented; artifacts stored on filesystem with SHA-256 and callgraphs upserted into Mongo.
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
SIGNALS-24-001 | DOING (2025-11-07) | Stand up Signals API skeleton with RBAC, sealed-mode config, DPoP/mTLS enforcement, and `/facts` scaffolding so downstream ingestion work can begin. Dependencies: AUTH-SIG-26-001. | Signals Guild, Authority Guild (src/Signals/StellaOps.Signals/TASKS.md)
SIGNALS-24-002 | DOING (2025-11-07) | Implement callgraph ingestion/normalization (Java/Node/Python/Go) with CAS persistence and retrieval APIs to feed reachability scoring. Dependencies: SIGNALS-24-001. | Signals Guild (src/Signals/StellaOps.Signals/TASKS.md)
SIGNALS-24-003 | BLOCKED (2025-10-27) | Implement runtime facts ingestion endpoint and normalizer (process, sockets, container metadata) populating `context_facts` with AOC provenance.<br>2025-10-27: Depends on `SIGNALS-24-001` for base API host and authentication plumbing. | Signals Guild, Runtime Guild (src/Signals/StellaOps.Signals/TASKS.md)
> 2025-11-07: Waiting on SIGNALS-24-001 / SIGNALS-24-002 DOING work to land before flipping this to DOING.
> 2025-11-07: Upstream SIGNALS-24-001 / SIGNALS-24-002 now DOING; this flips to DOING once host + callgraph ingestion merge.
> 2025-11-08: Targeting 2025-11-09 merge for SIGNALS-24-001/002; schema + AOC contract drafted so SIGNALS-24-003 can move to DOING immediately after those PRs land (dependencies confirmed, none missing).
SIGNALS-24-004 | BLOCKED (2025-10-27) | Deliver reachability scoring engine producing states/scores and writing to `reachability_facts`; expose configuration for weights. Dependencies: SIGNALS-24-003.<br>2025-10-27: Upstream ingestion pipelines (`SIGNALS-24-002/003`) blocked; scoring engine cannot proceed. | Signals Guild, Data Science (src/Signals/StellaOps.Signals/TASKS.md)
SIGNALS-24-005 | BLOCKED (2025-10-27) | Implement Redis caches (`reachability_cache:*`), invalidation on new facts, and publish `signals.fact.updated` events. Dependencies: SIGNALS-24-004.<br>2025-10-27: Awaiting scoring engine and ingestion layers before wiring cache/events. | Signals Guild, Platform Events Guild (src/Signals/StellaOps.Signals/TASKS.md)

6
docs/implplan/SPRINT_150_scheduling_automation.md
View File

@@ -51,7 +51,8 @@ Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
ORCH-SVC-38-101 | TODO | Standardize event envelope (policy/export/job lifecycle) with idempotency keys, ensure export/job failure events published to notifier bus with provenance metadata. Dependencies: ORCH-SVC-37-101. | Orchestrator Service Guild (src/Orchestrator/StellaOps.Orchestrator/TASKS.md)
ORCH-SVC-41-101 | TODO | Register `pack-run` job type, persist run metadata, integrate logs/artifacts collection, and expose API for Task Runner scheduling. Dependencies: ORCH-SVC-38-101. | Orchestrator Service Guild (src/Orchestrator/StellaOps.Orchestrator/TASKS.md)
ORCH-SVC-42-101 | TODO | Stream pack run logs via SSE/WS, add manifest endpoints, enforce quotas, and emit pack run events to Notifications Studio. Dependencies: ORCH-SVC-41-101. | Orchestrator Service Guild (src/Orchestrator/StellaOps.Orchestrator/TASKS.md)
ORCH-SVC-42-101 | TODO | Stream pack run logs via SSE/WS, add manifest endpoints, enforce quotas, and emit pack run events to Notifications Studio. Dependencies: ORCH-SVC-41-101. | Orchestrator Service Guild (src/Orchestrator/StellaOps.Orchestrator/TASKS.md)
> 2025-11-07: Still NOT STARTED—Authority pack RBAC (AUTH-PACKS-43-001) remains BLOCKED pending these approvals/log-stream APIs. Not missing; needs staffing.
ORCH-TEN-48-001 | TODO | Include `tenant_id`/`project_id` in job specs, set DB session context before processing, enforce context on all queries, and reject jobs missing tenant metadata. | Orchestrator Service Guild (src/Orchestrator/StellaOps.Orchestrator/TASKS.md)
WORKER-GO-32-001 | TODO | Bootstrap Go SDK project with configuration binding, auth headers, job claim/acknowledge client, and smoke sample. | Worker SDK Guild (src/Orchestrator/StellaOps.Orchestrator.WorkerSdk.Go/TASKS.md)
WORKER-GO-32-002 | TODO | Add heartbeat/progress helpers, structured logging hooks, Prometheus metrics, and jittered retry defaults. Dependencies: WORKER-GO-32-001. | Worker SDK Guild (src/Orchestrator/StellaOps.Orchestrator.WorkerSdk.Go/TASKS.md)
@@ -90,7 +91,8 @@ SCHED-IMPACT-16-303 | TODO | Snapshot/compaction + invalidation for removed imag
SCHED-SURFACE-01 | TODO | Evaluate Surface.FS pointers when planning delta scans to avoid redundant work and prioritise drift-triggered assets. | Scheduler Worker Guild (src/Scheduler/__Libraries/StellaOps.Scheduler.Worker/TASKS.md)
SCHED-VULN-29-001 | TODO | Expose resolver job APIs (`POST /vuln/resolver/jobs`, `GET /vuln/resolver/jobs/{id}`) to trigger candidate recomputation per artifact/policy change with RBAC and rate limits. | Scheduler WebService Guild, Findings Ledger Guild (src/Scheduler/StellaOps.Scheduler.WebService/TASKS.md)
SCHED-VULN-29-002 | TODO | Provide projector lag metrics endpoint and webhook notifications for backlog breaches consumed by DevOps dashboards. Dependencies: SCHED-VULN-29-001. | Scheduler WebService Guild, Observability Guild (src/Scheduler/StellaOps.Scheduler.WebService/TASKS.md)
SCHED-WEB-20-002 | BLOCKED (waiting on SCHED-WORKER-20-301) | Provide simulation trigger endpoint returning diff preview metadata and job state for UI/CLI consumption. | Scheduler WebService Guild (src/Scheduler/StellaOps.Scheduler.WebService/TASKS.md)
SCHED-WEB-20-002 | BLOCKED (waiting on SCHED-WORKER-20-301) | Provide simulation trigger endpoint returning diff preview metadata and job state for UI/CLI consumption. | Scheduler WebService Guild (src/Scheduler/StellaOps.Scheduler.WebService/TASKS.md)
> 2025-11-07: Worker counterpart (SCHED-WORKER-20-301) now DOING; revisit once API scaffolding lands.
SCHED-WEB-21-004 | DONE (2025-11-04) | Persist graph job lifecycle to Mongo storage and publish `scheduler.graph.job.completed@1` events + outbound webhook to Cartographer. Dependencies: SCHED-WEB-20-002. | Scheduler WebService Guild, Scheduler Storage Guild (src/Scheduler/StellaOps.Scheduler.WebService/TASKS.md)
> 2025-11-04: Graph job completions now persist to Mongo with optimistic guards, emit Redis/webhook notifications once per transition, and refresh result URI metadata idempotently (tests cover service + Mongo store paths).
SCHED-WORKER-21-203 | TODO | Export metrics (`graph_build_seconds`, `graph_jobs_inflight`, `overlay_lag_seconds`) and structured logs with tenant/graph identifiers. | Scheduler Worker Guild, Observability Guild (src/Scheduler/__Libraries/StellaOps.Scheduler.Worker/TASKS.md)

8
docs/implplan/SPRINT_180_experience_sdks.md
View File

@@ -227,6 +227,14 @@ WEB-AOC-19-001 `Shared AOC guard primitives` | DONE (2025-11-07) | Provide `AOCF
WEB-AOC-19-002 `Provenance & signature helpers` | TODO | Ship `ProvenanceBuilder`, checksum utilities, and signature verification helper integrated with guard logging. Cover DSSE/CMS formats with unit tests. Dependencies: WEB-AOC-19-001. | BE-Base Platform Guild (src/Web/StellaOps.Web/TASKS.md)
WEB-AOC-19-003 `Analyzer + test fixtures` | TODO | Author Roslyn analyzer preventing ingestion modules from writing forbidden keys without guard, and provide shared test fixtures for guard validation used by Concelier/Excititor service tests. Dependencies: WEB-AOC-19-002. | QA Guild, BE-Base Platform Guild (src/Web/StellaOps.Web/TASKS.md)
WEB-CONSOLE-23-001 `Global posture endpoints` | TODO | Provide consolidated `/console/dashboard` and `/console/filters` APIs returning tenant-scoped aggregates (findings by severity, VEX override counts, advisory deltas, run health, policy change log). Enforce AOC labelling, deterministic ordering, and cursor-based pagination for drill-down hints. | BE-Base Platform Guild, Product Analytics Guild (src/Web/StellaOps.Web/TASKS.md)
CONSOLE-VULN-29-001 `Vulnerability workspace` | DOING (2025-11-08) | Build `/console/vuln/*` APIs and filters surfacing tenant-scoped findings with policy/VEX badges so Docs/UI teams can document workflows. Dependencies: WEB-CONSOLE-23-001, CONCELIER-GRAPH-21-001. | Console Guild, BE-Base Platform Guild (src/Web/StellaOps.Web/TASKS.md)
> 2025-11-07: API scaffolding kicked off; `docs/advisory-ai/console.md` consuming placeholder responses until this lands. Scheduler/Signals hooks queued once filters stabilized.
> 2025-11-08: Driving filter + reachability badge wiring plus `/console/vuln/search` DTOs to keep DOCS-AIAI-31-004 on real payloads; aligning Signals/Scheduler dependencies now that upstream tickets exist.
> 2025-11-08: Published HTTP contract + sample payloads in `docs/api/console/workspaces.md` and `docs/api/console/samples/vuln-findings-sample.json` so Docs can stage screenshots while backend wires up.
CONSOLE-VEX-30-001 `VEX evidence workspace` | DOING (2025-11-08) | Provide `/console/vex/*` APIs streaming VEX statements, justification summaries, and advisory links with SSE refresh hooks. Dependencies: WEB-CONSOLE-23-001, EXCITITOR-CONSOLE-23-001. | Console Guild, BE-Base Platform Guild (src/Web/StellaOps.Web/TASKS.md)
> 2025-11-07: Endpoint contract draft in progress to unblock DOCS-AIAI-31-004 screenshot capture once responses are wired.
> 2025-11-08: Building SSE controller + `/console/vex/events` payloads and syncing Scheduler Signals tasks so DOCS-AIAI-31-004 can embed live data.
> 2025-11-08: SSE schema + NDJSON sample captured in `docs/api/console/workspaces.md` and `docs/api/console/samples/vex-statement-sse.ndjson`; waiting on Scheduler topic hook-up.
WEB-CONSOLE-23-002 `Live status & SSE proxy` | TODO | Expose `/console/status` polling endpoint and `/console/runs/{id}/stream` SSE/WebSocket proxy with heartbeat/backoff, queue lag metrics, and auth scope enforcement. Surface request IDs + retry headers. Dependencies: WEB-CONSOLE-23-001. | BE-Base Platform Guild, Scheduler Guild (src/Web/StellaOps.Web/TASKS.md)
WEB-CONSOLE-23-003 `Evidence export orchestrator` | TODO | Add `/console/exports` POST/GET routes coordinating evidence bundle creation, streaming CSV/JSON exports, checksum manifest retrieval, and signed attestation references. Ensure requests honor tenant + policy scopes and expose job tracking metadata. Dependencies: WEB-CONSOLE-23-002. | BE-Base Platform Guild, Policy Guild (src/Web/StellaOps.Web/TASKS.md)
WEB-CONSOLE-23-004 `Global search router` | TODO | Implement `/console/search` endpoint accepting CVE/GHSA/PURL/SBOM identifiers, performing fan-out queries with caching, ranking, and deterministic tie-breaking. Return typed results for Console navigation; respect result caps and latency SLOs. Dependencies: WEB-CONSOLE-23-003. | BE-Base Platform Guild (src/Web/StellaOps.Web/TASKS.md)

24
docs/implplan/SPRINT_190_ops_offline.md
View File

@@ -48,7 +48,9 @@ DEVOPS-AIRGAP-56-001 | TODO | Ship deny-all egress policies for Kubernetes (Netw
DEVOPS-AIRGAP-56-002 | TODO | Provide import tooling for bundle staging: checksum validation, offline object-store loader scripts, removable media guidance. Dependencies: DEVOPS-AIRGAP-56-001. | DevOps Guild, AirGap Importer Guild (ops/devops/TASKS.md)
DEVOPS-AIRGAP-56-003 | TODO | Build Bootstrap Pack pipeline bundling images/charts, generating checksums, and publishing manifest for offline transfer. Dependencies: DEVOPS-AIRGAP-56-002. | DevOps Guild, Container Distribution Guild (ops/devops/TASKS.md)
DEVOPS-AIRGAP-57-001 | TODO | Automate Mirror Bundle creation jobs with dual-control approvals, artifact signing, and checksum publication. Dependencies: DEVOPS-AIRGAP-56-003. | DevOps Guild, Mirror Creator Guild (ops/devops/TASKS.md)
DEVOPS-AIRGAP-57-002 | TODO | Configure sealed-mode CI tests that run services with sealed flag and ensure no egress occurs (iptables + mock DNS). Dependencies: DEVOPS-AIRGAP-57-001. | DevOps Guild, Authority Guild (ops/devops/TASKS.md)
DEVOPS-AIRGAP-57-002 | DOING (2025-11-08) | Configure sealed-mode CI tests that run services with sealed flag and ensure no egress occurs (iptables + mock DNS). Dependencies: DEVOPS-AIRGAP-57-001. | DevOps Guild, Authority Guild (ops/devops/TASKS.md)
> 2025-11-07: Harness scaffolded at `ops/devops/sealed-mode-ci/*` (README + runner script); integrate into CI to unblock AUTH-AIRGAP-57-001.
> 2025-11-08: `sealed-mode-compose.yml`, `run-sealed-ci.sh`, and `egress_probe.py` committed plus a `sealed-mode-ci` workflow stage that uploads `artifacts/sealed-mode-ci/<commit>/authority-sealed-ci.json`; Authority can now read the sealed evidence feed.
DEVOPS-AIRGAP-58-001 | TODO | Provide local SMTP/syslog container templates and health checks for sealed environments; integrate into Bootstrap Pack. Dependencies: DEVOPS-AIRGAP-57-002. | DevOps Guild, Notifications Guild (ops/devops/TASKS.md)
DEVOPS-AIRGAP-58-002 | TODO | Ship sealed-mode observability stack (Prometheus/Grafana/Tempo/Loki) pre-configured with offline dashboards and no remote exporters. Dependencies: DEVOPS-AIRGAP-58-001. | DevOps Guild, Observability Guild (ops/devops/TASKS.md)
DEVOPS-AOC-19-001 | BLOCKED (2025-10-26) | Integrate the AOC Roslyn analyzer and guard tests into CI, failing builds when ingestion projects attempt banned writes. | DevOps Guild, Platform Guild (ops/devops/TASKS.md)
@@ -235,4 +237,24 @@ PROV-OBS-54-001 | TODO | Deliver verification library that validates DSSE signat
PROV-OBS-54-002 | TODO | Generate .NET global tool for local verification + embed command helpers for CLI `stella forensic verify`. Provide deterministic packaging and offline kit instructions. Dependencies: PROV-OBS-54-001. | Provenance Guild, DevEx/CLI Guild (src/Provenance/StellaOps.Provenance.Attestation/TASKS.md)
[Ops & Offline] 190.K) Sovereign Crypto Enablement
Depends on: Sprint 100.A - Attestor, Sprint 110.A - AdvisoryAI, Sprint 120.A - AirGap, Sprint 130.A - Scanner, Sprint 140.A - Graph, Sprint 150.A - Orchestrator, Sprint 160.A - EvidenceLocker, Sprint 170.A - Notifier, Sprint 180.A - Cli
Summary: Deliver RootPack_RU-ready sovereign crypto providers (CryptoPro + PKCS#11), configuration knobs, deterministic tests, and repo-wide crypto routing audit.
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
SEC-CRYPTO-90-001 | DONE (2025-11-07) | Produce RootPack_RU sovereign crypto implementation plan, identify provider strategy (CryptoPro + PKCS#11), and slot work into Sprint 190 with task breakdown. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
SEC-CRYPTO-90-002 | DONE (2025-11-07) | Extend signature/catalog constants and configuration schema to recognize `GOST12-256/512`, regional crypto profiles, and provider preference ordering. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
SEC-CRYPTO-90-003 | DONE (2025-11-07) | Implement `StellaOps.Cryptography.Plugin.CryptoPro` provider (sign/verify/JWK export) using CryptoPro CSP/GostCryptography with deterministic logging + tests. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
SEC-CRYPTO-90-004 | DONE (2025-11-07) | Implement `StellaOps.Cryptography.Plugin.Pkcs11Gost` provider (Rutoken/JaCarta) via Pkcs11Interop, configurable slot/pin/module management, and disposal safeguards. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
SEC-CRYPTO-90-005 | DONE (2025-11-08) | Add configuration-driven provider selection (`crypto.regionalProfiles`), CLI/diagnostic verb to list providers/keys, and deterministic telemetry for usage. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
SEC-CRYPTO-90-006 | DONE (2025-11-08) | Build deterministic test harness (Streebog + signature vectors), manual runbooks for hardware validation, and capture RootPack audit metadata. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
SEC-CRYPTO-90-007 | DONE (2025-11-08) | Package RootPack_RU artifacts (plugin binaries, config templates, trust anchors) and document deployment/install steps + compliance evidence. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
SEC-CRYPTO-90-008 | DONE (2025-11-08) | Audit repository for any cryptography usage bypassing `StellaOps.Cryptography` and file remediation tasks to route through providers. | Security Guild (src/__Libraries/StellaOps.Cryptography/TASKS.md)
AUTH-CRYPTO-90-001 | DOING (2025-11-08) | Migrate Authority signing/key-loading paths (provider registry + crypto hash) so regional bundles can select sovereign providers per docs/security/crypto-routing-audit-2025-11-07.md. | Authority Core & Security Guild (src/Authority/StellaOps.Authority/TASKS.md)
SCANNER-CRYPTO-90-001 | DONE (2025-11-08) | Route remaining Scanner Worker hashing/digest consumers (Surface pointers, manifest publishers, CAS helpers, Sbomer plugins) through ICryptoHash/provider registry.<br>2025-11-08: EntryTrace execution, Surface manifest writer, Local CAS client, and Sbomer descriptor generator now accept ICryptoHash; tests updated with CryptoHashFactory/TestCryptoHash helpers. | Scanner Worker Guild & Security Guild (src/Scanner/StellaOps.Scanner.Worker/TASKS.md)
CONCELIER-CRYPTO-90-001 | DOING (2025-11-08) | Route OpenAPI discovery hashing plus Concelier mirror/RU connectors through `ICryptoHash`/provider registry so sovereign bundles can swap CryptoPro/PKCS#11 keys without code changes. | Concelier WebService Guild & Security Guild (src/Concelier/StellaOps.Concelier.WebService/TASKS.md)
If all tasks are done - read next sprint section - SPRINT_200_documentation_process.md

18
docs/implplan/SPRINT_200_documentation_process.md
View File

@@ -5,15 +5,15 @@ Depends on: Sprint 100.A - Attestor, Sprint 110.A - AdvisoryAI, Sprint 120.A - A
Summary: Documentation & Process focus on Docs Tasks (phase Md.I).
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
DOCS-AIAI-31-001 | TODO | Publish `/docs/advisory-ai/overview.md` covering capabilities, guardrails, RBAC. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-002 | TODO | Author `/docs/advisory-ai/architecture.md` detailing RAG pipeline, deterministics, caching, model options. Dependencies: DOCS-AIAI-31-001. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-003 | TODO | Write `/docs/advisory-ai/api.md` describing endpoints, schemas, errors, rate limits. Dependencies: DOCS-AIAI-31-002. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-004 | TODO | Create `/docs/advisory-ai/console.md` with screenshots, a11y notes, copy-as-ticket instructions. Dependencies: DOCS-AIAI-31-003. | Docs Guild, Console Guild (docs/TASKS.md)
DOCS-AIAI-31-005 | TODO | Publish `/docs/advisory-ai/cli.md` covering commands, exit codes, scripting patterns. Dependencies: DOCS-AIAI-31-004. | Docs Guild, DevEx/CLI Guild (docs/TASKS.md)
DOCS-AIAI-31-006 | TODO | Update `/docs/policy/assistant-parameters.md` covering temperature, token limits, ranking weights, TTLs. Dependencies: DOCS-AIAI-31-005. | Docs Guild, Policy Guild (docs/TASKS.md)
DOCS-AIAI-31-007 | TODO | Write `/docs/security/assistant-guardrails.md` detailing redaction, injection defense, logging. Dependencies: DOCS-AIAI-31-006. | Docs Guild, Security Guild (docs/TASKS.md)
DOCS-AIAI-31-008 | TODO | Publish `/docs/sbom/remediation-heuristics.md` (feasibility scoring, blast radius). Dependencies: DOCS-AIAI-31-007. | Docs Guild, SBOM Service Guild (docs/TASKS.md)
DOCS-AIAI-31-009 | TODO | Create `/docs/runbooks/assistant-ops.md` for warmup, cache priming, model outages, scaling. Dependencies: DOCS-AIAI-31-008. | Docs Guild, DevOps Guild (docs/TASKS.md)
DOCS-AIAI-31-001 | DONE (2025-11-03) | Publish `/docs/advisory-ai/overview.md` covering capabilities, guardrails, RBAC. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-002 | DONE (2025-11-03) | Author `/docs/advisory-ai/architecture.md` detailing RAG pipeline, deterministics, caching, model options. Dependencies: DOCS-AIAI-31-001. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-003 | DONE (2025-11-03) | Write `/docs/advisory-ai/api.md` describing endpoints, schemas, errors, rate limits. Dependencies: DOCS-AIAI-31-002. | Docs Guild, Advisory AI Guild (docs/TASKS.md)
DOCS-AIAI-31-004 | DOING (2025-11-07) | Create `/docs/advisory-ai/console.md` with screenshots, a11y notes, copy-as-ticket instructions. Dependencies: DOCS-AIAI-31-003, CONSOLE-VULN-29-001, CONSOLE-VEX-30-001, EXCITITOR-CONSOLE-23-001. | Docs Guild, Console Guild (docs/TASKS.md)
DOCS-AIAI-31-005 | BLOCKED (2025-11-03) | Publish `/docs/advisory-ai/cli.md` covering commands, exit codes, scripting patterns. Dependencies: DOCS-AIAI-31-004, CLI-VULN-29-001, CLI-VEX-30-001. | Docs Guild, DevEx/CLI Guild (docs/TASKS.md)
DOCS-AIAI-31-006 | BLOCKED (2025-11-03) | Update `/docs/policy/assistant-parameters.md` covering temperature, token limits, ranking weights, TTLs. Dependencies: DOCS-AIAI-31-005, POLICY-ENGINE-31-001. | Docs Guild, Policy Guild (docs/TASKS.md)
DOCS-AIAI-31-007 | DONE (2025-11-07) | Write `/docs/security/assistant-guardrails.md` detailing redaction, injection defense, logging. Dependencies: DOCS-AIAI-31-006. | Docs Guild, Security Guild (docs/TASKS.md)
DOCS-AIAI-31-008 | BLOCKED (2025-11-03) | Publish `/docs/sbom/remediation-heuristics.md` (feasibility scoring, blast radius). Dependencies: DOCS-AIAI-31-007, SBOM-AIAI-31-001. | Docs Guild, SBOM Service Guild (docs/TASKS.md)
DOCS-AIAI-31-009 | BLOCKED (2025-11-03) | Create `/docs/runbooks/assistant-ops.md` for warmup, cache priming, model outages, scaling. Dependencies: DOCS-AIAI-31-008, DEVOPS-AIAI-31-001. | Docs Guild, DevOps Guild (docs/TASKS.md)
DOCS-AIRGAP-56-001 | TODO | Publish `/docs/airgap/overview.md` outlining modes, lifecycle, responsibilities, and imposed rule banner. | Docs Guild, AirGap Controller Guild (docs/TASKS.md)
DOCS-AIRGAP-56-002 | TODO | Author `/docs/airgap/sealing-and-egress.md` covering network policies, EgressPolicy facade usage, and verification steps. Dependencies: DOCS-AIRGAP-56-001. | Docs Guild, DevOps Guild (docs/TASKS.md)
DOCS-AIRGAP-56-003 | TODO | Create `/docs/airgap/mirror-bundles.md` describing bundle format, DSSE/TUF/Merkle validation, creation/import workflows. Dependencies: DOCS-AIRGAP-56-002. | Docs Guild, Exporter Guild (docs/TASKS.md)

17
docs/implplan/SPRINT_201_reachability_explainability.md Normal file
View File

@@ -0,0 +1,17 @@
# Sprint 201 - Reachability Explainability & Replay Evidence
[Reachability Delivery] 201.A) Runtime facts + static callgraph union
Depends on: Sprint 140 Runtime Signals, Sprint 185 Replay Core, Sprint 186 Scanner Record Mode, Sprint 187 Evidence & CLI Replay
Summary: Close the explainability gaps by wiring Zastava runtime sampling, Scanner language lifters, Signals scoring, Replay manifests, docs, and test harnesses around the reachbench fixture packs.
Task ID | State | Task description | Owners (Source)
--- | --- | --- | ---
ZASTAVA-REACH-201-001 | TODO | Implement runtime symbol sampling in `StellaOps.Zastava.Observer` (EntryTrace-aware shell AST + build-id capture) and stream ND-JSON batches to Signals `/runtime-facts`, including CAS pointers for traces. Update runbook + config references. | Zastava Observer Guild (`src/Zastava/StellaOps.Zastava.Observer/TASKS.md`)
SCAN-REACH-201-002 | DOING (2025-11-08) | Ship language-aware static lifters (JVM, .NET/Roslyn+IL, Go SSA, Node/Deno TS AST, Rust MIR, Swift SIL, shell/binary analyzers) in Scanner Worker; emit canonical SymbolIDs, CAS-stored graphs, and attach reachability tags to SBOM components. | Scanner Worker Guild (`src/Scanner/StellaOps.Scanner.Worker/TASKS.md`)
SIGNALS-REACH-201-003 | DOING (2025-11-08) | Extend Signals ingestion to accept the new multi-language graphs + runtime facts, normalize into `reachability_graphs` CAS layout, and expose retrieval APIs for Policy/CLI. | Signals Guild (`src/Signals/StellaOps.Signals/TASKS.md`)
SIGNALS-REACH-201-004 | DOING (2025-11-08) | Build the reachability scoring engine (state/score/confidence), wire Redis caches + `signals.fact.updated` events, and integrate reachability weights defined in `docs/11_DATA_SCHEMAS.md`. | Signals Guild · Policy Guild (`src/Signals/StellaOps.Signals/TASKS.md`, `src/Policy/StellaOps.Policy.Engine/TASKS.md`)
REPLAY-REACH-201-005 | DOING (2025-11-08) | Update `StellaOps.Replay.Core` manifest schema + bundle writer so replay packs capture reachability graphs, runtime traces, analyzer versions, and evidence hashes; document new CAS namespace. | BE-Base Platform Guild (`src/__Libraries/StellaOps.Replay.Core/TASKS.md`)
DOCS-REACH-201-006 | TODO | Author the reachability doc set (`docs/signals/reachability.md`, `callgraph-formats.md`, `runtime-facts.md`, CLI/UI appendices) plus update Zastava + Replay guides with the new evidence and operators’ workflow. | Docs Guild (`docs/TASKS.md`)
QA-REACH-201-007 | TODO | Integrate `reachbench-2025-expanded` fixture pack under `tests/reachability/`, add evaluator harness tests that validate reachable vs unreachable cases, and wire CI guidance for deterministic runs. | QA Guild (`tests/README.md`)
> 2025-11-07: reachbench starter + expanded packs staged under repo root; consuming guilds must relocate fixtures into `tests/reachability/fixtures/` as part of QA-REACH-201-007 before enabling CI.

7
docs/modules/devops/architecture.md
View File

@@ -75,9 +75,10 @@ At startup, services **self‑advertise** their semver & channel; the UI surface
### 2.4 Gates & tests
* **Static**: linters, codegen checks, protobuf API freeze (backward‑compat tests).
* **Unit/integration**: per‑component, plus **end‑to‑end** flows (scan→vex→policy→sign→attest).
* **Perf SLOs**: hot paths (SBOM compose, diff, export) measured against budgets.
* **Security**: dependency audit vs Concelier export; container hardening tests; minimal caps.
* **Unit/integration**: per-component, plus **end-to-end** flows (scan→vex→policy→sign→attest).
* **Perf SLOs**: hot paths (SBOM compose, diff, export) measured against budgets.
* **Security**: dependency audit vs Concelier export; container hardening tests; minimal caps.
* **Deployment assets**: `Build Test Deploy` workflow’s `profile-validation` job installs Helm and runs `helm lint` + `helm template` against `deploy/helm/stellaops` for every `values*.yaml`, catching ConfigMap/templating drift before merges.
* **Analyzer smoke**: restart-time language plug-ins (currently Python) verified via `dotnet run --project src/Tools/LanguageAnalyzerSmoke` to ensure manifest integrity plus cold vs warm determinism (< 30 s / < 5 s budgets); the harness logs deviations from repository goldens for follow-up.
* **Canary cohort**: internal staging + selected customers; one week on **edge** before **stable** tag.

1509
docs/modules/excititor/architecture.md
View File

File diff suppressed because it is too large Load Diff

30
docs/modules/findings-ledger/workflow-inference.md Normal file
View File

@@ -0,0 +1,30 @@
# Findings Ledger — Workflow Inference Notes
> **Audience:** Findings Ledger Guild, Vuln Explorer API, Console Guild
> **Scope:** How workflow mutations (assign/comment/accept-risk/etc.) derive canonical ledger inputs when the caller omits low-level fields.
## 1. Chain + sequencing
- **Chain derivation.** When a request does not provide `chainId`, we deterministically derive it from `tenantId :: policyVersion` (`Guid` from SHA-256 first 16 bytes). This keeps per-policy ordering stable and avoids callers leaking raw GUID logic.
- **Sequence number.** We fetch the current chain head and expect `head.sequence + 1`. If the chain has no entries, the expected sequence is `1`. The append path still enforces optimistic concurrency and rejects mismatches.
- **Previous hash.** We reuse the head’s `event_hash` (defaulting to the all-zero hash for genesis events) so writers don’t need to manage hash pointers.
## 2. Event identifiers + timestamps
- **Event IDs.** If the caller omits `eventId`, we mint a V7 GUID to keep chronological ordering while remaining globally unique.
- **Occurred / recorded timestamps.** `occurredAt` defaults to “now” in UTC (based on `TimeProvider`). `recordedAt` always comes from the service’s `TimeProvider` to avoid caller-provided drift.
## 3. Status & severity fallbacks
- The reducer already maps event types to canonical statuses. Workflow service only writes `status` when the mutation explicitly changes it (e.g., `accept-risk` → `accepted_risk`, `target-fix` → `in_progress`, `verify-fix` → `verified`, `reopen` → `affected`). Otherwise we leave status null and let the reducer infer it.
- Severity is never inferred inside workflow handlers—they rely on policy evaluation or reducer logic.
## 4. Attachments metadata
- Attachments now include security context: every entry captures an AES-256-GCM envelope (`algorithm`, `ciphertext`, `nonce`, `tag`, `expiresAt`) derived from `attachments.encryptionKey`.
- Signed URLs are generated with HMAC-SHA256 using `attachments.signedUrlSecret` and inherit `attachments.signedUrlLifetime` (default 15 minutes). URLs plus envelopes share the same expiry window.
- Metadata is normalized (trimmed keys, deterministic ordering) before encryption so ledger hashes remain stable; duplicate IDs are deduplicated.
- Actual binary blobs stay in Evidence Locker/S3; the envelope is what downstream services use to decrypt the blob once downloaded.
## 5. Validation surface
- All handlers enforce tenant/policy/finding/artifact/vuln IDs, actor identity, and supported actor types.
- Mutation-specific requirements (e.g., assignment requires assignee, accept-risk needs justification) are validated before any ledger append occurs.
- Attachments are validated for ID/file name/MIME type/positive size and 64-char SHA-256 digests before encryption, preventing malformed payloads from burning hashes or emitting invalid URLs.
These rules let upstream APIs/clients send high-level workflow intents without micromanaging ledger sequencing or hashing, while preserving deterministic ledger entries. LEDGER-29-005 implements the service described here; LEDGER-29-006 builds on it for secure attachment handling.

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

@@ -150,6 +150,7 @@ sequenceDiagram
2. `inputbundle.tar.zst` (feeds, policies, tools, environment snapshot).
3. `outputbundle.tar.zst` (SBOM, findings, VEX, logs, Merkle proofs).
Every artifact is signed with multi-profile keys (FIPS, GOST, SM, etc.) managed by Authority. See `docs/replay/DETERMINISTIC_REPLAY.md` §2–§5 for the full schema.
- **Reachability subtree:** When reachability recording is enabled, Scanner uploads graphs & runtime traces under `cas://replay/<scan-id>/reachability/graphs/` and `cas://replay/<scan-id>/reachability/traces/`. Manifest references (StellaOps.Replay.Core) bind these URIs along with analyzer hashes so Replay + Signals can rehydrate explainability evidence deterministically.
- **Storage tiers:** Primary storage is Mongo (`replay_runs`, `replay_subjects`) plus the CAS bucket. Evidence Locker mirrors bundles for long-term retention and legal hold workflows (`docs/modules/evidence-locker/architecture.md`). Offline kits package bundles under `offline/replay/<scan-id>` with detached DSSE envelopes for air-gapped verification.
- **APIs & ownership:** Scanner WebService produces the bundles via `record` mode, Scanner Worker emits Merkle metadata, Signer/Authority provide DSSE signatures, Attestor anchors manifests to Rekor, CLI/Evidence Locker handle retrieval, and Docs Guild maintains runbooks. Responsibilities are tracked in `docs/implplan/SPRINT_185_replay_core.md` through `SPRINT_187_evidence_cli_replay.md`.
- **Operational policies:** Retention defaults to 180 days for hot CAS storage and 2 years for cold Evidence Locker copies. Rotation and pruning follow the checklist in `docs/runbooks/replay_ops.md`.

81
docs/observability/observability.md
View File

@@ -25,6 +25,51 @@ This guide captures the canonical signals emitted by Concelier and Excititor onc
- **Stale ingestion:** Alert when `max_over_time(ingestion_latency_seconds_sum / ingestion_latency_seconds_count)[30m]` exceeds 30 s or if `ingestion_write_total` has no growth for > 60 min.
- **Signature drop:** Warn when `rate(ingestion_signature_verified_total{result="fail"}[1h]) > 0`.
### 1.2 · `/obs/excititor/health`
`GET /obs/excititor/health` (scope `vex.admin`) returns a compact snapshot for Grafana tiles and Console widgets:
- `ingest` — overall status, worst lag (seconds), and the top connectors (status, lagSeconds, failure count, last success).
- `link` — freshness of consensus/linkset processing plus document counts and the number currently carrying conflicts.
- `signature` — recent coverage window (evaluated, with signatures, verified, failures, unsigned, coverage ratio).
- `conflicts` — rolling totals grouped by status plus per-bucket trend data for charts.
```json
{
"generatedAt": "2025-11-08T11:00:00Z",
"ingest": { "status": "healthy", "connectors": [ { "connectorId": "excititor:redhat", "lagSeconds": 45.3 } ] },
"link": { "status": "warning", "lastConsensusAt": "2025-11-08T10:57:03Z" },
"signature": { "status": "critical", "documentsEvaluated": 120, "verified": 30, "failures": 2 },
"conflicts": { "status": "warning", "conflictStatements": 325, "trend": [ { "bucketStart": "2025-11-08T10:00:00Z", "conflicts": 130 } ] }
}
```
| Setting | Default | Purpose |
|---------|---------|---------|
| `Excititor:Observability:IngestWarningThreshold` | `06:00:00` | Connector lag before `ingest.status` becomes `warning`. |
| `Excititor:Observability:IngestCriticalThreshold` | `24:00:00` | Connector lag before `ingest.status` becomes `critical`. |
| `Excititor:Observability:LinkWarningThreshold` | `00:15:00` | Maximum acceptable delay between consensus recalculations. |
| `Excititor:Observability:LinkCriticalThreshold` | `01:00:00` | Delay that marks link status as `critical`. |
| `Excititor:Observability:SignatureWindow` | `12:00:00` | Lookback window for signature coverage. |
| `Excititor:Observability:SignatureHealthyCoverage` | `0.8` | Coverage ratio that still counts as healthy. |
| `Excititor:Observability:SignatureWarningCoverage` | `0.5` | Coverage ratio that flips the status to `warning`. |
| `Excititor:Observability:ConflictTrendWindow` | `24:00:00` | Rolling window used for conflict aggregation. |
| `Excititor:Observability:ConflictTrendBucketMinutes` | `60` | Resolution of conflict `trend` buckets. |
| `Excititor:Observability:ConflictWarningRatio` | `0.15` | Fraction of consensus docs with conflicts that triggers `warning`. |
| `Excititor:Observability:ConflictCriticalRatio` | `0.3` | Ratio that marks `conflicts.status` as `critical`. |
| `Excititor:Observability:MaxConnectorDetails` | `50` | Number of connector entries returned (keeps payloads small). |
### 1.3 · Regression & DI hygiene
1. **Keep storage/integration tests green when telemetry touches persistence.**
- `./tools/mongodb/local-mongo.sh start` downloads MongoDB 6.0.16 (if needed), launches `rs0`, and prints `export EXCITITOR_TEST_MONGO_URI=mongodb://.../excititor-tests`. Copy that export into your shell.
- `./tools/mongodb/local-mongo.sh restart` is a shortcut for “stop if running, then start” using the same dataset—use it after tweaking config or when tests need a bounce without wiping fixtures.
- `./tools/mongodb/local-mongo.sh clean` stops the instance (if running) and deletes the managed data/log directories so storage tests begin from a pristine catalog.
- Run `dotnet test src/Excititor/__Tests/StellaOps.Excititor.Storage.Mongo.Tests/StellaOps.Excititor.Storage.Mongo.Tests.csproj -nologo -v minimal` (add `--filter` if you only touched specific suites). These tests exercise the same write paths that feed the dashboards, so regressions show up immediately.
- `./tools/mongodb/local-mongo.sh stop` when finished so CI/dev hosts stay clean; `status|logs|shell` are available for troubleshooting.
2. **Declare optional Minimal API dependencies with `[FromServices] ... = null`.** RequestDelegateFactory treats `[FromServices] IVexSigner? signer = null` (or similar) as optional, so host startup succeeds even when tests have not registered that service. This pattern keeps observability endpoints cancellable while avoiding brittle test overrides.
---
## 2 · Traces
@@ -45,6 +90,35 @@ This guide captures the canonical signals emitted by Concelier and Excititor onc
- Use `aoc.guard` spans to inspect guard payload snapshots. Sensitive fields are redacted automatically; raw JSON lives in secure logs only.
- For scheduled verification, filter traces by `initiator="scheduled"` to compare runtimes pre/post change.
### 2.3 Telemetry configuration (Excititor)
- Configure the web service via `Excititor:Telemetry`:
```jsonc
{
"Excititor": {
"Telemetry": {
"Enabled": true,
"EnableTracing": true,
"EnableMetrics": true,
"ServiceName": "stellaops-excititor-web",
"OtlpEndpoint": "http://otel-collector:4317",
"OtlpHeaders": {
"Authorization": "Bearer ${OTEL_PUSH_TOKEN}"
},
"ResourceAttributes": {
"env": "prod-us",
"service.group": "ingestion"
}
}
}
}
```
- Point the OTLP endpoint at the shared collector profile from §1 so Excititor metrics land in the `ingestion_*` dashboards next to Concelier. Resource attributes drive Grafana filtering (e.g., `env`, `service.group`).
- For offline/air-gap bundles set `Enabled=false` and collect the file exporter artifacts from the Offline Kit; import them into Grafana after transfer to keep time-to-truth dashboards consistent.
- Local development templates: run `tools/mongodb/local-mongo.sh start` to spin up a single-node replica set plus the matching `mongosh` client. The script prints the `export EXCITITOR_TEST_MONGO_URI=...` command that integration tests (e.g., `StellaOps.Excititor.Storage.Mongo.Tests`) will honor. Use `restart` for a quick bounce, `clean` to wipe data between suites, and `stop` when finished.
---
## 3 · Logs
@@ -61,6 +135,13 @@ Structured logs include the following keys (JSON):
| `violation.code` | Present when guard rejects `ERR_AOC_00x`. |
| `verification.window` | Present on `/aoc/verify` job logs. |
Excititor APIs mirror these identifiers via response headers:
| Header | Purpose |
| --- | --- |
| `X-Stella-TraceId` | W3C trace/span identifier for deep-linking from Console → Grafana/Loki. |
| `X-Stella-CorrelationId` | Stable correlation identifier (respects inbound header or falls back to the request trace ID). |
Logs are shipped to the central Loki/Elasticsearch cluster. Use the template query:
```logql

262
docs/policy/gateway.md
View File

@@ -1,124 +1,138 @@
# Policy Gateway
> **Delivery scope:** `StellaOps.Policy.Gateway` minimal API service fronting Policy Engine pack CRUD + activation endpoints for UI/CLI clients. Sender-constrained with DPoP and tenant headers, suitable for online and Offline Kit deployments.
## 1 · Responsibilities
- Proxy policy pack CRUD and activation requests to Policy Engine while enforcing scope policies (`policy:read`, `policy:author`, `policy:review`, `policy:operate`, `policy:activate`).
- Normalise responses (DTO + `ProblemDetails`) so Console, CLI, and automation receive consistent payloads.
- Guard activation actions with structured logging and metrics so approvals are auditable.
- Support dual auth modes:
- Forwarded caller tokens (Console/CLI) with DPoP proofs + `X-Stella-Tenant` header.
- Gateway client credentials (DPoP) for service automation or Offline Kit flows when no caller token is present.
## 2 · Endpoints
| Route | Method | Description | Required scope(s) |
|-------|--------|-------------|-------------------|
| `/api/policy/packs` | `GET` | List policy packs and revisions for the active tenant. | `policy:read` |
| `/api/policy/packs` | `POST` | Create a policy pack shell or upsert display metadata. | `policy:author` |
| `/api/policy/packs/{packId}/revisions` | `POST` | Create or update a policy revision (draft/approved). | `policy:author` |
| `/api/policy/packs/{packId}/revisions/{version}:activate` | `POST` | Activate a revision, enforcing single/two-person approvals. | `policy:operate`, `policy:activate` |
### Response shapes
- Successful responses return camel-case DTOs matching `PolicyPackDto`, `PolicyRevisionDto`, or `PolicyRevisionActivationDto` as described in the Policy Engine API doc (`/docs/api/policy.md`).
- Errors always return RFC 7807 `ProblemDetails` with deterministic fields (`title`, `detail`, `status`). Missing caller credentials now surface `401` with `"Upstream authorization missing"` detail.
## 3 · Authentication & headers
| Header | Source | Notes |
|--------|--------|-------|
| `Authorization` | Forwarded caller token *or* gateway client credentials. | Caller tokens must include tenant scope; gateway tokens default to `DPoP` scheme. |
| `DPoP` | Caller or gateway. | Required when Authority mandates proof-of-possession (default). Generated per request; gateway keeps ES256/ES384 key material under `etc/policy-gateway-dpop.pem`. |
| `X-Stella-Tenant` | Caller | Tenant isolation header. Forwarded unchanged; gateway automation omits it. |
Gateway client credentials are configured in `policy-gateway.yaml`:
```yaml
policyEngine:
baseAddress: "https://policy-engine.internal"
audience: "api://policy-engine"
clientCredentials:
enabled: true
clientId: "policy-gateway"
clientSecret: "<secret>"
scopes:
- policy:read
- policy:author
- policy:review
- policy:operate
- policy:activate
dpop:
enabled: true
keyPath: "../etc/policy-gateway-dpop.pem"
algorithm: "ES256"
```
> 🔐 **DPoP key** – store the private key alongside Offline Kit secrets; rotate it whenever the gateway identity or Authority configuration changes.
## 4 · Metrics & logging
All activation calls emit:
- `policy_gateway_activation_requests_total{outcome,source}` – counter labelled with `outcome` (`activated`, `pending_second_approval`, `already_active`, `bad_request`, `not_found`, `unauthorized`, `forbidden`, `error`) and `source` (`caller`, `service`).
- `policy_gateway_activation_latency_ms{outcome,source}` – histogram measuring proxy latency.
Structured logs (category `StellaOps.Policy.Gateway.Activation`) include `PackId`, `Version`, `Outcome`, `Source`, and upstream status code for audit trails.
## 5 · Sample `curl` workflows
Assuming you already obtained a DPoP-bound access token (`$TOKEN`) for tenant `acme`:
```bash
# Generate a DPoP proof for GET via the CLI helper
DPoP_PROOF=$(stella auth dpop proof \
--htu https://gateway.example.com/api/policy/packs \
--htm GET \
--token "$TOKEN")
curl -sS https://gateway.example.com/api/policy/packs \
-H "Authorization: DPoP $TOKEN" \
-H "DPoP: $DPoP_PROOF" \
-H "X-Stella-Tenant: acme"
# Draft a new revision
DPoP_PROOF=$(stella auth dpop proof \
--htu https://gateway.example.com/api/policy/packs/policy.core/revisions \
--htm POST \
--token "$TOKEN")
curl -sS https://gateway.example.com/api/policy/packs/policy.core/revisions \
-H "Authorization: DPoP $TOKEN" \
-H "DPoP: $DPoP_PROOF" \
-H "X-Stella-Tenant: acme" \
-H "Content-Type: application/json" \
-d '{"version":5,"requiresTwoPersonApproval":true,"initialStatus":"Draft"}'
# Activate revision 5 (returns 202 when awaiting the second approver)
DPoP_PROOF=$(stella auth dpop proof \
--htu https://gateway.example.com/api/policy/packs/policy.core/revisions/5:activate \
--htm POST \
--token "$TOKEN")
curl -sS https://gateway.example.com/api/policy/packs/policy.core/revisions/5:activate \
-H "Authorization: DPoP $TOKEN" \
-H "DPoP: $DPoP_PROOF" \
-H "X-Stella-Tenant: acme" \
-H "Content-Type: application/json" \
-d '{"comment":"Rollout baseline"}'
```
For air-gapped environments, bundle `policy-gateway.yaml` and the DPoP key in the Offline Kit (see `/docs/24_OFFLINE_KIT.md` §5.7).
> **DPoP proof helper:** Use `stella auth dpop proof` to mint sender-constrained proofs locally. The command accepts `--htu`, `--htm`, and `--token` arguments and emits a ready-to-use header value. Teams maintaining alternate tooling (for example, `scripts/make-dpop.sh`) can substitute it as long as the inputs and output match the CLI behaviour.
## 6 · Offline Kit guidance
- Include `policy-gateway.yaml.sample` and the resolved runtime config in the Offline Kit’s `config/` tree.
- Place the DPoP private key under `secrets/policy-gateway-dpop.pem` with restricted permissions; document rotation steps in the manifest.
- When building verification scripts, use the gateway endpoints above instead of hitting Policy Engine directly. The Offline Kit validator now expects `policy_gateway_activation_requests_total` metrics in the Prometheus snapshot.
## 7 · Change log
- **2025-10-27 – Sprint 18.5**: Initial gateway bootstrap + activation metrics + DPoP client credentials.
# Policy Gateway
> **Delivery scope:** `StellaOps.Policy.Gateway` minimal API service fronting Policy Engine pack CRUD + activation endpoints for UI/CLI clients. Sender-constrained with DPoP and tenant headers, suitable for online and Offline Kit deployments.
## 1 · Responsibilities
- Proxy policy pack CRUD and activation requests to Policy Engine while enforcing scope policies (`policy:read`, `policy:author`, `policy:review`, `policy:operate`, `policy:activate`).
- Normalise responses (DTO + `ProblemDetails`) so Console, CLI, and automation receive consistent payloads.
- Guard activation actions with structured logging and metrics so approvals are auditable.
- Support dual auth modes:
- Forwarded caller tokens (Console/CLI) with DPoP proofs + `X-Stella-Tenant` header.
- Gateway client credentials (DPoP) for service automation or Offline Kit flows when no caller token is present.
## 2 · Endpoints
| Route | Method | Description | Required scope(s) |
|-------|--------|-------------|-------------------|
| `/api/policy/packs` | `GET` | List policy packs and revisions for the active tenant. | `policy:read` |
| `/api/policy/packs` | `POST` | Create a policy pack shell or upsert display metadata. | `policy:author` |
| `/api/policy/packs/{packId}/revisions` | `POST` | Create or update a policy revision (draft/approved). | `policy:author` |
| `/api/policy/packs/{packId}/revisions/{version}:activate` | `POST` | Activate a revision, enforcing single/two-person approvals. | `policy:operate`, `policy:activate` |
### Response shapes
- Successful responses return camel-case DTOs matching `PolicyPackDto`, `PolicyRevisionDto`, or `PolicyRevisionActivationDto` as described in the Policy Engine API doc (`/docs/api/policy.md`).
- Errors always return RFC 7807 `ProblemDetails` with deterministic fields (`title`, `detail`, `status`). Missing caller credentials now surface `401` with `"Upstream authorization missing"` detail.
### Dual-control activation
- **Config-driven.** Set `PolicyEngine.activation.forceTwoPersonApproval=true` when every activation must collect two distinct `policy:activate` approvals. When false, operators can opt into dual-control per revision (`requiresTwoPersonApproval: true`).
- **Defaults.** `PolicyEngine.activation.defaultRequiresTwoPersonApproval` feeds the default when callers omit the checkbox/flag.
- **Statuses.** First approval on a dual-control revision returns `202 pending_second_approval`; duplicate actors get `400 duplicate_approval`; the second distinct approver receives the usual `200 activated`.
- **Audit trail.** With `PolicyEngine.activation.emitAuditLogs` on, Policy Engine emits structured `policy.activation.*` scopes (pack id, revision, tenant, approver IDs, comments) so the gateway metrics/ELK dashboards can show who approved what.
#### Activation configuration wiring
- **Helm ConfigMap.** `deploy/helm/stellaops/values*.yaml` now include a `policy-engine-activation` ConfigMap. The chart automatically injects it via `envFrom` into both the Policy Engine and Policy Gateway pods, so overriding the ConfigMap data updates the services with no manifest edits.
- **Type safety.** Quote ConfigMap values (e.g., `"true"`, `"false"`) because Kubernetes ConfigMaps carry string data. This mirrors the defaults checked into the repo and keeps `helm template` deterministic.
- **File-based overrides (optional).** The Policy Engine host already probes `/config/policy-engine/activation.yaml`, `../etc/policy-engine.activation.yaml`, and ambient `policy-engine.activation.yaml` files beside the binary. Mounting the ConfigMap as a file at `/config/policy-engine/activation.yaml` works immediately if/when we add a volume.
- **Offline/Compose.** Compose/offline bundles can continue exporting `STELLAOPS_POLICY_ENGINE__ACTIVATION__*` variables directly; the ConfigMap wiring simply mirrors those keys for Kubernetes clusters.
## 3 · Authentication & headers
| Header | Source | Notes |
|--------|--------|-------|
| `Authorization` | Forwarded caller token *or* gateway client credentials. | Caller tokens must include tenant scope; gateway tokens default to `DPoP` scheme. |
| `DPoP` | Caller or gateway. | Required when Authority mandates proof-of-possession (default). Generated per request; gateway keeps ES256/ES384 key material under `etc/policy-gateway-dpop.pem`. |
| `X-Stella-Tenant` | Caller | Tenant isolation header. Forwarded unchanged; gateway automation omits it. |
Gateway client credentials are configured in `policy-gateway.yaml`:
```yaml
policyEngine:
baseAddress: "https://policy-engine.internal"
audience: "api://policy-engine"
clientCredentials:
enabled: true
clientId: "policy-gateway"
clientSecret: "<secret>"
scopes:
- policy:read
- policy:author
- policy:review
- policy:operate
- policy:activate
dpop:
enabled: true
keyPath: "../etc/policy-gateway-dpop.pem"
algorithm: "ES256"
```
> 🔐 **DPoP key** – store the private key alongside Offline Kit secrets; rotate it whenever the gateway identity or Authority configuration changes.
## 4 · Metrics & logging
All activation calls emit:
- `policy_gateway_activation_requests_total{outcome,source}` – counter labelled with `outcome` (`activated`, `pending_second_approval`, `already_active`, `bad_request`, `not_found`, `unauthorized`, `forbidden`, `error`) and `source` (`caller`, `service`).
- `policy_gateway_activation_latency_ms{outcome,source}` – histogram measuring proxy latency.
Structured logs (category `StellaOps.Policy.Gateway.Activation`) include `PackId`, `Version`, `Outcome`, `Source`, and upstream status code for audit trails.
## 5 · Sample `curl` workflows
Assuming you already obtained a DPoP-bound access token (`$TOKEN`) for tenant `acme`:
```bash
# Generate a DPoP proof for GET via the CLI helper
DPoP_PROOF=$(stella auth dpop proof \
--htu https://gateway.example.com/api/policy/packs \
--htm GET \
--token "$TOKEN")
curl -sS https://gateway.example.com/api/policy/packs \
-H "Authorization: DPoP $TOKEN" \
-H "DPoP: $DPoP_PROOF" \
-H "X-Stella-Tenant: acme"
# Draft a new revision
DPoP_PROOF=$(stella auth dpop proof \
--htu https://gateway.example.com/api/policy/packs/policy.core/revisions \
--htm POST \
--token "$TOKEN")
curl -sS https://gateway.example.com/api/policy/packs/policy.core/revisions \
-H "Authorization: DPoP $TOKEN" \
-H "DPoP: $DPoP_PROOF" \
-H "X-Stella-Tenant: acme" \
-H "Content-Type: application/json" \
-d '{"version":5,"requiresTwoPersonApproval":true,"initialStatus":"Draft"}'
# Activate revision 5 (returns 202 when awaiting the second approver)
DPoP_PROOF=$(stella auth dpop proof \
--htu https://gateway.example.com/api/policy/packs/policy.core/revisions/5:activate \
--htm POST \
--token "$TOKEN")
curl -sS https://gateway.example.com/api/policy/packs/policy.core/revisions/5:activate \
-H "Authorization: DPoP $TOKEN" \
-H "DPoP: $DPoP_PROOF" \
-H "X-Stella-Tenant: acme" \
-H "Content-Type: application/json" \
-d '{"comment":"Rollout baseline"}'
```
For air-gapped environments, bundle `policy-gateway.yaml` and the DPoP key in the Offline Kit (see `/docs/24_OFFLINE_KIT.md` §5.7).
> **DPoP proof helper:** Use `stella auth dpop proof` to mint sender-constrained proofs locally. The command accepts `--htu`, `--htm`, and `--token` arguments and emits a ready-to-use header value. Teams maintaining alternate tooling (for example, `scripts/make-dpop.sh`) can substitute it as long as the inputs and output match the CLI behaviour.
## 6 · Offline Kit guidance
- Include `policy-gateway.yaml.sample` and the resolved runtime config in the Offline Kit’s `config/` tree.
- Place the DPoP private key under `secrets/policy-gateway-dpop.pem` with restricted permissions; document rotation steps in the manifest.
- When building verification scripts, use the gateway endpoints above instead of hitting Policy Engine directly. The Offline Kit validator now expects `policy_gateway_activation_requests_total` metrics in the Prometheus snapshot.
## 7 · Change log
- **2025-10-27 – Sprint 18.5**: Initial gateway bootstrap + activation metrics + DPoP client credentials.

69
docs/replay/DETERMINISTIC_REPLAY.md
View File

@@ -98,23 +98,58 @@ C --> J[Blob Store: Input/Output Bundles]
],
"trustProfile": "sha256:..."
},
"outputs": {
"sbomHash": "sha256:...",
"findingsHash": "sha256:...",
"vexHash": "sha256:...",
"logHash": "sha256:..."
},
"provenance": {
"signer": "scanner.authority",
"dsseEnvelopeHash": "sha256:...",
"rekorEntry": "optional"
}
}
```
---
## 4. Deterministic Execution Rules
"outputs": {
"sbomHash": "sha256:...",
"findingsHash": "sha256:...",
"vexHash": "sha256:...",
"logHash": "sha256:..."
},
"reachability": {
"graphs": [
{
"kind": "static",
"analyzer": "scanner/java@sha256:...",
"casUri": "cas://replay/scan-123/reachability/static-graph.tar.zst",
"sha256": "abc123"
},
{
"kind": "framework",
"analyzer": "scanner/framework@sha256:...",
"casUri": "cas://replay/scan-123/reachability/framework-graph.tar.zst",
"sha256": "def456"
}
],
"runtimeTraces": [
{
"source": "zastava",
"casUri": "cas://replay/scan-123/reachability/runtime-trace.ndjson.zst",
"sha256": "feedface",
"recordedAt": "2025-11-07T11:10:00Z"
}
]
},
"provenance": {
"signer": "scanner.authority",
"dsseEnvelopeHash": "sha256:...",
"rekorEntry": "optional"
}
}
```
### 3.2 Reachability Section
The optional `reachability` block captures the inputs needed to replay explainability decisions:
| Field | Description |
|-------|-------------|
| `reachability.graphs[]` | References to static/framework callgraph bundles. Each entry records the producing analyzer (`analyzer`/`version`), the CAS URI under `cas://replay/<scan-id>/reachability/graphs/`, and the SHA-256 digest of the tarball. |
| `reachability.runtimeTraces[]` | References to runtime observation bundles (e.g., Zastava ND-JSON traces). Each item stores the emitting source, CAS URI (typically `cas://replay/<scan-id>/reachability/traces/`), SHA-256, and capture timestamp. |
Replay engines MUST verify every referenced artifact hash before re-evaluating reachability. Missing graphs downgrade affected signals to `reachability:unknown` and should raise policy warnings.
---
## 4. Deterministic Execution Rules
### 4.1 Environment Normalization

31
docs/replay/DEVS_GUIDE_REPLAY.md
View File

@@ -30,10 +30,11 @@ Replay is the foundation for:
| **Subject** | OCI image digest, per-layer Merkle roots | ✅ |
| **Outputs** | SBOM, Findings, VEX, logs (content hashes) | ✅ |
| **Toolchain** | Sbomer, Scanner, Vexer binaries + versions + SHA256 | ✅ |
| **Feeds/VEX sources** | Full or pruned snapshot with Merkle proofs | ✅ |
| **Policy Bundle** | Lattice rules, mutes, trust profiles, thresholds | ✅ |
| **Environment** | OS, arch, locale, TZ, deterministic seed, runtime flags | ✅ |
| **Crypto Profile** | Algorithm suites (FIPS, GOST, SM, eIDAS) | ✅ |
| **Feeds/VEX sources** | Full or pruned snapshot with Merkle proofs | ✅ |
| **Policy Bundle** | Lattice rules, mutes, trust profiles, thresholds | ✅ |
| **Environment** | OS, arch, locale, TZ, deterministic seed, runtime flags | ✅ |
| **Reachability Evidence** | Callgraphs (`graphs[]`), runtime traces (`runtimeTraces[]`), analyzer/version hashes | ✅ |
| **Crypto Profile** | Algorithm suites (FIPS, GOST, SM, eIDAS) | ✅ |
---
@@ -69,8 +70,9 @@ stella replay manifest.json --what-if --vary=feeds
## Workflow
1. `stella scan image:tag --record out/`
- Generates Replay Manifest, InputBundle, OutputBundle, DSSE sigs.
1. `stella scan image:tag --record out/`
- Generates Replay Manifest, InputBundle, OutputBundle, DSSE sigs.
- Captures reachability graphs/traces (if enabled) and references them via `reachability.graphs[]` + `runtimeTraces[]`.
2. `stella verify manifest.json`
- Validates hashes, signatures, and completeness.
3. `stella replay manifest.json --strict`
@@ -82,14 +84,15 @@ stella replay manifest.json --what-if --vary=feeds
---
## Storage
- **Mongo collections**
- `replay_runs`: manifest + DSSE envelopes + status
- `bundles`: content-addressed (input/output/rootpack)
- `subjects`: OCI digests, Merkle roots per layer
- **File store**
- Bundles stored as `<sha256>.tar.zst`
## Storage
- **Mongo collections**
- `replay_runs`: manifest + DSSE envelopes + status
- `bundles`: content-addressed (input/output/rootpack)
- `subjects`: OCI digests, Merkle roots per layer
- `reachability_facts`: graph & runtime trace references tied to scan subjects
- **File store**
- Bundles stored as `<sha256>.tar.zst`
---

4
docs/replay/TEST_STRATEGY.md
View File

@@ -19,6 +19,7 @@ This playbook enumerates the deterministic replay validation suite. It guides th
| T-RETENTION-006 | **Retention Sweep** | Ensure Evidence Locker prunes hot CAS after SLA while preserving cold storage copies. | Evidence Locker, Ops | Replay retention config, audit logs |
| T-OFFLINE-007 | **Offline Kit Replay** | Execute `stella replay` using only Offline Kit artifacts. | CLI, Evidence Locker | Offline kit bundle, local RootPack |
| T-OPA-008 | **Runbook Drill** | Simulate replay-driven incident response per `docs/runbooks/replay_ops.md`. | Ops Guild, Scanner, Authority | Runbook checklist, incident notes |
| T-REACH-009 | **Reachability Replay** | Rehydrate reachability graphs/traces from replay bundles and compare against reachbench fixtures. | Scanner, Signals, Replay | `reachbench-2025-expanded`, reachability CAS references |
---
@@ -50,7 +51,8 @@ This playbook enumerates the deterministic replay validation suite. It guides th
- [ ] Replay verification metrics ingested into Telemetry Stack dashboards.
- [ ] Evidence Locker retention job validated against hot/cold tiers.
- [ ] CLI documentation updated with troubleshooting steps observed during tests.
- [ ] Runbook drill logged with timestamp and owners in `docs/runbooks/replay_ops.md`.
- [ ] Runbook drill logged with timestamp and owners in `docs/runbooks/replay_ops.md`.
- [ ] Reachability replay drill captured (`T-REACH-009`) with fixture references and Signals verification logs.
---

113
docs/security/crypto-routing-audit-2025-11-07.md Normal file
View File

@@ -0,0 +1,113 @@
# Crypto Routing Audit — 07 Nov 2025
**Scope.** Inventory direct uses of `System.Security.Cryptography` (and related primitives) outside the `StellaOps.Cryptography*` stack to identify callers that must be routed through sovereign-aware providers (default, PKCS#11, CryptoPro, future PQC).
**Method.** `rg -l "using System.Security.Cryptography" src | grep -Ev "__Tests|\.Tests/"` (filtered for runtime code). Counts reflect unique files per top-level module.
## Summary (runtime files by module)
| Module/Area | Files bypassing shared crypto |
|-------------|------------------------------|
| Concelier | 34 |
| Scanner | 31 |
| Authority | 20 |
| Excititor | 18 |
| Attestor | 18 |
| EvidenceLocker | 10 |
| Findings / Vuln Explorer | 7 |
| Zastava | 6 |
| ExportCenter| 6 |
| Policy | 4 |
| Scheduler | 3 |
| CLI | 3 |
| Bench | 3 |
| AdvisoryAI | 3 |
| Other (Notify, Registry, Signals, etc.) | 11 combined |
## Configuring `crypto.regionalProfiles`
All hosts can now express provider ordering and profile overrides via configuration:
```yaml
Crypto:
registry:
preferredProviders:
- default
- ru.pkcs11
activeProfile: ru-offline
profiles:
ru-offline:
preferredProviders:
- ru.cryptopro.csp
- ru.pkcs11
pkcs11:
keys:
- keyId: ru-slot-token
libraryPath: /usr/local/lib/librutokenecp.so
slotId: "0x1"
privateKeyLabel: signing-key
certificateThumbprint: "<thumbprint>"
cryptopro:
keys:
- keyId: ru-csp-token
libraryPath: /opt/cprocsp/lib/libcapi20.so
containerLabel: KRYPTO_PRO_KEY
certificateThumbprint: "<thumbprint>"
```
Each deployment picks a profile (`activeProfile`) that resolves to a deterministic provider order, and individual services call into `ICryptoProviderRegistry` rather than new-ing crypto stacks directly.
## Inspecting providers from the CLI
`stellaops crypto providers` now lists the registered providers, signing algorithms, certificate metadata, and the current preferred order. Use `--json` for machine-readable output or `--profile <name>` to preview another profile (e.g., `ru-offline`) before flipping configuration.
## High-priority hotspots
### Concelier (ingestion + mirror connectors)
- `src/Concelier/StellaOps.Concelier.WebService/Services/OpenApiDiscoveryDocumentProvider.cs` – builds SHA256 hashes for discovery docs inline.
- `src/Concelier/__Libraries/StellaOps.Concelier.Connector.StellaOpsMirror/Security/MirrorSignatureVerifier.cs` – performs RSA verification directly.
- `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Ru.Nkcki/RuNkckiConnector.cs` and `.Ru.Bdu` – local hash/signature handling for regional advisories.
**Action:** Introduce `ICryptoProviderRegistry` consumption inside connector/lib assemblies (probably through lightweight adapter service). File follow-up tasks in `src/Concelier/StellaOps.Concelier.WebService/TASKS.md` and connector TASK boards to migrate hashing/signing to the new PKCS#11/CryptoPro providers (priority for RU feeds to unblock RootPack_RU).
### Scanner (web service, worker, Sbomer plug-ins)
- `src/Scanner/StellaOps.Scanner.WebService/Utilities/ScanIdGenerator.cs` – direct SHA256 for id derivation.
- `src/Scanner/StellaOps.Scanner.WebService/Services/ReportSigner.cs` – uses `ECDsa.Create()` directly for DSSE hand-off.
- `src/Scanner/StellaOps.Scanner.Worker/Processing/Surface/SurfaceManifestPublisher.cs` – manual digesting before CAS writes.
**Action:** Create shared `IScanCryptoService` backed by `ICryptoProviderRegistry` so both web service and worker reuse sovereign providers. Add tasks under `src/Scanner/StellaOps.Scanner.WebService/TASKS.md` and `src/Scanner/StellaOps.Scanner.Worker/TASKS.md`.
### Authority (plugins + signing host)
- `StellaOps.Authority/Signing/*` classes still load PEM/PKCS#12 directly via `X509Certificate2` and `RSA`.
- `AuthoritySecretHasher` and `AuthorityClientCertificateValidator` maintain custom hashing.
**Action:** Wire Authority signing/loading paths to `ICryptoProviderRegistry` so active keys can point to `ru.cryptopro.csp` or `ru.pkcs11`. Open tasks in `src/Authority/StellaOps.Authority/TASKS.md` covering: signing key loading, JWKS generation, secret hashing migration.
### Excititor / Attestor
- Excititor connectors (e.g., `src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Ghsa/GhsaConnector.cs`) re-hash payloads in place.
- Attestor submission cache uses SHA256 for bundle ids.
**Action:** Introduce shared hashing helper that internally calls `ICryptoProviderRegistry.ResolveOrThrow(CryptoCapability.Signing, SignatureAlgorithms.GostR3410_2012_256)` for digest+sign combos; log follow-ups in respective TASK boards.
### Evidence Locker / Export Center
- Export packaging code manually builds SHA/V1 digests before signing manifests.
**Action:** Add backlog tasks for both modules to replace `SHA256.Create()` usage with provider-backed hashing (especially for offline bundle sealing).
## Next steps
1. **Open remediation tasks per module** referencing this audit (minimum: Concelier, Scanner, Authority, Excititor, Attestor, Evidence Locker, Export Center). Each task should specify which files to migrate and target provider (default vs sovereign).
2. **Provide shared helpers** (e.g., `ICryptoDigestService`, `ICasSigner`) in `StellaOps.Cryptography` to ease adoption and avoid each module talking to the registry manually.
3. **Follow-up audit** once migrations land; rerun the command and ensure only `StellaOps.Cryptography*` and vetted crypto libraries contain direct `System.Security.Cryptography` usage.
4. **RootPack validation runbook** — see `docs/security/rootpack_ru_validation.md` for deterministic tests, hardware validation, and required audit artifacts before shipping RootPack_RU.
### Remediation tracking snapshot (2025-11-08)
- **Authority:** `AUTH-CRYPTO-90-001` (Authority TASKS board)
- **Scanner:** `SCANNER-CRYPTO-90-001` (WebService TASKS board)
- **Concelier:** `CONCELIER-CRYPTO-90-001` (WebService TASKS board)
- **Excititor:** `EXCITITOR-CRYPTO-90-001` (WebService TASKS board)
- **Attestor:** `ATTESTOR-CRYPTO-90-001` (Attestor TASKS board)
- **Evidence Locker:** `EVID-CRYPTO-90-001` (Evidence Locker TASKS board)
- **Export Center:** `EXPORT-CRYPTO-90-001` (Exporter Service TASKS board)
> Stored query artifacts: `/tmp/crypto_runtime_non_tests.txt` (157 runtime files) and aggregated counts above prepared on 2025-11-07.

45
docs/security/dpop-mtls-rollout.md Normal file
View File

@@ -0,0 +1,45 @@
# Authority DPoP + mTLS Rollout Plan (Sprint 100)
_Last updated: 2025-11-07_
## Objectives
1. Enforce DPoP sender constraints (`AUTH-DPOP-11-001`).
2. Bind high-assurance tenants to mTLS tokens (`AUTH-MTLS-11-002`).
3. Provide telemetry + runbooks so plugins (SEC2/SEC3/SEC5) can validate enforcement without regressions.
## Phase 1 · Config & Telemetry (ETA 2025-11-08)
- [ ] Extend `authority.yaml` with `security.senderConstraints.dpop` section (nonce store, allowed algorithms, replay window).
- [ ] Wire structured logs (`authority.dpop.request`) containing tenant, client, cnf thumbprint, nonce status.
- [ ] Add `DPoPNonceStore` abstraction + Redis implementation for multi-node deployments.
- [ ] Update integration tests: `AuthorityTokenTests.DPoPNonceRequired`, `AuthorityTokenTests.DPoPMustMatchCnF`.
## Phase 2 · Enforcement & Fallback (ETA 2025-11-10)
- [ ] Reject `/token` requests lacking DPoP proof when tenant policy requires it.
- [ ] Persist `cnf.jkt` and expose through `/introspect` so downstream services validate sender.
- [ ] Add emergency bypass flag (`security.senderConstraints.dpop.allowTemporaryBypass`) for sealed recap drills; default disabled.
## Phase 3 · mTLS Binding (ETA 2025-11-10)
- [x] Capture client cert thumbprint on `/token` (mutual TLS) and store in `authority_tokens.senderCertificate`.
- [x] Validate cert hash on `/introspect` and `/fresh-auth`.
- [ ] Document bootstrap/rotation in `docs/11_AUTHORITY.md` + `docs/security/dpop-mtls-rollout.md` (this file).
## Verification Matrix
| Scenario | Test/Command | Expected |
| --- | --- | --- |
| DPoP required w/out proof | `dotnet test Authority.Tests --filter DPoPRequiresProofTest` | 400 with `use_dpop_nonce` header. |
| Nonce replay | Replay previous proof within window | 401 + audit log entry. |
| mTLS mismatch | Reuse token with different cert | 401 + `senderCertificateMismatch` metric increment. |
## Telemetry & Alerting
- Metrics: `authority_dpop_nonce_miss_total`, `authority_mtls_mismatch_total` (emitted with `reason` tags for context-missing, missing-certificate, and thumbprint-mismatch cases).
- Logs: `authority.security.senderConstraint` (structured).
- Alerts: Page DevOps when nonce miss > 5% or mTLS mismatches > 0 over 10 min.
## Dependencies
- Authority Core & Security Guild owners.
- DevOps to provide sealed-mode CI coverage (`DEVOPS-AIRGAP-57-002`).
- Plugin Standard Guild to consume new telemetry once rolled out.
## Communication
- Daily async update in `#guild-authority` thread referencing this plan.
- Link this document from `docs/implplan/SPRINT_100_identity_signing.md` notes once Phase 1 merges.

68
docs/security/rootpack_ru_package.md Normal file
View File

@@ -0,0 +1,68 @@
# RootPack_RU Packaging Guide
This guide describes the reproducible process for assembling the sovereign cryptography bundle that backs RootPack_RU deployments.
## 1. What the bundle contains
| Directory | Purpose |
|-----------|---------|
| `artifacts/` | Published binaries for `StellaOps.Cryptography.Plugin.CryptoPro` and `StellaOps.Cryptography.Plugin.Pkcs11Gost` (targeting `net10.0`). |
| `config/rootpack_ru.crypto.yaml` | Opinionated configuration template that enables the `ru-offline` crypto profile and defines CryptoPro + PKCS#11 keys. |
| `docs/` | Validation runbook, audit report, and this packaging guide. |
| `trust/` | Russian trust-anchor PEM files copied from `certificates/russian_trusted_*`. |
| `README.txt` | High-level summary plus operator checklist. |
## 2. Build the bundle
```bash
# from repository root
scripts/crypto/package-rootpack-ru.sh
# optionally specify destination
scripts/crypto/package-rootpack-ru.sh /tmp/rootpack_ru_$(date -u +%Y%m%dT%H%M%SZ)
```
The script performs the following steps:
1. `dotnet publish` for the CryptoPro + PKCS#11 plug-ins (`Release` configuration).
2. Copies the relevant documentation (`docs/security/rootpack_ru_validation.md`, `docs/security/crypto-routing-audit-2025-11-07.md`, and this guide).
3. Includes the example configuration found at `etc/rootpack/ru/crypto.profile.yaml`.
4. Adds the Russian trust anchors from `certificates/russian_trusted_*`.
5. Emits `README.txt` and optionally creates a `*.tar.gz` archive (set `PACKAGE_TAR=0` to skip the tarball).
## 3. Attach deterministic test evidence
After running `scripts/crypto/package-rootpack-ru.sh`, execute the deterministic harness to capture logs:
```bash
scripts/crypto/run-rootpack-ru-tests.sh
# or specify ROOTPACK_LOG_DIR=/tmp/rootpack_ru_tests scripts/crypto/run-rootpack-ru-tests.sh
```
Copy the resulting `logs/rootpack_ru_<timestamp>/` directory into the bundle before distributing it (or store it alongside the tarball in your evidence store).
Each harness run produces a `README.tests` file plus matching `.log/.trx` pairs for every project. Move the entire directory under an evidence folder inside the bundle (for example `evidence/validation/<timestamp>/`) so operators can quickly locate the README, raw logs, and provider JSON snapshots when assembling compliance paperwork:
```bash
dest="${1:-out/rootpack_ru}"
ts="$(ls logs | grep rootpack_ru_ | sort | tail -n1)"
mkdir -p "${dest}/evidence/validation"
cp -a "logs/${ts}" "${dest}/evidence/validation/${ts}"
```
## 4. Hardware validation + audit metadata
Follow `docs/security/rootpack_ru_validation.md` to:
- Validate CryptoPro CSP and PKCS#11 tokens.
- Capture `stellaops crypto providers --profile ru-offline --json` output.
- Archive JWKS snapshots and `CryptoProviderMetrics` samples.
- Document hardware serials and operator initials in `hardware_notes.md`.
Store these artifacts under `logs/rootpack_ru_<timestamp>/` (same directory as the test harness outputs) and reference them in release paperwork.
## 5. Deployment summary
1. Import the bundled trust anchors into the target installation (Authority + Scanner).
2. Apply `config/rootpack_ru.crypto.yaml`, update certificate thumbprints, slots, and container labels to match the operator tokens.
3. Restart the services so `ICryptoProviderRegistry` reloads the `ru-offline` profile.
4. Re-run the validation runbook to confirm JWKS, telemetry, and RootPack evidence are aligned with the shipping bundle.

45
docs/security/rootpack_ru_validation.md Normal file
View File

@@ -0,0 +1,45 @@
# RootPack_RU Crypto Validation Runbook
## Purpose
This runbook documents the repeatable steps for validating the Russian sovereign crypto profile (CryptoPro + PKCS#11) prior to publishing a RootPack bundle. It supplements the crypto routing audit by covering deterministic tests, hardware validation, and the audit metadata artifacts that must be attached to each release.
## 1. Deterministic Test Harness
1. Run `scripts/crypto/run-rootpack-ru-tests.sh` (optional `ROOTPACK_LOG_DIR=/tmp/rootpack_ru_logs` to override the output path). The script executes:
- `src/__Libraries/__Tests/StellaOps.Cryptography.Tests/StellaOps.Cryptography.Tests.csproj`
- `src/Scanner/__Tests/StellaOps.Scanner.Worker.Tests/StellaOps.Scanner.Worker.Tests.csproj`
- `src/Scanner/__Tests/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests.csproj`
and emits `.log` + `.trx` pairs plus `README.tests` under `logs/rootpack_ru_<timestamp>/`.
2. For ad-hoc runs (CI or IDE) ensure the same three projects succeed; the cryptography tests validate SHA-256/SHA-512 against BCL implementations and both Streebog variants against BouncyCastle digests.
3. Archive the generated log directory (`logs/rootpack_ru_<timestamp>/`) along with any additional test outputs inside the RootPack evidence bundle.
## 2. Hardware Validation (CryptoPro CSP)
1. Install CryptoPro CSP (v5.0 or later) on the validation host and import the qualified certificate configured for the deployment.
2. Configure `StellaOps:Crypto:CryptoPro:Keys` with the container handle and certificate thumbprint and set `StellaOps:Crypto:Registry:ActiveProfile=ru-offline`.
3. Run the provider diagnostics to confirm the key material is visible:
- `stellaops crypto providers --profile ru-offline --json > logs/ru_cryptopro_providers.json`
4. Issue a JWKS fetch (`curl https://authority.local/.well-known/jwks`) and verify the `kid` and `crv` values match the CryptoPro-backed key.
5. Capture the Authority logs showing `AuthoritySecretHasherInitializer` startup and the `CryptoProviderMetrics` counters for `ru.cryptopro.csp` usage.
## 3. Hardware Validation (PKCS#11 Tokens)
1. Install the vendor PKCS#11 library (e.g., Rutoken `rtPKCS11ECP.dll` or JaCarta) and configure the slot/PIN inside `StellaOps:Crypto:Pkcs11:Keys`.
2. Switch the registry profile to prioritize `ru.pkcs11` and rerun `stellaops crypto providers --profile ru-offline --json > logs/ru_pkcs11_providers.json`.
3. Execute a signing workflow (Authority JWKS refresh or Scanner manifest publish) and confirm the `CryptoProviderMetrics` counters record `ru.pkcs11` activity.
4. Export the token audit logs (if available) and store them with the RootPack evidence bundle.
## 4. RootPack Audit Metadata
Create a metadata bundle per validation run and store it under `logs/rootpack_ru_<timestamp>/` containing:
- `providers_ru_offline.json` – output from `stellaops crypto providers --profile ru-offline --json`.
- `crypto_tests.txt` – snippets from the unit-test executions listed above.
- `hardware_notes.md` – human-readable notes describing token serials, firmware, and operator initials.
- `jwks_snapshot.json` – raw JWKS response captured after sovereign providers are active.
- `metrics_snapshot.json` – scrape of `CryptoProviderMetrics` Prometheus samples for both providers.
Attach this directory to the RootPack artifact and reference it from the release checklist.
Refer back to `docs/security/crypto-routing-audit-2025-11-07.md` for the full inventory of components that must consume the shared cryptography stack, and `docs/security/rootpack_ru_package.md` for packaging/attachment steps.