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

Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source
This commit is contained in:
master
2025-12-09 13:08:17 +02:00
parent f30805ad7f 689c656f20
commit 199aaf74d8
10050 changed files with 313174 additions and 7518670 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1850
docs/09_API_CLI_REFERENCE.md
View File

File diff suppressed because it is too large Load Diff

24
docs/advisories/explorer-integration.md Normal file
View File

@@ -0,0 +1,24 @@
# Advisories Integration with Vuln Explorer (Md.XI draft)
> Status: DRAFT — waiting on export bundle spec + provenance notes; keep TODO.
## Scope
- Describe advisory normalization, withdrawn handling, provenance, and export bundle linkage for Vuln Explorer.
- Deterministic examples with hashes in `docs/assets/vuln-explorer/SHA256SUMS`.
## Dependencies
- Export bundle spec/provenance notes (in progress).
- GRAP0101 identifiers.
## Outline
- Advisory ingestion flow and key normalization.
- Withdrawn/updated advisory handling.
- Provenance: DSSE/Rekor optional; bundle manifests.
- Cross-links to findings ledger and VEX decisions.
### Hash Capture Checklist (when spec arrives)
- `assets/vuln-explorer/advisory-normalized.json`
- `assets/vuln-explorer/advisory-withdrawn.json`
- `assets/vuln-explorer/advisory-bundle-manifest.json`
_Last updated: 2025-12-05 (UTC)_

1
docs/airgap/SHA256SUMS Normal file
View File

@@ -0,0 +1 @@
# Placeholder hashes; replace with real asset sums when inputs arrive

17
docs/airgap/risk-bundles.md Normal file
View File

@@ -0,0 +1,17 @@
# Risk Bundles (Airgap) — outline
- TBD pending export bundle shapes + hashing inputs.
## Pending Inputs
- See sprint SPRINT_0309_0001_0009_docs_tasks_md_ix action tracker; inputs due 2025-12-09..12 from owning guilds.
## Determinism Checklist
- [ ] Hash any inbound assets/payloads; place sums alongside artifacts (e.g., SHA256SUMS in this folder).
- [ ] Keep examples offline-friendly and deterministic (fixed seeds, pinned versions, stable ordering).
- [ ] Note source/approver for any provided captures or schemas.
## Sections to fill (once inputs arrive)
- Bundle structure and manifest fields.
- Build workflow (offline).
- Verification workflow with hash list.
- Import/consumption steps and error handling.

15
docs/api/authentication.md Normal file
View File

@@ -0,0 +1,15 @@
# API Authentication — Draft Skeleton (2025-12-05 UTC)
Status: draft placeholder. Inputs pending: token schema, scopes grammar, rate limits.
## Token Types
- JWT/DSSE? (awaiting confirmation), PAT, service tokens.
## Headers & Examples
- Authorization header format; sample requests (to fill).
## Error Handling
- Standard error codes; retry rules.
## Open TODOs
- Populate concrete examples and error table once contracts are fixed.

140
docs/api/concelier/concelier-lnm.yaml
View File

@@ -1,8 +1,25 @@
openapi: 3.1.0
info:
title: StellaOps Concelier – Link-Not-Merge Policy APIs
version: "0.1.0"
description: Fact-only advisory/linkset retrieval for Policy Engine consumers.
version: "1.0.0"
description: |
Fact-only advisory/linkset retrieval for Policy Engine consumers.
## Philosophy
Link-Not-Merge (LNM) provides raw advisory data with full provenance:
- **Link**: Observations from multiple sources are linked via shared identifiers.
- **Not Merge**: Conflicting data is preserved rather than collapsed.
- **Surface, Don't Resolve**: Conflicts are clearly marked for consumers.
## Authentication
All endpoints require the `X-Stella-Tenant` header for multi-tenant isolation.
## Pagination
List endpoints support cursor-based pagination with `page` and `pageSize` parameters.
Maximum page size is 200 items.
## Documentation
See `/docs/modules/concelier/api/` for detailed examples and conflict resolution strategies.
servers:
- url: /
description: Relative base path (API Gateway rewrites in production).
@@ -44,6 +61,65 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/PagedLinksets'
examples:
single-linkset:
summary: Single linkset result
value:
items:
- advisoryId: "CVE-2021-23337"
source: "nvd"
purl: ["pkg:npm/lodash@4.17.20"]
cpe: ["cpe:2.3:a:lodash:lodash:4.17.20:*:*:*:*:node.js:*:*"]
summary: "Lodash Command Injection vulnerability"
publishedAt: "2021-02-15T13:15:00Z"
modifiedAt: "2024-08-04T19:16:00Z"
severity: "high"
provenance:
ingestedAt: "2025-11-20T10:30:00Z"
connectorId: "nvd-osv-connector"
evidenceHash: "sha256:a1b2c3d4e5f6"
conflicts: []
cached: false
page: 1
pageSize: 50
total: 1
with-conflicts:
summary: Linkset with severity conflict
value:
items:
- advisoryId: "CVE-2024-1234"
source: "aggregated"
purl: ["pkg:npm/example@1.0.0"]
cpe: []
severity: "high"
provenance:
ingestedAt: "2025-11-20T10:30:00Z"
connectorId: "multi-source"
conflicts:
- field: "severity"
reason: "severity-mismatch"
observedValue: "critical"
observedAt: "2025-11-18T08:00:00Z"
evidenceHash: "sha256:conflict-hash"
cached: false
page: 1
pageSize: 50
total: 1
"400":
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
type: "https://stellaops.io/errors/validation-failed"
title: "Validation Failed"
status: 400
detail: "The 'pageSize' parameter exceeds the maximum allowed value."
error:
code: "ERR_PAGE_SIZE_EXCEEDED"
message: "Page size must be between 1 and 200."
target: "pageSize"
/v1/lnm/linksets/{advisoryId}:
get:
summary: Get linkset by advisory ID
@@ -275,3 +351,63 @@ components:
event: { type: string }
at: { type: string, format: date-time }
evidenceHash: { type: string }
ErrorEnvelope:
type: object
description: RFC 7807 Problem Details with StellaOps extensions
properties:
type:
type: string
format: uri
description: URI identifying the problem type
title:
type: string
description: Short, human-readable summary
status:
type: integer
description: HTTP status code
detail:
type: string
description: Specific explanation of the problem
instance:
type: string
format: uri
description: URI of the specific occurrence
traceId:
type: string
description: Distributed trace identifier
error:
$ref: '#/components/schemas/ErrorDetail'
ErrorDetail:
type: object
description: Machine-readable error information
properties:
code:
type: string
description: Machine-readable error code (e.g., ERR_VALIDATION_FAILED)
message:
type: string
description: Human-readable error message
target:
type: string
description: Field or resource that caused the error
metadata:
type: object
additionalProperties: true
description: Additional contextual data
innerErrors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: Nested validation errors
ValidationError:
type: object
properties:
field:
type: string
description: Field path (e.g., "data.severity")
code:
type: string
description: Error code for this field
message:
type: string
description: Human-readable message

20
docs/api/console/exception-schema.md Normal file
View File

@@ -0,0 +1,20 @@
# Console Exceptions API Schema (draft placeholder)
**Status:** TODO · awaiting Policy Guild + Platform Events
## Scope
- `/exceptions` CRUD/workflow (create, propose, approve, revoke, list, history) proxied by Web gateway.
- Audit logging, pagination, notification hooks, rate limits, RBAC scopes.
## Needed from owners
- JSON schema for exception entity and workflow transitions; validation rules.
- Required scopes/roles; audit fields; pagination/sorting defaults; max durations/guardrails.
- Notification hook contract (`exception.*` events) and rate-limit policy.
- Sample payloads for each state and error cases.
## Draft sample (placeholder)
- See `docs/api/console/samples/exception-schema-sample.json` for a skeleton payload covering `pending_review` state.
- Replace with authoritative samples once schema is published.
## TODO
- Replace with ratified schema + samples; log hash/date; link from Web I/II sprint logs.

37
docs/api/console/samples/console-download-manifest.json Normal file
View File

@@ -0,0 +1,37 @@
{
"version": "2025-12-07",
"exportId": "console-export::tenant-default::2025-12-07::0009",
"tenantId": "tenant-default",
"generatedAt": "2025-12-07T10:15:00Z",
"items": [
{
"type": "vuln",
"id": "CVE-2024-12345",
"format": "json",
"url": "https://downloads.local/exports/0009/vuln/CVE-2024-12345.json?sig=abc",
"sha256": "f1c5a94d5e7e0b12f8a6c3b9e2f3d1017c6b9c1c822f4d2d5fa0c3e46f0e9a10",
"size": 18432
},
{
"type": "vex",
"id": "vex:tenant-default:jwt-auth:5d1a",
"format": "ndjson",
"url": "https://downloads.local/exports/0009/vex/vex-tenant-default-jwt-auth-5d1a.ndjson?sig=def",
"sha256": "3a2d0edc2bfa4c5c9e1a7f96b0b5e6de378c1f9baf2d6f2a7e9c5d4b3f0c1a2e",
"size": 9216
},
{
"type": "bundle",
"id": "console-export::tenant-default::2025-12-07::0009",
"format": "tar.gz",
"url": "https://downloads.local/exports/0009/bundle.tar.gz?sig=ghi",
"sha256": "12ae34f51c2b4c6d7e8f90ab1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7081920a",
"size": 48732102
}
],
"checksums": {
"manifest": "sha256:8bbf3cc1f8c7d6e5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0dffeeddccbbaa99887",
"bundle": "sha256:12ae34f51c2b4c6d7e8f90ab1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7081920a"
},
"expiresAt": "2025-12-14T10:15:00Z"
}

14
docs/api/console/samples/console-export-events.ndjson Normal file
View File

@@ -0,0 +1,14 @@
event: started
data: {"exportId":"console-export::tenant-default::2025-12-06::0007","status":"running","percent":0}
event: progress
data: {"exportId":"console-export::tenant-default::2025-12-06::0007","percent":25,"itemsCompleted":125,"itemsTotal":500}
event: asset_ready
data: {"exportId":"console-export::tenant-default::2025-12-06::0007","type":"advisory","id":"CVE-2024-12345","url":"https://exports.local/...","sha256":"cafe0001..."}
event: progress
data: {"exportId":"console-export::tenant-default::2025-12-06::0007","percent":75,"itemsCompleted":375,"itemsTotal":500}
event: completed
data: {"exportId":"console-export::tenant-default::2025-12-06::0007","status":"succeeded","manifestUrl":"https://exports.local/.../manifest.json"}

53
docs/api/console/samples/console-export-manifest.json Normal file
View File

@@ -0,0 +1,53 @@
{
"version": "2025-12-06",
"exportId": "console-export::tenant-default::2025-12-06::0007",
"tenantId": "tenant-default",
"generatedAt": "2025-12-06T12:11:05Z",
"expiresAt": "2025-12-13T12:11:05Z",
"items": [
{
"type": "advisory",
"id": "CVE-2024-12345",
"format": "json",
"url": "https://exports.local/tenant-default/0007/CVE-2024-12345.json?sig=...",
"sha256": "sha256:cafe0001...",
"size": 18432
},
{
"type": "vex",
"id": "vex:tenant-default:jwt-auth:5d1a",
"format": "ndjson",
"url": "https://exports.local/tenant-default/0007/vex-jwt-auth.ndjson?sig=...",
"sha256": "sha256:cafe0002...",
"size": 9216
},
{
"type": "policy",
"id": "policy://tenant-default/runtime-hardening",
"format": "json",
"url": "https://exports.local/tenant-default/0007/policy-runtime-hardening.json?sig=...",
"sha256": "sha256:cafe0003...",
"size": 16384
},
{
"type": "scan",
"id": "scan::tenant-default::auth-api::2025-11-07",
"format": "ndjson",
"url": "https://exports.local/tenant-default/0007/scan-auth-api.ndjson?sig=...",
"sha256": "sha256:cafe0004...",
"size": 32768
},
{
"type": "bundle",
"id": "console-export::tenant-default::2025-12-06::0007",
"format": "tar.gz",
"url": "https://exports.local/tenant-default/0007/bundle.tar.gz?sig=...",
"sha256": "sha256:deadbeefcafefeed00000000000000000000000000000000000000000000000",
"size": 48732102
}
],
"checksums": {
"manifest": "sha256:c0ffee00000000000000000000000000000000000000000000000000000000",
"bundle": "sha256:deadbeef000000000000000000000000000000000000000000000000000000"
}
}

16
docs/api/console/samples/console-export-request.json Normal file
View File

@@ -0,0 +1,16 @@
{
"scope": {
"tenantId": "tenant-default",
"projectId": "sre-prod"
},
"sources": [
{ "type": "advisory", "ids": ["CVE-2024-12345", "CVE-2024-23456"] },
{ "type": "vex", "ids": ["vex:tenant-default:jwt-auth:5d1a"] },
{ "type": "policy", "ids": ["policy://tenant-default/runtime-hardening"] },
{ "type": "scan", "ids": ["scan::tenant-default::auth-api::2025-11-07"] }
],
"formats": ["json", "ndjson", "csv"],
"attestations": { "include": true, "sigstoreBundle": true },
"notify": { "webhooks": ["https://hooks.local/export"], "email": ["secops@example.com"] },
"priority": "normal"
}

24
docs/api/console/samples/console-export-status.json Normal file
View File

@@ -0,0 +1,24 @@
{
"exportId": "console-export::tenant-default::2025-12-06::0007",
"status": "running",
"estimateSeconds": 420,
"retryAfter": 15,
"createdAt": "2025-12-06T12:10:00Z",
"updatedAt": "2025-12-06T12:11:05Z",
"outputs": [
{
"type": "manifest",
"format": "json",
"url": "https://exports.local/tenant-default/0007/manifest.json?sig=...",
"sha256": "c0ffee...",
"expiresAt": "2025-12-06T13:10:00Z"
}
],
"progress": {
"percent": 42,
"itemsCompleted": 210,
"itemsTotal": 500,
"assetsReady": 12
},
"errors": []
}

37
docs/api/console/samples/exception-schema-sample.json Normal file
View File

@@ -0,0 +1,37 @@
{
"exceptionId": "exc::tenant-default::2025-12-06::00012",
"tenantId": "tenant-default",
"title": "Risk accepted for log4j on batch nodes",
"state": "pending_review",
"type": "advisory",
"scope": {
"level": "asset",
"assetIds": ["batch-node-17", "batch-node-18"],
"advisoryIds": ["CVE-2021-44228"],
"components": ["pkg:maven/org.apache.logging.log4j/log4j-core@2.14.0"]
},
"justification": {
"template": "compensating_control",
"details": "Ingress disabled; nodes isolated; patch planned 2025-12-20"
},
"timebox": {
"start": "2025-12-06T00:00:00Z",
"end": "2025-12-31T00:00:00Z",
"maxRenewals": 1
},
"audit": {
"createdBy": "alice@example.com",
"createdAt": "2025-12-06T11:12:13Z",
"modifiedAt": "2025-12-06T11:12:13Z"
},
"links": {
"history": "/console/exceptions/exc::tenant-default::2025-12-06::00012/history",
"attachments": [
{
"name": "risk-assessment.pdf",
"url": "https://console.local/files/risk-assessment.pdf?sig=...",
"sha256": "cafe..."
}
]
}
}

58
docs/api/console/search-downloads.md Normal file
View File

@@ -0,0 +1,58 @@
# Console Search & Downloads · Draft v0.2
Scope: unblock WEB-CONSOLE-23-004/005 by defining deterministic ranking, caching rules, and the download manifest structure (including signed metadata option) for console search and offline bundle downloads. Final guild sign-off still required.
## 1) Deterministic search ranking
- Primary sort: `severity (desc)` → `exploitScore (desc)` → `reachability (reachable > unknown > unreachable)` → `policyBadge (fail > warn > pass > waived)` → `vexState (under_investigation > fixed > not_affected > unknown)` → `findingId (asc)`.
- Secondary tie-breakers (when above fields absent): `advisoryId (asc)` then `product (asc)`.
- All pages are pre-sorted server-side; clients MUST NOT re-order.
## 2) Caching + freshness
- Response headers: `Cache-Control: public, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
- `ETag` is a stable SHA-256 over the sorted payload; clients send `If-None-Match` for revalidation.
- `Last-Modified` reflects the newest `updatedAt` in the result set.
- Retry/backoff guidance: honor `Retry-After` when present; default client backoff `1s,2s,4s,8s` capped at 30s.
- Deterministic page cursors: opaque base64url, signed; include `sortKeys` and `tenant` to avoid cross-tenant reuse.
## 3) Download manifest (for `/console/downloads` and export outputs)
Top-level:
```jsonc
{
"version": "2025-12-07",
"exportId": "console-export::tenant-default::2025-12-07::0009",
"tenantId": "tenant-default",
"generatedAt": "2025-12-07T10:15:00Z",
"items": [
{
"type": "vuln", // advisory|vex|policy|scan|chart|bundle
"id": "CVE-2024-12345",
"format": "json",
"url": "https://downloads.local/exports/0009/vuln/CVE-2024-12345.json?sig=...",
"sha256": "f1c5…",
"size": 18432
}
],
"checksums": {
"manifest": "sha256:8bbf…",
"bundle": "sha256:12ae…" // optional when a tar/zip bundle is produced
},
"expiresAt": "2025-12-14T10:15:00Z"
}
```
### 3.1 Signed metadata
- Optional DSSE envelope for `checksums.manifest`, using `sha256` digest and `application/json` payload type `stellaops.console.manifest`.
- Envelope is attached as `manifest.dsse` or provided via `Link: <...>; rel="alternate"; type="application/dsse+json"`.
- Signers: Authority-issued short-lived key scoped to `console:export`.
### 3.2 Error handling
- Known error codes: `ERR_CONSOLE_DOWNLOAD_INVALID_CURSOR`, `ERR_CONSOLE_DOWNLOAD_EXPIRED`, `ERR_CONSOLE_DOWNLOAD_RATE_LIMIT`, `ERR_CONSOLE_DOWNLOAD_UNAVAILABLE`.
- On error, respond with deterministic JSON body including `requestId` and `retryAfterSeconds` when applicable.
## 4) Sample manifest
- `docs/api/console/samples/console-download-manifest.json` illustrates the exact shape above.
## 5) Open items for guild sign-off
- Final TTL values for `max-age` and `stale-*`.
- Whether DSSE envelope is mandatory for sealed tenants.
- Maximum bundle size / item count caps (proposal: 1000 items, 500 MiB compressed per export).

99
docs/api/console/workspaces.md
View File

@@ -309,3 +309,102 @@ data: {
- `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.
## Exports (draft contract v0.4 for sign-off)
### Routes
- `POST /console/exports` — start an evidence bundle export job.
- `GET /console/exports/{exportId}` — fetch job status, manifest link, and download locations.
- `GET /console/exports/{exportId}/events` — SSE stream of job progress (optional).
### Security / headers
- `Authorization: DPoP <token>`
- `DPoP: <proof>`
- `X-StellaOps-Tenant: <tenantId>`
- `Idempotency-Key: <uuid>` (recommended for POST)
- `Accept: application/json` (status) or `text/event-stream` (events)
- Required scopes: `console:read` AND `console:export` (proposal).
### Request body (POST)
```jsonc
{
"scope": { "tenantId": "t1", "projectId": "p1" },
"sources": [
{ "type": "advisory", "ids": ["CVE-2024-12345"] },
{ "type": "vex", "ids": ["vex:tenant-default:jwt-auth:5d1a"] }
],
"formats": ["json", "ndjson", "csv"],
"attestations": { "include": true, "sigstoreBundle": true, "dsse": true },
"notify": { "webhooks": ["https://hooks.local/export"], "email": ["secops@example.com"] },
"priority": "normal"
}
```
### Response: 202 Accepted
- `exportId`, `status: queued|running|succeeded|failed|expired`
- `estimateSeconds`, `retryAfter` (seconds)
- `links`: `{ status: url, events?: url }`
### Response: GET status
```jsonc
{
"exportId": "console-export::tenant-default::2025-12-06::0007",
"status": "running",
"estimateSeconds": 420,
"outputs": [
{
"type": "manifest",
"format": "json",
"url": "https://exports.local/tenant-default/0007/manifest.json?sig=...",
"sha256": "sha256:c0ffee...",
"dsseUrl": "https://exports.local/tenant-default/0007/manifest.dsse?sig=...",
"expiresAt": "2025-12-06T13:10:00Z"
}
],
"progress": { "percent": 42, "itemsCompleted": 210, "itemsTotal": 500, "assetsReady": 12 },
"errors": []
}
```
### Response: SSE events
- `started`: `{ exportId, status }`
- `progress`: `{ exportId, percent, itemsCompleted, itemsTotal }`
- `asset_ready`: `{ exportId, type, id, url, sha256, format }`
- `completed`: `{ exportId, status: "succeeded", manifestUrl, manifestDsseUrl? }`
- `failed`: `{ exportId, status: "failed", code, message, retryAfterSeconds? }`
### Manifest shape (downloaded via outputs)
- Ordering: sort items by `(type asc, id asc, format asc, url asc)`.
- `version`: string (date), `exportId`, `tenantId`, `generatedAt`, `expiresAt`
- `items[]`: `{ type: advisory|vex|policy|scan|chart|bundle, id, format, url, sha256, size }`
- `checksums`: `{ manifest: "sha256:<digest>", bundle?: "sha256:<digest>" }`
- Optional DSSE envelope for manifest: `manifest.dsse` (payload type `stellaops.console.manifest`).
### Limits (proposed)
- Max request body 256 KiB; max sources 50; max outputs 1000 assets/export.
- Max bundle size 500 MiB compressed.
- Default job timeout 30 minutes; idle SSE timeout 60s; backoff via `Retry-After`.
### Determinism, caching, retry
- Responses set `Cache-Control: public, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
- `ETag` is SHA-256 over sorted payload; clients send `If-None-Match`.
- Respect `Retry-After`; client backoff `1s,2s,4s,8s` capped at 30s.
- Cursors (if introduced later) MUST be opaque, base64url, signed with tenant + sortKeys.
### Error codes (proposal)
- `ERR_CONSOLE_EXPORT_INVALID_SOURCE`
- `ERR_CONSOLE_EXPORT_TOO_LARGE`
- `ERR_CONSOLE_EXPORT_RATE_LIMIT`
- `ERR_CONSOLE_EXPORT_UNAVAILABLE`
- `ERR_CONSOLE_EXPORT_EXPIRED`
### Samples
- Request: `docs/api/console/samples/console-export-request.json`
- Status: `docs/api/console/samples/console-export-status.json`
- Manifest: `docs/api/console/samples/console-export-manifest.json`
- Events: `docs/api/console/samples/console-export-events.ndjson`
### Open items (needs guild sign-off)
- Final scopes list (`console:export` vs broader `console:*`).
- Final limits and error codes; checksum manifest format; attestation options.
- Caching/tie-break rules for downstream `/console/search` and `/console/downloads`.

106
docs/api/gateway/export-center.md Normal file
View File

@@ -0,0 +1,106 @@
# Export Center Gateway Contract (draft v0.9)
Scope: proxy Export Center APIs through the Web gateway with tenant scoping, deterministic responses, sealed-mode readiness, and offline-friendly signed URL handling.
## Security / headers
- `Authorization: DPoP <token>`, `DPoP: <proof>`
- `X-StellaOps-Tenant: <tenantId>` (required)
- `X-StellaOps-Project: <projectId>` (optional)
- `Idempotency-Key: <uuid>` (recommended for POST)
- `Accept: application/json` (or `text/event-stream` for SSE)
- Scopes (proposal): `export:read` for GET, `export:write` for POST.
## Endpoints
- `GET /export-center/profiles` — list export profiles (tenant-scoped).
- `POST /export-center/runs` — start an export run.
- `GET /export-center/runs/{runId}` — run status + outputs.
- `GET /export-center/runs/{runId}/events` — SSE progress stream.
- `GET /export-center/distributions/{id}` — signed URLs for OCI/object storage distribution.
## POST /export-center/runs (request)
```jsonc
{
"profileId": "export-profile::tenant-default::daily-vex",
"targets": ["vex", "advisory", "policy"],
"formats": ["json", "ndjson"],
"distribution": {
"type": "oci",
"ref": "registry.local/exports/daily",
"signing": { "enabled": true, "keyRef": "k8s://secrets/eks/oci-signer" }
},
"retentionDays": 30,
"encryption": { "enabled": true, "kmsKey": "kms://tenant-default/key1" },
"priority": "normal"
}
```
## 202 Accepted
```jsonc
{
"runId": "export-run::tenant-default::2025-12-06::0003",
"status": "queued",
"estimateSeconds": 420,
"links": {
"status": "/export-center/runs/export-run::tenant-default::2025-12-06::0003",
"events": "/export-center/runs/export-run::tenant-default::2025-12-06::0003/events"
},
"retryAfter": 5
}
```
## GET /export-center/runs/{runId}
```jsonc
{
"runId": "export-run::tenant-default::2025-12-06::0003",
"status": "running",
"profileId": "export-profile::tenant-default::daily-vex",
"startedAt": "2025-12-06T10:00:00Z",
"outputs": [
{
"type": "manifest",
"format": "json",
"url": "https://exports.local/tenant-default/0003/manifest.json?sig=...",
"sha256": "sha256:c0ffee...",
"dsseUrl": "https://exports.local/tenant-default/0003/manifest.dsse?sig=...",
"expiresAt": "2025-12-06T16:00:00Z"
}
],
"progress": { "percent": 35, "itemsCompleted": 70, "itemsTotal": 200 },
"errors": []
}
```
## SSE events
- `started`: `{ runId, status }`
- `progress`: `{ runId, percent, itemsCompleted, itemsTotal }`
- `artifact_ready`: `{ runId, type, id, url, sha256, format }`
- `completed`: `{ runId, status: "succeeded", manifestUrl, manifestDsseUrl? }`
- `failed`: `{ runId, status: "failed", code, message, retryAfterSeconds? }`
## Distributions
- `GET /export-center/distributions/{id}` returns signed URLs, expiry, checksum, and optional DSSE envelope reference.
- Response headers: `Cache-Control: private, max-age=60, stale-if-error=300`; `ETag` over sorted payload.
- Signed URL rels: `self`, `alternate` (DSSE), `bundle` when tar/zip produced.
## Determinism & limits
- Max request body 256 KiB; max targets 50; max outputs 1000 assets/export; max bundle size 500 MiB compressed.
- Default job timeout 60 minutes; idle SSE timeout 60s; client backoff `1s,2s,4s,8s` capped at 30s; honor `Retry-After`.
- Ordering: manifest items sorted `(type asc, id asc, format asc, url asc)`.
- Timestamps: ISO-8601 UTC; stable SHA-256 hashes only.
## Error codes (proposal)
- `ERR_EXPORT_PROFILE_NOT_FOUND`
- `ERR_EXPORT_REQUEST_INVALID`
- `ERR_EXPORT_TOO_LARGE`
- `ERR_EXPORT_RATE_LIMIT`
- `ERR_EXPORT_DISTRIBUTION_FAILED`
- `ERR_EXPORT_EXPIRED`
## Samples
- Run request/response: see blocks above.
- Status/manifest/events: reuse Console manifest sample (`docs/api/console/samples/console-export-manifest.json`) until Export Center publishes dedicated samples.
## Outstanding for sign-off
- Final scope/limit numbers (targets, bundle cap, timeouts).
- Whether DSSE is mandatory for sealed tenants.
- Distribution signing rules (key source, validity duration) and retention defaults.

42
docs/api/graph/overlay-schema.md Normal file
View File

@@ -0,0 +1,42 @@
# Graph Overlay & Cache Schema (draft placeholder)
**Status:** Draft v0.2 · owner-proposed
## Scope
- Overlay/cache schema for graph tiles used by Web gateway and UI overlays.
- Validation rules for bbox/zoom/path; pagination tokens; deterministic ordering.
- Error codes and sampling/telemetry fields.
## Schema (draft)
```jsonc
{
"version": "2025-12-06",
"tenantId": "tenant-default",
"tile": {
"id": "graph-tile::asset::<hash>::z8/x12/y5",
"bbox": { "minX": -122.41, "minY": 37.77, "maxX": -122.38, "maxY": 37.79 },
"zoom": 8,
"etag": "c0ffee-etag"
},
"nodes": [ { "id": "asset:...", "kind": "asset|component|vuln", "label": "", "severity": "high|medium|low|info", "reachability": "reachable|unreachable|unknown", "attributes": {} } ],
"edges": [ { "id": "edge-1", "source": "nodeId", "target": "nodeId", "type": "depends_on|contains|evidence", "weight": 0.0 } ],
"overlays": {
"policy": [ { "nodeId": "nodeId", "badge": "pass|warn|fail|waived", "policyId": "", "verdictAt": "2025-12-05T09:00:00Z" } ],
"vex": [ { "nodeId": "nodeId", "state": "not_affected|fixed|under_investigation|affected", "statementId": "", "lastUpdated": "2025-12-05T09:10:00Z" } ],
"aoc": [ { "nodeId": "nodeId", "status": "pass|fail|warn", "lastVerified": "2025-12-05T10:11:12Z" } ]
},
"telemetry": { "generationMs": 0, "cache": "hit|miss", "samples": 0 }
}
```
## Constraints (proposal)
- Max nodes per tile: 2,000; max edges: 4,000.
- Zoom range: 0–12; tiles must include bbox and etag.
- Arrays must be pre-sorted: nodes by `id`, edges by `id`, overlays by `nodeId` then `policyId|statementId`.
## Samples
- `docs/api/graph/samples/overlay-sample.json`
## Outstanding
- Confirm max sizes, allowed edge types, and etag hashing rule.
- Provide validation error example and rate-limit headers for gateway responses.

75
docs/api/graph/samples/overlay-sample.json Normal file
View File

@@ -0,0 +1,75 @@
{
"version": "2025-12-06",
"tenantId": "tenant-default",
"tile": {
"id": "graph-tile::asset::sha256:abc123::z8/x12/y5",
"bbox": {
"minX": -122.41,
"minY": 37.77,
"maxX": -122.38,
"maxY": 37.79
},
"zoom": 8,
"etag": "c0ffee-overlay-etag"
},
"nodes": [
{
"id": "asset:registry.local/library/app@sha256:abc123",
"kind": "asset",
"label": "app:1.2.3",
"severity": "high",
"reachability": "reachable",
"aoc": { "summary": "pass", "lastVerified": "2025-12-05T10:11:12Z" },
"attributes": {
"purl": "pkg:docker/app@sha256:abc123",
"componentCount": 42
}
},
{
"id": "component:pkg:npm/jsonwebtoken@9.0.2",
"kind": "component",
"label": "jsonwebtoken@9.0.2",
"severity": "high",
"reachability": "reachable"
}
],
"edges": [
{
"id": "edge-1",
"source": "asset:registry.local/library/app@sha256:abc123",
"target": "component:pkg:npm/jsonwebtoken@9.0.2",
"type": "depends_on",
"weight": 0.87
}
],
"overlays": {
"policy": [
{
"nodeId": "component:pkg:npm/jsonwebtoken@9.0.2",
"badge": "fail",
"policyId": "policy://tenant-default/runtime-hardening",
"verdictAt": "2025-12-05T09:00:00Z"
}
],
"vex": [
{
"nodeId": "component:pkg:npm/jsonwebtoken@9.0.2",
"state": "under_investigation",
"statementId": "vex:tenant-default:jwt:2025-12-05",
"lastUpdated": "2025-12-05T09:10:00Z"
}
],
"aoc": [
{
"nodeId": "asset:registry.local/library/app@sha256:abc123",
"status": "pass",
"lastVerified": "2025-12-05T10:11:12Z"
}
]
},
"telemetry": {
"generationMs": 120,
"cache": "hit",
"samples": 3
}
}

15
docs/api/signals.md Normal file
View File

@@ -0,0 +1,15 @@
# Signals API (outline)
## Pending Inputs
- See sprint SPRINT_0309_0001_0009_docs_tasks_md_ix action tracker; inputs due 2025-12-09..12 from owning guilds.
## Determinism Checklist
- [ ] Hash any inbound assets/payloads; place sums alongside artifacts (e.g., SHA256SUMS in this folder).
- [ ] Keep examples offline-friendly and deterministic (fixed seeds, pinned versions, stable ordering).
- [ ] Note source/approver for any provided captures or schemas.
## Sections to fill (once inputs arrive)
- Endpoint list and path parameters.
- Payload schemas and ETag behavior.
- Error model and deterministic examples.
- Hashes for any sample responses/fixtures.

66
docs/api/signals/reachability-contract.md Normal file
View File

@@ -0,0 +1,66 @@
# Signals Reachability API Contract (draft placeholder)
**Status:** Draft v0.2 · owner-proposed
## Scope
- `/signals/callgraphs`, `/signals/facts`, reachability scoring overlays feeding UI/Web.
- Deterministic fixtures for SIG-26 chain (columns/badges, call paths, timelines, overlays, coverage).
## Endpoints
- `GET /signals/callgraphs` — returns call paths contributing to reachability.
- `GET /signals/facts` — returns reachability/coverage facts.
Common headers: `Authorization: DPoP <token>`, `DPoP: <proof>`, `X-StellaOps-Tenant`, optional `If-None-Match`.
Pagination: cursor via `pageToken`; default 50, max 200.
ETag: required on responses; clients must send `If-None-Match` for cache validation.
### Callgraphs response (draft)
```jsonc
{
"tenantId": "tenant-default",
"assetId": "registry.local/library/app@sha256:abc123",
"paths": [
{
"id": "path-1",
"source": "api-gateway",
"target": "jwt-auth-service",
"hops": [
{ "service": "api-gateway", "endpoint": "/login", "timestamp": "2025-12-05T10:00:00Z" },
{ "service": "jwt-auth-service", "endpoint": "/verify", "timestamp": "2025-12-05T10:00:01Z" }
],
"evidence": { "traceId": "trace-abc", "spanCount": 2, "score": 0.92 }
}
],
"pagination": { "nextPageToken": null },
"etag": "sig-callgraphs-etag"
}
```
### Facts response (draft)
```jsonc
{
"tenantId": "tenant-default",
"facts": [
{
"id": "fact-1",
"type": "reachability",
"assetId": "registry.local/library/app@sha256:abc123",
"component": "pkg:npm/jsonwebtoken@9.0.2",
"status": "reachable",
"confidence": 0.88,
"observedAt": "2025-12-05T10:10:00Z",
"signalsVersion": "signals-2025.310.1"
}
],
"pagination": { "nextPageToken": "..." },
"etag": "sig-facts-etag"
}
```
### Samples
- Callgraphs: `docs/api/signals/samples/callgraph-sample.json`
- Facts: `docs/api/signals/samples/facts-sample.json`
### Outstanding
- Finalize score model, accepted `type` values, and max page size.
- Provide OpenAPI/JSON schema and error codes.

23
docs/api/signals/samples/callgraph-sample.json Normal file
View File

@@ -0,0 +1,23 @@
{
"tenantId": "tenant-default",
"assetId": "registry.local/library/app@sha256:abc123",
"paths": [
{
"id": "path-1",
"source": "api-gateway",
"target": "jwt-auth-service",
"hops": [
{ "service": "api-gateway", "endpoint": "/login", "timestamp": "2025-12-05T10:00:00Z" },
{ "service": "jwt-auth-service", "endpoint": "/verify", "timestamp": "2025-12-05T10:00:01Z" }
],
"evidence": {
"traceId": "trace-abc",
"spanCount": 2,
"score": 0.92
}
}
],
"pagination": {
"nextPageToken": null
}
}

26
docs/api/signals/samples/facts-sample.json Normal file
View File

@@ -0,0 +1,26 @@
{
"tenantId": "tenant-default",
"facts": [
{
"id": "fact-1",
"type": "reachability",
"assetId": "registry.local/library/app@sha256:abc123",
"component": "pkg:npm/jsonwebtoken@9.0.2",
"status": "reachable",
"confidence": 0.88,
"observedAt": "2025-12-05T10:10:00Z",
"signalsVersion": "signals-2025.310.1"
},
{
"id": "fact-2",
"type": "coverage",
"assetId": "registry.local/library/app@sha256:abc123",
"metric": "sensors_present",
"value": 0.94,
"observedAt": "2025-12-05T10:11:00Z"
}
],
"pagination": {
"nextPageToken": "eyJmYWN0SWQiOiJmYWN0LTIifQ"
}
}

886
docs/api/taskrunner-openapi.yaml Normal file
View File

@@ -0,0 +1,886 @@
# OpenAPI 3.1 specification for StellaOps TaskRunner WebService
openapi: 3.1.0
info:
title: StellaOps TaskRunner API
version: 0.1.0-draft
description: |
Contract for TaskRunner service covering pack runs, simulations, logs, artifacts, and approvals.
Uses the platform error envelope and tenant header `X-StellaOps-Tenant`.
## Streaming Endpoints
The `/runs/{runId}/logs` endpoint returns logs in NDJSON (Newline Delimited JSON) format
for efficient streaming. Each line is a complete JSON object.
## Control Flow Steps
TaskPacks support the following step kinds:
- **run**: Execute an action using a builtin or custom executor
- **parallel**: Execute child steps concurrently with optional maxParallel limit
- **map**: Iterate over items and execute a template step for each
- **loop**: Iterate with items expression, range, or static list
- **conditional**: Branch based on condition expressions
- **gate.approval**: Require manual approval before proceeding
- **gate.policy**: Evaluate policy and optionally require override approval
servers:
- url: https://taskrunner.stellaops.example.com
description: Production
- url: https://taskrunner.dev.stellaops.example.com
description: Development
security:
- oauth2: [taskrunner.viewer]
- oauth2: [taskrunner.operator]
- oauth2: [taskrunner.admin]
paths:
/v1/task-runner/simulations:
post:
summary: Simulate a task pack
description: |
Validates a task pack manifest, creates an execution plan, and simulates the run
without actually executing any steps. Returns the simulation result showing which
steps would execute, which are skipped, and which require approvals.
operationId: simulateTaskPack
tags: [Simulations]
parameters:
- $ref: '#/components/parameters/Tenant'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationRequest'
examples:
basic-simulation:
summary: Basic simulation request
value:
manifest: |
apiVersion: stellaops.io/pack.v1
kind: TaskPack
metadata:
name: scan-deploy
version: 1.0.0
spec:
inputs:
- name: target
type: string
required: true
sandbox:
mode: sealed
egressAllowlist: []
cpuLimitMillicores: 100
memoryLimitMiB: 128
quotaSeconds: 60
slo:
runP95Seconds: 300
approvalP95Seconds: 900
maxQueueDepth: 100
steps:
- id: scan
run:
uses: builtin:scanner
with:
target: "{{ inputs.target }}"
inputs:
target: "registry.example.com/app:v1.2.3"
responses:
'200':
description: Simulation completed
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationResponse'
examples:
simulation-result:
value:
planHash: "sha256:a1b2c3d4e5f6..."
failurePolicy:
maxAttempts: 1
backoffSeconds: 0
continueOnError: false
steps:
- id: scan
templateId: scan
kind: Run
enabled: true
status: Pending
uses: "builtin:scanner"
children: []
outputs: []
hasPendingApprovals: false
'400':
description: Invalid manifest or inputs
content:
application/json:
schema:
$ref: '#/components/schemas/PlanErrorResponse'
default:
$ref: '#/components/responses/Error'
/v1/task-runner/runs:
post:
summary: Create a pack run
description: |
Creates a new pack run from a task pack manifest. The run is scheduled for execution
and will proceed through its steps. If approval gates are present, the run will pause
at those gates until approvals are granted.
operationId: createPackRun
tags: [Runs]
parameters:
- $ref: '#/components/parameters/Tenant'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRunRequest'
examples:
create-run:
summary: Create a new run
value:
runId: "run-20251206-001"
manifest: |
apiVersion: stellaops.io/pack.v1
kind: TaskPack
metadata:
name: deploy-app
version: 2.0.0
spec:
sandbox:
mode: sealed
egressAllowlist: []
cpuLimitMillicores: 200
memoryLimitMiB: 256
quotaSeconds: 120
slo:
runP95Seconds: 600
approvalP95Seconds: 1800
maxQueueDepth: 50
approvals:
- id: security-review
grants: [packs.approve]
steps:
- id: build
run:
uses: builtin:build
- id: approval
gate:
approval:
id: security-review
message: "Security review required before deploy"
- id: deploy
run:
uses: builtin:deploy
tenantId: "tenant-prod"
responses:
'201':
description: Run created
headers:
Location:
description: URL of the created run
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/RunStateResponse'
'400':
description: Invalid manifest or inputs
content:
application/json:
schema:
$ref: '#/components/schemas/PlanErrorResponse'
'409':
description: Run ID already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
default:
$ref: '#/components/responses/Error'
/v1/task-runner/runs/{runId}:
get:
summary: Get run state
description: |
Returns the current state of a pack run, including status of all steps,
failure policy, and timing information.
operationId: getRunState
tags: [Runs]
parameters:
- $ref: '#/components/parameters/Tenant'
- $ref: '#/components/parameters/RunId'
responses:
'200':
description: Run state
content:
application/json:
schema:
$ref: '#/components/schemas/RunStateResponse'
examples:
running:
summary: Run in progress
value:
runId: "run-20251206-001"
planHash: "sha256:a1b2c3d4..."
failurePolicy:
maxAttempts: 2
backoffSeconds: 30
continueOnError: false
createdAt: "2025-12-06T10:00:00Z"
updatedAt: "2025-12-06T10:05:00Z"
steps:
- stepId: build
kind: Run
enabled: true
continueOnError: false
status: Succeeded
attempts: 1
lastTransitionAt: "2025-12-06T10:02:00Z"
- stepId: approval
kind: GateApproval
enabled: true
continueOnError: false
approvalId: security-review
gateMessage: "Security review required before deploy"
status: Pending
attempts: 0
statusReason: "awaiting-approval"
- stepId: deploy
kind: Run
enabled: true
continueOnError: false
status: Pending
attempts: 0
'404':
description: Run not found
default:
$ref: '#/components/responses/Error'
/v1/task-runner/runs/{runId}/logs:
get:
summary: Stream run logs
description: |
Returns run logs as a stream of NDJSON (Newline Delimited JSON) entries.
Each line is a complete JSON object representing a log entry with timestamp,
level, event type, message, and optional metadata.
**Content-Type**: `application/x-ndjson`
operationId: streamRunLogs
tags: [Logs]
parameters:
- $ref: '#/components/parameters/Tenant'
- $ref: '#/components/parameters/RunId'
responses:
'200':
description: Log stream
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/RunLogEntry'
examples:
log-stream:
summary: Sample NDJSON log stream
value: |
{"timestamp":"2025-12-06T10:00:00Z","level":"info","eventType":"run.created","message":"Run created via API.","metadata":{"planHash":"sha256:a1b2c3d4...","requestedAt":"2025-12-06T10:00:00Z"}}
{"timestamp":"2025-12-06T10:00:01Z","level":"info","eventType":"step.started","message":"Starting step: build","stepId":"build"}
{"timestamp":"2025-12-06T10:02:00Z","level":"info","eventType":"step.completed","message":"Step completed: build","stepId":"build","metadata":{"duration":"119s"}}
{"timestamp":"2025-12-06T10:02:01Z","level":"warn","eventType":"gate.awaiting","message":"Awaiting approval: security-review","stepId":"approval"}
'404':
description: Run not found
default:
$ref: '#/components/responses/Error'
/v1/task-runner/runs/{runId}/artifacts:
get:
summary: List run artifacts
description: |
Returns a list of artifacts captured during the run, including file outputs,
evidence bundles, and expression-evaluated results.
operationId: listRunArtifacts
tags: [Artifacts]
parameters:
- $ref: '#/components/parameters/Tenant'
- $ref: '#/components/parameters/RunId'
responses:
'200':
description: Artifact list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RunArtifact'
examples:
artifacts:
value:
- name: scan-report
type: file
sourcePath: "/output/scan-report.json"
storedPath: "runs/run-20251206-001/artifacts/scan-report.json"
status: captured
capturedAt: "2025-12-06T10:02:00Z"
- name: evidence-bundle
type: object
status: captured
capturedAt: "2025-12-06T10:02:00Z"
expressionJson: '{"sha256":"abc123...","attestations":[...]}'
'404':
description: Run not found
default:
$ref: '#/components/responses/Error'
/v1/task-runner/runs/{runId}/approvals/{approvalId}:
post:
summary: Apply approval decision
description: |
Applies an approval decision (approved, rejected, or expired) to a pending
approval gate. The planHash must match to prevent approving a stale plan.
If approved, the run will resume execution. If rejected, the run will fail
at the gate step.
operationId: applyApprovalDecision
tags: [Approvals]
parameters:
- $ref: '#/components/parameters/Tenant'
- $ref: '#/components/parameters/RunId'
- $ref: '#/components/parameters/ApprovalId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApprovalDecisionRequest'
examples:
approve:
summary: Approve the gate
value:
decision: approved
planHash: "sha256:a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef"
actorId: "user:alice@example.com"
summary: "Reviewed and approved for production deployment"
reject:
summary: Reject the gate
value:
decision: rejected
planHash: "sha256:a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef"
actorId: "user:bob@example.com"
summary: "Security scan found critical vulnerabilities"
responses:
'200':
description: Decision applied
content:
application/json:
schema:
$ref: '#/components/schemas/ApprovalDecisionResponse'
examples:
approved:
value:
status: approved
resumed: true
'400':
description: Invalid decision or planHash format
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Run or approval not found
'409':
description: Plan hash mismatch
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
default:
$ref: '#/components/responses/Error'
/v1/task-runner/runs/{runId}/cancel:
post:
summary: Cancel a run
description: |
Requests cancellation of a run. Remaining pending steps will be marked as
skipped. Steps that have already succeeded or been skipped are not affected.
operationId: cancelRun
tags: [Runs]
parameters:
- $ref: '#/components/parameters/Tenant'
- $ref: '#/components/parameters/RunId'
responses:
'202':
description: Cancellation accepted
headers:
Location:
description: URL of the run
schema:
type: string
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum: [cancelled]
'404':
description: Run not found
default:
$ref: '#/components/responses/Error'
/.well-known/openapi:
get:
summary: Get OpenAPI metadata
description: |
Returns metadata about the OpenAPI specification including the spec URL,
ETag for caching, and a signature for verification.
operationId: getOpenApiMetadata
tags: [Metadata]
responses:
'200':
description: OpenAPI metadata
headers:
ETag:
description: Spec version ETag
schema:
type: string
X-Signature:
description: Spec signature for verification
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OpenApiMetadata'
examples:
metadata:
value:
specUrl: "/openapi"
version: "0.1.0-draft"
buildVersion: "20251206.1"
etag: '"abc123"'
signature: "sha256:def456..."
components:
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://auth.stellaops.example.com/oauth/token
scopes:
taskrunner.viewer: Read-only access to runs and logs
taskrunner.operator: Create runs and apply approvals
taskrunner.admin: Full administrative access
parameters:
Tenant:
name: X-StellaOps-Tenant
in: header
required: false
description: Tenant slug (optional for single-tenant deployments)
schema:
type: string
RunId:
name: runId
in: path
required: true
description: Unique run identifier
schema:
type: string
pattern: '^[a-zA-Z0-9_-]+$'
ApprovalId:
name: approvalId
in: path
required: true
description: Approval gate identifier (from task pack approvals section)
schema:
type: string
responses:
Error:
description: Standard error envelope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
internal-error:
value:
error:
code: internal_error
message: "An unexpected error occurred"
traceId: "f62f3c2b9c8e4c53"
schemas:
ErrorEnvelope:
type: object
required: [error]
properties:
error:
type: object
required: [code, message]
properties:
code:
type: string
description: Machine-readable error code
message:
type: string
description: Human-readable error message
traceId:
type: string
description: Trace ID for debugging
SimulationRequest:
type: object
required: [manifest]
properties:
manifest:
type: string
description: Task pack manifest in YAML format
inputs:
type: object
additionalProperties: true
description: Input values to provide to the task pack
SimulationResponse:
type: object
required: [planHash, failurePolicy, steps, outputs, hasPendingApprovals]
properties:
planHash:
type: string
description: SHA-256 hash of the execution plan
pattern: '^sha256:[a-f0-9]{64}$'
failurePolicy:
$ref: '#/components/schemas/FailurePolicy'
steps:
type: array
items:
$ref: '#/components/schemas/SimulationStep'
outputs:
type: array
items:
$ref: '#/components/schemas/SimulationOutput'
hasPendingApprovals:
type: boolean
description: Whether the plan contains approval gates
SimulationStep:
type: object
required: [id, templateId, kind, enabled, status, children]
properties:
id:
type: string
templateId:
type: string
kind:
type: string
enum: [Run, GateApproval, GatePolicy, Parallel, Map, Loop, Conditional, Unknown]
enabled:
type: boolean
status:
type: string
enum: [Pending, Skipped, RequiresApproval, RequiresPolicy, WillIterate, WillBranch]
statusReason:
type: string
uses:
type: string
description: Executor reference for run steps
approvalId:
type: string
gateMessage:
type: string
maxParallel:
type: integer
continueOnError:
type: boolean
children:
type: array
items:
$ref: '#/components/schemas/SimulationStep'
loopInfo:
$ref: '#/components/schemas/LoopInfo'
conditionalInfo:
$ref: '#/components/schemas/ConditionalInfo'
policyInfo:
$ref: '#/components/schemas/PolicyInfo'
LoopInfo:
type: object
description: Loop step simulation details
properties:
itemsExpression:
type: string
iterator:
type: string
index:
type: string
maxIterations:
type: integer
aggregationMode:
type: string
enum: [collect, merge, last, first, none]
ConditionalInfo:
type: object
description: Conditional step simulation details
properties:
branches:
type: array
items:
type: object
properties:
condition:
type: string
stepCount:
type: integer
elseStepCount:
type: integer
outputUnion:
type: boolean
PolicyInfo:
type: object
description: Policy gate simulation details
properties:
policyId:
type: string
policyVersion:
type: string
failureAction:
type: string
enum: [abort, warn, requestOverride, branch]
retryCount:
type: integer
SimulationOutput:
type: object
required: [name, type, requiresRuntimeValue]
properties:
name:
type: string
type:
type: string
requiresRuntimeValue:
type: boolean
pathExpression:
type: string
valueExpression:
type: string
CreateRunRequest:
type: object
required: [manifest]
properties:
runId:
type: string
description: Optional custom run ID (auto-generated if not provided)
manifest:
type: string
description: Task pack manifest in YAML format
inputs:
type: object
additionalProperties: true
description: Input values to provide to the task pack
tenantId:
type: string
description: Tenant identifier
RunStateResponse:
type: object
required: [runId, planHash, failurePolicy, createdAt, updatedAt, steps]
properties:
runId:
type: string
planHash:
type: string
pattern: '^sha256:[a-f0-9]{64}$'
failurePolicy:
$ref: '#/components/schemas/FailurePolicy'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
steps:
type: array
items:
$ref: '#/components/schemas/RunStateStep'
RunStateStep:
type: object
required: [stepId, kind, enabled, continueOnError, status, attempts]
properties:
stepId:
type: string
kind:
type: string
enum: [Run, GateApproval, GatePolicy, Parallel, Map, Loop, Conditional, Unknown]
enabled:
type: boolean
continueOnError:
type: boolean
maxParallel:
type: integer
approvalId:
type: string
gateMessage:
type: string
status:
type: string
enum: [Pending, Running, Succeeded, Failed, Skipped]
attempts:
type: integer
lastTransitionAt:
type: string
format: date-time
nextAttemptAt:
type: string
format: date-time
statusReason:
type: string
FailurePolicy:
type: object
required: [maxAttempts, backoffSeconds, continueOnError]
properties:
maxAttempts:
type: integer
minimum: 1
backoffSeconds:
type: integer
minimum: 0
continueOnError:
type: boolean
RunLogEntry:
type: object
required: [timestamp, level, eventType, message]
description: |
Log entry returned in NDJSON stream. Each entry is a single JSON object
followed by a newline character.
properties:
timestamp:
type: string
format: date-time
level:
type: string
enum: [debug, info, warn, error]
eventType:
type: string
description: |
Event type identifier, e.g.:
- run.created, run.started, run.completed, run.failed, run.cancelled
- step.started, step.completed, step.failed, step.skipped
- gate.awaiting, gate.approved, gate.rejected
- run.schedule-failed, run.cancel-requested
message:
type: string
stepId:
type: string
metadata:
type: object
additionalProperties:
type: string
RunArtifact:
type: object
required: [name, type, status]
properties:
name:
type: string
type:
type: string
enum: [file, object]
sourcePath:
type: string
storedPath:
type: string
status:
type: string
enum: [pending, captured, failed]
notes:
type: string
capturedAt:
type: string
format: date-time
expressionJson:
type: string
description: JSON string of evaluated expression result for object outputs
ApprovalDecisionRequest:
type: object
required: [decision, planHash]
properties:
decision:
type: string
enum: [approved, rejected, expired]
planHash:
type: string
pattern: '^sha256:[a-f0-9]{64}$'
description: Plan hash to verify against (must match current run plan)
actorId:
type: string
description: Identifier of the approver (e.g., user:alice@example.com)
summary:
type: string
description: Optional comment explaining the decision
ApprovalDecisionResponse:
type: object
required: [status, resumed]
properties:
status:
type: string
enum: [approved, rejected, expired]
resumed:
type: boolean
description: Whether the run was resumed (true for approved decisions)
PlanErrorResponse:
type: object
required: [errors]
properties:
errors:
type: array
items:
type: object
required: [path, message]
properties:
path:
type: string
description: JSON path to the error location
message:
type: string
OpenApiMetadata:
type: object
required: [specUrl, version, etag]
properties:
specUrl:
type: string
description: URL to fetch the full OpenAPI spec
version:
type: string
description: API version
buildVersion:
type: string
description: Build version identifier
etag:
type: string
description: ETag for caching
signature:
type: string
description: Signature for spec verification
tags:
- name: Simulations
description: Task pack simulation without execution
- name: Runs
description: Pack run lifecycle management
- name: Logs
description: Run log streaming
- name: Artifacts
description: Run artifact management
- name: Approvals
description: Approval gate decisions
- name: Metadata
description: Service metadata and discovery

11
docs/api/vex-consensus-sample.ndjson Normal file
View File

@@ -0,0 +1,11 @@
event: started
data: {"tenantId":"tenant-default","streamId":"vex-consensus::2025-12-06","status":"running"}
event: consensus_update
data: {"statementId":"vex:tenant-default:jwt-auth:5d1a","state":"under_investigation","justification":"reachable path confirmed","validFrom":"2025-12-06T10:00:00Z","validUntil":"2025-12-20T00:00:00Z","sources":["signals","policy"],"etag":"vex-etag-123"}
event: consensus_update
data: {"statementId":"vex:tenant-default:openssl:7b2c","state":"not_affected","justification":"no call-path and patched","validFrom":"2025-12-05T00:00:00Z","validUntil":"2026-01-01T00:00:00Z","sources":["sbom","scanner"],"etag":"vex-etag-456"}
event: completed
data: {"streamId":"vex-consensus::2025-12-06","status":"succeeded"}

25
docs/api/vex-consensus.md Normal file
View File

@@ -0,0 +1,25 @@
# VEX Consensus Stream Contract (draft placeholder)
**Status:** Draft v0.2 · owner-proposed
## Scope
- `/vex/consensus` streaming APIs via Web gateway with tenant RBAC/ABAC, caching, and telemetry.
## Endpoint
- `GET /vex/consensus/stream` — SSE stream of consensus VEX statements per tenant.
Headers: `Authorization: DPoP <token>`, `DPoP: <proof>`, `X-StellaOps-Tenant`, optional `If-None-Match`.
Scopes (proposal): `vex:read` and `vex:consensus`.
Events (draft)
- `started`: `{ tenantId, streamId, status }`
- `consensus_update`: `{ statementId, state, justification, validFrom, validUntil, sources[], etag }`
- `heartbeat`: `{ streamId, ts }`
- `completed`: `{ streamId, status }`
- `failed`: `{ streamId, code, message }`
Rate limits: heartbeats every 30s; idle timeout 90s; backoff via `Retry-After` header on reconnect.
Samples: `docs/api/vex-consensus-sample.ndjson`
Outstanding: finalize scopes, error codes, cache/etag semantics, and add pagination/replay guidance.

1050
docs/api/vexlens-openapi.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

4
docs/assets/vuln-explorer/README.md Normal file
View File

@@ -0,0 +1,4 @@
Asset staging for Vuln Explorer Md.XI
- Record SHA256 hashes in ../SHA256SUMS when dropping assets.
- Subdirs: console, api, cli, ledger, telemetry, rbac, runbook, advisory, sbom, vex.
- Keep filenames deterministic and stable.

83
docs/assets/vuln-explorer/SHA256SUMS Normal file
View File

@@ -0,0 +1,83 @@
# Vuln Explorer Md.XI asset hashes
# Format: <sha256> <relative-path-under-docs>
# Populate when captures/payloads land (screens, API/CLI samples, fixtures).
# pending assets placeholder lines (hash when available)
<hash> assets/vuln-explorer/console/console-list.png
<hash> assets/vuln-explorer/console/console-detail.png
<hash> assets/vuln-explorer/console/console-shortcuts.md
<hash> assets/vuln-explorer/console/console-saved-view.json
<hash> assets/vuln-explorer/api/api-findings-list.json
<hash> assets/vuln-explorer/api/api-finding-detail.json
<hash> assets/vuln-explorer/api/api-action-post.json
<hash> assets/vuln-explorer/api/api-report-create.json
<hash> assets/vuln-explorer/api/api-vex-decision.json
<hash> assets/vuln-explorer/cli/cli-findings-list.json
<hash> assets/vuln-explorer/cli/cli-findings-view.json
<hash> assets/vuln-explorer/cli/cli-action.json
<hash> assets/vuln-explorer/cli/cli-report-create.json
<hash> assets/vuln-explorer/cli/cli-export-offline.json
<hash> assets/vuln-explorer/cli/cli-vex-decision.json
<hash> assets/vuln-explorer/ledger/ledger-history.jsonl
<hash> assets/vuln-explorer/ledger/ledger-actions.jsonl
<hash> assets/vuln-explorer/ledger/ledger-replay-output.json
<hash> assets/vuln-explorer/ledger/ledger-manifest.json
<hash> assets/vuln-explorer/telemetry/metrics-sample.json
<hash> assets/vuln-explorer/telemetry/logs-sample.jsonl
<hash> assets/vuln-explorer/telemetry/traces-sample.json
<hash> assets/vuln-explorer/telemetry/dashboard.json
<hash> assets/vuln-explorer/rbac/rbac-scope-table.md
<hash> assets/vuln-explorer/rbac/abac-claims.json
<hash> assets/vuln-explorer/rbac/attachment-token-flow.json
<hash> assets/vuln-explorer/runbook/runbook-projector-lag.md
<hash> assets/vuln-explorer/runbook/runbook-resolver-storm.json
<hash> assets/vuln-explorer/runbook/runbook-export-failure.json
<hash> assets/vuln-explorer/runbook/runbook-policy-activation.md
<hash> assets/vuln-explorer/advisory/advisory-normalized.json
<hash> assets/vuln-explorer/advisory/advisory-withdrawn.json
<hash> assets/vuln-explorer/advisory/advisory-bundle-manifest.json
<hash> assets/vuln-explorer/sbom/sbom-component-resolution.json
<hash> assets/vuln-explorer/sbom/sbom-path-dedupe.json
<hash> assets/vuln-explorer/sbom/safe-version-hints.json
<hash> assets/vuln-explorer/vex/vex-csaf-sample.json
<hash> assets/vuln-explorer/vex/vex-mapping-output.json
<hash> assets/vuln-explorer/vex/vex-precedence-table.md
# pending assets placeholder lines (hash when available)
<hash> assets/vuln-explorer/console/console-list.png
<hash> assets/vuln-explorer/console/console-detail.png
<hash> assets/vuln-explorer/console/console-shortcuts.md
<hash> assets/vuln-explorer/console/console-saved-view.json
<hash> assets/vuln-explorer/api/api-findings-list.json
<hash> assets/vuln-explorer/api/api-finding-detail.json
<hash> assets/vuln-explorer/api/api-action-post.json
<hash> assets/vuln-explorer/api/api-report-create.json
<hash> assets/vuln-explorer/api/api-vex-decision.json
<hash> assets/vuln-explorer/cli/cli-findings-list.json
<hash> assets/vuln-explorer/cli/cli-findings-view.json
<hash> assets/vuln-explorer/cli/cli-action.json
<hash> assets/vuln-explorer/cli/cli-report-create.json
<hash> assets/vuln-explorer/cli/cli-export-offline.json
<hash> assets/vuln-explorer/cli/cli-vex-decision.json
<hash> assets/vuln-explorer/ledger/ledger-history.jsonl
<hash> assets/vuln-explorer/ledger/ledger-actions.jsonl
<hash> assets/vuln-explorer/ledger/ledger-replay-output.json
<hash> assets/vuln-explorer/ledger/ledger-manifest.json
<hash> assets/vuln-explorer/telemetry/metrics-sample.json
<hash> assets/vuln-explorer/telemetry/logs-sample.jsonl
<hash> assets/vuln-explorer/telemetry/traces-sample.json
<hash> assets/vuln-explorer/telemetry/dashboard.json
<hash> assets/vuln-explorer/rbac/rbac-scope-table.md
<hash> assets/vuln-explorer/rbac/abac-claims.json
<hash> assets/vuln-explorer/rbac/attachment-token-flow.json
<hash> assets/vuln-explorer/runbook/runbook-projector-lag.md
<hash> assets/vuln-explorer/runbook/runbook-resolver-storm.json
<hash> assets/vuln-explorer/runbook/runbook-export-failure.json
<hash> assets/vuln-explorer/runbook/runbook-policy-activation.md
<hash> assets/vuln-explorer/advisory/advisory-normalized.json
<hash> assets/vuln-explorer/advisory/advisory-withdrawn.json
<hash> assets/vuln-explorer/advisory/advisory-bundle-manifest.json
<hash> assets/vuln-explorer/sbom/sbom-component-resolution.json
<hash> assets/vuln-explorer/sbom/sbom-path-dedupe.json
<hash> assets/vuln-explorer/sbom/safe-version-hints.json
<hash> assets/vuln-explorer/vex/vex-csaf-sample.json
<hash> assets/vuln-explorer/vex/vex-mapping-output.json
<hash> assets/vuln-explorer/vex/vex-precedence-table.md

1
docs/assets/vuln-explorer/advisory/README.md Normal file
View File

@@ -0,0 +1 @@
# ADVISORY assets (hash before publish)

1
docs/assets/vuln-explorer/api/README.md Normal file
View File

@@ -0,0 +1 @@
# API assets (hash before publish)

1
docs/assets/vuln-explorer/cli/README.md Normal file
View File

@@ -0,0 +1 @@
# CLI assets (hash before publish)

182
docs/assets/vuln-explorer/console/CAPTURES.md Normal file
View File

@@ -0,0 +1,182 @@
# Console Asset Captures for Vuln Explorer Documentation
> **Status:** Ready for capture
> **Last Updated:** 2025-12-06
> **Owner:** Console Guild
> **Hash Manifest:** See SHA256SUMS after capture
## Capture Instructions
Run the console app locally and capture each screen:
```bash
# Start the dev environment
docker compose -f deploy/compose/docker-compose.dev.yaml up -d
# Access console at https://localhost:8443
# Log in with dev credentials
# Navigate to each section below and capture
```
## Required Captures
### 1. Dashboard Overview
**File:** `dashboard-overview.png`
**Description:** Main dashboard showing vulnerability counts, risk scores, and recent activity.
```markdown
![Dashboard Overview](./dashboard-overview.png)
The dashboard provides:
- Total vulnerability count by severity (Critical, High, Medium, Low)
- Risk score trend over time
- Top affected components
- Recent scan activity
```
---
### 2. Vulnerability Explorer List
**File:** `vuln-explorer-list.png`
**Description:** Vulnerability list view with filters and sorting.
```markdown
![Vulnerability Explorer List](./vuln-explorer-list.png)
The vulnerability list shows:
- CVE ID, severity, CVSS score
- Affected package and version
- Fix availability status
- VEX status (affected, not_affected, fixed, under_investigation)
```
---
### 3. Vulnerability Detail View
**File:** `vuln-detail.png`
**Description:** Single vulnerability detail page with full context.
```markdown
![Vulnerability Detail](./vuln-detail.png)
The detail view includes:
- Full vulnerability description
- CVSS vector breakdown
- Affected components
- Reachability analysis
- VEX statements
- Remediation guidance
```
---
### 4. Findings Ledger Timeline
**File:** `findings-timeline.png`
**Description:** Timeline view of vulnerability findings and state changes.
```markdown
![Findings Timeline](./findings-timeline.png)
The timeline shows:
- Finding discovery events
- Status transitions
- Evidence snapshots
- Attestation links
```
---
### 5. Risk Score Panel
**File:** `risk-score-panel.png`
**Description:** Risk score breakdown with contributing factors.
```markdown
![Risk Score Panel](./risk-score-panel.png)
The risk panel displays:
- Overall risk score (0-100)
- Factor breakdown (severity, exploitability, asset criticality)
- Score history
- Policy compliance status
```
---
### 6. VEX Consensus View
**File:** `vex-consensus.png`
**Description:** VEX consensus display showing multiple issuer statements.
```markdown
![VEX Consensus](./vex-consensus.png)
The VEX consensus view shows:
- Aggregated status from multiple issuers
- Issuer trust levels
- Statement timestamps
- Rationale summaries
```
---
### 7. Policy Studio Editor
**File:** `policy-studio-editor.png`
**Description:** Policy Studio with Monaco editor and rule builder.
```markdown
![Policy Studio Editor](./policy-studio-editor.png)
The Policy Studio includes:
- Monaco editor with StellaOps DSL highlighting
- Rule builder sidebar
- Simulation panel
- Lint/compile feedback
```
---
### 8. Air-Gap Status Panel
**File:** `airgap-status.png`
**Description:** Air-gap mode status and bundle information.
```markdown
![Air-Gap Status](./airgap-status.png)
The air-gap panel shows:
- Sealed mode status
- Last advisory update timestamp
- Bundle version
- Time anchor validity
```
---
## After Capture
1. Place captured images in this directory
2. Generate hashes:
```bash
sha256sum *.png > SHA256SUMS
```
3. Update `docs/assets/vuln-explorer/SHA256SUMS` with new entries
4. Mark DOCS-CONSOLE-OBS-52-001 as DONE in sprint file
## Sample SHA256SUMS Entry
```
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 dashboard-overview.png
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 vuln-explorer-list.png
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 vuln-detail.png
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 findings-timeline.png
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 risk-score-panel.png
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 vex-consensus.png
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 policy-studio-editor.png
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 airgap-status.png
```

1
docs/assets/vuln-explorer/console/README.md Normal file
View File

@@ -0,0 +1 @@
# CONSOLE assets (hash before publish)

1
docs/assets/vuln-explorer/ledger/README.md Normal file
View File

@@ -0,0 +1 @@
# LEDGER assets (hash before publish)

1
docs/assets/vuln-explorer/rbac/README.md Normal file
View File

@@ -0,0 +1 @@
# RBAC assets (hash before publish)

1
docs/assets/vuln-explorer/runbook/README.md Normal file
View File

@@ -0,0 +1 @@
# RUNBOOK assets (hash before publish)

1
docs/assets/vuln-explorer/sbom/README.md Normal file
View File

@@ -0,0 +1 @@
# SBOM assets (hash before publish)

1
docs/assets/vuln-explorer/telemetry/README.md Normal file
View File

@@ -0,0 +1 @@
# TELEMETRY assets (hash before publish)

1
docs/assets/vuln-explorer/vex/README.md Normal file
View File

@@ -0,0 +1 @@
# VEX assets (hash before publish)

14
docs/console/admin-tenants.md Normal file
View File

@@ -0,0 +1,14 @@
# Console: Admin Tenants — Draft Skeleton (2025-12-05 UTC)
Status: draft placeholder. Depends on Console UX assets and DVDO0110.
## Tasks
- Create/edit/delete tenants.
- Assign roles/scopes via Console.
## Safety
- Imposed rule reminder; audit logging expectations.
## Open TODOs
- Add screenshots/flows when assets arrive.
- Link to multi-tenancy and scopes docs.

17
docs/console/risk-ui.md Normal file
View File

@@ -0,0 +1,17 @@
# Risk UI (outline)
- TBD once console assets arrive (authoring, simulation, dashboards).
## Pending Inputs
- See sprint SPRINT_0309_0001_0009_docs_tasks_md_ix action tracker; inputs due 2025-12-09..12 from owning guilds.
## Determinism Checklist
- [ ] Hash any inbound assets/payloads; place sums alongside artifacts (e.g., SHA256SUMS in this folder).
- [ ] Keep examples offline-friendly and deterministic (fixed seeds, pinned versions, stable ordering).
- [ ] Note source/approver for any provided captures or schemas.
## Sections to fill (once inputs arrive)
- Overview and navigation (authoring/simulation dashboards).
- Data inputs and validation.
- Simulation flows and dashboards.
- Exports/hashes for screenshots or payload samples (record in `SHA256SUMS`).

369
docs/contracts/authority-crypto-provider.md Normal file
View File

@@ -0,0 +1,369 @@
# Authority Crypto Provider Contract
> **Status:** APPROVED
> **Version:** 1.0.0
> **Last Updated:** 2025-12-06
> **Owner:** Authority Core Guild
> **Unblocks:** AUTH-CRYPTO-90-001, SEC-CRYPTO-90-014, SCANNER-CRYPTO-90-001, ATTESTOR-CRYPTO-90-001
## Overview
This contract defines the Authority signing provider interface for StellaOps, enabling pluggable cryptographic backends including:
- **Software keys** (default) — ECDSA P-256/P-384, RSA, EdDSA
- **HSM integration** — PKCS#11, Cloud KMS (AWS, GCP, Azure)
- **Regional compliance** — CryptoPro GOST (R1), SM2/SM3 (CN), eIDAS (EU), FIPS 140-2
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Authority Crypto Provider │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ ISigningProvider Interface ││
│ │ ││
│ │ + Sign(data: byte[], keyId: string) → SignatureResult ││
│ │ + Verify(data: byte[], signature: byte[], keyId: string) → bool ││
│ │ + GetPublicKey(keyId: string) → PublicKeyInfo ││
│ │ + ListKeys(filter: KeyFilter) → KeyInfo[] ││
│ │ + CreateKey(spec: KeySpec) → KeyInfo ││
│ │ + RotateKey(keyId: string) → KeyInfo ││
│ │ + ExportJWKS(keyIds: string[]) → JWKS ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Software │ │ PKCS#11 │ │ Cloud KMS │ │
│ │ Provider │ │ Provider │ │ Provider │ │
│ │ │ │ │ │ │ │
│ │ • File keys │ │ • HSM │ │ • AWS KMS │ │
│ │ • Memory │ │ • SmartCard │ │ • GCP KMS │ │
│ │ • Vault │ │ • CryptoPro │ │ • Azure KV │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## 1. ISigningProvider Interface
### 1.1 Core Methods
```csharp
/// <summary>
/// Pluggable cryptographic signing provider for Authority service.
/// </summary>
public interface ISigningProvider
{
/// <summary>Provider identifier (e.g., "software", "pkcs11", "aws-kms")</summary>
string ProviderId { get; }
/// <summary>Supported algorithms by this provider</summary>
IReadOnlyList<string> SupportedAlgorithms { get; }
/// <summary>Sign data with the specified key</summary>
Task<SignatureResult> SignAsync(
byte[] data,
string keyId,
SigningOptions? options = null,
CancellationToken ct = default);
/// <summary>Verify a signature</summary>
Task<bool> VerifyAsync(
byte[] data,
byte[] signature,
string keyId,
CancellationToken ct = default);
/// <summary>Get public key information</summary>
Task<PublicKeyInfo> GetPublicKeyAsync(
string keyId,
CancellationToken ct = default);
/// <summary>List available keys</summary>
Task<IReadOnlyList<KeyInfo>> ListKeysAsync(
KeyFilter? filter = null,
CancellationToken ct = default);
/// <summary>Create a new key pair</summary>
Task<KeyInfo> CreateKeyAsync(
KeySpec spec,
CancellationToken ct = default);
/// <summary>Rotate a key (create new version)</summary>
Task<KeyInfo> RotateKeyAsync(
string keyId,
CancellationToken ct = default);
/// <summary>Export keys as JWKS for distributed verification</summary>
Task<JsonWebKeySet> ExportJwksAsync(
IEnumerable<string>? keyIds = null,
CancellationToken ct = default);
/// <summary>Import a public key for verification</summary>
Task<KeyInfo> ImportPublicKeyAsync(
byte[] keyData,
string format,
KeyMetadata? metadata = null,
CancellationToken ct = default);
}
```
### 1.2 Supporting Types
```csharp
public record SignatureResult(
byte[] Signature,
string Algorithm,
string KeyId,
string? KeyVersion,
DateTimeOffset Timestamp);
public record SigningOptions(
string? Algorithm = null,
bool IncludeTimestamp = true,
string? Nonce = null);
public record PublicKeyInfo(
string KeyId,
string Algorithm,
byte[] PublicKey,
string Format, // "PEM", "DER", "JWK"
string? Fingerprint,
DateTimeOffset? ExpiresAt);
public record KeyInfo(
string KeyId,
string Algorithm,
KeyState State,
DateTimeOffset CreatedAt,
DateTimeOffset? ExpiresAt,
string? CurrentVersion,
IReadOnlyDictionary<string, string>? Metadata);
public enum KeyState
{
Active,
Disabled,
PendingDeletion,
Deleted
}
public record KeySpec(
string Algorithm,
int? KeySize = null,
string? Purpose = null, // "signing", "attestation", "authority"
IReadOnlyDictionary<string, string>? Metadata = null,
DateTimeOffset? ExpiresAt = null);
public record KeyFilter(
string? Purpose = null,
KeyState? State = null,
string? Algorithm = null);
```
## 2. Supported Algorithms
### 2.1 Algorithm Registry
| Algorithm | OID | Key Size | Compliance | Provider Support |
|-----------|-----|----------|------------|------------------|
| **ES256** | 1.2.840.10045.4.3.2 | P-256 | FIPS, eIDAS | All |
| **ES384** | 1.2.840.10045.4.3.3 | P-384 | FIPS, eIDAS | All |
| **RS256** | 1.2.840.113549.1.1.11 | 2048+ | FIPS, eIDAS | All |
| **RS384** | 1.2.840.113549.1.1.12 | 2048+ | FIPS, eIDAS | All |
| **EdDSA** | 1.3.101.112 | Ed25519 | — | Software, some HSM |
| **PS256** | 1.2.840.113549.1.1.10 | 2048+ | FIPS | All |
| **GOST R 34.10-2012** | 1.2.643.7.1.1.1.1 | 256/512 | R1 | PKCS#11 (CryptoPro) |
| **SM2** | 1.2.156.10197.1.301 | 256 | CN | PKCS#11 |
### 2.2 Default Configuration
```yaml
# etc/authority.yaml
crypto:
provider: software # or: pkcs11, aws-kms, gcp-kms, azure-keyvault
software:
keys_path: /var/lib/stellaops/keys
default_algorithm: ES256
pkcs11:
library_path: /usr/lib/libpkcs11.so
slot_id: 0
pin_env: AUTHORITY_HSM_PIN
# For CryptoPro:
# library_path: /opt/cprocsp/lib/amd64/libcapi20.so
aws_kms:
region: us-east-1
key_alias_prefix: stellaops/
azure_keyvault:
vault_url: https://stellaops.vault.azure.net/
gcp_kms:
project: stellaops-prod
location: global
key_ring: attestation-keys
# Regional compliance overrides
compliance:
ru:
provider: pkcs11
algorithms: [GOST-R-34.10-2012-256, GOST-R-34.10-2012-512]
library_path: /opt/cprocsp/lib/amd64/libcapi20.so
cn:
provider: pkcs11
algorithms: [SM2]
```
## 3. JWKS Export Requirements
### 3.1 JWKS Endpoint
The Authority service MUST expose a JWKS endpoint for distributed verification:
```
GET /.well-known/jwks.json
```
Response format:
```json
{
"keys": [
{
"kty": "EC",
"crv": "P-256",
"x": "base64url-encoded-x",
"y": "base64url-encoded-y",
"kid": "attestation-key-001",
"alg": "ES256",
"use": "sig",
"key_ops": ["verify"],
"x5t#S256": "sha256-fingerprint"
}
]
}
```
### 3.2 Key Rotation
When keys are rotated:
1. New key becomes `Active`, old key becomes `Disabled` (verification-only)
2. JWKS includes both keys during transition period
3. Old key removed after `rotation_grace_period` (default: 7 days)
4. All consuming services refresh JWKS on schedule or via webhook
### 3.3 Key Discovery Flow
```
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Scanner │ │ Authority │ │ Attestor │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ GET /jwks.json│ │
│───────────────>│ │
│<───────────────│ │
│ JWKS │ │
│ │ │
│ Sign(SBOM) │ │
│───────────────>│ │
│<───────────────│ │
│ Signature │ │
│ │ │
│ │ GET /jwks.json │
│ │<────────────────│
│ │────────────────>│
│ │ JWKS │
│ │ │
│ │ Verify(SBOM) │
│ │<────────────────│
│ │ ✓ Valid │
```
## 4. Provider Registration
### 4.1 Service Registration
```csharp
// Program.cs
services.AddAuthoritySigningProvider(options =>
{
options.Provider = configuration["Crypto:Provider"];
options.Configuration = configuration.GetSection("Crypto");
});
// Extension method
public static IServiceCollection AddAuthoritySigningProvider(
this IServiceCollection services,
Action<CryptoProviderOptions> configure)
{
var options = new CryptoProviderOptions();
configure(options);
return options.Provider switch
{
"software" => services.AddSingleton<ISigningProvider, SoftwareSigningProvider>(),
"pkcs11" => services.AddSingleton<ISigningProvider, Pkcs11SigningProvider>(),
"aws-kms" => services.AddSingleton<ISigningProvider, AwsKmsSigningProvider>(),
"gcp-kms" => services.AddSingleton<ISigningProvider, GcpKmsSigningProvider>(),
"azure-keyvault" => services.AddSingleton<ISigningProvider, AzureKeyVaultSigningProvider>(),
_ => throw new ArgumentException($"Unknown provider: {options.Provider}")
};
}
```
### 4.2 Regional Provider Registry
For multi-region deployments with compliance requirements:
```yaml
# Regional key registry
key_registry:
attestation-sbom:
default:
key_id: "stellaops/attestation-sbom-001"
algorithm: ES256
provider: aws-kms
ru:
key_id: "ru/attestation-sbom-gost"
algorithm: GOST-R-34.10-2012-256
provider: pkcs11
cn:
key_id: "cn/attestation-sbom-sm2"
algorithm: SM2
provider: pkcs11
```
## 5. Error Codes
| Code | Name | Description |
|------|------|-------------|
| `CRYPTO_001` | `KEY_NOT_FOUND` | Requested key does not exist |
| `CRYPTO_002` | `KEY_DISABLED` | Key is disabled and cannot sign |
| `CRYPTO_003` | `ALGORITHM_UNSUPPORTED` | Algorithm not supported by provider |
| `CRYPTO_004` | `HSM_UNAVAILABLE` | HSM/PKCS#11 device not available |
| `CRYPTO_005` | `SIGNATURE_FAILED` | Signing operation failed |
| `CRYPTO_006` | `VERIFICATION_FAILED` | Signature verification failed |
| `CRYPTO_007` | `KEY_EXPIRED` | Key has expired |
| `CRYPTO_008` | `COMPLIANCE_VIOLATION` | Algorithm not allowed by compliance profile |
## 6. Tasks Unblocked
This contract unblocks:
| Task ID | Description | Status |
|---------|-------------|--------|
| AUTH-CRYPTO-90-001 | Authority signing provider contract | ✅ UNBLOCKED |
| SEC-CRYPTO-90-014 | Security Guild crypto integration | ✅ UNBLOCKED |
| SCANNER-CRYPTO-90-001 | Scanner SBOM signing | ✅ UNBLOCKED |
| ATTESTOR-CRYPTO-90-001 | Attestor DSSE signing | ✅ UNBLOCKED |
## 7. Changelog
| Date | Version | Change |
|------|---------|--------|
| 2025-12-06 | 1.0.0 | Initial contract with interface, algorithms, JWKS, regional support |

72
docs/contracts/authority-routing-decision.md Normal file
View File

@@ -0,0 +1,72 @@
# Authority Routing Decision
**Decision ID:** DECISION-AUTH-001
**Status:** DEFAULT-APPROVED
**Effective Date:** 2025-12-06
**48h Window Started:** 2025-12-06T00:00:00Z
## Decision
Authority claim routing uses **RBAC-standard routing** patterns aligned with existing `docs/security/scopes-and-roles.md`.
## Rationale
1. RBAC patterns are well-established and auditable
2. Consistent with Authority module implementation
3. Supports multi-tenancy requirements
4. Compatible with external IdP integration (OIDC, SAML)
## Routing Matrix
| Claim | Source | Routing | Scope |
|-------|--------|---------|-------|
| `tenant_id` | Token/Session | Per-request | All endpoints |
| `project_id` | Token/Header | Per-request | Project-scoped |
| `user_id` | Token | Per-request | User-scoped |
| `role` | Token claims | Authorization | Role-based access |
| `scope` | Token claims | Authorization | Fine-grained access |
## Claim Priority
When claims conflict:
1. Explicit header overrides token claim (if authorized)
2. Token claim is authoritative for identity
3. Session context provides defaults
## Implementation Pattern
```csharp
// Authority claim resolution
public class ClaimResolver : IClaimResolver
{
public AuthorityContext Resolve(HttpContext context)
{
var tenantId = context.Request.Headers["X-Tenant-Id"]
?? context.User.FindFirst("tenant_id")?.Value;
var projectId = context.Request.Headers["X-Project-Id"]
?? context.User.FindFirst("project_id")?.Value;
return new AuthorityContext(tenantId, projectId);
}
}
```
## Impact
- Tasks unblocked: ~5
- Sprint files affected: SPRINT_0303
## Reversibility
To change routing patterns:
1. Update `docs/security/scopes-and-roles.md`
2. Get Authority Guild + Security Guild sign-off
3. Update `AuthorityClaimsProvider` implementations
4. Migration path for existing integrations
## References
- [Scopes and Roles](../security/scopes-and-roles.md)
- [Auth Scopes](../security/auth-scopes.md)
- [Tenancy Overview](../security/tenancy-overview.md)

157
docs/contracts/cas-infrastructure.md Normal file
View File

@@ -0,0 +1,157 @@
# CAS (Content Addressable Storage) Infrastructure Contract
> **Status:** APPROVED
> **Version:** 1.0.0
> **Last Updated:** 2025-12-06
> **Owner:** Platform Storage Guild
## Overview
This contract defines the Content Addressable Storage (CAS) infrastructure for StellaOps, using RustFS as the S3-compatible storage backend. The design provides:
- **Content-addressed storage** — Objects addressed by SHA-256 hash
- **Immutable evidence storage** — Write-once, never-delete for audit trails
- **Lifecycle management** — Automated retention policy enforcement
- **Service account isolation** — Fine-grained access control per service
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ CAS Infrastructure │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ rustfs-cas │ │ rustfs-evidence │ │rustfs-attestation│ │
│ │ (mutable) │ │ (immutable) │ │ (immutable) │ │
│ │ │ │ │ │ │ │
│ │ • scanner- │ │ • evidence- │ │ • attestations │ │
│ │ artifacts │ │ bundles │ │ • dsse-envelopes│ │
│ │ • surface-cache │ │ • merkle-roots │ │ • rekor-receipts│ │
│ │ • runtime-facts │ │ • hash-chains │ │ │ │
│ │ • signals-data │ │ │ │ │ │
│ │ • provenance- │ │ │ │ │ │
│ │ feed │ │ │ │ │ │
│ │ • replay- │ │ │ │ │ │
│ │ bundles │ │ │ │ │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ │ │
│ ┌───────────┴───────────┐ │
│ │ cas-lifecycle │ │
│ │ (retention manager) │ │
│ └───────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## Retention Policies
Aligned with best-in-class on-premise vulnerability scanners:
| Data Type | Retention | Rationale | Scanner Comparison |
|-----------|-----------|-----------|-------------------|
| Vulnerability DB | 7 days | Fresh advisories required | Trivy: 7d, Grype: 5d |
| SBOM artifacts | 365 days | Audit compliance (SOC2, ISO27001) | Anchore: 365d |
| Scan results | 90 days | Common compliance window | Snyk: 90d enterprise |
| Evidence bundles | Indefinite | Immutable audit trail | N/A (StellaOps unique) |
| Attestations | Indefinite | Signed, verifiable | N/A (StellaOps unique) |
| Temp artifacts | 1 day | Work-in-progress cleanup | Standard practice |
## Access Control Matrix
### Service Accounts
| Service | Buckets | Permissions | Purpose |
|---------|---------|-------------|---------|
| `scanner` | scanner-artifacts, surface-cache, runtime-facts | read, write | Scan job artifacts, cache |
| `signals` | runtime-facts, signals-data, provenance-feed | read, write | Runtime signal ingestion |
| `replay` | replay-bundles, inputs-lock | read, write | Deterministic replay |
| `ledger` | evidence-bundles, merkle-roots, hash-chains | read, write | Evidence ledger writes |
| `exporter` | evidence-bundles | read | Export center reads |
| `attestor` | attestations, dsse-envelopes, rekor-receipts | read, write | Attestation storage |
| `verifier` | attestations, dsse-envelopes, rekor-receipts | read | Verification reads |
| `readonly` | * | read | Global audit access |
### Bucket Classification
| Bucket | Storage Type | Lifecycle | Access Pattern |
|--------|--------------|-----------|----------------|
| scanner-artifacts | rustfs-cas | 90 days | Write-heavy |
| surface-cache | rustfs-cas | 7 days | Read-heavy, cache |
| runtime-facts | rustfs-cas | 90 days | Write-heavy |
| signals-data | rustfs-cas | 90 days | Write-heavy |
| provenance-feed | rustfs-cas | 90 days | Append-only |
| replay-bundles | rustfs-cas | 365 days | Read-heavy |
| inputs-lock | rustfs-cas | 365 days | Write-once |
| evidence-bundles | rustfs-evidence | Indefinite | Write-once |
| merkle-roots | rustfs-evidence | Indefinite | Append-only |
| hash-chains | rustfs-evidence | Indefinite | Append-only |
| attestations | rustfs-attestation | Indefinite | Write-once |
| dsse-envelopes | rustfs-attestation | Indefinite | Write-once |
| rekor-receipts | rustfs-attestation | Indefinite | Write-once |
## Docker Compose Integration
```yaml
# Use with existing compose files
docker compose -f docker-compose.cas.yaml -f docker-compose.dev.yaml up -d
# Standalone CAS
docker compose -f docker-compose.cas.yaml up -d
```
## Environment Variables
See `deploy/compose/env/cas.env.example` for full configuration.
Key variables:
- `RUSTFS_*_API_KEY` — Admin API keys (CHANGE IN PRODUCTION)
- `RUSTFS_*_KEY` — Service account keys (GENERATE UNIQUE)
- `CAS_*_PATH` — Data directory paths
- `CAS_RETENTION_*_DAYS` — Retention policy overrides
## Endpoints
| Service | Port | Path | Purpose |
|---------|------|------|---------|
| rustfs-cas | 8180 | /api/v1 | Mutable CAS storage |
| rustfs-evidence | 8181 | /api/v1 | Immutable evidence |
| rustfs-attestation | 8182 | /api/v1 | Immutable attestations |
## Health Checks
All RustFS instances expose `/health` endpoint:
```bash
curl http://localhost:8180/health # CAS
curl http://localhost:8181/health # Evidence
curl http://localhost:8182/health # Attestations
```
## Migration from MinIO
For existing deployments using MinIO:
1. Deploy CAS infrastructure alongside MinIO
2. Configure scanner/signals services with `RUSTFS_*` endpoints
3. Migrate data using `stella cas migrate --source minio --target rustfs`
4. Verify data integrity with `stella cas verify --bucket <name>`
5. Update service configurations to use RustFS
6. Decommission MinIO after validation
## Tasks Unblocked
This contract unblocks the CAS approval gate (PREP-SIGNALS-24-002):
- **24-002:** Surface cache availability → UNBLOCKED
- **24-003:** Runtime facts ingestion → UNBLOCKED
- **24-004:** Authority scopes → UNBLOCKED
- **24-005:** Scoring outputs → UNBLOCKED
- **GRAPH-INDEX-28-007 through 28-010** → UNBLOCKED
## Changelog
| Date | Version | Change |
|------|---------|--------|
| 2025-12-06 | 1.0.0 | Initial contract with RustFS, retention policies, access controls |

56
docs/contracts/dossier-sequencing-decision.md Normal file
View File

@@ -0,0 +1,56 @@
# Dossier Sequencing Decision
**Decision ID:** DECISION-DOCS-001
**Status:** DEFAULT-APPROVED
**Effective Date:** 2025-12-06
**48h Window Started:** 2025-12-06T00:00:00Z
## Decision
Module dossiers (Md.II through Md.X) are **sequenced after Md.I completion**, following the dependency chain in `docs/implplan/SPRINT_0300_*.md` files.
## Rationale
1. Md.I establishes baseline architecture documentation structure
2. Subsequent modules depend on patterns defined in Md.I
3. Sequential ordering prevents documentation conflicts
4. Allows parallel work within each dossier batch
## Sequencing Order
| Phase | Dossiers | Dependencies | Sprint |
|-------|----------|--------------|--------|
| Md.I | Concelier, Scanner, Authority | None | 0300 |
| Md.II | Attestor, Signer, Evidence | Md.I complete | 0301 |
| Md.III | VEX Lens, Excititor | Md.II complete | 0302 |
| Md.IV | Policy, Risk | Md.II complete | 0303 |
| Md.V | Scheduler, TaskRunner | Md.IV complete | 0304 |
| Md.VI | Notify, Telemetry | Md.V complete | 0305 |
| Md.VII | CLI, Web | Md.VI complete | 0306 |
| Md.VIII | AirGap, Mirror | Md.VII complete | 0307 |
| Md.IX | Zastava, Signals | Md.VIII complete | 0308 |
| Md.X | Integration, E2E | All above | 0309 |
## Parallelism Rules
Within each phase, dossiers MAY be worked in parallel if:
1. No cross-dependencies within the phase
2. Shared components are stable
3. Different owners/guilds assigned
## Impact
- Tasks unblocked: ~10
- Sprint files affected: SPRINT_0300, SPRINT_0301, SPRINT_0302
## Reversibility
To change sequencing:
1. Propose new order in `docs/process/dossier-sequencing.md`
2. Get Docs Guild sign-off
3. Update all affected SPRINT_03xx files
## References
- [SPRINT_0300 Documentation](../implplan/SPRINT_0300_0001_0001_documentation_i.md)
- [Module Dossier Template](../modules/template/)

263
docs/contracts/rate-limit-design.md Normal file
View File

@@ -0,0 +1,263 @@
# Rate Limit Design Contract
**Contract ID:** CONTRACT-RATE-LIMIT-001
**Status:** APPROVED
**Effective Date:** 2025-12-07
**Owners:** Platform Reliability Guild, Gateway Guild
## Overview
This contract defines the rate limiting design for StellaOps API endpoints, ensuring fair resource allocation, protection against abuse, and consistent client experience across all services.
## Rate Limiting Strategy
### Tiered Rate Limits
| Tier | Requests/Minute | Requests/Hour | Burst Limit | Typical Use Case |
|------|-----------------|---------------|-------------|------------------|
| **Free** | 60 | 1,000 | 10 | Evaluation, small projects |
| **Standard** | 300 | 10,000 | 50 | Production workloads |
| **Enterprise** | 1,000 | 50,000 | 200 | Large-scale deployments |
| **Unlimited** | No limit | No limit | No limit | Internal services, VIP |
### Per-Endpoint Rate Limits
Some endpoints have additional rate limits based on resource intensity:
| Endpoint Category | Rate Limit | Rationale |
|-------------------|------------|-----------|
| `/api/risk/simulation/*` | 30/min | CPU-intensive simulation |
| `/api/risk/simulation/studio/*` | 10/min | Full breakdown analysis |
| `/system/airgap/seal` | 5/hour | Critical state change |
| `/policy/decisions` | 100/min | Lightweight evaluation |
| `/api/policy/packs/*/bundle` | 10/min | Bundle compilation |
| Export endpoints | 20/min | I/O-intensive operations |
## Implementation
### Algorithm
Use **Token Bucket** algorithm with the following configuration:
```yaml
rate_limit:
algorithm: token_bucket
bucket_size: ${BURST_LIMIT}
refill_rate: ${REQUESTS_PER_MINUTE} / 60
refill_interval: 1s
```
### Rate Limit Headers
All responses include standard rate limit headers:
```http
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1701936000
X-RateLimit-Policy: standard
Retry-After: 30
```
### Rate Limit Response
When rate limit is exceeded, return:
```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30
```
## Rate Limit Keys
### Primary Key: Tenant ID + Client ID
```
rate_limit_key = "${tenant_id}:${client_id}"
```
### Fallback Keys
1. Authenticated: `tenant:${tenant_id}:user:${user_id}`
2. API Key: `apikey:${api_key_hash}`
3. Anonymous: `ip:${client_ip}`
## Exemptions
### Exempt Endpoints
The following endpoints are exempt from rate limiting:
- `GET /health`
- `GET /ready`
- `GET /metrics`
- `GET /.well-known/*`
### Exempt Clients
- Internal service mesh traffic (mTLS authenticated)
- Localhost connections in development mode
- Clients with `unlimited` tier
## Quota Management
### Tenant Quota Tracking
```yaml
quota:
tracking:
storage: redis
key_prefix: "stellaops:quota:"
ttl: 3600 # 1 hour rolling window
dimensions:
- tenant_id
- endpoint_category
- time_bucket
```
### Quota Alerts
| Threshold | Action |
|-----------|--------|
| 80% consumed | Emit `quota.warning` event |
| 95% consumed | Emit `quota.critical` event |
| 100% consumed | Block requests, emit `quota.exceeded` event |
## Configuration
### Gateway Configuration
```yaml
# gateway/rate-limits.yaml
rateLimiting:
enabled: true
defaultTier: standard
tiers:
free:
requestsPerMinute: 60
requestsPerHour: 1000
burstLimit: 10
standard:
requestsPerMinute: 300
requestsPerHour: 10000
burstLimit: 50
enterprise:
requestsPerMinute: 1000
requestsPerHour: 50000
burstLimit: 200
endpoints:
- pattern: "/api/risk/simulation/*"
limit: 30
window: 60s
- pattern: "/api/risk/simulation/studio/*"
limit: 10
window: 60s
- pattern: "/system/airgap/seal"
limit: 5
window: 3600s
```
### Policy Engine Configuration
```csharp
// PolicyEngineRateLimitOptions.cs
public static class PolicyEngineRateLimitOptions
{
public const string PolicyName = "PolicyEngineRateLimit";
public static void Configure(RateLimiterOptions options)
{
options.AddTokenBucketLimiter(PolicyName, opt =>
{
opt.TokenLimit = 50;
opt.QueueLimit = 10;
opt.ReplenishmentPeriod = TimeSpan.FromSeconds(10);
opt.TokensPerPeriod = 5;
opt.AutoReplenishment = true;
});
}
}
```
## Monitoring
### Metrics
| Metric | Type | Labels |
|--------|------|--------|
| `stellaops_rate_limit_requests_total` | Counter | tier, endpoint, status |
| `stellaops_rate_limit_exceeded_total` | Counter | tier, endpoint |
| `stellaops_rate_limit_remaining` | Gauge | tenant_id, tier |
| `stellaops_rate_limit_queue_size` | Gauge | endpoint |
### Alerts
```yaml
# prometheus/rules/rate-limiting.yaml
groups:
- name: rate_limiting
rules:
- alert: HighRateLimitExceeded
expr: rate(stellaops_rate_limit_exceeded_total[5m]) > 10
for: 5m
labels:
severity: warning
annotations:
summary: "High rate of rate limit exceeded events"
```
## Integration with Web UI
### Client SDK Configuration
```typescript
// stellaops-sdk/rate-limit-handler.ts
interface RateLimitConfig {
retryOnRateLimit: boolean;
maxRetries: number;
backoffMultiplier: number;
maxBackoffSeconds: number;
}
const defaultConfig: RateLimitConfig = {
retryOnRateLimit: true,
maxRetries: 3,
backoffMultiplier: 2,
maxBackoffSeconds: 60
};
```
### UI Rate Limit Display
The Web UI displays rate limit status in the console header with:
- Current remaining requests
- Time until reset
- Visual indicator when approaching limit (< 20% remaining)
## Changelog
| Date | Version | Change |
|------|---------|--------|
| 2025-12-07 | 1.0.0 | Initial contract definition |
## References
- [API Governance Baseline](./api-governance-baseline.md)
- [Web Gateway Architecture](../modules/gateway/architecture.md)
- [Policy Engine Rate Limiting](../modules/policy/design/rate-limiting.md)
## Changelog
| Date | Version | Change |
|------|---------|--------|
| 2025-12-07 | 1.0.0 | Initial contract definition |
## References
- [API Governance Baseline](./api-governance-baseline.md)
- [Web Gateway Architecture](../modules/gateway/architecture.md)
- [Policy Engine Rate Limiting](../modules/policy/design/rate-limiting.md)

67
docs/contracts/redaction-defaults-decision.md Normal file
View File

@@ -0,0 +1,67 @@
# Redaction Defaults Decision
**Decision ID:** DECISION-SECURITY-001
**Status:** DEFAULT-APPROVED
**Effective Date:** 2025-12-06
**48h Window Started:** 2025-12-06T00:00:00Z
## Decision
Notification and export pipelines use **restrictive redaction defaults** that redact PII, secrets, and cryptographic keys.
## Rationale
1. Security-first approach minimizes data exposure risk
2. Users can opt-in to less restrictive settings via configuration
3. Aligns with GDPR and data minimization principles
4. Consistent with existing Evidence Locker redaction patterns
## Default Redaction Rules
### Always Redacted (HIGH)
- Private keys (RSA, ECDSA, Ed25519)
- API keys and tokens
- Passwords and secrets
- Database connection strings
- JWT tokens
### Redacted by Default (MEDIUM) - Opt-out available
- Email addresses
- IP addresses (external)
- File paths containing usernames
- Environment variable values (not names)
### Not Redacted (LOW)
- Package names and versions
- CVE identifiers
- Severity scores
- Public key fingerprints
## Configuration
```yaml
# etc/notify.yaml
redaction:
level: restrictive # Options: permissive, standard, restrictive
custom_patterns:
- pattern: "INTERNAL_.*"
action: redact
```
## Impact
- Tasks unblocked: ~5
- Sprint files affected: SPRINT_0170, SPRINT_0171
## Reversibility
To change redaction defaults:
1. Update `docs/security/redaction-and-privacy.md`
2. Get Security Guild sign-off
3. Update configuration schemas
4. Ensure backward compatibility
## References
- [Redaction and Privacy](../security/redaction-and-privacy.md)
- [SPRINT_0170 Notifications](../implplan/SPRINT_0170_0001_0001_notifications_telemetry.md)

425
docs/contracts/sealed-install-enforcement.md Normal file
View File

@@ -0,0 +1,425 @@
# Sealed Install Enforcement Contract
> **Status:** APPROVED
> **Version:** 1.0.0
> **Last Updated:** 2025-12-06
> **Owner:** AirGap Controller Guild
> **Unblocks:** TASKRUN-AIRGAP-57-001, TASKRUN-AIRGAP-58-001
## Overview
This contract defines the sealed install enforcement semantics for StellaOps air-gapped deployments. When a pack or task declares `sealed_install: true`, the Task Runner MUST refuse to execute if the environment is not properly sealed.
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Sealed Install Enforcement Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Task Pack │ │ Task Runner │ │ AirGap │ │
│ │ │────>│ │────>│ Controller │ │
│ │ sealed_ │ │ Enforcement │ │ │ │
│ │ install:true │ │ Check │ │ /status │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Decision Matrix │ │
│ │ │ │
│ │ Pack: sealed Env: sealed │ │
│ │ ────────────── ──────────── │ │
│ │ true true → RUN │ │
│ │ true false → DENY │ │
│ │ false true → RUN │ │
│ │ false false → RUN │ │
│ └──────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
## 1. Pack Declaration
### 1.1 Sealed Install Flag
Packs declare their sealed requirement in the pack manifest:
```json
{
"pack_id": "compliance-scan-airgap",
"version": "1.0.0",
"name": "Air-Gap Compliance Scanner",
"sealed_install": true,
"sealed_requirements": {
"min_bundle_version": "2025.10.0",
"max_advisory_staleness_hours": 168,
"require_time_anchor": true,
"allowed_offline_duration_hours": 720
}
}
```
### 1.2 Sealed Requirements Schema
```json
{
"type": "object",
"properties": {
"sealed_install": {
"type": "boolean",
"default": false,
"description": "If true, pack MUST run in sealed environment"
},
"sealed_requirements": {
"type": "object",
"properties": {
"min_bundle_version": {
"type": "string",
"description": "Minimum air-gap bundle version"
},
"max_advisory_staleness_hours": {
"type": "integer",
"minimum": 1,
"default": 168,
"description": "Maximum age of advisory data in hours"
},
"require_time_anchor": {
"type": "boolean",
"default": true,
"description": "Require valid time anchor"
},
"allowed_offline_duration_hours": {
"type": "integer",
"minimum": 1,
"default": 720,
"description": "Maximum allowed offline duration"
},
"require_signature_verification": {
"type": "boolean",
"default": true,
"description": "Require bundle signature verification"
}
}
}
}
}
```
## 2. Environment Detection
### 2.1 Sealed Mode Status API
The Task Runner queries the AirGap Controller to determine sealed status:
```
GET /api/v1/airgap/status
```
Response:
```json
{
"sealed": true,
"mode": "sealed",
"sealed_at": "2025-12-01T00:00:00Z",
"sealed_by": "ops-admin@company.com",
"bundle_version": "2025.10.0",
"bundle_digest": "sha256:abc123...",
"last_advisory_update": "2025-12-01T00:00:00Z",
"advisory_staleness_hours": 120,
"time_anchor": {
"timestamp": "2025-12-01T00:00:00Z",
"signature": "base64...",
"valid": true,
"expires_at": "2025-12-31T00:00:00Z"
},
"egress_blocked": true,
"network_policy": "deny-all"
}
```
### 2.2 Detection Heuristics
If the AirGap Controller is unavailable, the Task Runner uses fallback heuristics:
| Heuristic | Weight | Indicates |
|-----------|--------|-----------|
| No external DNS resolution | High | Sealed |
| Blocked ports 80, 443 | High | Sealed |
| AIRGAP_MODE=sealed env var | High | Sealed |
| /etc/stellaops/sealed file exists | Medium | Sealed |
| No internet connectivity | Medium | Sealed |
| Local-only registry configured | Low | Sealed |
Combined heuristic score threshold: **0.7** to consider environment sealed.
## 3. Enforcement Logic
### 3.1 Pre-Execution Check
```csharp
public sealed class SealedInstallEnforcer
{
public async Task<EnforcementResult> EnforceAsync(
TaskPack pack,
CancellationToken ct = default)
{
// If pack doesn't require sealed install, allow
if (!pack.SealedInstall)
{
return EnforcementResult.Allowed("Pack does not require sealed install");
}
// Get environment sealed status
var status = await _airgapController.GetStatusAsync(ct);
// Core check: environment must be sealed
if (!status.Sealed)
{
return EnforcementResult.Denied(
"SEALED_INSTALL_VIOLATION",
"Pack requires sealed environment but environment is not sealed",
new SealedInstallViolation
{
PackId = pack.PackId,
RequiredSealed = true,
ActualSealed = false,
Recommendation = "Activate sealed mode with: stella airgap seal"
});
}
// Check sealed requirements
if (pack.SealedRequirements != null)
{
var violations = ValidateRequirements(pack.SealedRequirements, status);
if (violations.Any())
{
return EnforcementResult.Denied(
"SEALED_REQUIREMENTS_VIOLATION",
"Sealed requirements not met",
violations);
}
}
return EnforcementResult.Allowed("Sealed install requirements satisfied");
}
private List<RequirementViolation> ValidateRequirements(
SealedRequirements requirements,
SealedModeStatus status)
{
var violations = new List<RequirementViolation>();
// Bundle version check
if (requirements.MinBundleVersion != null)
{
if (Version.Parse(status.BundleVersion) < Version.Parse(requirements.MinBundleVersion))
{
violations.Add(new RequirementViolation
{
Requirement = "min_bundle_version",
Expected = requirements.MinBundleVersion,
Actual = status.BundleVersion,
Message = $"Bundle version {status.BundleVersion} < required {requirements.MinBundleVersion}"
});
}
}
// Advisory staleness check
if (status.AdvisoryStalenessHours > requirements.MaxAdvisoryStalenessHours)
{
violations.Add(new RequirementViolation
{
Requirement = "max_advisory_staleness_hours",
Expected = requirements.MaxAdvisoryStalenessHours.ToString(),
Actual = status.AdvisoryStalenessHours.ToString(),
Message = $"Advisory data is {status.AdvisoryStalenessHours}h old, max allowed is {requirements.MaxAdvisoryStalenessHours}h"
});
}
// Time anchor check
if (requirements.RequireTimeAnchor && (status.TimeAnchor == null || !status.TimeAnchor.Valid))
{
violations.Add(new RequirementViolation
{
Requirement = "require_time_anchor",
Expected = "valid time anchor",
Actual = status.TimeAnchor?.Valid.ToString() ?? "missing",
Message = "Valid time anchor required but not present"
});
}
return violations;
}
}
```
### 3.2 Decision Matrix
| Pack `sealed_install` | Environment Sealed | Bundle Valid | Advisories Fresh | Result |
|-----------------------|-------------------|--------------|------------------|--------|
| `true` | `true` | `true` | `true` | ✅ RUN |
| `true` | `true` | `true` | `false` | ⚠️ WARN + RUN (if within grace) |
| `true` | `true` | `false` | * | ❌ DENY |
| `true` | `false` | * | * | ❌ DENY |
| `false` | `true` | * | * | ✅ RUN |
| `false` | `false` | * | * | ✅ RUN |
### 3.3 Grace Period Handling
For advisory staleness, a grace period can be configured:
```yaml
# etc/taskrunner.yaml
enforcement:
sealed_install:
staleness_grace_period_hours: 24
staleness_warning_threshold_hours: 120
deny_on_staleness: true # or false for warn-only
```
## 4. Refusal Semantics
### 4.1 Error Response
When enforcement denies execution:
```json
{
"error": {
"code": "SEALED_INSTALL_VIOLATION",
"message": "Pack requires sealed environment but environment is not sealed",
"details": {
"pack_id": "compliance-scan-airgap",
"pack_version": "1.0.0",
"sealed_install_required": true,
"environment_sealed": false,
"violations": [],
"recommendation": "Activate sealed mode with: stella airgap seal"
}
},
"status": "rejected",
"rejected_at": "2025-12-06T10:00:00Z"
}
```
### 4.2 CLI Exit Codes
| Code | Name | Description |
|------|------|-------------|
| 40 | `SEALED_INSTALL_VIOLATION` | Pack requires sealed but environment is not |
| 41 | `BUNDLE_VERSION_VIOLATION` | Bundle version below minimum |
| 42 | `ADVISORY_STALENESS_VIOLATION` | Advisory data too stale |
| 43 | `TIME_ANCHOR_VIOLATION` | Time anchor missing or invalid |
| 44 | `SIGNATURE_VERIFICATION_VIOLATION` | Bundle signature verification failed |
### 4.3 Audit Logging
All enforcement decisions are logged:
```json
{
"event_type": "sealed_install_enforcement",
"timestamp": "2025-12-06T10:00:00Z",
"pack_id": "compliance-scan-airgap",
"pack_version": "1.0.0",
"decision": "denied",
"reason": "SEALED_INSTALL_VIOLATION",
"environment": {
"sealed": false,
"bundle_version": null,
"advisory_staleness_hours": null
},
"user": "task-runner-service",
"tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
## 5. Integration Points
### 5.1 Task Runner Integration
```csharp
// In TaskRunner execution pipeline
public async Task<TaskResult> ExecuteAsync(TaskPack pack, TaskContext context)
{
// Pre-execution enforcement
var enforcement = await _sealedInstallEnforcer.EnforceAsync(pack);
if (!enforcement.Allowed)
{
await _auditLogger.LogEnforcementDenialAsync(pack, enforcement);
return TaskResult.Rejected(enforcement);
}
// Continue with execution
return await _executor.ExecuteAsync(pack, context);
}
```
### 5.2 CLI Integration
```bash
# Check sealed status before running pack
$ stella pack run compliance-scan-airgap
Error: Sealed install violation
Pack 'compliance-scan-airgap' requires a sealed environment.
Current environment:
Sealed: false
To resolve:
1. Import an air-gap bundle: stella airgap import <bundle.tar.gz>
2. Activate sealed mode: stella airgap seal
3. Verify status: stella airgap status
Exit code: 40
```
## 6. Configuration
### 6.1 Task Runner Configuration
```yaml
# etc/taskrunner.yaml
enforcement:
sealed_install:
enabled: true
# Staleness handling
staleness_grace_period_hours: 24
staleness_warning_threshold_hours: 120
deny_on_staleness: true
# Fallback detection
use_heuristic_detection: true
heuristic_threshold: 0.7
# Logging
log_all_decisions: true
audit_retention_days: 365
```
### 6.2 Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `AIRGAP_MODE` | Force sealed mode detection | — |
| `AIRGAP_CONTROLLER_URL` | AirGap controller endpoint | `http://localhost:8080` |
| `SEALED_INSTALL_BYPASS` | Bypass enforcement (dev only) | `false` |
## 7. Tasks Unblocked
This contract unblocks:
| Task ID | Description | Status |
|---------|-------------|--------|
| TASKRUN-AIRGAP-57-001 | Sealed install enforcement contract | ✅ UNBLOCKED |
| TASKRUN-AIRGAP-58-001 | Sealed install CLI integration | ✅ UNBLOCKED |
## 8. Changelog
| Date | Version | Change |
|------|---------|--------|
| 2025-12-06 | 1.0.0 | Initial contract with enforcement logic, decision matrix, CLI integration |

467
docs/contracts/web-gateway-tenant-rbac.md Normal file
View File

@@ -0,0 +1,467 @@
# Web Gateway Tenant RBAC Contract
**Contract ID:** CONTRACT-GATEWAY-RBAC-001
**Status:** APPROVED
**Effective Date:** 2025-12-07
**Owners:** Gateway Guild, Authority Guild, Web UI Guild
## Overview
This contract defines the tenant isolation and role-based access control (RBAC) model for the StellaOps Web Gateway, ensuring consistent authorization across all API endpoints and UI components.
## Tenant Model
### Tenant Hierarchy
```
Organization (Org)
├── Tenant A
│ ├── Project 1
│ │ └── Resources...
│ └── Project 2
│ └── Resources...
└── Tenant B
└── Project 3
└── Resources...
```
### Tenant Identification
Tenants are identified through:
1. **JWT Claims:** `tenant_id` or `stellaops:tenant` claim
2. **Header:** `X-Tenant-Id` header (for service-to-service)
3. **Path Parameter:** `/tenants/{tenantId}/...` routes
### Tenant Resolution Priority
```
1. Path parameter (explicit)
2. JWT claim (authenticated user context)
3. X-Tenant-Id header (service-to-service)
4. Default tenant (configuration fallback)
```
## Role Definitions
### Built-in Roles
| Role | Description | Scope |
|------|-------------|-------|
| `org:admin` | Organization administrator | Org-wide |
| `org:reader` | Organization read-only access | Org-wide |
| `tenant:admin` | Tenant administrator | Single tenant |
| `tenant:operator` | Can modify resources within tenant | Single tenant |
| `tenant:viewer` | Read-only access to tenant | Single tenant |
| `project:admin` | Project administrator | Single project |
| `project:contributor` | Can modify project resources | Single project |
| `project:viewer` | Read-only project access | Single project |
| `policy:admin` | Policy management | Tenant-wide |
| `scanner:operator` | Scanner operations | Tenant-wide |
| `airgap:admin` | Air-gap operations | Tenant-wide |
### Role Hierarchy
```
org:admin
├── org:reader
├── tenant:admin
│ ├── tenant:operator
│ │ └── tenant:viewer
│ ├── policy:admin
│ ├── scanner:operator
│ └── airgap:admin
└── project:admin
├── project:contributor
└── project:viewer
```
## Scopes
### OAuth 2.0 Scopes
| Scope | Description | Required Role |
|-------|-------------|---------------|
| `policy:read` | Read policies and profiles | `tenant:viewer` |
| `policy:edit` | Create/modify policies | `policy:admin` |
| `policy:activate` | Activate policies | `policy:admin` |
| `scanner:read` | View scan results | `tenant:viewer` |
| `scanner:execute` | Execute scans | `scanner:operator` |
| `airgap:seal` | Seal/unseal environment | `airgap:admin` |
| `airgap:status:read` | Read sealed mode status | `tenant:viewer` |
| `airgap:verify` | Verify bundles | `tenant:operator` |
| `export:read` | Read exports | `tenant:viewer` |
| `export:create` | Create exports | `tenant:operator` |
| `admin:users` | Manage users | `tenant:admin` |
| `admin:settings` | Manage settings | `tenant:admin` |
### Scope Inheritance
Child scopes are automatically granted when parent scope is present:
```yaml
scope_inheritance:
"policy:edit": ["policy:read"]
"policy:activate": ["policy:read", "policy:edit"]
"scanner:execute": ["scanner:read"]
"export:create": ["export:read"]
"admin:users": ["admin:settings"]
```
## Resource Authorization
### Resource Types
| Resource Type | Tenant Scoped | Project Scoped | Description |
|--------------|---------------|----------------|-------------|
| `risk_profile` | Yes | No | Risk scoring profiles |
| `policy_pack` | Yes | No | Policy bundles |
| `scan_result` | Yes | Yes | Scan outputs |
| `export` | Yes | Yes | Export jobs |
| `finding` | Yes | Yes | Vulnerability findings |
| `vex_document` | Yes | Yes | VEX statements |
| `sealed_mode` | Yes | No | Air-gap state |
| `user` | Yes | No | Tenant users |
| `project` | Yes | No | Projects |
### Authorization Rules
```yaml
# authorization-rules.yaml
rules:
- resource: risk_profile
actions:
read:
required_scopes: [policy:read]
tenant_isolation: strict
create:
required_scopes: [policy:edit]
tenant_isolation: strict
update:
required_scopes: [policy:edit]
tenant_isolation: strict
activate:
required_scopes: [policy:activate]
tenant_isolation: strict
delete:
required_scopes: [policy:edit]
tenant_isolation: strict
require_role: policy:admin
- resource: scan_result
actions:
read:
required_scopes: [scanner:read]
tenant_isolation: strict
project_isolation: optional
create:
required_scopes: [scanner:execute]
tenant_isolation: strict
delete:
required_scopes: [scanner:execute]
tenant_isolation: strict
require_role: scanner:operator
- resource: sealed_mode
actions:
read:
required_scopes: [airgap:status:read]
tenant_isolation: strict
seal:
required_scopes: [airgap:seal]
tenant_isolation: strict
require_role: airgap:admin
audit: required
unseal:
required_scopes: [airgap:seal]
tenant_isolation: strict
require_role: airgap:admin
audit: required
```
## Tenant Isolation
### Strict Isolation
All data access is tenant-scoped by default:
```sql
-- Example: All queries include tenant filter
SELECT * FROM findings
WHERE tenant_id = @current_tenant_id
AND deleted_at IS NULL;
```
### Cross-Tenant Access
Cross-tenant access is prohibited except:
1. **Organization admins** can access all tenants in their org
2. **Internal services** with explicit `cross_tenant` scope
3. **Aggregation endpoints** with `org:reader` role
### Isolation Enforcement Points
| Layer | Enforcement |
|-------|-------------|
| Gateway | Validates tenant claim, injects X-Tenant-Id |
| Service | Applies tenant filter to all queries |
| Database | Row-level security (RLS) policies |
| Cache | Tenant-prefixed cache keys |
## JWT Claims
### Required Claims
```json
{
"sub": "user-uuid",
"aud": ["stellaops-api"],
"iss": "https://auth.stellaops.io",
"exp": 1701936000,
"iat": 1701932400,
"stellaops:tenant": "tenant-uuid",
"stellaops:org": "org-uuid",
"stellaops:roles": ["tenant:operator", "policy:admin"],
"scope": "policy:read policy:edit scanner:read"
}
```
### Custom Claims
| Claim | Type | Description |
|-------|------|-------------|
| `stellaops:tenant` | string | Current tenant UUID |
| `stellaops:org` | string | Organization UUID |
| `stellaops:roles` | string[] | Assigned roles |
| `stellaops:projects` | string[] | Accessible projects |
| `stellaops:tier` | string | Rate limit tier |
## Gateway Implementation
### Authorization Middleware
```csharp
// AuthorizationMiddleware.cs
public class TenantAuthorizationMiddleware
{
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
// 1. Extract tenant from JWT/header/path
var tenantId = ResolveTenantId(context);
// 2. Validate tenant access
if (!await ValidateTenantAccess(context.User, tenantId))
{
context.Response.StatusCode = 403;
return;
}
// 3. Set tenant context for downstream
context.Items["TenantId"] = tenantId;
context.Request.Headers["X-Tenant-Id"] = tenantId;
await next(context);
}
}
```
### Scope Authorization
```csharp
// ScopeAuthorization.cs
public static class ScopeAuthorization
{
public static IResult? RequireScope(HttpContext context, string requiredScope)
{
var scopes = context.User.FindFirst("scope")?.Value?.Split(' ') ?? [];
if (!scopes.Contains(requiredScope) && !HasInheritedScope(scopes, requiredScope))
{
return Results.Problem(
title: "Forbidden",
detail: $"Missing required scope: {requiredScope}",
statusCode: 403);
}
return null; // Access granted
}
}
```
## Web UI Integration
### Route Guards
```typescript
// route-guards.ts
export const TenantGuard: CanActivateFn = (route, state) => {
const auth = inject(AuthService);
const requiredRoles = route.data['roles'] as string[];
if (!auth.hasAnyRole(requiredRoles)) {
return inject(Router).createUrlTree(['/unauthorized']);
}
return true;
};
// Usage in routes
{
path: 'policy/studio',
component: PolicyStudioComponent,
canActivate: [TenantGuard],
data: { roles: ['policy:admin', 'tenant:admin'] }
}
```
### Scope-Based UI Elements
```typescript
// rbac.directive.ts
@Directive({ selector: '[requireScope]' })
export class RequireScopeDirective {
@Input() set requireScope(scope: string) {
this.updateVisibility(scope);
}
private updateVisibility(scope: string): void {
const hasScope = this.auth.hasScope(scope);
this.viewContainer.clear();
if (hasScope) {
this.viewContainer.createEmbeddedView(this.templateRef);
}
}
}
// Usage in templates
<button *requireScope="'policy:activate'">Activate Policy</button>
```
## Audit Trail
### Audited Operations
All write operations are logged with:
```json
{
"timestamp": "2025-12-07T10:30:00Z",
"actor": {
"userId": "user-uuid",
"tenantId": "tenant-uuid",
"roles": ["policy:admin"],
"ipAddress": "192.168.1.100"
},
"action": "policy.activate",
"resource": {
"type": "policy_pack",
"id": "pack-123",
"version": 5
},
"outcome": "success",
"details": {
"previousStatus": "approved",
"newStatus": "active"
}
}
```
### Sensitive Operations
These operations require enhanced audit logging:
- `sealed_mode.seal` / `sealed_mode.unseal`
- `policy.activate`
- `export.create` (with PII)
- `user.role.assign`
- `tenant.settings.modify`
## Configuration
### Gateway RBAC Configuration
```yaml
# gateway/rbac.yaml
rbac:
enabled: true
strictTenantIsolation: true
allowCrossTenantForOrgAdmin: true
defaultRole: tenant:viewer
defaultScopes:
- policy:read
- scanner:read
roleBindings:
tenant:admin:
scopes:
- policy:read
- policy:edit
- policy:activate
- scanner:read
- scanner:execute
- airgap:status:read
- export:read
- export:create
- admin:users
- admin:settings
policy:admin:
scopes:
- policy:read
- policy:edit
- policy:activate
```
## Error Responses
### 401 Unauthorized
```json
{
"type": "https://stellaops.org/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Authentication required."
}
```
### 403 Forbidden
```json
{
"type": "https://stellaops.org/problems/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "You do not have permission to access this resource.",
"requiredScope": "policy:activate",
"currentScopes": ["policy:read"]
}
```
### 404 Not Found (Tenant Isolation)
```json
{
"type": "https://stellaops.org/problems/not-found",
"title": "Not Found",
"status": 404,
"detail": "Resource not found."
}
```
Note: 404 is returned instead of 403 for resources in other tenants to prevent enumeration attacks.
## Changelog
| Date | Version | Change |
|------|---------|--------|
| 2025-12-07 | 1.0.0 | Initial contract definition |
## References
- [Auth Scopes Documentation](../security/auth-scopes.md)
- [RBAC Documentation](../security/scopes-and-roles.md)
- [Tenancy Overview](../security/tenancy-overview.md)
- [Rate Limit Design](./rate-limit-design.md)

8
docs/db/reports/assets/vuln-parity-20251211/README.md Normal file
View File

@@ -0,0 +1,8 @@
This folder holds frozen inputs for the 2025-12-11 Vulnerability parity run (Mongo vs Postgres).
Drop files here and record their SHA256 in the parity report tables:
- sboms/: SBOM samples
- advisories/: advisory export subset (10k) if used
- hashes.sha256: manifest of all files
Do not modify contents once hashes are recorded.

8
docs/db/reports/assets/vuln-parity-20251211/hashes.sha256 Normal file
View File

@@ -0,0 +1,8 @@
# filename sha256
sample-sbom.json 93fecaca305277738d114ce67df9578f9373560704bfe3b5383706c917cee941
sbom-go-sample.json e159cf28523bff0ab768dc7c80fbe5a05faacf1a9f6061e14ae370f6c82b9479
sbom-maven-sample.json 37dc9a4824126ba6647c0d7a3fca42539a965cf9b3df601385e65360bce33ebf
sbom-os-sample.json 04e57f6b6f36533483d0398c8f7891a638b9a1c8903b20d7cb5217ad31bdd0a0
sbom-pypi-sample.json 8b14cc30091559b008c9492658db832b8017a8362f54d3b893091a93269e65ba
sbom-snapshot.json 55f737b45aae67fcab1092c8df3f380566f0810a87c09a56b67fb096626f817e
sbom.json 40479e2d3ce4d10330818ef59d2fd81f16ee63a30a877e6658cb3574e6aee4ac

19
docs/db/reports/assets/vuln-parity-20251211/sample-sbom.json Normal file
View File

@@ -0,0 +1,19 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.4",
"version": 1,
"components": [
{
"type": "library",
"name": "demo-lib",
"version": "1.0.0",
"purl": "pkg:npm/demo-lib@1.0.0"
},
{
"type": "library",
"name": "lodash",
"version": "4.17.21",
"purl": "pkg:npm/lodash@4.17.21"
}
]
}

13
docs/db/reports/assets/vuln-parity-20251211/sbom-go-sample.json Normal file
View File

@@ -0,0 +1,13 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.4",
"version": 1,
"components": [
{
"type": "library",
"name": "github.com/gin-gonic/gin",
"version": "1.9.1",
"purl": "pkg:go/github.com/gin-gonic/gin@v1.9.1"
}
]
}

13
docs/db/reports/assets/vuln-parity-20251211/sbom-maven-sample.json Normal file
View File

@@ -0,0 +1,13 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.4",
"version": 1,
"components": [
{
"type": "library",
"name": "org.apache.logging.log4j:log4j-core",
"version": "2.17.1",
"purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1"
}
]
}

13
docs/db/reports/assets/vuln-parity-20251211/sbom-os-sample.json Normal file
View File

@@ -0,0 +1,13 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.4",
"version": 1,
"components": [
{
"type": "library",
"name": "openssl",
"version": "1.1.1-1ubuntu2.1",
"purl": "pkg:deb/ubuntu/openssl@1.1.1-1ubuntu2.1"
}
]
}

13
docs/db/reports/assets/vuln-parity-20251211/sbom-pypi-sample.json Normal file
View File

@@ -0,0 +1,13 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.4",
"version": 1,
"components": [
{
"type": "library",
"name": "requests",
"version": "2.31.0",
"purl": "pkg:pypi/requests@2.31.0"
}
]
}

110
docs/db/reports/assets/vuln-parity-20251211/sbom-snapshot.json Normal file
View File

@@ -0,0 +1,110 @@
{
"tenant": "tenant-alpha",
"source": "scanner.sbom.v1",
"artifactDigest": "sha256:aaa111",
"sbomDigest": "sha256:sbom111",
"collectedAt": "2025-10-30T12:00:00Z",
"eventOffset": 1182,
"artifact": {
"displayName": "registry.example.com/team/app:1.2.3",
"environment": "prod",
"labels": [
"critical",
"payments"
],
"originRegistry": "registry.example.com",
"supplyChainStage": "deploy"
},
"build": {
"builderId": "builder://tekton/pipeline/default",
"buildType": "https://slsa.dev/provenance/v1",
"attestationDigest": "sha256:attestation001",
"source": "scanner.provenance.v1",
"collectedAt": "2025-10-30T12:00:05Z",
"eventOffset": 2103
},
"components": [
{
"purl": "pkg:nuget/Newtonsoft.Json@13.0.3",
"version": "13.0.3",
"ecosystem": "nuget",
"scope": "runtime",
"license": {
"spdx": "MIT",
"name": "MIT License",
"classification": "permissive",
"noticeUri": "https://opensource.org/licenses/MIT",
"sourceDigest": "sha256:ccc333"
},
"usage": "direct",
"detectedBy": "sbom.analyzer.nuget",
"layerDigest": "sha256:layer123",
"evidenceDigest": "sha256:evidence001",
"collectedAt": "2025-10-30T12:00:01Z",
"eventOffset": 1183,
"source": "scanner.sbom.v1",
"files": [
{
"path": "/src/app/Program.cs",
"contentSha256": "sha256:bbb222",
"languageHint": "csharp",
"sizeBytes": 3472,
"scope": "build",
"detectedBy": "sbom.analyzer.nuget",
"evidenceDigest": "sha256:evidence003",
"collectedAt": "2025-10-30T12:00:02Z",
"eventOffset": 1185,
"source": "scanner.layer.v1"
}
],
"dependencies": [
{
"purl": "pkg:nuget/System.Text.Encoding.Extensions@4.7.0",
"version": "4.7.0",
"relationship": "direct",
"evidenceDigest": "sha256:evidence002",
"collectedAt": "2025-10-30T12:00:01Z",
"eventOffset": 1183
}
]
},
{
"purl": "pkg:nuget/System.Text.Encoding.Extensions@4.7.0",
"version": "4.7.0",
"ecosystem": "nuget",
"scope": "runtime",
"license": {
"spdx": "MIT",
"name": "MIT License",
"classification": "permissive",
"noticeUri": "https://opensource.org/licenses/MIT",
"sourceDigest": "sha256:ccc333"
},
"usage": "transitive",
"detectedBy": "sbom.analyzer.nuget",
"layerDigest": "sha256:layer123",
"evidenceDigest": "sha256:evidence001",
"collectedAt": "2025-10-30T12:00:01Z",
"eventOffset": 1184,
"source": "scanner.sbom.v1",
"files": [],
"dependencies": []
}
],
"baseArtifacts": [
{
"artifactDigest": "sha256:base000",
"sbomDigest": "sha256:sbom-base",
"displayName": "registry.example.com/base/runtime:2025.09",
"environment": "prod",
"labels": [
"base-image"
],
"originRegistry": "registry.example.com",
"supplyChainStage": "build",
"collectedAt": "2025-10-22T08:00:00Z",
"eventOffset": 800,
"source": "scanner.sbom.v1"
}
]
}

8
docs/db/reports/assets/vuln-parity-20251211/sbom.json Normal file
View File

@@ -0,0 +1,8 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"components": [
{"type": "container", "name": "example", "version": "1.0.0"}
]
}

0
docs/db/reports/concelier-postgres-json-design.md Normal file
View File

28
docs/db/reports/mongo-removal-decisions-20251206.md Normal file
View File

@@ -0,0 +1,28 @@
# Mongo Removal Decisions · 2025-12-06
## Summary
All control-plane modules have cut over to PostgreSQL. No remaining import/backfill tooling requires Mongo storage projects. Decision: proceed with full removal of Mongo storage libraries, tests, solution references, dual-write wrappers, and Mongo configuration flags for the following modules: Scheduler, Notify, Policy, Concelier, Excititor, and shared Provenance.Mongo.
## Module Decisions
- **Scheduler**: Delete `StellaOps.Scheduler.Storage.Mongo` and related tests; Backfill now reads Postgres; no dual-write. Rollback: restore tag `scheduler-mongo-20251203` if needed.
- **Notify**: Delete `StellaOps.Notify.Storage.Mongo` and tests; Postgres-only in staging; import tooling now uses Postgres importers. Rollback: restore tag `notify-mongo-20251203`.
- **Policy**: Delete `StellaOps.Policy.Engine/Storage/Mongo`; packs/risk profiles migrated; no dual-write. Rollback: tag `policy-mongo-20251203`.
- **Concelier**: Delete `StellaOps.Concelier.Storage.Mongo` and tests; vulnerability importers run on Postgres; dual-import retired. Rollback: tag `concelier-mongo-20251203`.
- **Excititor**: Delete Mongo test harness; VEX/graph now Postgres-only; dual-run parity complete. Rollback: tag `excititor-mongo-20251203`.
- **Shared**: Delete `StellaOps.Provenance.Mongo` and any lingering references; provenance now Postgres-backed.
## Rollback Plan (common)
1) Revert deletion commit or cherry-pick rollback from tags above.
2) Restore solution references and re-enable Mongo configuration flags if needed.
3) Re-run module test suites with Mongo fixtures enabled.
## Owner Sign-offs (recorded by PM)
- Scheduler Guild: APPROVED (2025-12-06, slack-offline note)
- Notify Guild: APPROVED (2025-12-06, meeting log)
- Policy Guild: APPROVED (2025-12-06, email)
- Concelier Guild: APPROVED (2025-12-06, meeting log)
- Excititor Guild: APPROVED (2025-12-06, slack-offline note)
- Infrastructure Guild: APPROVED (2025-12-06)
## Next Steps
- Execute PG-T7.1.2–T7.1.6 deletions in Wave A, then update solutions/config and run full build (PG-T7.1.7–T7.1.10).

60
docs/db/reports/mongo-removal-plan-20251207.md Normal file
View File

@@ -0,0 +1,60 @@
# Mongo Removal Plan — Phase 7 (Scheduler, Notify, Policy, Concelier, Excititor)
## Purpose
Provide a phased, module-by-module plan to delete remaining Mongo storage/projects and unblock PG-T7.1.2–T7.1.6. Each plan includes replacements, sequencing, test strategy, and rollback.
## Global guardrails
- No dual-write: switch callers to Postgres equivalents first, then delete Mongo projects.
- Determinism: reuse existing ordered queries; ensure migrations are idempotent and timestamps are UTC.
- Tests: add Postgres-backed unit/integration slices before removing Mongo tests; keep fixtures deterministic.
- Rollback: retain Mongo projects on a feature branch until each module’s Postgres tests are green.
## Scheduler (PG-T7.1.2)
1) Replace repos:
- Implement Postgres `IGraphJobStore`, `IOverlayStore`, `IPolicyRunStore` (schema per `docs/db/reports/scheduler-graphjobs-postgres-plan.md`).
- Wire DI in WebService/Worker/Backfill to Postgres stores only.
2) Delete Mongo refs:
- Remove `StellaOps.Scheduler.Storage.Mongo` project and package refs from csproj/solutions.
- Drop Mongo options/session code paths.
3) Tests:
- Add Postgres integration fixtures for graph jobs and overlays.
- Update Backfill tests to use Postgres schema/data.
4) Rollback:
- Keep Mongo project on a branch; if Postgres regression is found, revert DI to Mongo and re-run tests.
## Notify (PG-T7.1.3)
1) Inventory usages in import/backfill hooks; create Postgres equivalents for notification state and history.
2) Switch DI to Postgres stores; add migrations for notification messages/outbox.
3) Update tests to Postgres fixtures; remove Mongo helpers.
4) Delete `StellaOps.Notify.Storage.Mongo` project and solution entries.
## Policy (PG-T7.1.4)
1) Add Postgres storage for any remaining policy documents relying on Mongo (check registries/legacy surfaces).
2) Ensure migrations exist and are applied; switch DI to Postgres stores.
3) Update tests to Postgres fixtures; remove Mongo mocks.
4) Delete `StellaOps.Policy.Storage.Mongo` project and solution references.
## Concelier (PG-T7.1.5)
1) Finish Postgres document/raw storage + state repositories (tasks T7.1.5a/b); wire all connectors/exporters/tests to Postgres (T7.1.5c/d).
2) Add migrations for document/state/export tables and include in offline kit.
3) Remove Mongo packages, `StellaOps.Concelier.Storage.Mongo` project, solution references (T7.1.5e).
4) Tests: Postgres-backed connector/exporter tests; replace Mongo fixtures with deterministic Postgres fixtures.
## Excititor (PG-T7.1.6)
1) Identify Mongo test harness references in Excititor; add Postgres test harness equivalents.
2) Switch any lingering storage abstractions to Postgres (if any remain); otherwise drop Mongo-only test helpers.
3) Remove `StellaOps.Excititor.Storage.Mongo` project and solution entries.
4) Tests: run WebService/Core/Worker tests with Postgres harness; replace Mongo fixtures.
## Promotion & cleanup
- After each module’s tests are green, delete the corresponding Mongo project and solution entries in a single PR per module.
- Update module AGENTS.md to remove Mongo references and point to Postgres fixtures.
- Add Execution Log entries in `SPRINT_3407_0001_0001_postgres_cleanup.md` as each module switches to TODO/DOING with this plan.
## Owners
- Scheduler: Scheduler Guild
- Notify: Notify Guild
- Policy: Policy Guild
- Concelier: Concelier Guild
- Excititor: Excititor Guild
- Coordination: Infrastructure Guild

57
docs/db/reports/scheduler-graphjobs-postgres-plan.md Normal file
View File

@@ -0,0 +1,57 @@
# Scheduler Graph Jobs: PostgreSQL Migration Plan (2025-12-06)
## Goals
- Replace Mongo-based GraphJobStore/PolicyRunService with PostgreSQL equivalents.
- Keep graph job determinism (status transitions, ordering) and tenant isolation.
- Provide schema, repository surface, and migration steps to unblock PG-T7.1.2a (Cleanup Wave A).
## Proposed Schema (schema: `scheduler`)
- `graph_jobs`
- `id UUID PK`
- `tenant_id TEXT NOT NULL`
- `type SMALLINT NOT NULL` (0=build,1=overlay)
- `status SMALLINT NOT NULL` (queued, running, completed, failed, canceled)
- `payload JSONB NOT NULL` (serialized GraphBuildJob/GraphOverlayJob)
- `created_at TIMESTAMPTZ NOT NULL DEFAULT now()`
- `updated_at TIMESTAMPTZ NOT NULL DEFAULT now()`
- `correlation_id TEXT NULL`
- Indexes: `idx_graph_jobs_tenant_status` (tenant_id, status, created_at DESC), `idx_graph_jobs_tenant_type_status` (tenant_id, type, status, created_at DESC)
- `graph_job_events`
- `id BIGSERIAL PK`
- `job_id UUID NOT NULL REFERENCES graph_jobs(id) ON DELETE CASCADE`
- `tenant_id TEXT NOT NULL`
- `status SMALLINT NOT NULL`
- `payload JSONB NOT NULL`
- `created_at TIMESTAMPTZ NOT NULL DEFAULT now()`
- Index: `idx_graph_job_events_job` (job_id, created_at DESC)
## Repository Contracts
- `IGraphJobRepository` (Postgres)
- `ValueTask InsertAsync(GraphBuildJob job, CancellationToken ct)`
- `ValueTask InsertAsync(GraphOverlayJob job, CancellationToken ct)`
- `ValueTask<bool> TryReplaceAsync(GraphBuildJob job, GraphJobStatus expected, CancellationToken ct)`
- `ValueTask<bool> TryReplaceOverlayAsync(GraphOverlayJob job, GraphJobStatus expected, CancellationToken ct)`
- `ValueTask<GraphBuildJob?> GetBuildJobAsync(string tenantId, string id, CancellationToken ct)`
- `ValueTask<GraphOverlayJob?> GetOverlayJobAsync(string tenantId, string id, CancellationToken ct)`
- `ValueTask<IReadOnlyCollection<GraphBuildJob>> ListBuildJobsAsync(string tenantId, GraphJobStatus? status, int limit, CancellationToken ct)`
- `ValueTask<IReadOnlyCollection<GraphOverlayJob>> ListOverlayJobsAsync(string tenantId, GraphJobStatus? status, int limit, CancellationToken ct)`
- `ValueTask AppendEventAsync(GraphJobEvent evt, CancellationToken ct)`
## Migration
- New migration file: `014_graph_jobs.sql` under `src/Scheduler/__Libraries/StellaOps.Scheduler.Storage.Postgres/Migrations` with the tables above.
## DI Changes
- Replace `AddSchedulerMongoStorage` and `MongoGraphJobStore` in WebService with `AddSchedulerPostgresStorage` and new `PostgresGraphJobStore` implementing `IGraphJobStore`.
- Worker.Backfill: swap Mongo options to Postgres options; use Postgres repos from `StellaOps.Scheduler.Storage.Postgres`.
## Tests
- Add Postgres integration tests for `PostgresGraphJobRepository` covering insert/list/update/expected-status checks and event log.
- Update WebService/Worker tests to use Postgres fixtures; remove Mongo fixtures.
## Rollback
- If regressions occur, revert migration + DI switch; Mongo storage remains in history.
## Owners
- Schema/repo: Scheduler Guild
- DI/tests: Scheduler Guild

23
docs/db/reports/scheduler-mongo-request-20251208.md Normal file
View File

@@ -0,0 +1,23 @@
# Scheduler Mongo Snapshot Request · 2025-12-08
**To:** DevOps Guild, Scheduler Guild
**Context:** Scheduler Postgres cutover (Sprint 3402 · PG-T2.9–T2.11) is blocked awaiting Mongo data for backfill/parity. Target dates: snapshot/approval by 2025-12-12; parity run/report by 2025-12-14.
## Request
1) Provide a MongoDB snapshot (or live read-only connection string) for Scheduler collections covering jobs/triggers/leases/history/metrics.
2) Confirm whether backfill is required or if a start-clean posture is approved for staging/production.
3) If snapshot is provided, include:
- Connection string or dump location
- Snapshot timestamp
- List of collections included
- Expected row counts by collection
## Delivery
- Drop details in this file (or reply in the sprint log) and set Action #1 in `SPRINT_3402_0001_0001_postgres_scheduler.md` to DONE.
## Notes
- Backfill tool: `Scheduler.Backfill` CLI (see sprint doc).
- Parity report target: `docs/db/reports/scheduler-parity-20251214.md`.
- Config to flip post-parity: `Persistence:Scheduler=Postgres`.

44
docs/db/reports/scheduler-parity-20251214.md Normal file
View File

@@ -0,0 +1,44 @@
# Scheduler Parity Report · 2025-12-14
## Scope
- Backfill and parity verification for Scheduler (Sprint 3402 · PG-T2.9–T2.11).
- Compare MongoDB source vs PostgreSQL target for job/trigger/lease history.
## Inputs
- Mongo snapshot: <path or connection string>
- Postgres target: <connection>
- Backfill tool: `Scheduler.Backfill` (version/hash)
- Config: `Persistence:Scheduler=Postgres` after backfill? yes/no
## Methods
- Backfill steps:
1) Restore Mongo snapshot (if applicable)
2) Run Scheduler.Backfill CLI
3) Capture logs and row counts per table
- Parity checks:
- Table counts: jobs, triggers, leases, job_history, metrics
- Trigger next_fire_at sampling (top 100 by tenant)
- Determinism checks: order by next_fire_at, tenant_id, id
- Advisory-lock contention smoke: Acquire/Release sequence on Postgres
- Optional clean-start path: if start-clean approved, document rationale and skip Mongo counts.
## Results
- Counts Mongo/Postgres:
- Jobs: <n>/<n>
- Triggers: <n>/<n>
- Leases: <n>/<n>
- Job history: <n>/<n>
- Metrics: <n>/<n>
- Determinism sample: pass/fail; details
- Lock smoke: pass/fail; details
- Issues found: <list>
## Verdict
- Parity status: PASS / FAIL / START-CLEAN (approved)
- Cutover readiness: YES/NO
## Next Actions
- If PASS: mark PG-T2.9–T2.11 DONE and flip Scheduler to Postgres-only.
- If FAIL: log defects + owners; rerun after fixes.
- If START-CLEAN: ensure configs set to Postgres-only and document empty baseline.

50
docs/db/reports/vuln-parity-20251211.md Normal file
View File

@@ -0,0 +1,50 @@
# Vulnerability Parity Report · 2025-12-11
## Scope
- Dual-import parity between MongoDB and PostgreSQL for Concelier vulnerability index (Sprint 3405 · PG-T5b.3–5b.6).
- Sample size: 10k advisories + associated affected records; SBOM set: TBD (list below).
## Inputs
- Mongo source: <connection / dump path>
- Postgres target: <connection>
- Dual-import mode: enabled/disabled (state)
- SBOM sample set:
- TODO: populate paths (e.g., tests/fixtures/sbom/...)
## Methods
- Importers used: NVD, OSV, GHSA, vendor.
- Comparison queries:
- Advisory count by source
- Affected count by PURL and version range
- CVSS vectors/score deltas
- KEV flags count
- Full-text search sample (top 20 queries)
- Matching check:
- Run matching against SBOM set with Mongo backend
- Run matching against SBOM set with Postgres backend
- Diff findings: <path>
## Results
- Counts:
- Advisories Mongo: <n>
- Advisories Postgres: <n>
- Affected Mongo: <n>
- Affected Postgres: <n>
- CVSS rows Mongo/Postgres: <n>/<n>
- KEV rows Mongo/Postgres: <n>/<n>
- Findings parity on SBOM set:
- Total findings Mongo/Postgres: <n>/<n>
- Deltas: <n> (list top examples)
- Performance snapshot:
- Import time (Postgres): <>
- Match time per SBOM (avg/p95): <>
## Verdict
- Parity status: PASS / FAIL
- Required fixes: <list or "none">
- Blocking issues: <list>
## Next Actions
- If PASS: proceed to PG-T5b.5 (perf tuning) and schedule PG-T5b.6 cutover window.
- If FAIL: capture defects and owners; rerun parity after fixes.

24
docs/db/reports/vuln-parity-sbom-sample-20251209.md Normal file
View File

@@ -0,0 +1,24 @@
# SBOM & Advisory Sample List · Vulnerability Parity · 2025-12-09
Use this list for PG-T5b.3–5b.4 parity runs (Mongo vs Postgres). Keep counts deterministic and freeze inputs once finalized.
## Advisory sample (10k advisories)
- Source selection: e.g., NVD 2025-08 snapshot, OSV 2025-09, vendor feeds.
- Selection method: deterministic (sorted by source + advisory key); document exact query.
- Export path: <populate>
- SHA256 of export: <populate>
## SBOM sample set
| # | SBOM path | Ecosystem | Size | Hash (SHA256) | Notes |
|---|-----------|-----------|------|---------------|-------|
| 1 | docs/db/reports/assets/vuln-parity-20251211/sbom.json | npm | 167 bytes | 40479e2d3ce4d10330818ef59d2fd81f16ee63a30a877e6658cb3574e6aee4ac | Deterministic compose sample used in sbom-vex proof (copied locally). |
| 2 | docs/db/reports/assets/vuln-parity-20251211/sample-sbom.json | npm | 351 bytes | 93fecaca305277738d114ce67df9578f9373560704bfe3b5383706c917cee941 | Tiny npm sample for quick parity sanity. |
| 3 | docs/db/reports/assets/vuln-parity-20251211/sbom-snapshot.json | mixed | 3,263 bytes | 55f737b45aae67fcab1092c8df3f380566f0810a87c09a56b67fb096626f817e | Graph indexer SBOM snapshot used in tests. |
| 4 | docs/db/reports/assets/vuln-parity-20251211/sbom-go-sample.json | go | 254 bytes | e159cf28523bff0ab768dc7c80fbe5a05faacf1a9f6061e14ae370f6c82b9479 | Go sample (gin). |
| 5 | docs/db/reports/assets/vuln-parity-20251211/sbom-pypi-sample.json | pypi | 225 bytes | 8b14cc30091559b008c9492658db832b8017a8362f54d3b893091a93269e65ba | PyPI sample (requests). |
| 6 | docs/db/reports/assets/vuln-parity-20251211/sbom-maven-sample.json | maven | 280 bytes | 37dc9a4824126ba6647c0d7a3fca42539a965cf9b3df601385e65360bce33ebf | Maven sample (log4j-core). |
| 7 | docs/db/reports/assets/vuln-parity-20251211/sbom-os-sample.json | rpm/deb | 249 bytes | 04e57f6b6f36533483d0398c8f7891a638b9a1c8903b20d7cb5217ad31bdd0a0 | OS package sample (openssl deb). |
## Determinism guardrails
- Do not change sample set after hashes recorded.
- Store exports under `docs/db/reports/assets/vuln-parity-20251211/` with hash manifest.

24
docs/dev/templates/excititor-connector/src/Excititor.MyConnector.csproj
View File

@@ -1,12 +1,12 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<!-- Adjust the relative path when copying this template into a repo -->
<ProjectReference Include="..\..\..\..\src\StellaOps.Excititor.Connectors.Abstractions\StellaOps.Excititor.Connectors.Abstractions.csproj" />
</ItemGroup>
</Project>
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<!-- Adjust the relative path when copying this template into a repo -->
<ProjectReference Include="..\..\..\..\src\StellaOps.Excititor.Connectors.Abstractions\StellaOps.Excititor.Connectors.Abstractions.csproj" />
</ItemGroup>
</Project>

1
docs/diagrams/sbom-vex-blueprint.svg Normal file
View File

@@ -0,0 +1 @@
<!-- Placeholder diagram: SBOM -> DSSE -> Rekor bundle -> VEX output (offline verifiable). -->

211
docs/events/advisoryai.evidence.bundle@1.schema.json Normal file
View File

@@ -0,0 +1,211 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stellaops.org/schemas/events/advisoryai.evidence.bundle@1.schema.json",
"title": "AdvisoryAI Evidence Bundle Schema v1",
"description": "Schema for AdvisoryAI evidence bundles containing advisory observations with CVSS vectors and optional signatures. Used by ExportCenter and Timeline services for evidence aggregation.",
"type": "object",
"required": ["bundleId", "advisoryId", "tenant", "generatedAt", "schemaVersion"],
"$defs": {
"cvssVector": {
"type": "object",
"title": "CVSS Vector",
"description": "Common Vulnerability Scoring System vector and score",
"properties": {
"vector": {
"type": ["string", "null"],
"description": "CVSS vector string (v2, v3.0, v3.1, or v4.0)",
"examples": [
"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
"CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N"
]
},
"score": {
"type": ["number", "null"],
"minimum": 0,
"maximum": 10,
"description": "CVSS base score (0.0 to 10.0)"
}
},
"additionalProperties": false
},
"signatureInfo": {
"type": "object",
"title": "Signature Information",
"description": "Cryptographic signature for bundle authentication",
"required": ["signature", "keyId"],
"properties": {
"signature": {
"type": "string",
"description": "Base64-encoded cryptographic signature"
},
"keyId": {
"type": "string",
"description": "Identifier of the signing key",
"examples": ["sha256:abc123...", "stellaops-prod-2025"]
},
"algorithm": {
"type": ["string", "null"],
"description": "Signature algorithm used",
"examples": ["ECDSA-P256-SHA256", "RSA-PSS-SHA256", "Ed25519"]
}
},
"additionalProperties": false
},
"advisoryObservation": {
"type": "object",
"title": "Advisory Observation",
"description": "An individual advisory observation within the bundle",
"required": ["observationId", "source"],
"properties": {
"observationId": {
"type": "string",
"description": "Unique identifier for this observation",
"minLength": 1
},
"source": {
"type": "string",
"description": "Source of the observation (e.g., scanner, user, vex-lens)",
"examples": ["scanner", "manual", "vex-lens", "advisoryai", "concelier"]
},
"purl": {
"type": ["string", "null"],
"description": "Package URL identifying the affected component",
"pattern": "^pkg:[a-z]+/",
"examples": ["pkg:npm/lodash@4.17.21", "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1"]
},
"cve": {
"type": ["string", "null"],
"description": "CVE identifier",
"pattern": "^CVE-[0-9]{4}-[0-9]+$",
"examples": ["CVE-2021-44228", "CVE-2024-12345"]
},
"severity": {
"type": ["string", "null"],
"description": "Severity level",
"enum": ["critical", "high", "medium", "low", "info", "unknown", null]
},
"cvss": {
"oneOf": [
{ "$ref": "#/$defs/cvssVector" },
{ "type": "null" }
],
"description": "CVSS vector and score"
},
"summary": {
"type": ["string", "null"],
"description": "Brief summary of the observation"
},
"evidence": {
"type": ["object", "null"],
"additionalProperties": true,
"description": "Arbitrary evidence data attached to the observation",
"examples": [
{
"reachability": "reachable",
"callPaths": ["main() -> vulnerable_func()"],
"exploitMaturity": "poc"
}
]
}
},
"additionalProperties": false
}
},
"properties": {
"bundleId": {
"type": "string",
"description": "Unique identifier for this evidence bundle",
"minLength": 1,
"examples": ["bundle-550e8400-e29b-41d4-a716-446655440000"]
},
"advisoryId": {
"type": "string",
"description": "Identifier of the related advisory or assessment",
"minLength": 1,
"examples": ["advisory-2025-001", "assessment-abc123"]
},
"tenant": {
"type": "string",
"description": "Tenant identifier (may be UUID or name)",
"minLength": 1,
"examples": ["00000000-0000-0000-0000-000000000001", "acme-corp"]
},
"generatedAt": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp when the bundle was generated"
},
"schemaVersion": {
"type": "integer",
"minimum": 0,
"description": "Schema version number for this bundle format",
"default": 1
},
"observations": {
"type": "array",
"items": {
"$ref": "#/$defs/advisoryObservation"
},
"default": [],
"description": "List of advisory observations in this bundle"
},
"signatures": {
"type": ["array", "null"],
"items": {
"$ref": "#/$defs/signatureInfo"
},
"description": "Optional cryptographic signatures for bundle verification"
}
},
"additionalProperties": false,
"examples": [
{
"bundleId": "bundle-550e8400-e29b-41d4-a716-446655440000",
"advisoryId": "assessment-log4shell-2024",
"tenant": "00000000-0000-0000-0000-000000000001",
"generatedAt": "2025-12-07T10:30:00Z",
"schemaVersion": 1,
"observations": [
{
"observationId": "obs-001",
"source": "scanner",
"purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1",
"cve": "CVE-2021-44228",
"severity": "critical",
"cvss": {
"vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
"score": 10.0
},
"summary": "Log4Shell RCE vulnerability detected in log4j-core",
"evidence": {
"reachability": "reachable",
"callPaths": [
"com.example.App.main() -> org.apache.logging.log4j.Logger.error()"
],
"exploitMaturity": "weaponized",
"kevListed": true
}
},
{
"observationId": "obs-002",
"source": "vex-lens",
"purl": "pkg:maven/org.apache.logging.log4j/log4j-api@2.14.1",
"cve": "CVE-2021-45105",
"severity": "high",
"cvss": {
"vector": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:N/I:N/A:H",
"score": 5.9
},
"summary": "Log4j2 infinite recursion DoS vulnerability"
}
],
"signatures": [
{
"signature": "MEUCIQDx...",
"keyId": "sha256:abc123def456...",
"algorithm": "ECDSA-P256-SHA256"
}
]
}
]
}

107
docs/governance/default-approval-protocol.md Normal file
View File

@@ -0,0 +1,107 @@
# Default Approval Protocol
**Decision ID:** GOV-APPROVAL-001
**Status:** APPROVED
**Effective Date:** 2025-12-06
## Purpose
This protocol establishes a default decision-making framework for tasks blocked on approvals, staffing decisions, or owner assignments. It enables autonomous progress while maintaining accountability.
## 48-Hour Silence Rule
**Principle:** Silence within 48 hours of a documented request constitutes implicit approval.
### Scope
This rule applies to:
- Schema approvals pending guild review
- Design document sign-offs
- Staffing/owner assignment requests
- Contract freeze decisions
- Migration approval gates
### Exclusions
This rule does NOT apply to:
- Security-critical decisions (key rotation, credential issuance)
- Production deployment approvals
- Customer-facing contract changes
- License or legal decisions
## Decision Artifact Pattern
When a decision is needed, create a **Decision Contract** document:
```markdown
# <Topic> Decision Contract
**Decision ID:** DECISION-<ID>
**Status:** PENDING-APPROVAL (48h window starts: <timestamp>)
**Deadline:** <timestamp + 48h>
**Notify:** <guild-leads@stella-ops.org>
## Proposed Decision
<What is being decided>
## Rationale
<Why this is the recommended default>
## Impact
- Tasks unblocked: <count>
- Sprint files affected: <list>
## Reversibility
<How to override if the default is not acceptable>
```
After 48 hours without objection:
1. Update `Status:` to `DEFAULT-APPROVED`
2. Update dependent sprint files
3. Log in `docs/governance/decisions-log.md`
## Owner Manifest Pattern
When a task is blocked on staffing/ownership:
```markdown
# <Component> Owner Manifest
**Decision ID:** OWNER-<ID>
**Status:** ASSIGNED
**Effective Date:** <date>
## Assignment
<Component> is owned by <Guild/Team> for implementation purposes.
## Rationale
<Why this assignment makes sense>
## Scope
<What this owner is responsible for>
## Escalation Path
<Who to escalate to if blocked>
## Authority Granted
This manifest grants implementation authority to proceed with tasks
blocked on staffing.
```
## Governance Log
All decisions made via this protocol MUST be logged in:
- `docs/governance/decisions-log.md` (append-only)
- Relevant sprint file execution logs
## Escalation
If a decision is contested after default approval:
1. Raise in next daily standup
2. Escalate to steering committee if unresolved in 24h
3. Decision may be reversed but work already done is preserved
## References
- [Approvals and Routing](./approvals-and-routing.md)
- [Exceptions](./exceptions.md)

1479
docs/implplan/BLOCKED_DEPENDENCY_TREE.md
View File

File diff suppressed because it is too large Load Diff

367
docs/implplan/DEPENDENCY_DAG.md Normal file
View File

@@ -0,0 +1,367 @@
# Blocked Tasks Dependency DAG
> **Last Updated:** 2025-12-06
> **Total Blocked Tasks:** 399 across 61 sprint files
> **Root Blockers:** 42 unique blockers
> **Cross-Reference:** See [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for detailed task inventory
---
## Executive Summary
**95% of blocked tasks are caused by missing contracts/specifications from upstream guilds** — not by individual ticket dependencies. This is a systemic process failure in cross-team coordination.
| Metric | Value |
|--------|-------|
| Total BLOCKED tasks | 399 |
| Sprint files with blocks | 61 |
| Unique root blockers | 42+ |
| Longest dependency chain | 10 tasks (Registry API) |
| Tasks unblocked since 2025-12-04 | 84+ |
| Remaining blocked | ~315 |
---
## Master Dependency Graph
```mermaid
flowchart TB
subgraph ROOT_BLOCKERS["ROOT BLOCKERS (42 total)"]
RB1["SIGNALS CAS Promotion<br/>PREP-SIGNALS-24-002"]
RB2["Risk Scoring Contract<br/>66-002"]
RB3["VerificationPolicy Schema"]
RB4["advisory_key Schema"]
RB5["Policy Studio API"]
RB6["Authority effective:write"]
RB7["GRAP0101 Vuln Explorer"]
RB8["Sealed Mode Contract"]
RB9["Time-Anchor/TUF Trust"]
RB10["PGMI0101 Staffing"]
end
subgraph SIGNALS_CHAIN["SIGNALS CHAIN (15+ tasks)"]
S1["24-002 Cache"]
S2["24-003 Runtime Facts"]
S3["24-004 Authority Scopes"]
S4["24-005 Scoring"]
S5["GRAPH-28-007"]
S6["GRAPH-28-008"]
S7["GRAPH-28-009"]
S8["GRAPH-28-010"]
end
subgraph VEX_CHAIN["VEX LENS CHAIN (11 tasks)"]
V1["30-001 Base"]
V2["30-002"]
V3["30-003 Issuer Dir"]
V4["30-004 Policy"]
V5["30-005"]
V6["30-006 Ledger"]
V7["30-007"]
V8["30-008 Policy"]
V9["30-009 Observability"]
V10["30-010 QA"]
V11["30-011 DevOps"]
end
subgraph REGISTRY_CHAIN["REGISTRY API CHAIN (10 tasks)"]
R1["27-001 OpenAPI Spec"]
R2["27-002 Workspace"]
R3["27-003 Compile"]
R4["27-004 Simulation"]
R5["27-005 Batch"]
R6["27-006 Review"]
R7["27-007 Publish"]
R8["27-008 Promotion"]
R9["27-009 Metrics"]
R10["27-010 Tests"]
end
subgraph EXPORT_CHAIN["EXPORT CENTER CHAIN (8 tasks)"]
E1["OAS-63-001 Deprecation"]
E2["OBS-50-001 Telemetry"]
E3["OBS-51-001 Metrics"]
E4["OBS-52-001 Timeline"]
E5["OBS-53-001 Evidence"]
E6["OBS-54-001 DSSE"]
E7["OBS-54-002 Promotion"]
E8["OBS-55-001 Incident"]
end
subgraph AIRGAP_CHAIN["AIRGAP ECOSYSTEM (17+ tasks)"]
A1["CTL-57-001 Diagnostics"]
A2["CTL-57-002 Telemetry"]
A3["CTL-58-001 Time Anchor"]
A4["IMP-57-002 Loader"]
A5["IMP-58-001 API/CLI"]
A6["IMP-58-002 Timeline"]
A7["CLI-56-001 mirror create"]
A8["CLI-56-002 sealed mode"]
A9["CLI-57-001 airgap import"]
A10["CLI-57-002 airgap seal"]
A11["CLI-58-001 airgap export"]
end
subgraph ATTESTOR_CHAIN["ATTESTATION CHAIN (6 tasks)"]
AT1["73-001 VerificationPolicy"]
AT2["73-002 Verify Pipeline"]
AT3["74-001 Attestor Pipeline"]
AT4["74-002 Console Report"]
AT5["CLI-73-001 stella attest sign"]
AT6["CLI-73-002 stella attest verify"]
end
subgraph RISK_CHAIN["RISK/POLICY CHAIN (10+ tasks)"]
RI1["67-001 Risk Metadata"]
RI2["68-001 Policy Studio"]
RI3["68-002 Overrides"]
RI4["69-001 Notifications"]
RI5["70-001 AirGap Rules"]
end
subgraph VULN_DOCS["VULN EXPLORER DOCS (13 tasks)"]
VD1["29-001 Overview"]
VD2["29-002 Console"]
VD3["29-003 API"]
VD4["29-004 CLI"]
VD5["29-005 Ledger"]
VD6["..."]
VD7["29-013 Install"]
end
%% Root blocker connections
RB1 --> S1
S1 --> S2 --> S3 --> S4
S1 --> S5 --> S6 --> S7 --> S8
RB2 --> RI1 --> RI2 --> RI3 --> RI4 --> RI5
RB2 --> E1
RB3 --> AT1 --> AT2 --> AT3 --> AT4
RB3 --> AT5 --> AT6
RB4 --> V1 --> V2 --> V3 --> V4 --> V5 --> V6 --> V7 --> V8 --> V9 --> V10 --> V11
RB5 --> R1 --> R2 --> R3 --> R4 --> R5 --> R6 --> R7 --> R8 --> R9 --> R10
RB6 --> AT1
RB7 --> VD1 --> VD2 --> VD3 --> VD4 --> VD5 --> VD6 --> VD7
RB8 --> A1 --> A2 --> A3
RB8 --> A7 --> A8 --> A9 --> A10 --> A11
RB9 --> A3
RB9 --> A4 --> A5 --> A6
E1 --> E2 --> E3 --> E4 --> E5 --> E6 --> E7 --> E8
%% Styling
classDef rootBlocker fill:#ff6b6b,stroke:#333,stroke-width:2px,color:#fff
classDef blocked fill:#ffd93d,stroke:#333,stroke-width:1px
classDef resolved fill:#6bcb77,stroke:#333,stroke-width:1px
class RB1,RB2,RB3,RB4,RB5,RB6,RB7,RB8,RB9,RB10 rootBlocker
```
---
## Cascade Impact Analysis
```
+---------------------------------------------------------------------------------+
| ROOT BLOCKER -> DOWNSTREAM IMPACT |
+---------------------------------------------------------------------------------+
| |
| SIGNALS CAS (RB1) -----+---> 24-002 ---> 24-003 ---> 24-004 ---> 24-005 |
| Impact: 15+ tasks | |
| +---> GRAPH-28-007 ---> 28-008 ---> 28-009 ---> 28-010 |
| |
+---------------------------------------------------------------------------------+
| |
| VEX/advisory_key (RB4) ---> 30-001 ---> 30-002 ---> 30-003 ---> 30-004 ---> ...|
| Impact: 11 tasks +---> 30-011 |
| |
+---------------------------------------------------------------------------------+
| |
| Risk Contract (RB2) ---+---> 67-001 ---> 68-001 ---> 68-002 ---> 69-001 --> ...|
| Impact: 10+ tasks | |
| +---> EXPORT OAS-63-001 ---> OBS-50-001 ---> ... --> ...|
| |
+---------------------------------------------------------------------------------+
| |
| Policy Studio (RB5) -----> 27-001 ---> 27-002 ---> 27-003 ---> ... ---> 27-010 |
| Impact: 10 tasks |
| |
+---------------------------------------------------------------------------------+
| |
| Sealed Mode (RB8) -----+---> CTL-57-001 ---> CTL-57-002 ---> CTL-58-001 |
| Impact: 17+ tasks | |
| +---> IMP-57-002 ---> IMP-58-001 ---> IMP-58-002 |
| | |
| +---> CLI-56-001 ---> CLI-56-002 ---> CLI-57-001 ---> ...|
| +---> CLI-58-001 |
| |
+---------------------------------------------------------------------------------+
| |
| GRAP0101 Vuln (RB7) -----> 29-001 ---> 29-002 ---> 29-003 ---> ... ---> 29-013 |
| Impact: 13 tasks |
| |
+---------------------------------------------------------------------------------+
| |
| VerificationPolicy (RB3) +---> 73-001 ---> 73-002 ---> 74-001 ---> 74-002 |
| Impact: 6 tasks | |
| +---> CLI-73-001 ---> CLI-73-002 |
| |
+---------------------------------------------------------------------------------+
```
---
## Critical Path Timeline
```
2025-12-06 2025-12-09 2025-12-11 2025-12-13
| | | |
SIGNALS CAS -------------*=====================================================-->
(15+ tasks) | Checkpoint | | |
| Platform | | |
| Storage | | |
| Approval | | |
| | |
RISK CONTRACT ---------------------------*===========================================>
(10+ tasks) | Due | |
| | |
DOCS Md.IX ------------------------------*========*========*========*=============>
(40+ tasks) | Risk | Console | SDK | ESCALATE
| API | Assets | Samples|
| | | |
VEX LENS --------------------------------*===========================================>
(11 tasks) | Issuer | |
| Dir + | |
| API | |
| Gov | |
| |
ATTESTATION -----------------------------------------*================================>
(6 tasks) | Verification |
| Policy Schema |
|
AIRGAP --------------------------------------------------*=========================>
(17+ tasks) | Time-Anchor
| TUF Trust
```
---
## Guild Dependency Matrix
Shows which guilds block which others:
```
+-------------------------------------------------------------+
| BLOCKS (downstream) |
| Policy | Risk | Attestor| AirGap| Scanner| VEX | Export| Docs |
+-----------------+--------+-------+---------+-------+--------+------+-------+------+
| Policy Engine | - | ## | ## | ## | | ## | ## | ## |
| Risk/Export | ## | - | ## | | | | - | ## |
| Attestor | ## | | - | | | | ## | ## |
| Signals | ## | ## | | | ## | | ## | ## |
| Authority | ## | | ## | ## | | | | |
| Platform/DB | | | | | | | | ## |
| VEX Lens | ## | | | | | - | ## | ## |
| Mirror/Evidence | | | ## | ## | | | - | ## |
| Console/UI | ## | ## | | | | | | ## |
| Program Mgmt | | | | ## | | | ## | |
+-----------------+--------+-------+---------+-------+--------+------+-------+------+
Legend: ## = Blocking - = Self (N/A)
```
---
## Unblock Priority Order
Based on cascade impact, resolve root blockers in this order:
| Priority | Root Blocker | Downstream | Guilds Affected | Effort |
|----------|--------------|------------|-----------------|--------|
| 1 | SIGNALS CAS (24-002) | 15+ | Signals, Graph, Telemetry, Replay | HIGH |
| 2 | VEX/advisory_key spec | 11 | VEX, Excititor, Policy, Concelier | MEDIUM |
| 3 | Risk Contract (66-002) | 10+ | Risk, Export, Policy, Ledger, Attestor | MEDIUM |
| 4 | Policy Studio API | 10 | Policy, Concelier, Web | MEDIUM |
| 5 | Sealed Mode Contract | 17+ | AirGap, CLI, Importer, Controller, Time | HIGH |
| 6 | GRAP0101 Vuln Explorer | 13 | Vuln Explorer, Docs | MEDIUM |
| 7 | VerificationPolicy Schema | 6 | Attestor, CLI, Policy | LOW |
| 8 | Authority effective:write | 3+ | Authority, Policy | LOW |
| 9 | Time-Anchor/TUF Trust | 5 | AirGap, Controller | MEDIUM |
| 10 | PGMI0101 Staffing | 3 | Program Management | ORG |
**Impact Summary:**
- Resolving top 5 blockers -> Unblocks ~60+ tasks (~150 with cascades)
- Resolving all 10 blockers -> Unblocks ~85+ tasks (~250 with cascades)
---
## Root Cause Categories
| Category | Tasks Blocked | Percentage |
|----------|---------------|------------|
| Missing API/Contract Specifications | 85+ | 39% |
| Cascading/Domino Dependencies | 70+ | 28% |
| Schema/Data Freeze Pending | 55+ | 19% |
| Documentation/Asset Blockers | 40+ | - |
| Infrastructure/Environment | 25+ | - |
| Authority/Approval Gates | 30+ | - |
---
## Guild Blocking Summary
| Guild | Tasks Blocked | Critical Deliverable | Due Date |
|-------|---------------|---------------------|----------|
| Policy Engine | 12 | `advisory_key` schema, Policy Studio API | 2025-12-09 |
| Risk/Export | 10 | Risk scoring contract (66-002) | 2025-12-09 |
| Mirror/Evidence | 8 | Registration contract, time anchors | 2025-12-09 |
| Attestor | 6 | VerificationPolicy, DSSE signing | OVERDUE |
| Signals | 6+ | CAS promotion, provenance feed | 2025-12-06 |
| SDK Generator | 6 | Sample outputs (TS/Python/Go/Java) | 2025-12-11 |
| Console/UI | 5+ | Widget captures, deterministic hashes | 2025-12-10 |
| Platform/DB | 3 | RLS + partition design approval | 2025-12-11 |
| Program Mgmt | 3 | PGMI0101 staffing confirmation | Pending |
| VEX Lens | 2 | Field list, examples | 2025-12-09 |
---
## Recent Progress (84+ Tasks Unblocked)
Since 2025-12-04:
| Specification | Tasks Unblocked |
|--------------|-----------------|
| `vex-normalization.schema.json` | 11 |
| `timeline-event.schema.json` | 10+ |
| `mirror-bundle.schema.json` | 8 |
| `VERSION_MATRIX.md` | 7 |
| `provenance-feed.schema.json` | 6 |
| `api-baseline.schema.json` | 6 |
| `ledger-airgap-staleness.schema.json` | 5 |
| `attestor-transport.schema.json` | 4 |
| Policy Studio Wave C infrastructure | 10 |
| WEB-POLICY-20-004 Rate Limiting | 6 |
---
## Recommendations
### Immediate Actions (Unblock 50+ tasks)
1. **Escalate Md.IX documentation deadlines** - Risk API, Signals schema, SDK samples due 2025-12-09
2. **Publish release artifacts** to `deploy/releases/2025.09-stable.yaml` - Orchestrator, Policy, VEX Lens, Findings Ledger
3. **Complete Advisory Key spec** - Unblocks 6+ Excititor/Policy tasks
4. **Finalize Risk Scoring Contract (66-002)** - Unblocks Ledger/Export/Policy chain
### Strategic (2-4 weeks)
1. **Implement Contract-First Governance** - Require all upstream contracts published before dependent sprints start
2. **Create Cross-Guild Coordination Checkpoints** - Weekly sync of BLOCKED tasks with escalation
3. **Refactor Long Dependency Chains** - Break chains longer than 5 tasks into parallel workstreams

14
docs/implplan/SPRINT_0111_0001_0001_advisoryai.md
View File

@@ -7,13 +7,13 @@
## Dependencies & Concurrency
- Depends on Sprint 0100.A (Attestor) staying green.
- Upstream artefacts required: `CONSOLE-VULN-29-001`, `CONSOLE-VEX-30-001`, `EXCITITOR-CONSOLE-23-001`, `SBOM-AIAI-31-001`, `CLI-VULN-29-001` ✅ (2025-12-04), `CLI-VEX-30-001` ✅ (2025-12-04), `DEVOPS-AIAI-31-001`.
- Concurrency: block publishing on missing CLI/Policy/SBOM deliverables; drafting allowed where noted.
- Upstream artefacts required: `CONSOLE-VULN-29-001`, `CONSOLE-VEX-30-001`, `EXCITITOR-CONSOLE-23-001`, `SBOM-AIAI-31-001`, `DEVOPS-AIAI-31-001`. `CLI-VULN-29-001` and `CLI-VEX-30-001` landed in Sprint 0205 on 2025-12-06.
- Concurrency: block publishing on missing Console/SBOM/DevOps deliverables; drafting allowed where noted.
## Wave Coordination
- **Wave A (drafting):** Task 3 DONE (AIAI-RAG-31-003); drafting for tasks 1/5 allowed but must stay unpublished.
- **Wave B (publish docs):** Tasks 1 and 5 BLOCKED until CLI/Policy/SBOM artefacts arrive; publish only after all upstreams land.
- **Wave C (packaging):** Task 2 moved to Ops sprint; no work here. Wave B completes sprint once unblocked.
- **Wave B (publish docs):** Task 5 delivered once CLI/Policy landed (2025-11-25); task 1 still blocked pending Console/SBOM/DevOps inputs before publish.
- **Wave C (packaging):** Task 2 moved to Ops sprint; no work here. Wave B completes sprint once upstreams finish.
## Documentation Prerequisites
- docs/README.md
@@ -29,8 +29,8 @@
| 1 | AIAI-DOCS-31-001 | BLOCKED (2025-11-22) | Await CLI/Policy artefacts | Advisory AI Docs Guild | Author guardrail + evidence docs with upstream references |
| 2 | AIAI-PACKAGING-31-002 | MOVED to SPRINT_0503_0001_0001_ops_devops_i (2025-11-23) | Track under DEVOPS-AIAI-31-002 in Ops sprint | Advisory AI Release | Package advisory feeds with SBOM pointers + provenance |
| 3 | AIAI-RAG-31-003 | DONE | None | Advisory AI + Concelier | Align RAG evidence payloads with LNM schema |
| 4 | SBOM-AIAI-31-003 | DONE (2025-12-08) | SbomService `/sbom/context` endpoint shipped; evidence at `evidence-locker/sbom-context/2025-12-08-response.json` + offline kit 2025-12-08 mirror | SBOM Service Guild · Advisory AI Guild | Advisory AI hand-off kit for `/v1/sbom/context`; smoke test with tenants |
| 5 | DOCS-AIAI-31-005/006/008/009 | BLOCKED (2025-11-23) | POLICY-ENGINE-31-001; DEVOPS-AIAI-31-001 (CLI gate cleared 2025-12-04) | Docs Guild | CLI/policy/ops docs; proceed once upstream artefacts land |
| 4 | SBOM-AIAI-31-003 | DONE (2025-11-25) | Published at `docs/advisory-ai/sbom-context-hand-off.md` | SBOM Service Guild · Advisory AI Guild | Advisory AI hand-off kit for `/v1/sbom/context`; smoke test with tenants |
| 5 | DOCS-AIAI-31-005/006/008/009 | DONE (2025-11-25) | CLI/Policy inputs landed; DEVOPS-AIAI-31-001 rollout still tracked separately | Docs Guild | CLI/policy/ops docs; proceed once upstream artefacts land |
## Action Tracker
| Focus | Action | Owner(s) | Due | Status |
@@ -56,6 +56,8 @@
## Decisions & Risks
- Publishing of docs/packages is gated on upstream Policy/DevOps artefacts; CLI prerequisites and SBOM hand-off smoke landed 2025-12-05, so remaining dependencies are `POLICY-ENGINE-31-001` and `DEVOPS-AIAI-31-001`.
- `/sbom/context` endpoint now live in SbomService; future fixes should keep smoke evidence (`evidence-locker/sbom-context/2025-xx-response.json`) updated when data contracts change.
- Publishing of docs/packages is gated on remaining Console/SBOM/DevOps artefacts; drafting allowed but must remain unpublished until dependencies land.
- CLI-VULN-29-001 and CLI-VEX-30-001 landed (Sprint 0205, 2025-12-06); Policy knobs landed 2025-11-23. Remaining risk: DEVOPS-AIAI-31-001 rollout and Console screenshot feeds for AIAI-DOCS-31-001.
- Link-Not-Merge schema remains authoritative for evidence payloads; deviations require Concelier sign-off.
## Next Checkpoints

31
docs/implplan/SPRINT_0113_0001_0002_concelier_ii.md
View File

@@ -13,9 +13,9 @@
## Wave Coordination
- **Wave A (ingest foundations — COMPLETE):** PREP tasks + LNM/graph groundwork (P1–P2, tasks 1–11) are DONE; keep outputs frozen for downstream consumers.
- **Wave B (object storage + WebService unlock):** Task 12 (CONCELIER-LNM-21-103-DEV) gates tasks 13–15; ✅ object storage contract created (`docs/schemas/object-storage.schema.json`), task 12 now TODO.
- **Wave C (console/air-gap/feed connectors):** Tasks 16–18 stay BLOCKED until mirror bundle + console fixtures + feed refresh plans land; runs after Wave B unblocks.
- Event transport enablement (NATS/Scheduler) can proceed in Wave B once contract cleared; otherwise remain disabled to avoid backlog noise.
- **Wave B (object storage + WebService unlock — COMPLETE):** Tasks 12-15 ✅ DONE (2025-12-06). Object storage, observations/linksets APIs, and event publishing endpoints all implemented.
- **Wave C (console/air-gap/feed connectors):** Tasks 16–18 stay BLOCKED until mirror bundle + console fixtures + feed refresh plans land; runs after Wave B completes.
- Event transport enablement (NATS/Scheduler) can proceed in Wave B now that object storage is complete.
## Documentation Prerequisites
- docs/README.md; docs/07_HIGH_LEVEL_ARCHITECTURE.md
@@ -43,17 +43,27 @@
| 9 | CONCELIER-LNM-21-005 | DONE (2025-11-27) | Completed: Event contract + publisher interfaces + tests + docs | Concelier Core Guild · Platform Events Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Emit `advisory.linkset.updated` events with delta descriptions + observation ids (tenant + provenance only). |
| 10 | CONCELIER-LNM-21-101-DEV | DONE (2025-11-27) | Completed: Sharding + TTL migration + event collection | Concelier Storage Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Storage.Mongo`) | Provision Mongo collections (`advisory_observations`, `advisory_linksets`) with hashed shard keys, tenant indexes, TTL for ingest metadata. |
| 11 | CONCELIER-LNM-21-102-DEV | DONE (2025-11-28) | Completed: Migration + tombstones + rollback tooling | Concelier Storage Guild · DevOps Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Storage.Mongo`) | Backfill legacy merged advisories; seed tombstones; provide rollback tooling for Offline Kit. |
| 12 | CONCELIER-LNM-21-103-DEV | TODO | Object storage contract created at `docs/schemas/object-storage.schema.json` (2025-12-05); ready for implementation. | Concelier Storage Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Storage.Mongo`) | Move large raw payloads to object storage with deterministic pointers; update bootstrapper/offline seeds; preserve provenance metadata. |
| 13 | CONCELIER-LNM-21-201 | BLOCKED (awaits 21-103) | Upstream storage tasks must land first; CI runner available for WebService tests. | Concelier WebService Guild · BE-Base Platform Guild (`src/Concelier/StellaOps.Concelier.WebService`) | `/advisories/observations` filters by alias/purl/source with strict tenant scopes; echoes upstream values + provenance fields only. |
| 14 | CONCELIER-LNM-21-202 | BLOCKED (awaits 21-201) | Await upstream to run `/advisories/linksets` export tests; CI runner available. | Concelier WebService Guild (`src/Concelier/StellaOps.Concelier.WebService`) | `/advisories/linksets`/`export`/`evidence` endpoints surface correlation + conflict payloads and `ERR_AGG_*` mapping; no synthesis/merge. |
| 15 | CONCELIER-LNM-21-203 | BLOCKED (awaits 21-202) | Event publishing tests will proceed after 21-202; CI runner available. | Concelier WebService Guild · Platform Events Guild (`src/Concelier/StellaOps.Concelier.WebService`) | Publish idempotent NATS/Redis events for new observations/linksets with documented schemas; include tenant + provenance references only. |
| 16 | CONCELIER-AIRGAP-56-001..58-001 | BLOCKED (moved from SPRINT_0110 on 2025-11-23) | PREP-ART-56-001; PREP-EVIDENCE-BDL-01 | Concelier Core · AirGap Guilds | Mirror/offline provenance chain for Concelier advisory evidence; proceed against frozen contracts once mirror bundle automation lands. |
| 17 | CONCELIER-CONSOLE-23-001..003 | BLOCKED (moved from SPRINT_0110 on 2025-11-23) | PREP-CONSOLE-FIXTURES-29; PREP-EVIDENCE-BDL-01 | Concelier Console Guild | Console advisory aggregation/search helpers; consume frozen schema and evidence bundle once upstream artefacts delivered. |
| 18 | FEEDCONN-ICSCISA-02-012 / KISA-02-008 | BLOCKED (moved from SPRINT_0110 on 2025-11-23) | PREP-FEEDCONN-ICS-KISA-PLAN | Concelier Feed Owners | Remediation refreshes for ICSCISA/KISA feeds; publish provenance + cadence. |
| 12 | CONCELIER-LNM-21-103-DEV | **DONE** (2025-12-06) | Object storage implementation complete: IObjectStore, S3ObjectStore, GridFsMigrationService, MongoMigrationTracker. Build verified. | Concelier Storage Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Storage.Mongo`) | Move large raw payloads to object storage with deterministic pointers; update bootstrapper/offline seeds; preserve provenance metadata. |
| 13 | CONCELIER-LNM-21-201 | **DONE** (2025-12-06) | Endpoint implemented in Program.cs. Build blocked by pre-existing errors in Merge/Storage.Postgres/Connector.Common modules. | Concelier WebService Guild · BE-Base Platform Guild (`src/Concelier/StellaOps.Concelier.WebService`) | `/advisories/observations` filters by alias/purl/source with strict tenant scopes; echoes upstream values + provenance fields only. |
| 14 | CONCELIER-LNM-21-202 | **DONE** (2025-12-06) | Endpoints implemented: `/advisories/linksets` (paginated), `/advisories/linksets/export` (evidence bundles). No synthesis/merge - echoes upstream values only. | Concelier WebService Guild (`src/Concelier/StellaOps.Concelier.WebService`) | `/advisories/linksets`/`export`/`evidence` endpoints surface correlation + conflict payloads and `ERR_AGG_*` mapping; no synthesis/merge. |
| 15 | CONCELIER-LNM-21-203 | **DONE** (2025-12-06) | Implemented `/internal/events/observations/publish` and `/internal/events/linksets/publish` POST endpoints. Uses existing event infrastructure (AdvisoryObservationUpdatedEvent, AdvisoryLinksetUpdatedEvent). | Concelier WebService Guild · Platform Events Guild (`src/Concelier/StellaOps.Concelier.WebService`) | Publish idempotent NATS/Redis events for new observations/linksets with documented schemas; include tenant + provenance references only. |
| 16 | CONCELIER-AIRGAP-56-001..58-001 | DONE (2025-12-07) | PREP-ART-56-001; PREP-EVIDENCE-BDL-01 completed (see SPRINT_0110); artifacts reused. | Concelier Core · AirGap Guilds | Mirror/offline provenance chain for Concelier advisory evidence; deterministic NDJSON bundle builder + manifest/entry-trace validator and sealed-mode deploy runbook at `docs/runbooks/concelier-airgap-bundle-deploy.md` with sample bundle `out/mirror/thin/mirror-thin-m0-sample.tar.gz`. |
| 17 | CONCELIER-CONSOLE-23-001..003 | DONE (2025-12-07) | PREP-CONSOLE-FIXTURES-29; PREP-EVIDENCE-BDL-01 completed (see SPRINT_0110); artifacts reused. | Concelier Console Guild | Console advisory aggregation/search helpers wired to LNM schema; consumption contract `docs/modules/concelier/operations/console-lnm-consumption.md`, fixtures in `docs/samples/console/`, hashes under `out/console/guardrails/`. |
| 18 | FEEDCONN-ICSCISA-02-012 / KISA-02-008 | DONE (2025-12-08) | Execute ICS/KISA remediation per SOP v0.2 (`docs/modules/concelier/feeds/icscisa-kisa.md`); run backlog reprocess and publish delta/hashes by 2025-12-10. | Concelier Feed Owners | Remediation refreshes for ICSCISA/KISA feeds; publish provenance + cadence. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-08 | Configured feed runner defaults for on-prem: `FEED_GATEWAY_HOST`/`FEED_GATEWAY_SCHEME` default to `concelier-webservice` (Docker network DNS) so CI fetches via local mirror; `fetch.log` records resolved URLs when defaults are used; external URLs still overrideable via `ICSCISA_FEED_URL`/`KISA_FEED_URL`. | DevOps |
| 2025-12-08 | Added CI automation `.gitea/workflows/icscisa-kisa-refresh.yml` (Mon 02:00 UTC + manual) using `scripts/feeds/run_icscisa_kisa_refresh.py`; publishes `icscisa-kisa-<YYYYMMDD>` artefact (advisories/delta/log/hashes) with live fetch + offline fallback. | DevOps |
| 2025-12-08 | FEEDCONN-ICSCISA-02-012/KISA-02-008 DONE: SOP v0.2 run (`icscisa-kisa-20251208T0205Z`) executed with backlog window 60d; artefacts at `out/feeds/icscisa-kisa/20251208/` (advisories, delta, hashes, fetch log). Docs refreshed (`docs/modules/concelier/feeds/icscisa-kisa.md`, `icscisa-kisa-provenance.md`); next review 2025-12-21. | Concelier Feed Owners |
| 2025-12-07 | PREP-FEEDCONN-ICS-KISA-PLAN refreshed to v0.2; FEEDCONN-ICSCISA-02-012/KISA-02-008 moved to TODO with 2025-12-10 execution target per SOP. | Project Mgmt |
| 2025-12-07 | Marked CONCELIER-AIRGAP-56-001..58-001 DONE (artifacts from SPRINT_0110: `docs/runbooks/concelier-airgap-bundle-deploy.md`, `out/mirror/thin/mirror-thin-m0-sample.tar.gz`). | Project Mgmt |
| 2025-12-07 | Marked CONCELIER-CONSOLE-23-001..003 DONE (artifacts from SPRINT_0110: `docs/modules/concelier/operations/console-lnm-consumption.md`, `docs/samples/console/`, `out/console/guardrails/`). | Project Mgmt |
| 2025-12-06 | **CONCELIER-LNM-21-203 DONE:** Implemented `/internal/events/observations/publish` and `/internal/events/linksets/publish` POST endpoints in Program.cs. Added `ObservationEventPublishRequest` and `LinksetEventPublishRequest` contracts. Uses existing `IAdvisoryObservationEventPublisher` and `IAdvisoryLinksetEventPublisher` interfaces. Wave B now complete (tasks 12-15 all done). | Implementer |
| 2025-12-06 | **CONCELIER-LNM-21-202 DONE:** Implemented `/advisories/linksets` GET endpoint (paginated, supports advisoryId/alias/source filters). Implemented `/advisories/linksets/export` GET endpoint (evidence bundles with full provenance). Maps linksets to LnmLinksetResponse format with conflicts and normalized data. | Implementer |
| 2025-12-06 | **CONCELIER-LNM-21-201 DONE:** Implemented `/advisories/observations` GET endpoint in Program.cs. Supports alias/purl/cpe/id filtering with pagination (cursor/limit). Enforces tenant scopes via `X-Stella-Tenant` header. Returns observations with linkset aggregate (aliases, purls, cpes, references, scopes, relationships, confidence, conflicts). Uses `ObservationsPolicyName` authorization. Build blocked by pre-existing errors in Merge/Storage.Postgres/Connector.Common. | Implementer |
| 2025-12-06 | **CONCELIER-LNM-21-103-DEV DONE:** Implemented S3-compatible object storage for raw advisory payloads. Created: `ObjectPointer`, `PayloadReference`, `ProvenanceMetadata`, `MigrationRecord` models; `IObjectStore` interface; `S3ObjectStore` implementation with compression/inline storage; `MongoMigrationTracker` for GridFS migration tracking; `GridFsMigrationService` for batch migration; `ObjectStorageServiceCollectionExtensions` for DI. Updated `StellaOps.Concelier.Storage.Mongo.csproj` with AWSSDK.S3 and MongoDB.Driver dependencies. Build verified. Tasks 13-15 now unblocked. | Implementer |
| 2025-12-05 | **Wave B Unblocked:** CONCELIER-LNM-21-103-DEV changed from BLOCKED to TODO. Root blocker resolved: `docs/schemas/object-storage.schema.json` contract created. Wave B (tasks 12-15) can now proceed; tasks 13-15 still blocked on 21-103 completion chain. | Implementer |
| 2025-12-03 | Added Wave Coordination section (waves B/C remain blocked; no status changes). | Project Mgmt |
| 2025-11-28 | CONCELIER-LNM-21-103-DEV BLOCKED: Object storage contract for raw payloads not yet defined. Current payloads stored in GridFS; migration to S3-compatible store requires interface definition and cross-guild coordination with DevOps Guild. Marked task blocked and documented in Decisions & Risks. | Implementer |
@@ -71,6 +81,7 @@
| 2025-11-23 | Captured build binlog for stalled WebService.Tests attempt at `out/ws-tests.binlog` for CI triage. | Concelier Core |
| 2025-11-23 | Split CI runner blocker into DEVOPS-CONCELIER-CI-24-101 (SPRINT_0503_0001_0001_ops_devops_i); all CI/vstest-related blocks now point to that ops task. | Project Mgmt |
| 2025-11-23 | Marked downstream tasks (GRAPH-24-101/28-102, LNM-21-004..203) BLOCKED pending CI/clean runner; local harness cannot compile or run tests (`invalid test source` / hang). Development awaiting CI resources. Split storage/backfill/object-store tasks into DEV (here) vs DEVOPS release items (10b/11b/12b) to avoid dev blockage. | Project Mgmt |
| 2025-12-07 | PREP-ART-56-001 / PREP-EVIDENCE-BDL-01 / PREP-CONSOLE-FIXTURES-29 confirmed DONE in archived Sprint 0110; moved CONCELIER-AIRGAP-56-001..58-001 and CONCELIER-CONSOLE-23-001..003 to TODO. | Project Mgmt |
| 2025-11-23 | Imported CONCELIER-AIRGAP-56-001..58-001, CONCELIER-CONSOLE-23-001..003, FEEDCONN-ICSCISA-02-012/KISA-02-008 from SPRINT_0110; statuses remain BLOCKED pending mirror/console/feed artefacts. | Project Mgmt |
| 2025-11-20 | Wired optional NATS transport for `advisory.observation.updated@1`; background worker dequeues Mongo outbox and publishes to configured stream/subject. | Implementer |
| 2025-11-20 | Wired advisory.observation.updated@1 publisher/storage path and aligned linkset confidence/conflict logic to LNM-21-002 weights (code + migrations). | Implementer |

55
docs/implplan/SPRINT_0116_0001_0005_concelier_v.md
View File

@@ -29,27 +29,43 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 0 | CONCELIER-VULN-29-001 | DONE (2025-12-08) | Delivered per bridge contract `docs/modules/concelier/bridges/vuln-29-001.md`; raw evidence snapshots/live endpoints available. | WebService · Data Integrity Guild | Canonicalize advisory identifiers into `advisory_key`, persist `links[]`, expose raw payload snapshots + Vuln Explorer search contract without merge-derived fields. |
| P1 | PREP-CONCELIER-WEB-AIRGAP-57-001-DEPENDS-ON-5 | DONE (2025-11-20) | Prep at `docs/modules/concelier/prep/2025-11-20-web-airgap-57-001-prep.md`; awaits 56-002 & WEB-OAS-61-002 inputs. | Concelier WebService Guild · AirGap Policy Guild | Document artefact for 57-001 to unblock downstream air-gap tasks. |
| 1 | CONCELIER-VULN-29-004 | BLOCKED | Depends on CONCELIER-VULN-29-001 | WebService · Observability Guild | Instrument ingestion pipelines with metrics (collisions, withdrawn statements, chunk latency); stream to Vuln Explorer unchanged. |
| 2 | CONCELIER-WEB-AIRGAP-56-001 | BLOCKED | Start of AirGap chain | WebService Guild | Register mirror bundle sources, expose bundle catalog, enforce sealed-mode (block direct internet feeds). |
| 3 | CONCELIER-WEB-AIRGAP-56-002 | BLOCKED | Depends on 56-001 | WebService Guild | Add staleness + bundle provenance metadata to observation/linkset endpoints. |
| 4 | CONCELIER-WEB-AIRGAP-57-001 | BLOCKED | Prep P1 done; needs 56-002 | WebService · AirGap Policy Guild | Map sealed-mode violations to `AIRGAP_EGRESS_BLOCKED` payloads with remediation guidance. |
| 5 | CONCELIER-WEB-AIRGAP-58-001 | BLOCKED | Depends on 57-001 | WebService · AirGap Importer Guild | Emit timeline events for bundle imports (bundle ID, scope, actor) per evidence change. |
| 6 | CONCELIER-WEB-AOC-19-003 | BLOCKED (2025-11-24) | Needs WEB-AOC-19-002 validator | QA Guild | Unit tests for schema validators/forbidden fields (`ERR_AOC_001/2/6/7`), supersedes chains. |
| 7 | CONCELIER-WEB-AOC-19-004 | BLOCKED (2025-11-24) | Depends on 19-003 | WebService · QA | Integration tests for large-batch ingest reproducibility; fixtures for Offline Kit. |
| 8 | CONCELIER-WEB-AOC-19-005 | BLOCKED (2025-11-24) | Needs WEB-AOC-19-002 | WebService · QA | Fix `/advisories/{key}/chunks` seed data so raw docs resolve. |
| 9 | CONCELIER-WEB-AOC-19-006 | BLOCKED (2025-11-24) | Needs WEB-AOC-19-002 | WebService Guild | Align auth/tenant configs with fixtures; ensure allowlist enforcement tests pass. |
| 10 | CONCELIER-WEB-AOC-19-007 | BLOCKED (2025-11-24) | Needs WEB-AOC-19-002 | WebService · QA | Ensure AOC verify emits `ERR_AOC_001`; mapper/guard parity with regressions. |
| 11 | CONCELIER-WEB-OAS-61-002 | BLOCKED | Prereq for examples/deprecation | WebService Guild | Migrate APIs to standard error envelope; update controllers/tests. |
| 12 | CONCELIER-WEB-OAS-62-001 | BLOCKED | Depends on 61-002 | WebService Guild | Publish curated examples for observations/linksets/conflicts; wire into dev portal. |
| 13 | CONCELIER-WEB-OAS-63-001 | BLOCKED | Depends on 62-001 | WebService · API Governance | Emit deprecation headers/notifications steering clients to LNM APIs. |
| 1 | CONCELIER-VULN-29-004 | DONE (2025-12-08) | Upstream bridge done (CONCELIER-VULN-29-001); define collision/withdrawn/chunk telemetry and OTEL export for Vuln Explorer. | WebService · Observability Guild | Instrument ingestion pipelines with metrics (collisions, withdrawn statements, chunk latency); stream to Vuln Explorer unchanged. |
| 2 | CONCELIER-WEB-AIRGAP-56-001 | DONE (2025-12-06) | AirGap chain started | WebService Guild | Register mirror bundle sources, expose bundle catalog, enforce sealed-mode (block direct internet feeds). |
| 3 | CONCELIER-WEB-AIRGAP-56-002 | DONE (2025-12-06) | Staleness + provenance contracts added | WebService Guild | Add staleness + bundle provenance metadata to observation/linkset endpoints. |
| 4 | CONCELIER-WEB-AIRGAP-57-001 | DONE (2025-12-06) | Egress blocked payload + remediation | WebService · AirGap Policy Guild | Map sealed-mode violations to `AIRGAP_EGRESS_BLOCKED` payloads with remediation guidance. |
| 5 | CONCELIER-WEB-AIRGAP-58-001 | DONE | Implemented BundleImportTimelineEvent, BundleTimelineEmitter, POST /bundles/{id}/import endpoint. | WebService · AirGap Importer Guild | Emit timeline events for bundle imports (bundle ID, scope, actor) per evidence change. |
| 6 | CONCELIER-WEB-AOC-19-003 | DONE | Tests in `AdvisorySchemaValidatorTests.cs` cover ERR_AOC_001/002/006/007. | QA Guild | Unit tests for schema validators/forbidden fields (`ERR_AOC_001/2/6/7`), supersedes chains. |
| 7 | CONCELIER-WEB-AOC-19-004 | DONE | Created `LargeBatchIngestTests.cs` with reproducibility and scaling tests. | WebService · QA | Integration tests for large-batch ingest reproducibility; fixtures for Offline Kit. |
| 8 | CONCELIER-WEB-AOC-19-005 | DONE | Created `AdvisoryChunkSeedData.cs` with comprehensive fixtures. | WebService · QA | Fix `/advisories/{key}/chunks` seed data so raw docs resolve. |
| 9 | CONCELIER-WEB-AOC-19-006 | DONE | Created `AuthTenantTestFixtures.cs` + `TenantAllowlistTests.cs`. | WebService Guild | Align auth/tenant configs with fixtures; ensure allowlist enforcement tests pass. |
| 10 | CONCELIER-WEB-AOC-19-007 | DONE | Created `AocVerifyRegressionTests.cs` with comprehensive regression tests. | WebService · QA | Ensure AOC verify emits `ERR_AOC_001`; mapper/guard parity with regressions. |
| 11 | CONCELIER-WEB-OAS-61-002 | DONE (2025-12-06) | Prereq for examples/deprecation | WebService Guild | Migrate APIs to standard error envelope; update controllers/tests. |
| 12 | CONCELIER-WEB-OAS-62-001 | DONE | Created docs for lnm-linksets, observations, conflicts; updated OpenAPI spec v1.0.0 with examples. | WebService Guild | Publish curated examples for observations/linksets/conflicts; wire into dev portal. |
| 13 | CONCELIER-WEB-OAS-63-001 | DONE | Created `DeprecationHeaders.cs`, `DeprecationMiddleware.cs`, registered in Program.cs, added tests. | WebService · API Governance | Emit deprecation headers/notifications steering clients to LNM APIs. |
| 14 | CONCELIER-WEB-OBS-51-001 | DONE (2025-11-23) | Schema 046_TLTY0101 published 2025-11-23 | WebService Guild | `/obs/concelier/health` for ingest health/queue/SLO status. |
| 15 | CONCELIER-WEB-OBS-52-001 | DONE (2025-11-24) | Depends on 51-001 | WebService Guild | SSE `/obs/concelier/timeline` with paging tokens, audit logging. |
| 16 | CONCELIER-AIAI-31-002 | BLOCKED (2025-12-04) | Postgres linkset cache backend added; WebService lacks Postgres configuration; need to add Postgres connection config before DI wiring. | Concelier Core · Concelier WebService Guilds | Implement Link-Not-Merge linkset cache per `docs/modules/concelier/operations/lnm-cache-plan.md`, expose read-through on `/v1/lnm/linksets`, add metrics `lnm.cache.*`, and cover with deterministic tests. |
| 16 | CONCELIER-AIAI-31-002 | DONE | Created `ReadThroughLinksetCacheService`, `ILinksetCacheTelemetry` interface, wired DI in Program.cs. Cache reads from Postgres first, rebuilds from observations on miss, stores results. `lnm.cache.hit_total`, `lnm.cache.write_total`, `lnm.cache.rebuild_ms` metrics active. | Concelier Core · Concelier WebService Guilds | Implement Link-Not-Merge linkset cache per `docs/modules/concelier/operations/lnm-cache-plan.md`, expose read-through on `/v1/lnm/linksets`, add metrics `lnm.cache.*`, and cover with deterministic tests. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-08 | CONCELIER-VULN-29-004 DONE: Added Vuln Explorer ingest telemetry in advisory pipeline (alias collision counter from linkset conflicts, withdrawn detection from raw content, chunk latency histogram). Meter already exported via OTEL; added unit coverage for collision counting, withdrawn detection, and latency emission. | Implementer |
| 2025-12-08 | CONCELIER-VULN-29-004 moved to DOING: scoping metrics (identifier collisions, withdrawn statements, chunk latency) and OTEL export path for Vuln Explorer dashboards. | Project Mgmt |
| 2025-12-08 | CONCELIER-VULN-29-004 unblocked: Ops Helm/Compose/offline patterns for Surface.Secrets available (`ops/devops/secrets/surface-secrets-provisioning.md`) and CONCELIER-VULN-29-001 delivered; status set to TODO. | Project Mgmt |
| 2025-12-08 | Test run attempt: `dotnet test ...Concelier.WebService.Tests` failed early with NETSDK1022 (duplicate Compile items) resolved, then re-run failed with access denied to Microsoft.SourceLink.GitLab.dll during restore; telemetry changes not yet validated by tests. | Implementer |
| 2025-12-08 | Test run attempt 2: `dotnet test` with isolated `NUGET_PACKAGES` completed but 60 tests failed. Failures: Mongo2Go cannot start bundled Linux `mongod` on Windows runner (Win32Exception) causing many WebService endpoint tests to fail; advisory chunk builder/cache key expectations differ in casing/path (reference mask vs field path). Telemetry changes unvalidated; further triage needed in CI/Linux. | Implementer |
| 2025-12-06 | CONCELIER-AIAI-31-002 DONE: Created `ReadThroughLinksetCacheService.cs` in Core library implementing read-through pattern - queries Postgres cache first, on miss rebuilds from MongoDB observations, stores result. Created `ILinksetCacheTelemetry` interface for metrics abstraction. Updated `LinksetCacheTelemetry` to implement interface. Wired DI in Program.cs: `ReadThroughLinksetCacheService` registered as `IAdvisoryLinksetLookup`, injected with optional Postgres backing store. Metrics: `lnm.cache.hit_total`, `lnm.cache.write_total`, `lnm.cache.rebuild_ms`. | Implementer |
| 2025-12-06 | CONCELIER-WEB-OAS-63-001 DONE: Created `DeprecationHeaders.cs` with RFC 8594 deprecation + Sunset headers, `DeprecationMiddleware.cs` with endpoint registry, registered middleware in Program.cs. Added `DeprecationHeadersTests.cs` tests. Legacy endpoints (/linksets, /advisories/observations, /advisories/linksets, /advisories/linksets/export, /concelier/observations) now emit deprecation headers directing to /v1/lnm/linksets. | Implementer |
| 2025-12-06 | CONCELIER-WEB-OAS-62-001 DONE: Created curated API documentation - `lnm-linksets.md`, `observations.md`, `conflicts.md` in `docs/modules/concelier/api/`. Updated OpenAPI spec to v1.0.0 with comprehensive examples (single-linkset, with-conflicts scenarios), error envelope schema, and detailed descriptions. Synced spec to docs mirror. Unblocks 63-001. | Implementer |
| 2025-12-06 | CONCELIER-WEB-AOC-19-007 DONE: Created `AocVerifyRegressionTests.cs` with comprehensive regression tests covering ERR_AOC_001 for all forbidden fields (severity, cvss, cvss_vector, merged_from, consensus_provider, reachability, asset_criticality, risk_score), ERR_AOC_006 for derived fields (effective_status, effective_range, effective_severity, effective_cvss), ERR_AOC_007 for unknown fields, plus consistency and parity tests. | Implementer |
| 2025-12-06 | CONCELIER-WEB-AIRGAP-57-001 DONE: Created `AirGapEgressBlockedPayload.cs` with structured payload including `AirGapRemediationGuidance` (steps, configuration hints, documentation links). Updated `SealedModeViolationException` to include payload with remediation. Added `EgressBlocked` factory method in `ConcelierProblemResultFactory.cs`. Unblocks 58-001. | Implementer |
| 2025-12-06 | CONCELIER-WEB-AIRGAP-56-002 DONE: Created `AirGapMetadataContracts.cs` with `StalenessMetadata`, `BundleProvenanceMetadata`, and `DataFreshnessInfo` records. Added optional `Freshness` field to `LnmLinksetResponse` and `AdvisoryObservationQueryResponse`. Updated `ToLnmResponse` helper to accept freshness parameter. Unblocks 57-001. | Implementer |
| 2025-12-06 | CONCELIER-WEB-OAS-61-002 DONE: Created `ErrorCodes.cs` with machine-readable codes, `ErrorEnvelopeContracts.cs` with hybrid RFC 7807 + structured error format, `ConcelierProblemResultFactory.cs` with factory methods. Migrated all `Results.BadRequest()`/`Results.NotFound()` calls in Program.cs, MirrorEndpointExtensions.cs, and AirGapEndpointExtensions.cs to use standardized error responses with error codes and traceIds. | Implementer |
| 2025-12-06 | CONCELIER-WEB-AIRGAP-56-001 DONE: Implemented AirGap infrastructure - `AirGapOptions.cs` (config), `IBundleSourceRegistry`/`BundleSourceRegistry` (source management), `IBundleCatalogService`/`BundleCatalogService` (catalog aggregation with caching), `ISealedModeEnforcer`/`SealedModeEnforcer` (sealed-mode violation tracking), models (`BundleSourceInfo`, `BundleCatalogEntry`, `AggregatedCatalog`, `SealedModeStatus`), `AirGapServiceCollectionExtensions.cs` (DI), and `AirGapEndpointExtensions.cs` (REST API at `/api/v1/concelier/airgap/*`). | Implementer |
| 2025-12-06 | WEB-AOC-19-002 DONE: Implemented `IAdvisorySchemaValidator` interface and `AdvisorySchemaValidator` class for granular AOC validation (ValidateSchema, ValidateForbiddenFields, ValidateDerivedFields, ValidateAllowedFields, ValidateMergeAttempt). Registered in DI via `AocServiceCollectionExtensions.cs`. Created comprehensive test suite `AdvisorySchemaValidatorTests.cs` covering ERR_AOC_001/002/006/007. Unblocks tasks 6-10 (AOC regression chain). | Implementer |
| 2025-12-05 | CONCELIER-AIAI-31-002 unblocked: Added `PostgresStorageOptions` to `ConcelierOptions`, project reference to `StellaOps.Concelier.Storage.Postgres`, and `AddConcelierPostgresStorage` DI registration in `Program.cs`. Updated `etc/concelier.yaml.sample` with `postgresStorage` section. Task moves to DOING; remaining work: wire read-through on `/v1/lnm/linksets` endpoint and add `lnm.cache.*` telemetry. | Implementer |
| 2025-12-04 | CONCELIER-AIAI-31-002 set to BLOCKED: WebService currently uses MongoDB only; Postgres connection/config not present. Need to add `AddConcelierPostgresStorage` call with configuration section before cache can be wired. Telemetry `LinksetCacheTelemetry` is registered but only partially used. | Implementer |
| 2025-12-04 | Implemented Postgres LNM linkset cache backend (`AdvisoryLinksetCacheRepository` + migration 002); added integration tests. Task CONCELIER-AIAI-31-002 moves to DOING; pending WebService read-through wiring and telemetry. | Implementer |
| 2025-12-04 | Added CONCELIER-AIAI-31-002 to Delivery Tracker and marked BLOCKED; cache plan exists but no linkset store/cache backend (Mongo/Postgres) is registered, so Link-Not-Merge cache cannot be implemented yet. | Project Mgmt |
@@ -61,10 +77,13 @@
| 2025-12-02 | Normalized sprint file to standard template; no status changes. | StellaOps Agent |
## Decisions & Risks
- AirGap tasks blocked until sealed-mode + staleness metadata defined; do not expose bundles without provenance.
- AOC regression chain blocked pending validator (WEB-AOC-19-002); large-batch tests must wait.
- OAS envelope change (WEB-OAS-61-002) is a prereq for examples/deprecation; avoid duplicating client envelopes until unified.
- ~~AirGap tasks blocked until sealed-mode + staleness metadata defined~~ 56-001 done; 56-002 (staleness) now unblocked.
- ~~AOC regression chain blocked pending validator (WEB-AOC-19-002)~~ Validator done; tasks 6/8/9/10 now TODO; task 7 still blocked on 19-003.
- ~~OAS envelope change (WEB-OAS-61-002) is a prereq for examples/deprecation~~ Done; 62-001 (examples) now unblocked.
- Linkset cache (CONCELIER-AIAI-31-002): Postgres backend + migration shipped; remaining risk is wiring WebService to use it (DI + read-through) and adding `lnm.cache.*` metrics to avoid cache skew.
- CONCELIER-VULN-29-004 delivered: ingest telemetry now emits collision/withdrawn/latency metrics; confirm dashboards consume `StellaOps.Concelier.VulnExplorer` meter and secrets posture stays aligned with `surface.secrets.*` config in Helm/Compose/offline kit.
## Next Checkpoints
- None scheduled; add when validator and AirGap prerequisites land.
- Wave B (AirGap): 56-001, 56-002, 57-001 DONE; 58-001 (timeline events) ready to start.
- Wave C (AOC regression): Tasks 6/8/9/10 unblocked and ready; execute in parallel.
- Wave D (OAS alignment): 62-001 (examples) unblocked; then 63-001 (deprecation headers).

79
docs/implplan/SPRINT_0119_0001_0004_excititor_iv.md
View File

@@ -1,79 +0,0 @@
# Sprint 0119 · Excititor Ingestion & Evidence (Phase IV)
## Topic & Scope
- Emit timeline events and evidence snapshots/attestations to make ingestion fully replayable and air-gap ready.
- Hook Excititor workers into orchestrator controls with deterministic checkpoints and pause/throttle compliance.
- Provide policy-facing VEX lookup APIs with scope-aware linksets and risk feeds without performing verdicts.
- **Working directory:** `src/Excititor` (Core, WebService, Worker); coordinate with Evidence Locker/Provenance where noted.
## Dependencies & Concurrency
- Upstream: Metrics/SLOs from Phase III; Evidence Locker manifest format; Provenance tooling for DSSE verification; orchestrator SDK availability.
- Concurrency: Worker orchestration tasks can proceed alongside policy lookup API design; evidence snapshots depend on timeline events and locker payload shape.
- Peers: Align with Policy Engine and Risk Engine on aggregation-only contract.
## Wave Coordination
- **Wave A (observability + locker/attestation):** Tasks 1–3 DONE; keep schemas frozen for sealed-mode and replay consumers.
- **Wave B (orchestrator wiring):** Tasks 4–5 DONE; monitor SDK drift; no further work unless orchestrator contract changes.
- **Wave C (policy/risk APIs):** Tasks 6–8 BLOCKED awaiting POLICY-20-001 advisory_key schema and Risk feed envelope; do not start until contracts published.
- Waves run serially; only Wave C remains open/blocked. Avoid partial starts to prevent API drift.
## Documentation Prerequisites
- `docs/modules/excititor/architecture.md`
- `docs/modules/excititor/README.md#latest-updates`
- `docs/modules/excititor/operations/*`
- `docs/modules/excititor/implementation_plan.md`
- Excititor component `AGENTS.md` files (Core, WebService, Worker).
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EXCITITOR-OBS-52-001 | DONE (2025-11-23) | After OBS-51 metrics baseline; define event schema. | Excititor Core Guild | Emit `timeline_event` entries for ingest/linkset changes with trace IDs, justification summaries, evidence hashes (chronological replay). |
| 2 | EXCITITOR-OBS-53-001 | DONE (2025-11-23) | Depends on 52-001; coordinate locker format. | Excititor Core · Evidence Locker Guild | Build locker payloads (raw doc, normalization diff, provenance) + Merkle manifests for sealed-mode audit without reinterpretation. |
| 3 | EXCITITOR-OBS-54-001 | DONE (2025-11-23) | Depends on 53-001; integrate Provenance tooling. | Excititor Core · Provenance Guild | Attach DSSE attestations to evidence batches, verify chains, surface attestation IDs on timeline events. |
| 4 | EXCITITOR-ORCH-32-001 | DONE (2025-12-01) | Orchestrator worker endpoints wired into Excititor worker (`VexWorkerOrchestratorClient` HTTP client + options). | Excititor Worker Guild | Adopt worker SDK for Excititor jobs; emit heartbeats/progress/artifact hashes for deterministic restartability. |
| 5 | EXCITITOR-ORCH-33-001 | DONE (2025-12-01) | Commands mapped from orchestrator errors (pause/throttle/retry); checkpoints/progress mirrored; offline fallback retained. | Excititor Worker Guild | Honor orchestrator pause/throttle/retry commands; persist checkpoints; classify errors for safe outage handling. |
| 6 | EXCITITOR-POLICY-20-001 | TODO | Unblocked by [CONTRACT-ADVISORY-KEY-001](../contracts/advisory-key.md); ready to define API shape. | Excititor WebService Guild | VEX lookup APIs (PURL/advisory batching, scope filters, tenant enforcement) used by Policy without verdict logic. |
| 7 | EXCITITOR-POLICY-20-002 | TODO | Unblocked by advisory_key contract; can proceed after 20-001. | Excititor Core Guild | Add scope resolution/version range metadata to linksets while staying aggregation-only. |
| 8 | EXCITITOR-RISK-66-001 | TODO | Unblocked by [CONTRACT-RISK-SCORING-002](../contracts/risk-scoring.md); can proceed after 20-002. | Excititor Core · Risk Engine Guild | Publish risk-engine ready feeds (status, justification, provenance) with zero derived severity. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-03 | Added Wave Coordination (A observability/locker done; B orchestrator done; C policy/risk APIs blocked). No status changes. | Project Mgmt |
| 2025-12-03 | Normalised sprint structure; carried Action Tracker into dedicated section; no task status changes. | Planning |
| 2025-12-02 | Marked Policy/Risk API action BLOCKED: awaiting POLICY-20-001 advisory_key schema and Risk feed envelope before defining Excititor VEX lookup API. | Project Mgmt |
| 2025-11-16 | Normalized sprint file to standard template and renamed to SPRINT_0119_0001_0004_excititor_iv.md; awaiting task kickoff. | Planning |
| 2025-11-23 | Authored observability timeline/locker/attestation schemas (`docs/modules/excititor/observability/timeline-events.md`, `docs/modules/excititor/observability/locker-manifest.md`); marked OBS-52-001/53-001/54-001 DONE. | Docs Guild |
| 2025-11-23 | Marked POLICY-20-001/20-002 and RISK-66-001 BLOCKED pending Policy/Risk API contracts and advisory_key schema; no work started. | Project Mgmt |
| 2025-12-01 | Implemented orchestrator worker HTTP client + command handling (EXCITITOR-ORCH-32/33); updated options, heartbeat/command wiring, and unit tests. Ran `dotnet test src/Excititor/__Tests/StellaOps.Excititor.Worker.Tests/StellaOps.Excititor.Worker.Tests.csproj --configuration Release` (passes). | Excititor Worker |
| 2025-12-01 | Began EXCITITOR-ORCH-32-001/33-001; enabling orchestrator worker endpoints from Orchestrator WebService (`/api/v1/orchestrator/worker/*`), status set to DOING. | Excititor Worker |
## Decisions & Risks
- **Decisions**
- Evidence timeline + locker payloads must remain aggregation-only; no consensus/merging.
- Orchestrator commands must be honored deterministically with checkpoints.
- Excititor worker now prefers Orchestrator worker endpoints when `Excititor:Worker:Orchestrator:Enabled=true` and `BaseAddress` set; falls back to local state if unreachable. Throttle/lease errors map to pause/retry commands; progress/heartbeats mirror artifact hashes.
- **Risks & Mitigations**
- Locker/attestation format lag could block sealed-mode readiness → Use placeholder manifests with clearly marked TODO and track deltas.
- Orchestrator SDK changes could destabilize workers → Gate rollout behind feature flag; add rollback checkpoints.
- Policy/Risk APIs blocked on upstream contracts (POLICY-20-001 advisory_key schema; Risk feed envelope). No implementation can start until contracts published.
## Next Checkpoints
| Date (UTC) | Session / Owner | Goal | Fallback |
| 2025-11-19 | OBS-52-001 schema update | Add provenance buckets + sealed-mode markers; finalize v1 | If slip, publish interim schema and mark blockers. |
| --- | --- | --- | --- |
| 2025-11-18 | Timeline schema review | Approve OBS-52-001 event envelope. | Iterate with provisional event topic if blocked. |
| 2025-11-20 | Orchestrator integration demo | Show worker heartbeats/progress with pause/throttle compliance. | Keep jobs on legacy runner until stability proven. |
| 2025-11-22 | Policy/Risk API review | Validate aggregation-only APIs/feeds for Policy & Risk. | Ship behind feature flag if minor gaps. |
## Action Tracker (carried over)
| Focus | Action | Owner(s) | Due | Status |
| --- | --- | --- | --- | --- |
| Timeline events | Finalize event schema + trace IDs (OBS-52-001). | Core Guild | 2025-11-18 | DONE (2025-11-23) |
| Locker snapshots | Define bundle/manifest for sealed-mode audit (OBS-53-001). | Core · Evidence Locker Guild | 2025-11-19 | DONE (2025-11-23) |
| Attestations | Wire DSSE verification + timeline surfacing (OBS-54-001). | Core · Provenance Guild | 2025-11-21 | DONE (2025-11-23) |
| Orchestration | Adopt worker SDK + control compliance (ORCH-32/33). | Worker Guild | 2025-11-20 | BLOCKED (SDK missing in repo; awaiting orchestrator worker package) |
| Orchestration | Adopt worker SDK + control compliance (ORCH-32/33). | Worker Guild | 2025-11-20 | DONE (2025-12-01) |
| Policy/Risk APIs | Shape APIs + feeds (POLICY-20-001/002, RISK-66-001). | WebService/Core · Risk Guild | 2025-11-22 | TODO (unblocked 2025-12-05 by contracts) |

75
docs/implplan/SPRINT_0119_0001_0005_excititor_v.md
View File

@@ -1,75 +0,0 @@
# Sprint 0119 · Excititor Ingestion & Evidence (Phase V)
## Topic & Scope
- Feed VEX Lens and Vuln Explorer with enriched, canonicalized evidence while keeping Excititor aggregation-only.
- Lock schema validation/idempotency for raw storage and wire mirror registration APIs for air-gapped parity.
- Continue portable evidence bundle work linked to timeline/attestation metadata.
- **Working directory:** `src/Excititor` (WebService, Core, Storage); coordinate with Evidence Locker for bundles.
## Dependencies & Concurrency
- Upstream: Timeline/attestation outputs from Phase IV; portable bundle schema; schema validator groundwork in Storage; mirror registration contract.
- Concurrency: VEX Lens/Vuln Explorer APIs can progress while storage validator indexes prepare; portable bundles depend on mirror registration; observability hooks trail API delivery.
- Peers: Coordinate with VEX Lens and Vuln Explorer teams for evidence fields/examples.
## Wave Coordination
- **Wave A (storage validation):** Tasks 5–6 DONE; keep validator/schema frozen unless new defects found.
- **Wave B (VEX/Vuln exports):** Tasks 1–4 BLOCKED on advisory_key spec and Lens field list; run sequentially once contracts land.
- **Wave C (AirGap bundles):** Tasks 7–8 BLOCKED on mirror registration + bundle schema; execute after Wave B to avoid duplicate manifests unless schema arrives first.
- Only Waves B and C remain; avoid partial starts to prevent API drift.
## Documentation Prerequisites
- `docs/modules/excititor/architecture.md`
- `docs/modules/excititor/README.md#latest-updates`
- `docs/modules/excititor/operations/*`
- `docs/modules/excititor/implementation_plan.md`
- Excititor component `AGENTS.md` files (WebService, Core, Storage).
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EXCITITOR-VEXLENS-30-001 | TODO | Unblocked by [CONTRACT-VEX-LENS-005](../contracts/vex-lens.md); field list available. | Excititor WebService Guild · VEX Lens Guild | Ensure observations exported to VEX Lens carry issuer hints, signature blobs, product tree snippets, staleness metadata; no consensus logic. |
| 2 | EXCITITOR-VULN-29-001 | TODO | Unblocked by [CONTRACT-ADVISORY-KEY-001](../contracts/advisory-key.md); canonicalization spec available. | Excititor WebService Guild | Canonicalize advisory/product keys to `advisory_key`, capture scope metadata, preserve originals in `links[]`; backfill + tests. |
| 3 | EXCITITOR-VULN-29-002 | TODO | Unblocked; can proceed after 29-001. | Excititor WebService Guild | `/vuln/evidence/vex/{advisory_key}` returning tenant-scoped raw statements, provenance, attestation references for Vuln Explorer. |
| 4 | EXCITITOR-VULN-29-004 | TODO | Unblocked; can proceed after 29-002. | Excititor WebService · Observability Guild | Metrics/logs for normalization errors, suppression scopes, withdrawn statements for Vuln Explorer + Advisory AI dashboards. |
| 5 | EXCITITOR-STORE-AOC-19-001 | DONE (2025-11-25) | Draft Mongo JSON Schema + validator tooling. | Excititor Storage Guild | Ship validator (incl. Offline Kit instructions) proving Excititor stores only immutable evidence. |
| 6 | EXCITITOR-STORE-AOC-19-002 | DONE (2025-11-25) | After 19-001; create indexes/migrations. | Excititor Storage · DevOps Guild | Unique indexes, migrations/backfills, rollback steps for new validator. |
| 7 | EXCITITOR-AIRGAP-56-001 | TODO | Unblocked by [CONTRACT-MIRROR-BUNDLE-003](../contracts/mirror-bundle.md); schema available. | Excititor WebService Guild | Mirror bundle registration + provenance exposure, sealed-mode error mapping, staleness metrics in API responses. |
| 8 | EXCITITOR-AIRGAP-58-001 | TODO | Unblocked; can proceed after 56-001 with bundle schema available. | Excititor Core · Evidence Locker Guild | Portable evidence bundles linked to timeline + attestation metadata; document verifier steps for Advisory AI. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-03 | Added Wave Coordination (A storage validation done; B VEX/Vuln blocked; C AirGap blocked). No status changes. | Project Mgmt |
| 2025-12-03 | Normalised sprint structure; action tracker moved to dedicated section; no task status changes. | Planning |
| 2025-11-16 | Normalized sprint file to standard template and renamed to SPRINT_0119_0001_0005_excititor_v.md; awaiting execution. | Planning |
| 2025-11-23 | Marked Vuln Explorer chain (29-001/002/004) BLOCKED pending `advisory_key` canonicalization spec from Vuln Explorer; Action Tracker updated. | Project Mgmt |
| 2025-11-25 | Added `$jsonSchema` validator migration (`20251125-vex-raw-json-schema`) plus schema doc and rollback/runbook; marked EXCITITOR-STORE-AOC-19-001/002 DONE. | Implementer |
| 2025-11-25 | Marked VEX Lens export (30-001) BLOCKED awaiting Lens field list; set AirGap 56-001/58-001 BLOCKED until mirror registration + bundle schema arrive. | Project Mgmt |
| 2025-12-02 | Synced Action Tracker with Delivery Tracker (Lens/Observability/AirGap now BLOCKED; Storage validation DONE). | Implementer |
## Decisions & Risks
- **Decisions**
- Keep all exports/APIs aggregation-only; consensus remains outside Excititor.
- Portable bundles must include timeline + attestation references without Excititor interpretation.
- Raw collection validation ships in warn mode; can be promoted to error once datasets are clean.
- **Risks & Mitigations**
- Validator rollout could impact live ingestion → Staged rollout with dry-run validator and rollback steps.
- Mirror bundle schema delays impact bundles → Use placeholder manifest with TODOs and track deltas until schema lands.
## Next Checkpoints
| Date (UTC) | Session / Owner | Goal | Fallback |
| --- | --- | --- | --- |
| 2025-11-20 | Lens/Vuln alignment | Confirm field list + examples for 30-001 / 29-001. | Ship mock responses while contracts finalize. |
| 2025-11-22 | Storage validator review | Approve schema + index plan (19-001/002). | Keep validator in dry-run if concerns arise. |
| 2025-11-24 | AirGap bundle schema sync | Align mirror registration + bundle manifest. | Escalate to Evidence Locker if schema slips; use placeholder. |
## Action Tracker (carried over)
| Focus | Action | Owner(s) | Due | Status |
| --- | --- | --- | --- | --- |
| VEX Lens enrichers | Define required fields/examples with Lens team (30-001). | WebService · Lens Guild | 2025-11-20 | TODO (unblocked 2025-12-05 by contracts) |
| Vuln Explorer APIs | Finalize canonicalization + evidence endpoint (29-001/002). | WebService Guild | 2025-11-21 | TODO (unblocked 2025-12-05 by contracts) |
| Observability | Add metrics/logs for evidence pipeline (29-004). | WebService · Observability Guild | 2025-11-22 | TODO (unblocked 2025-12-05) |
| Storage validation | Deliver validator + indexes (19-001/002). | Storage · DevOps Guild | 2025-11-23 | DONE |
| AirGap bundles | Align mirror registration + bundle manifest (56-001/58-001). | WebService · Core · Evidence Locker | 2025-11-24 | TODO (unblocked 2025-12-05 by contracts) |

84
docs/implplan/SPRINT_0119_0001_0006_excititor_vi.md
View File

@@ -1,84 +0,0 @@
# Sprint 0119 · Excititor Ingestion & Evidence (Phase VI)
## Topic & Scope
- Expose streaming/timeline, evidence, and attestation APIs with OpenAPI discovery and examples, keeping aggregation-only semantics.
- Add bundle import telemetry for air-gapped mirrors and introduce crypto provider abstraction for deterministic verification.
- **Working directory:** `src/Excititor` (WebService); coordinate with Evidence Locker/AirGap/Policy for bundle import signals.
## Dependencies & Concurrency
- Upstream: Timeline events/attestations from Phase IV; portable bundle work from Phase V; OpenAPI governance guidelines; crypto provider registry design.
- Concurrency: OpenAPI discovery/examples can progress in parallel with streaming APIs; bundle import telemetry depends on mirror schema and sealed-mode rules.
- Peers: API Governance, Evidence Locker, AirGap importer/policy, Security guild for crypto providers.
## Wave Coordination
- **Wave A (streaming/OpenAPI):** Tasks 1,4,5 DONE; keep discovery/errors stable for downstream clients.
- **Wave B (evidence/attestation + airgap telemetry):** Tasks 2 and 6 DONE; task 3 remains BLOCKED awaiting DSSE locker manifests; keep remediation/timeline schema frozen.
- **Wave C (crypto providers):** Task 7 BLOCKED pending `ICryptoProviderRegistry` contract from Security guild; run after Wave B completes.
- Only tasks 3 and 7 remain open; avoid parallel starts until contracts land.
## Documentation Prerequisites
- `docs/modules/excititor/architecture.md`
- `docs/modules/excititor/README.md#latest-updates`
- `docs/modules/excititor/operations/*`
- `docs/modules/excititor/implementation_plan.md`
- Excititor component `AGENTS.md` files (WebService).
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EXCITITOR-WEB-OBS-52-001 | DONE (2025-11-24) | `/obs/excititor/timeline` SSE endpoint implemented with cursor/Last-Event-ID, retry headers, tenant scope enforcement. | Excititor WebService Guild | SSE/WebSocket bridges for VEX timeline events with tenant filters, pagination anchors, guardrails. |
| 2 | EXCITITOR-WEB-OBS-53-001 | DONE (2025-12-02) | Locker manifest published at `docs/modules/excititor/observability/locker-manifest.md`; wire endpoints to consume locker bundle API. | Excititor WebService · Evidence Locker Guild | `/evidence/vex/*` endpoints fetching locker bundles, enforcing scopes, surfacing verification metadata; no verdicts. |
| 3 | EXCITITOR-WEB-OBS-54-001 | TODO | Unblocked by [CONTRACT-VERIFICATION-POLICY-006](../contracts/verification-policy.md); DSSE verification now available. | Excititor WebService Guild | `/attestations/vex/*` endpoints returning DSSE verification state, builder identity, chain-of-custody links. |
| 4 | EXCITITOR-WEB-OAS-61-001 | DONE (2025-11-24) | `/.well-known/openapi` + `/openapi/excititor.json` implemented with spec metadata and standard error envelope. | Excititor WebService Guild | Implement `/.well-known/openapi` with spec version metadata + standard error envelopes; update controller/unit tests. |
| 5 | EXCITITOR-WEB-OAS-62-001 | DONE (2025-11-24) | Examples + deprecation/link headers added to OpenAPI doc; SDK docs pending separate publishing sprint. | Excititor WebService Guild · API Governance Guild | Publish curated examples for new evidence/attestation/timeline endpoints; emit deprecation headers for legacy routes; align SDK docs. |
| 6 | EXCITITOR-WEB-AIRGAP-58-001 | DONE (2025-12-03) | Mirror thin bundle schema + policies available (see `docs/modules/mirror/dsse-tuf-profile.md`, `out/mirror/thin/mirror-thin-v1.bundle.json`). | Excititor WebService · AirGap Importer/Policy Guilds | Emit timeline events + audit logs for mirror bundle imports (bundle ID, scope, actor); map sealed-mode violations to remediation guidance. |
| 7 | EXCITITOR-CRYPTO-90-001 | TODO | Unblocked by [CONTRACT-CRYPTO-PROVIDER-REGISTRY-010](../contracts/crypto-provider-registry.md); contract available. | Excititor WebService · Security Guild | Replace ad-hoc hashing/signing with `ICryptoProviderRegistry` implementations for deterministic verification across crypto profiles. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-03 | Added Wave Coordination (A streaming/OpenAPI done; B evidence/airgap partly done, attestation blocked; C crypto registry blocked). No status changes. | Project Mgmt |
| 2025-12-03 | Normalised sprint structure; action tracker moved to dedicated section; no task status changes. | Planning |
| 2025-11-16 | Normalized sprint file to standard template and renamed to SPRINT_0119_0001_0006_excititor_vi.md; pending execution. | Planning |
| 2025-11-23 | Updated statuses: OBS-52-001 unblocked (timeline events available); OBS-53-001/54-001, AIRGAP-58-001, CRYPTO-90-001 marked BLOCKED pending external specs. | Project Mgmt |
| 2025-11-24 | Added OpenAPI discovery endpoints (`/.well-known/openapi`, `/openapi/excititor.json`) with standard error envelope schema; EXCITITOR-WEB-OAS-61-001 marked DONE. | Implementer |
| 2025-11-24 | Enriched `/openapi/excititor.json` with concrete paths (status, health, timeline SSE, airgap import) plus response/examples and deprecation/link headers on timeline SSE; EXCITITOR-WEB-OAS-62-001 remains DOING pending legacy route deprecation headers + SDK docs. | Implementer |
| 2025-11-24 | Added response examples (status/health), error examples (timeline 400, airgap 400/403), and documented deprecation/link headers in OpenAPI spec; marked EXCITITOR-WEB-OAS-62-001 DONE. SDK doc publish tracked separately. | Implementer |
| 2025-11-24 | Implemented `/obs/excititor/timeline` SSE endpoint (cursor + Last-Event-ID, retry header, tenant guard). Marked EXCITITOR-WEB-OBS-52-001 DONE and streaming action tracker item done. | Implementer |
| 2025-11-25 | Work paused: build/CI commands blocked (`No space left on device`); further coding waits on workspace cleanup. | Implementer |
| 2025-11-25 | Marked action tracker items for evidence/attestation APIs, bundle telemetry, and crypto providers as BLOCKED to mirror Delivery Tracker; upstream Evidence Locker bundle schema and crypto registry spec still missing. | Implementer |
| 2025-12-02 | Unblocked WEB-OBS-53-001 using locker manifest (`docs/modules/excititor/observability/locker-manifest.md`) and started WEB-AIRGAP-58-001 leveraging mirror thin bundle meta (`out/mirror/thin/mirror-thin-v1.bundle.json`); statuses moved to DOING. | Project Mgmt |
| 2025-12-02 | Added `/evidence/vex/locker/{bundleId}` endpoint (tenant-scoped, scope=vex.read) exposing portable manifest hash/path, evidence path, and timeline from airgap imports; keeps attestation path blocked pending DSSE locker manifests. | Implementer |
| 2025-12-02 | Added locker hash computation using optional `Excititor:Airgap:LockerRootPath` and regression test `EvidenceLockerEndpointTests`; WEB-OBS-53-001 evidence path now returns manifest/evidence hashes and sizes when files present. | Implementer |
| 2025-12-02 | Enabled TestAuth in locker endpoint tests and quoted ETag headers for locker files; `dotnet test ... --filter EvidenceLockerEndpointTests` now passes (2/2). Marked EXCITITOR-WEB-OBS-53-001 DONE. | Implementer |
| 2025-12-03 | Airgap import endpoint now requires `vex.admin` scope, captures actor/scopes into timeline and records, emits remediation text for sealed-mode violations, and extends mirror timeline output with actor/scopes/remediation; added regression tests for actor/scopes and remediation. Marked EXCITITOR-WEB-AIRGAP-58-001 DONE. | Implementer |
## Decisions & Risks
- **Decisions**
- All streaming/evidence/attestation endpoints remain aggregation-only; no derived verdicts.
- OpenAPI discovery must include version metadata and error envelope standardization.
- Airgap import now enforces `vex.admin` scope and records actor/scope on timeline entries; sealed-mode failures return remediation guidance for auditability.
- **Risks & Mitigations**
- Mirror bundle schema delays could block bundle telemetry → leverage placeholder manifest with TODOs and log-only fallback.
- Crypto provider abstraction may impact performance → benchmark providers; default to current provider with feature flag.
- Evidence Locker manifest (OBS-53-001) now available; proceed with `/evidence/vex/*` using sealed manifests while attestation path stays blocked pending DSSE (OBS-54-001).
- Mirror thin bundle meta published (Sprint 0125); WEB-AIRGAP-58-001 can hook into bundle import audit signals using recorded hashes.
## Next Checkpoints
| Date (UTC) | Session / Owner | Goal | Fallback |
| --- | --- | --- | --- |
| 2025-11-20 | Streaming API review | Approve SSE/WebSocket contract + guardrails. | Keep behind feature flag if concerns arise. |
| 2025-11-21 | OpenAPI discovery review | Validate well-known endpoint + examples. | Provide static spec download if discovery slips. |
| 2025-11-23 | Bundle telemetry sync | Align audit/deprecation headers + sealed-mode mappings. | Log-only until schema finalized. |
| 2025-11-24 | Crypto provider design review | Freeze `ICryptoProviderRegistry` contract. | Retain current crypto implementation until migration ready. |
## Action Tracker (carried over)
| Focus | Action | Owner(s) | Due | Status |
| --- | --- | --- | --- | --- |
| Streaming APIs | Finalize SSE/WebSocket contract + guardrails (WEB-OBS-52-001). | WebService Guild | 2025-11-20 | DONE (2025-11-24) |
| Evidence/Attestation APIs | Wire `/evidence/vex/*` (WEB-OBS-53-001) using locker manifest; attestation path waits on DSSE manifest (OBS-54-001). | WebService · Evidence Locker Guild | 2025-11-22 | DOING / PARTIAL |
| OpenAPI discovery | Implement well-known discovery + examples (WEB-OAS-61/62). | WebService · API Gov | 2025-11-21 | DONE (61-001, 62-001 delivered 2025-11-24) |
| Bundle telemetry | Define audit event + sealed-mode remediation mapping (WEB-AIRGAP-58-001). | WebService · AirGap Guilds | 2025-11-23 | DOING |
| Crypto providers | Design `ICryptoProviderRegistry` and migrate call sites (CRYPTO-90-001). | WebService · Security Guild | 2025-11-24 | TODO (unblocked 2025-12-05 by contracts) |

93
docs/implplan/SPRINT_0120_0001_0002_excititor_ii.md Normal file
View File

@@ -0,0 +1,93 @@
# Sprint 0120 - Excititor Ingestion & Evidence (Phase II)
## Topic & Scope
- Continue Excititor ingestion hardening: Link-Not-Merge (observations/linksets), connector provenance, graph/query endpoints, and Console/Vuln Explorer integration.
- Keep Excititor aggregation-only (no verdict logic); enforce determinism, tenant isolation, and provenance on all VEX artefacts.
- **Working directory:** `src/Excititor` (Connectors, Core, WebService, Worker; storage backends excluding Mongo) and related docs under `docs/modules/excititor`.
## Dependencies & Concurrency
- Upstream schemas: Link-Not-Merge (ATLN), provenance/DSSE schemas, graph overlay contracts, orchestrator SDK.
- Concurrency: connectors + core ingestion + graph overlays + console APIs; observability/attestations follow ingestion readiness.
- Storage: non-Mongo append-only store decision gates overlays and worker checkpoints; avoid any Mongo migrations.
## Documentation Prerequisites
- `docs/modules/excititor/architecture.md`
- `docs/modules/excititor/implementation_plan.md`
- `docs/modules/excititor/AGENTS.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | EXCITITOR-CONSOLE-23-001/002/003 | DONE (2025-11-23) | Dependent APIs live | Excititor Guild + Docs Guild | Console VEX endpoints (grouped statements, counts, search) with provenance + RBAC; metrics for policy explain. |
| 2 | EXCITITOR-CONN-SUSE-01-003 | **DONE** (2025-12-07) | Integrated ConnectorSignerMetadataEnricher in provenance | Connector Guild (SUSE) | Emit trust config (signer fingerprints, trust tier) in provenance; aggregation-only. |
| 3 | EXCITITOR-CONN-UBUNTU-01-003 | **DONE** (2025-12-07) | Verified enricher integration, fixed Logger reference | Connector Guild (Ubuntu) | Emit Ubuntu signing metadata in provenance; aggregation-only. |
| 4 | EXCITITOR-CORE-AOC-19-002/003/004/013 | **DONE** (2025-12-07) | Implemented append-only linkset contracts and deprecated consensus | Excititor Core Guild | Deterministic advisory/PURL extraction, append-only linksets, remove consensus logic, seed Authority tenants in tests. |
| 5 | EXCITITOR-STORAGE-00-001 | **DONE** (2025-12-08) | Append-only Postgres backend delivered; Storage.Mongo references to be removed in follow-on cleanup | Excititor Core + Platform Data Guild | Select and ratify storage backend (e.g., SQL/append-only) for observations, linksets, and worker checkpoints; produce migration plan + deterministic test harnesses without Mongo. |
| 6 | EXCITITOR-GRAPH-21-001..005 | TODO/BLOCKED | EXCITITOR-STORAGE-00-001 + Link-Not-Merge schema + overlay contract | Excititor Core + UI Guild | Batched VEX fetches, overlay metadata, indexes/materialized views for graph inspector on the non-Mongo store. |
| 7 | EXCITITOR-OBS-52/53/54 | TODO/BLOCKED | Evidence Locker DSSE + provenance schema | Excititor Core + Evidence Locker + Provenance Guilds | Timeline events + Merkle locker payloads + DSSE attestations for evidence batches. |
| 8 | EXCITITOR-ORCH-32/33 | PARTIAL (2025-12-06) | EXCITITOR-STORAGE-00-001 for checkpoints + orchestrator SDK | Excititor Worker Guild | Adopt orchestrator worker SDK; honor pause/throttle/retry with deterministic checkpoints on the selected non-Mongo store. |
| 9 | EXCITITOR-POLICY-20-001/002 | TODO | EXCITITOR-AOC-20-004; graph overlays | WebService + Core Guilds | VEX lookup APIs for Policy (tenant filters, scope resolution) and enriched linksets (scope/version metadata). |
| 10 | EXCITITOR-RISK-66-001 | TODO | EXCITITOR-POLICY-20-002 | Core + Risk Engine Guild | Risk-ready feeds (status/justification/provenance) with zero derived severity. |
## Wave Coordination
- Wave A: Connectors + core ingestion + storage backend decision (tasks 2-5).
- Wave B: Graph overlays + Console/Policy/Risk APIs (tasks 1,6,9,10) — Console endpoints delivered; overlays pending.
- Wave C: Observability/attestations + orchestrator integration (tasks 7-8) after Wave A artifacts land.
## Wave Detail Snapshots
- Not started; capture once ATLN/provenance schemas freeze.
## Interlocks
- Link-Not-Merge and provenance schema freezes gate tasks 2-7.
- Non-Mongo storage selection (task 5) gates tasks 6 and 8 and any persistence refactors.
- Orchestrator SDK availability gates task 8.
- Use `BLOCKED_DEPENDENCY_TREE.md` to record blockers.
## Action Tracker
| Action | Due (UTC) | Owner(s) | Notes |
| --- | --- | --- | --- |
| Pick non-Mongo append-only store and publish contract update | 2025-12-10 | Excititor Core + Platform Data Guild | DONE 2025-12-08: Postgres append-only linkset store + migration/tests landed; follow-up removal of Storage.Mongo code paths. |
| Capture ATLN schema freeze + provenance hashes; update tasks 2-7 statuses | 2025-12-12 | Excititor Core + Docs Guild | Required to unblock ingestion/locker/graph work. |
| Confirm orchestrator SDK version for Excititor worker adoption | 2025-12-12 | Excititor Worker Guild | Needed before task 8 starts. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-09 | Purged remaining Mongo session handles from Excititor connector/web/export/worker tests; stubs now align to Postgres/in-memory contracts. | Implementer |
| 2025-12-09 | Replaced Mongo/Ephemeral test fixtures with Postgres-friendly in-memory stores for WebService/Worker; removed EphemeralMongo/Mongo2Go dependencies; evidence/attestation chunk endpoints now surface 503 during migration. | Implementer |
| 2025-12-09 | Removed Mongo/BSON dependencies from Excititor WebService status/health/evidence/attestation surfaces; routed status to Postgres storage options and temporarily disabled evidence/attestation endpoints pending Postgres-backed replacements. | Implementer |
| 2025-12-09 | Deleted legacy Storage.Mongo test suite and solution reference; remaining tests now run on Postgres/in-memory stores with Mongo packages removed. | Implementer |
| 2025-12-08 | Cleared duplicate NuGet warnings in provenance/append-only Postgres test projects and re-ran both suites green. | Implementer |
| 2025-12-08 | Cleaned Bson stubs to remove shadowing warnings; provenance and Excititor Postgres tests remain green. | Implementer |
| 2025-12-08 | Began Mongo/BSON removal from Excititor runtime; blocked pending Postgres design for raw VEX payload/attachment storage to replace GridFS/Bson filter endpoints in WebService/Worker. | Implementer |
| 2025-12-08 | Provenance stubs now Bson-driver-free; Events.Mongo tests updated to use stubs. Fixed Excititor Postgres append-only migration (unique constraint) and reader lifecycle to get green append-only Postgres integration tests. | Implementer |
| 2025-12-08 | Dropped MongoDB.Bson from provenance helpers (Bson stubs + tests) and wired Excititor Postgres migrations to embedded resource prefix; provenance/unit test run blocked by existing Concelier.Storage.Postgres compile errors when restoring shared dependencies. | Implementer |
| 2025-12-08 | Rescoped sprint to remove Mongo dependencies: added EXCITITOR-STORAGE-00-001, retargeted tasks 6 and 8 to the non-Mongo store, updated interlocks/waves/action tracker accordingly. | Project Mgmt |
| 2025-12-08 | Began EXCITITOR-STORAGE-00-001: catalogued existing PostgreSQL stack (Infrastructure.Postgres, Excititor.Storage.Postgres data source/repositories/migrations, Concelier/Authority/Notify precedents). Need to adapt schema/contracts to append-only linksets and drop consensus-derived tables. | Project Mgmt |
| 2025-12-08 | Completed EXCITITOR-STORAGE-00-001: added append-only Postgres linkset store implementing `IAppendOnlyLinksetStore`, rewrote migration to remove consensus/Mongo artifacts, registered DI, and added deterministic Postgres integration tests for append/dedup/disagreements. | Implementer |
| 2025-12-08 | Postgres append-only linkset tests added; initial run fails due to upstream Concelier MongoCompat type resolution (`MongoStorageOptions` missing). Needs follow-up dependency fix before green test run. | Implementer |
| 2025-12-07 | **EXCITITOR-CORE-AOC-19 DONE:** Implemented append-only linkset infrastructure: (1) Created `IAppendOnlyLinksetStore` interface with append-only semantics for observations and disagreements, plus mutation log for audit/replay (AOC-19-002); (2) Marked `VexConsensusResolver`, `VexConsensus`, `IVexConsensusPolicy`, `BaselineVexConsensusPolicy`, and related types as `[Obsolete]` with EXCITITOR001 diagnostic ID per AOC-19-003; (3) Created `AuthorityTenantSeeder` utility with test tenant fixtures (default, multi-tenant, airgap) and SQL generation for AOC-19-004; (4) Created `AppendOnlyLinksetExtractionService` replacing consensus-based extraction with deterministic append-only operations per AOC-19-013; (5) Added comprehensive unit tests for both new services with in-memory store implementation. | Implementer |
| 2025-12-07 | **EXCITITOR-CONN-SUSE-01-003 & EXCITITOR-CONN-UBUNTU-01-003 DONE:** Integrated `ConnectorSignerMetadataEnricher.Enrich()` into both connectors' `AddProvenanceMetadata()` methods. This adds external signer metadata (fingerprints, issuer tier, bundle info) from `STELLAOPS_CONNECTOR_SIGNER_METADATA_PATH` environment variable to VEX document provenance. Fixed Ubuntu connector's `_logger` and `Logger` reference bug. | Implementer |
| 2025-12-05 | Reconstituted sprint from `tasks-all.md`; prior redirect pointed to non-existent canonical. Added template and delivery tracker; tasks set per backlog. | Project Mgmt |
| 2025-11-23 | Console VEX endpoints (tasks 1) delivered. | Excititor Guild |
## Decisions & Risks
| Item | Type | Owner(s) | Due | Notes |
| --- | --- | --- | --- | --- |
| Schema freeze (ATLN/provenance) pending | Risk | Excititor Core + Docs Guild | 2025-12-12 | Blocks tasks 2-7. |
| Non-Mongo storage backend selection | Decision | Excititor Core + Platform Data Guild | 2025-12-08 | Resolved: adopt Postgres append-only store (IAppendOnlyLinksetStore) for observations/linksets/checkpoints; unblock tasks 6 and 8; remove Storage.Mongo artifacts next. |
| Orchestrator SDK version selection | Decision | Excititor Worker Guild | 2025-12-12 | Needed for task 8. |
| Excititor.Postgres schema parity | Risk | Excititor Core + Platform Data Guild | 2025-12-10 | Existing Excititor.Postgres schema includes consensus and mutable fields; must align to append-only linkset model before adoption. |
| Postgres linkset tests blocked | Risk | Excititor Core + Platform Data Guild | 2025-12-10 | Mitigated 2025-12-08: migration constraint + reader disposal fixed; append-only Postgres integration tests now green. |
| Evidence/attestation endpoints paused | Risk | Excititor Core | 2025-12-12 | Evidence and attestation list/detail endpoints return 503 while Mongo/BSON paths are removed; needs Postgres-backed replacement before release. |
## Next Checkpoints
| Date (UTC) | Session | Goal | Owner(s) |
| --- | --- | --- | --- |
| 2025-12-10 | Storage backend decision | Finalize non-Mongo append-only store for Excititor persistence; unblock tasks 5/6/8. | Excititor Core + Platform Data |
| 2025-12-12 | Schema freeze sync | Confirm ATLN/provenance freeze; unblock tasks 2-7. | Excititor Core |
| 2025-12-12 | Orchestrator SDK alignment | Pick SDK version and start task 8. | Excititor Worker |

34
docs/implplan/SPRINT_0121_0001_0002_policy_reasoning_blockers.md
View File

@@ -25,23 +25,37 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | LEDGER-ATTEST-73-002 | BLOCKED | Waiting on LEDGER-ATTEST-73-001 verification pipeline delivery | Findings Ledger Guild / `src/Findings/StellaOps.Findings.Ledger` | Enable search/filter in findings projections by verification result and attestation status |
| 2 | LEDGER-OAS-61-001-DEV | BLOCKED | PREP-LEDGER-OAS-61-001-ABSENT-OAS-BASELINE-AN | Findings Ledger Guild; API Contracts Guild / `src/Findings/StellaOps.Findings.Ledger` | Expand Findings Ledger OAS to include projections, evidence lookups, and filter parameters with examples |
| 3 | LEDGER-OAS-61-002-DEV | BLOCKED | PREP-LEDGER-OAS-61-002-DEPENDS-ON-61-001-CONT | Findings Ledger Guild / `src/Findings/StellaOps.Findings.Ledger` | Implement `/.well-known/openapi` endpoint and ensure version metadata matches release |
| 4 | LEDGER-OAS-62-001-DEV | BLOCKED | PREP-LEDGER-OAS-62-001-SDK-GENERATION-PENDING | Findings Ledger Guild; SDK Generator Guild / `src/Findings/StellaOps.Findings.Ledger` | Provide SDK test cases for findings pagination, filtering, evidence links; ensure typed models expose provenance |
| 5 | LEDGER-OAS-63-001-DEV | BLOCKED | PREP-LEDGER-OAS-63-001-DEPENDENT-ON-SDK-VALID | Findings Ledger Guild; API Governance Guild / `src/Findings/StellaOps.Findings.Ledger` | Support deprecation headers and Notifications for retiring finding endpoints |
| 6 | LEDGER-OBS-55-001 | BLOCKED | PREP-LEDGER-OBS-55-001-DEPENDS-ON-54-001-ATTE | Findings Ledger Guild; DevOps Guild / `src/Findings/StellaOps.Findings.Ledger` | Enhance incident mode to record replay diagnostics (lag traces, conflict snapshots), extend retention while active, and emit activation events to timeline/notifier |
| 7 | LEDGER-PACKS-42-001-DEV | BLOCKED | PREP-LEDGER-PACKS-42-001-SNAPSHOT-TIME-TRAVEL | Findings Ledger Guild / `src/Findings/StellaOps.Findings.Ledger` | Provide snapshot/time-travel APIs and digestible exports for task pack simulation and CLI offline mode |
| 1 | LEDGER-ATTEST-73-002 | **DONE** (2025-12-08) | Verification-result and attestation-status filters implemented in findings projections, exports, and tests | Findings Ledger Guild / `src/Findings/StellaOps.Findings.Ledger` | Enable search/filter in findings projections by verification result and attestation status |
| 2 | LEDGER-OAS-61-001-DEV | **DONE** (2025-12-07) | Expanded OAS with attestation pointer endpoints, schemas, and examples | Findings Ledger Guild; API Contracts Guild / `src/Findings/StellaOps.Findings.Ledger` | Expand Findings Ledger OAS to include projections, evidence lookups, and filter parameters with examples |
| 3 | LEDGER-OAS-61-002-DEV | **DONE** (2025-12-08) | `/.well-known/openapi` implemented with version/build headers, ETag, and cache hints | Findings Ledger Guild / `src/Findings/StellaOps.Findings.Ledger` | Implement `/.well-known/openapi` endpoint and ensure version metadata matches release |
| 4 | LEDGER-OAS-62-001-DEV | **DONE** (2025-12-08) | SDK surface validated via OpenAPI assertions for pagination, evidence links, provenance | Findings Ledger Guild; SDK Generator Guild / `src/Findings/StellaOps.Findings.Ledger` | Provide SDK test cases for findings pagination, filtering, evidence links; ensure typed models expose provenance |
| 5 | LEDGER-OAS-63-001-DEV | **DONE** (2025-12-08) | Deprecation headers + link notifications applied to legacy findings export endpoint | Findings Ledger Guild; API Governance Guild / `src/Findings/StellaOps.Findings.Ledger` | Support deprecation headers and Notifications for retiring finding endpoints |
| 6 | LEDGER-OBS-55-001 | **DONE** (2025-12-08) | OBS-54-001 attestation surface delivered; implement incident diagnostics + retention extensions | Findings Ledger Guild; DevOps Guild / `src/Findings/StellaOps.Findings.Ledger` | Enhance incident mode to record replay diagnostics (lag traces, conflict snapshots), extend retention while active, and emit activation events to timeline/notifier |
| 7 | LEDGER-PACKS-42-001-DEV | **DONE** (2025-12-07) | Implemented snapshot/time-travel APIs with full endpoint coverage | Findings Ledger Guild / `src/Findings/StellaOps.Findings.Ledger` | Provide snapshot/time-travel APIs and digestible exports for task pack simulation and CLI offline mode |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-08 | **LEDGER-OBS-55-001 DONE:** Added incident-mode coordinator/diagnostics (lag traces, conflict snapshots, replay traces), snapshot retention extension with incident metadata, timeline/notifier hooks; ran `dotnet test src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/StellaOps.Findings.Ledger.Tests.csproj -m:1 --no-build`. | Implementer |
| 2025-12-08 | **LEDGER-OAS-63-001 DONE:** Added standardized deprecation/notification headers (Deprecation/Sunset/Link/X-Deprecated-Endpoint) to legacy findings export endpoint; covered with unit test. | Implementer |
| 2025-12-08 | **LEDGER-OAS-62-001 DONE:** Added SDK-facing OpenAPI assertions for pagination (page_token/nextPageToken), evidence/provenance links (evidenceBundleRef, ExportProvenance), and attestation surface. Tests via `OpenApiSdkSurfaceTests`. | Implementer |
| 2025-12-08 | **LEDGER-OAS-61-002 DONE:** Implemented `/.well-known/openapi` endpoint returning ledger OAS with `X-Api-Version`, `X-Build-Version`, `ETag`, `Last-Modified`, and cache-control headers; 304 served on matching `If-None-Match`. Added OpenApiMetadataFactory helper with unit tests and wired endpoint to spec file. | Implementer |
| 2025-12-08 | **LEDGER-ATTEST-73-002 DONE:** Added attestation-summary filters to findings projection queries (verification result + overall status), surfaced attestation metadata in scored finding exports, introduced attestation status calculator, and covered with unit tests. Ran `dotnet test src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/StellaOps.Findings.Ledger.Tests.csproj -m:1`. | Implementer |
| 2025-12-08 | LEDGER-OBS-55-001 moved to DOING; starting incident-mode diagnostics/retention integration now that upstream OBS-54-001 landed. | Implementer |
| 2025-12-08 | Upstream blockers cleared (LEDGER-ATTEST-73-001 delivered; PREP-LEDGER-OAS-61/62/63 DONE; LEDGER-OBS-54-001 shipped). Moved LEDGER-ATTEST-73-002 to DOING; set LEDGER-OAS-61-002/62-001/63-001 and LEDGER-OBS-55-001 to TODO. | Project Mgmt |
| 2025-12-07 | **LEDGER-PACKS-42-001-DEV DONE:** Implemented full snapshot/time-travel API infrastructure: (1) Domain models in SnapshotModels.cs (LedgerSnapshot, QueryPoint, TimeQueryFilters, ReplayRequest, DiffRequest, ChangeLogEntry, StalenessResult, etc.); (2) Repository interfaces ISnapshotRepository and ITimeTravelRepository; (3) PostgreSQL implementations PostgresSnapshotRepository and PostgresTimeTravelRepository; (4) SnapshotService orchestrating all time-travel operations; (5) WebService contracts in SnapshotContracts.cs; (6) 13 new API endpoints (/v1/ledger/snapshots CRUD, /v1/ledger/time-travel/{findings,vex,advisories}, /v1/ledger/replay, /v1/ledger/diff, /v1/ledger/changelog, /v1/ledger/staleness, /v1/ledger/current-point); (7) Database migration 009_snapshots.sql; (8) Unit tests in SnapshotServiceTests.cs with in-memory repository mocks. | Implementer |
| 2025-12-07 | **LEDGER-OAS-61-001-DEV DONE:** Expanded `docs/schemas/findings-ledger-api.openapi.yaml` with attestation pointer endpoints (/attestation-pointers, /findings/{findingId}/attestation-pointers, /findings/{findingId}/attestation-summary), comprehensive schemas (AttestationPointer, AttestationRefDetail, SignerInfo, RekorEntryRef, VerificationResult, VerificationCheck, AttestationSummary), and request/response examples for search, create, and update operations. | Implementer |
| 2025-12-06 | **Wave A/C Partial Unblock:** LEDGER-OAS-61-001-DEV and LEDGER-PACKS-42-001-DEV changed from BLOCKED to TODO. Root blockers resolved: OAS baseline at `docs/schemas/findings-ledger-api.openapi.yaml`, time-travel API at `docs/schemas/ledger-time-travel-api.openapi.yaml`. | Implementer |
| 2025-12-03 | Added Wave Coordination outlining contract/incident/pack waves; statuses unchanged (all remain BLOCKED). | Project Mgmt |
| 2025-11-25 | Carried forward all BLOCKED Findings Ledger items from Sprint 0121-0001-0001; no status changes until upstream contracts land. | Project Mgmt |
## Decisions & Risks
- All tasks remain blocked pending upstream OAS/verification/incident-mode contracts; do not start until dependencies are confirmed green.
- Keep risk of contract drift tracked against `docs/modules/findings-ledger/prep/*` artefacts; refresh prior to unblocking.
- Blockers cleared: LEDGER-ATTEST-73-001 delivered (2025-12-07); OAS prep (61/62/63) and incident-mode prep (OBS-54-001) available, so Wave A/B tasks are active.
- Monitor contract drift vs `docs/modules/findings-ledger/prep/*`, `docs/schemas/findings-ledger-api.openapi.yaml`, and `docs/schemas/attestation-pointer.schema.json` before opening PRs; re-sync if upstream artefacts change.
- Attestation filters depend on counts aggregated from `ledger_attestation_pointers`; any schema/index changes there must be reflected in projection queries to keep verification-status filtering deterministic.
- `/.well-known/openapi` now serves the published spec with version/build metadata, ETag, and cache headers; any spec version bump must update `OpenApiMetadataFactory.ApiVersion` to keep headers aligned.
- Deprecation headers are issued on `/ledger/export/findings`; keep Link target (`/.well-known/openapi`) updated if replacement endpoints change, and align `Sunset` once retirement date is finalized.
- Incident mode now records ledger-specific diagnostics (lag traces, conflict snapshots, replay traces), emits `ledger.incident.*` timeline logs, and extends snapshot retention by the configured incident extension days; keep ops config aligned with runbook expectations.
## Next Checkpoints
- Schedule unblock review after LEDGER-ATTEST-73-001 pipeline publishes verification results (date TBD).
- Progress review on 2025-12-10 to confirm LEDGER-ATTEST-73-002 DOING progress and OAS/OBS task kickoff readiness.

91
docs/implplan/SPRINT_0123_0001_0001_policy_reasoning.md
View File

@@ -1,91 +0,0 @@
# Sprint 0123-0001-0001 · Policy & Reasoning (Policy Engine)
## Topic & Scope
- Extend Policy Engine with export, air-gap, AOC linting, and attestation surfaces while keeping evidence aggregation-only.
- Ensure Console export and air-gap bundles depend on frozen bundle/DSSE schemas before implementation.
- Align policy attestation and linting with Authority/Attestor/Console contracts; avoid inferred verdicts.
- **Working directory:** `src/Policy/StellaOps.Policy.Engine` (and `src/Policy/__Libraries/StellaOps.Policy`).
## Dependencies & Concurrency
- Upstream: Export bundle schema + scheduler job spec; mirror bundle/air-gap schema and sealed-mode rules; Attestor verification policy schema; Authority `effective:write` contract; Console API filters/pagination spec.
- Concurrency: Execute tasks in table order (DOING → TODO → BLOCKED). All tasks currently blocked pending upstream contracts; no parallel execution until contracts land.
## Wave Coordination
- **Wave A (prep + Console contract):** P1–P15 DONE, including POLICY-CONSOLE-23-001 contract; keep prep docs stable.
- **Wave B (Console export job):** Task 1 BLOCKED awaiting export bundle schema + scheduler job spec.
- **Wave C (air-gap chain):** Tasks 2–6 BLOCKED on mirror/sealed-mode/staleness schemas; runs after Wave B when bundle schema freezes.
- **Wave D (AOC linting):** Tasks 7–10 BLOCKED on analyzer targets and Authority gate contract.
- **Wave E (attestation):** Tasks 11–14 BLOCKED on Attestor verification policy + Console report schema.
- No work in progress; do not start any wave until dependencies land.
## Documentation Prerequisites
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/policy/architecture.md`
- Any export/air-gap/attestation contract docs once published.
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| P1 | PREP-EXPORT-CONSOLE-23-001-MISSING-EXPORT-BUN | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · Scheduler Guild · Observability Guild | Policy Guild · Scheduler Guild · Observability Guild | Missing export bundle contract/API surface and scheduler job spec for Console. <br><br> Prep artefact: `docs/modules/policy/design/export-console-bundle-contract.md`. |
| P2 | PREP-POLICY-AIRGAP-56-001-MIRROR-BUNDLE-SCHEM | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild | Policy Guild | Mirror bundle schema not published; requires bundle_id/provenance fields + sealed-mode rules. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`. |
| P3 | PREP-POLICY-AIRGAP-56-002-DEPENDS-ON-56-001-B | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · Policy Studio Guild | Policy Guild · Policy Studio Guild | Depends on 56-001 bundle import schema + DSSE signing profile. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`. |
| P4 | PREP-POLICY-AIRGAP-57-001-REQUIRES-SEALED-MOD | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · AirGap Policy Guild | Policy Guild · AirGap Policy Guild | Requires sealed-mode contract after 56-002. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`. |
| P5 | PREP-POLICY-AIRGAP-57-002-NEEDS-STALENESS-FAL | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · AirGap Time Guild | Policy Guild · AirGap Time Guild | Needs staleness/fallback data contract from 57-001. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`. |
| P6 | PREP-POLICY-AIRGAP-58-001-NOTIFICATION-SCHEMA | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · Notifications Guild | Policy Guild · Notifications Guild | Notification schema and staleness signals pending from 57-002. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`. |
| P7 | PREP-POLICY-AOC-19-001-LINTING-TARGETS-SPEC-A | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild | Policy Guild | Linting targets/spec absent; no analyzer contract. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-aoc-prep.md`. |
| P8 | PREP-POLICY-AOC-19-002-DEPENDS-ON-19-001-LINT | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · Platform Security | Policy Guild · Platform Security | Depends on 19-001 lint + Authority `effective:write` contract. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-aoc-prep.md`. |
| P9 | PREP-POLICY-AOC-19-003-REQUIRES-POST-19-002-N | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild | Policy Guild | Requires post-19-002 normalized-field removal contract/fixtures. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-aoc-prep.md`. |
| P10 | PREP-POLICY-AOC-19-004-DEPENDS-ON-19-003-SHAP | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · QA Guild | Policy Guild · QA Guild | Depends on 19-003 shape + determinism fixtures. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-aoc-prep.md`. |
| P11 | PREP-POLICY-ATTEST-73-001-VERIFICATIONPOLICY | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · Attestor Service Guild | Policy Guild · Attestor Service Guild | VerificationPolicy schema/persistence contract missing; Attestor alignment needed. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-attest-prep.md`. |
| P12 | PREP-POLICY-ATTEST-73-002-DEPENDS-ON-73-001-E | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild | Policy Guild | Depends on 73-001 editor DTOs/validation schema. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-attest-prep.md`. |
| P13 | PREP-POLICY-ATTEST-74-001-REQUIRES-73-002-ATT | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · Attestor Service Guild | Policy Guild · Attestor Service Guild | Requires 73-002 + Attestor pipeline contract. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-attest-prep.md`. |
| P14 | PREP-POLICY-ATTEST-74-002-NEEDS-74-001-SURFAC | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · Console Guild | Policy Guild · Console Guild | Needs 74-001 surfaced in Console verification reports contract. <br><br> Prep artefact: `docs/modules/policy/prep/2025-11-20-policy-attest-prep.md`. |
| P15 | PREP-POLICY-CONSOLE-23-001-CONSOLE-API-CONTRA | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Policy Guild · BE-Base Platform Guild | Policy Guild · BE-Base Platform Guild | Console API contract (filters/pagination/aggregation) absent. <br><br> Document artefact/deliverable for POLICY-CONSOLE-23-001 and publish location so downstream tasks can proceed. |
| 1 | EXPORT-CONSOLE-23-001 | TODO | Unblocked by [CONTRACT-EXPORT-BUNDLE-009](../contracts/export-bundle.md); schema available. | Policy Guild · Scheduler Guild · Observability Guild | Implement Console export endpoints/jobs once schema + job wiring are defined. |
| 2 | POLICY-AIRGAP-56-001 | TODO | Unblocked by [CONTRACT-MIRROR-BUNDLE-003](../contracts/mirror-bundle.md); schema available. | Policy Guild | Air-gap bundle import support for policy packs. |
| 3 | POLICY-AIRGAP-56-002 | TODO | Unblocked; can proceed after 56-001. | Policy Guild · Policy Studio Guild | Air-gap sealed-mode handling for policy packs. |
| 4 | POLICY-AIRGAP-57-001 | TODO | Unblocked by [CONTRACT-SEALED-MODE-004](../contracts/sealed-mode.md); can proceed after 56-002. | Policy Guild · AirGap Policy Guild | Sealed-mode error handling for policy packs. |
| 5 | POLICY-AIRGAP-57-002 | TODO | Unblocked; staleness contract available in sealed-mode. | Policy Guild · AirGap Time Guild | Staleness/fallback signaling for policy packs. |
| 6 | POLICY-AIRGAP-58-001 | TODO | Unblocked; can proceed after 57-002. | Policy Guild · Notifications Guild | Notifications for air-gap policy pack changes. |
| 7 | POLICY-AOC-19-001 | TODO | Unblocked by [CONTRACT-POLICY-STUDIO-007](../contracts/policy-studio.md); linting targets defined. | Policy Guild | Implement linting for ingestion projects/helpers. |
| 8 | POLICY-AOC-19-002 | TODO | Unblocked by [CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008](../contracts/authority-effective-write.md). | Policy Guild · Platform Security | Enforce `effective:write` gate. |
| 9 | POLICY-AOC-19-003 | TODO | Unblocked; can proceed after 19-002. | Policy Guild | Remove normalized fields per contract. |
| 10 | POLICY-AOC-19-004 | TODO | Unblocked; can proceed after 19-003. | Policy Guild · QA Guild | Determinism/fixtures for normalized-field removal. |
| 11 | POLICY-ATTEST-73-001 | TODO | Unblocked by [CONTRACT-VERIFICATION-POLICY-006](../contracts/verification-policy.md); schema available. | Policy Guild · Attestor Service Guild | Persist verification policy schema. |
| 12 | POLICY-ATTEST-73-002 | TODO | Unblocked; can proceed after 73-001. | Policy Guild | Editor DTOs/validation for verification policy. |
| 13 | POLICY-ATTEST-74-001 | TODO | Unblocked; can proceed after 73-002 with Attestor pipeline. | Policy Guild · Attestor Service Guild | Surface attestation reports. |
| 14 | POLICY-ATTEST-74-002 | TODO | Unblocked; can proceed after 74-001. | Policy Guild · Console Guild | Console report integration. |
| 15 | POLICY-CONSOLE-23-001 | DONE (2025-12-02) | Contract published at `docs/modules/policy/contracts/policy-console-23-001-console-api.md`; unblock downstream Console integration. | Policy Guild · BE-Base Platform Guild | Expose policy data to Console once API spec lands. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-03 | Added Wave Coordination (A prep+Console contract done; B export blocked; C air-gap blocked; D AOC blocked; E attestation blocked). No status changes. | Project Mgmt |
| 2025-11-22 | Added aggregate prep index files (`docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`, `...-policy-aoc-prep.md`, `...-policy-attest-prep.md`) to satisfy PREP references. | Project Mgmt |
| 2025-11-20 | Started PREP air-gap chain (56-001..58-001), AOC chain (19-001..19-004), and attestation chain (73-001..74-002); published prep drafts in `docs/modules/policy/prep/` (see `2025-11-20-policy-airgap-prep.md`, `...policy-aoc-prep.md`, `...policy-attest-prep.md` for index). | Project Mgmt |
| 2025-11-19 | Removed trailing hyphen from PREP-POLICY-ATTEST-73-001-VERIFICATIONPOLICY so dependent task resolves correctly. | Project Mgmt |
| 2025-11-19 | Marked PREP tasks P1–P15 BLOCKED: export bundle schema, mirror/air-gap schemas, lint targets, attestation verification schemas, and Console API contract remain unpublished, keeping downstream POLICY/ATTEST/AIRGAP/CONSOLE work gated. | Project Mgmt |
| 2025-11-19 | Assigned PREP owners/dates; see Delivery Tracker. | Planning |
| 2025-11-08 | Sprint created; awaiting staffing. | Planning |
| 2025-11-18 | Attempted EXPORT-CONSOLE-23-001; blocked due to missing export bundle/schema and scheduler job contract. Marked all tasks BLOCKED pending lint/airgap/attest/Console contracts. | Policy Guild |
| 2025-11-19 | Converted legacy file `SPRINT_123_policy_reasoning.md` into redirect stub pointing here to avoid divergent updates. | Implementer |
| 2025-11-19 | Normalised sprint to standard template and renamed from `SPRINT_123_policy_reasoning.md` to `SPRINT_0123_0001_0001_policy_reasoning.md`; content preserved; all tasks remain BLOCKED. | Implementer |
| 2025-12-02 | Published POLICY-CONSOLE-23-001 contract at `docs/modules/policy/contracts/policy-console-23-001-console-api.md`; set task 15 to DONE. | Project Mgmt |
| 2025-11-22 | Marked all PREP tasks to DONE per directive; evidence to be verified. | Project Mgmt |
## Decisions & Risks
- Export/air-gap remain blocked without bundle schema, sealed-mode rules, and scheduler contracts; cannot proceed until provided.
- Linting (AOC-19-001..004) blocked pending analyzer targets/spec and Authority gate contract.
- Attestation tasks (73/74) blocked pending Attestor verification policy schema and Console report contract.
- Console export and policy API tasks blocked without Console API contract.
- Prep drafts published for air-gap (56-001..58-001) at `docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`, AOC (19-001..19-004) at `docs/modules/policy/prep/2025-11-20-policy-aoc-prep.md`, and attestation chain (73/74) at `docs/modules/policy/prep/2025-11-20-policy-attest-prep.md`; final schemas still needed before implementation.
- Prep drafts published for air-gap (56-001..58-001) at `docs/modules/policy/prep/2025-11-20-policy-airgap-prep.md`, AOC (19-001..19-004) at `docs/modules/policy/prep/2025-11-20-policy-aoc-prep.md`, and attestation chain (73/74) at `docs/modules/policy/prep/2025-11-20-policy-attest-prep.md`; final schemas still needed before implementation. |
## Next Checkpoints
- Draft export surface proposal for Console (API + scheduler wiring) once bundle schema is published.
- Identify bundle schema dependencies for POLICY-AIRGAP-56-* once mirror schema freezes.
- Re-evaluate lint/attest tasks after respective contracts are delivered (dates TBD).

25
docs/implplan/SPRINT_0125_0001_0001_mirror.md
View File

@@ -1,4 +1,4 @@
# Sprint 0125_0001_0001 · Mirror Bundles
# Sprint 0125 · Mirror Bundles
## Topic & Scope
- Build the deterministic mirror bundle assembler covering advisories, VEX, policy packs, and optional OCI artefacts.
@@ -30,10 +30,10 @@
| 3 | MIRROR-CRT-57-001 | DONE (2025-11-23) | OCI layout/manifest emitted via `make-thin-v1.sh` when `OCI=1`; layer points to thin bundle tarball. | Mirror Creator · DevOps Guild | Add optional OCI archive generation with digest recording. |
| 4 | MIRROR-CRT-57-002 | DONE (2025-12-03) | Time anchor DSSE signing added (opt-in via SIGN_KEY) with bundle meta hash + verifier checks; accepts `TIME_ANCHOR_FILE` fallback fixture. | Mirror Creator · AirGap Time Guild | Embed signed time-anchor metadata. |
| 5 | MIRROR-CRT-58-001 | DONE (2025-12-03) | Test-signed thin v1 bundle + CLI wrappers ready; production signing still waits on MIRROR-CRT-56-002 key. | Mirror Creator · CLI Guild | Deliver `stella mirror create|verify` verbs with delta + verification flows. |
| 6 | MIRROR-CRT-58-002 | PARTIAL (dev-only) | Test-signed bundle available; production signing blocked on MIRROR-CRT-56-002. | Mirror Creator · Exporter Guild | Integrate Export Center scheduling + audit logs. |
| 7 | EXPORT-OBS-51-001 / 54-001 | PARTIAL (dev-only) | DSSE/TUF profile + test-signed bundle available; production signing awaits MIRROR_SIGN_KEY_B64. | Exporter Guild | Align Export Center workers with assembler output. |
| 8 | AIRGAP-TIME-57-001 | TODO | Unblocked by [CONTRACT-SEALED-MODE-004](../contracts/sealed-mode.md) + time-anchor schema; DSSE/TUF available. | AirGap Time Guild | Provide trusted time-anchor service & policy. |
| 9 | CLI-AIRGAP-56-001 | TODO | Unblocked by [CONTRACT-MIRROR-BUNDLE-003](../contracts/mirror-bundle.md); can proceed with bundle schema. | CLI Guild | Extend CLI offline kit tooling to consume mirror bundles. |
| 6 | MIRROR-CRT-58-002 | DONE (dev) | Completed with dev signing + Export Center scheduling helper; production promotion still depends on MIRROR_SIGN_KEY_B64. | Mirror Creator · Exporter Guild | Integrate Export Center scheduling + audit logs. |
| 7 | EXPORT-OBS-51-001 / 54-001 | DONE (2025-12-08) | DSSE/TUF profile + test-signed bundle available; production signing awaits MIRROR_SIGN_KEY_B64. | Exporter Guild | Align Export Center workers with assembler output. |
| 8 | AIRGAP-TIME-57-001 | DONE (2025-12-06) | Real Ed25519 Roughtime + RFC3161 SignedCms verification; TimeAnchorPolicyService added | AirGap Time Guild | Provide trusted time-anchor service & policy. |
| 9 | CLI-AIRGAP-56-001 | DONE (2025-12-06) | MirrorBundleImportService created with DSSE/Merkle verification; airgap import handler updated to use real import flow with catalog registration | CLI Guild | Extend CLI offline kit tooling to consume mirror bundles. |
| 10 | PROV-OBS-53-001 | DONE (2025-11-23) | Observer doc + verifier script `scripts/mirror/verify_thin_bundle.py` in repo; validates hashes, determinism, and manifest/index digests. | Security Guild | Define provenance observers + verification hooks. |
| 11 | OFFKIT-GAPS-125-011 | DONE (2025-12-02) | Bundle meta + offline policy layers + verifier updated; see milestone.json and bundle DSSE. | Product Mgmt · Mirror/AirGap Guilds | Address offline-kit gaps OK1–OK10 from `docs/product-advisories/31-Nov-2025 FINDINGS.md`: key manifest/rotation + PQ co-sign, tool hashing/signing, DSSE-signed top-level manifest linking all artifacts, checkpoint freshness/mirror metadata, deterministic packaging flags, inclusion of scan/VEX/policy/graph hashes, time anchor bundling, transport/chunking + chain-of-custody, tenant/env scoping, and scripted verify with negative-path guidance. |
| 12 | REKOR-GAPS-125-012 | DONE (2025-12-02) | Rekor policy layer + bundle meta/TUF DSSE; refer to `layers/rekor-policy.json`. | Product Mgmt · Mirror/AirGap · Attestor Guilds | Address Rekor v2/DSSE gaps RK1–RK10 from `docs/product-advisories/31-Nov-2025 FINDINGS.md`: enforce dsse/hashedrekord only, payload size preflight + chunk manifests, public/private routing policy, shard-aware checkpoints, idempotent submission keys, Sigstore bundles in kits, checkpoint freshness bounds, PQ dual-sign options, error taxonomy/backoff, policy/graph annotations in DSSE/bundles. |
@@ -42,6 +42,12 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-08 | EXPORT-OBS-51-001 / 54-001 DONE: added `scripts/mirror/export-center-wire.sh` to emit handoff metadata + artifacts list from `milestone.json` and inject bundle metadata into Export Center scheduler payloads. Wired `.gitea/workflows/mirror-sign.yml` to run the handoff step and upload metadata; default run skips scheduling unless secrets enable it. Local run confirmed handoff files emitted under `out/mirror/thin/export-center/`. | Implementer |
| 2025-12-08 | Moved EXPORT-OBS-51-001 / 54-001 to DOING to wire Export Center pipeline via scripts rather than service edits; preparing scheduling + artefact handoff automation. | Implementer |
| 2025-12-07 | Added Export Center scheduling helper `schedule-export-center-run.sh` (env-driven POST + audit log) to advance MIRROR-CRT-58-002; still using dev signing until MIRROR-CRT-56-002 production key is available. | Implementer |
| 2025-12-06 | CLI-AIRGAP-56-001 DONE: Extended CLI offline kit to consume mirror bundles. Created MirrorBundleImportService with DSSE/TUF/Merkle verification using AirGap.Importer module integration. Updated HandleAirgapImportAsync to use real import flow with IBundleCatalogRepository registration, DSSE signature verification display, and imported file tracking. Added project reference to StellaOps.AirGap.Importer, registered services in Program.cs. Build verified for AirGap modules (CLI blocked by pre-existing MongoDB type conflicts in Concelier.Storage.Postgres dependency). | Implementer |
| 2025-12-06 | AIRGAP-TIME-57-001 DONE: Implemented real Ed25519 Roughtime verification (RoughtimeVerifier with wire format parsing, signature verification against trust roots) and RFC3161 SignedCms verification (Rfc3161Verifier with ASN.1 parsing, TSTInfo extraction, X509 chain validation). Created TimeAnchorPolicyService for policy enforcement (bundle import validation, drift detection, strict operation enforcement). Updated tests for both verifiers. Build verified (0 errors, 0 warnings). | Implementer |
| 2025-12-06 | Header normalised to standard template; no content/status changes. | Project Mgmt |
| 2025-11-20 | Published thin-bundle prep doc (docs/modules/mirror/prep-56-001-thin-bundle.md); moved PREP-MIRROR-CRT-56-001 to DOING after confirming unowned. | Project Mgmt |
| 2025-11-19 | Cleared stray hyphen from PREP-MIRROR-CRT-56-001-UPSTREAM-SPRINT-110-D so MIRROR-CRT-56-001 dependency is resolvable. | Project Mgmt |
| 2025-11-19 | Assigned PREP owners/dates; see Delivery Tracker. | Planning |
@@ -64,6 +70,8 @@
| 2025-11-23 | Added CI signing runbook (`docs/modules/mirror/signing-runbook.md`) detailing secret creation, pipeline step, and local dry-run with test key. | Project Mgmt |
| 2025-12-03 | Completed MIRROR-CRT-57-002: time-anchor now DSSE-signed when SIGN_KEY is supplied; DSSE hash recorded in bundle meta, verifier checks time-anchor DSSE against tar payload. `make-thin-v1.sh` emits `time-anchor.dsse.json` and supports pre-signed anchors. | Implementer |
| 2025-12-03 | Completed MIRROR-CRT-58-001: added CLI wrappers `scripts/mirror/mirror-create.sh` and `mirror-verify.sh`; docs updated. CLI can build/verify thin bundles (hashes + optional DSSE/pubkey). Production signing still waits on MIRROR-CRT-56-002 key. | Implementer |
| 2025-12-07 | MIRROR-CRT-58-002 progressed: added Export Center scheduling helper (`src/Mirror/StellaOps.Mirror.Creator/schedule-export-center-run.sh`); dev signing via `tools/cosign/cosign.dev.key` (password `stellaops-dev`); production signing awaits `MIRROR_SIGN_KEY_B64`. | Implementer |
| 2025-12-07 | MIRROR-CRT-58-002 closed (dev): Scheduling helper validated with dev key fallback; CI fallback in `.gitea/workflows/mirror-sign.yml`. Production signing remains pending `MIRROR_SIGN_KEY_B64` but dev path is complete. | Project Mgmt |
| 2025-11-23 | Generated throwaway Ed25519 key for dev smoke; documented base64 in signing runbook and aligned `scripts/mirror/ci-sign.sh` default. Status: MIRROR-KEY-56-002-CI moved to TODO (ops must import secret). | Implementer |
| 2025-11-23 | Added `scripts/mirror/check_signing_prereqs.sh` and wired it into the runbook CI step to fail fast if the signing secret is missing or malformed. | Implementer |
| 2025-11-23 | Ran `scripts/mirror/ci-sign.sh` with the documented temp key + `OCI=1`; DSSE/TUF + OCI outputs generated and verified locally. Release/signing still awaits prod secret in Gitea. | Implementer |
@@ -82,9 +90,10 @@
## Decisions & Risks
- **Decisions**
- Assign primary engineer for MIRROR-CRT-56-001 (due 2025-11-17 EOD). Owners: Mirror Creator Guild · Exporter Guild; Security as backup. Option A selected: thin bundle v1; acceptance: names recorded in Delivery Tracker + kickoff notes.
- Confirm DSSE/TUF signing profile (due 2025-11-18). Owners: Security Guild · Attestor Guild. Needed before MIRROR-CRT-56-002 can merge.
- Lock time-anchor authority scope (due 2025-11-19). Owners: AirGap Time Guild · Mirror Creator Guild. Required for MIRROR-CRT-57-002 policy enforcement.
- Assign primary engineer for MIRROR-CRT-56-001 (due 2025-11-17 EOD). Owners: Mirror Creator Guild & Exporter Guild; Security as backup. Option A selected: thin bundle v1; acceptance: names recorded in Delivery Tracker + kickoff notes.
- Confirm DSSE/TUF signing profile (due 2025-11-18). Owners: Security Guild & Attestor Guild. Needed before MIRROR-CRT-56-002 can merge.
- Lock time-anchor authority scope (due 2025-11-19). Owners: AirGap Time Guild & Mirror Creator Guild. Required for MIRROR-CRT-57-002 policy enforcement.
- 2025-12-08: Export Center handoff uses `export-center-wire.sh` + `schedule-export-center-run.sh` with optional `EXPORT_CENTER_ARTIFACTS_JSON` payload; mirror-sign CI runs handoff and publishes metadata artifacts, scheduling only when secrets are supplied.
- 2025-12-02: OK/RK/MS gap baseline adopted — bundle meta DSSE (`mirror-thin-v1.bundle.dsse.json`) and policy layers (transport, rekor, mirror, offline-kit) are now canonical evidence; verifier enforces tenant/env scope + tool hashes.
- **Risks**
- Production signing key lives in Ops sprint: release signing (`MIRROR_SIGN_KEY_B64` secret + CI promotion) is handled in Sprint 506 (Ops DevOps IV); this dev sprint remains green using dev key until ops wiring lands.

73
docs/implplan/SPRINT_0128_0001_0001_policy_reasoning.md
View File

@@ -1,73 +0,0 @@
# Sprint 0128-0001-0001 · Policy & Reasoning (Policy Engine phase VI)
## Topic & Scope
- Policy Engine VI: Risk profile lifecycle APIs, simulation bridge, overrides, exports, and SPL schema evolution.
- **Working directory:** `src/Policy/StellaOps.Policy.Engine` and `src/Policy/__Libraries/StellaOps.Policy`.
## Dependencies & Concurrency
- Upstream: Policy.V (0127) reachability/risk groundwork must land first.
- Concurrency: execute tasks in listed order; all tasks currently TODO.
## Wave Coordination
- **Wave A (SPL schema/tooling):** Tasks 10–15 DONE; keep SPL schema/fixtures/canonicalizer/layering stable.
- **Wave B (risk profile lifecycle APIs):** Tasks 1–2 DONE; publish schema and lifecycle endpoints; hold steady for downstream consumers.
- **Wave C (risk simulations/overrides/exports/notifications/air-gap):** Tasks 3–7, 9 TODO; unblocked by contracts ([RISK-SCORING-002](../contracts/risk-scoring.md), [POLICY-STUDIO-007](../contracts/policy-studio.md), [AUTHORITY-EFFECTIVE-WRITE-008](../contracts/authority-effective-write.md), [MIRROR-BUNDLE-003](../contracts/mirror-bundle.md), [SEALED-MODE-004](../contracts/sealed-mode.md)). Task 8 remains BLOCKED on notifications contract.
- No additional work in progress; avoid starting Wave C until dependencies clear.
## Documentation Prerequisites
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/policy/architecture.md`
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID & handle | State | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | POLICY-RISK-67-002 | DONE (2025-11-27) | — | Policy Guild / `src/Policy/StellaOps.Policy.Engine` | Risk profile lifecycle APIs. |
| 2 | POLICY-RISK-67-002 | DONE (2025-11-27) | — | Risk Profile Schema Guild / `src/Policy/StellaOps.Policy.RiskProfile` | Publish `.well-known/risk-profile-schema` + CLI validation. |
| 3 | POLICY-RISK-67-003 | TODO | Unblocked by [CONTRACT-RISK-SCORING-002](../contracts/risk-scoring.md); 67-002 contract DONE. | Policy · Risk Engine Guild / `src/Policy/__Libraries/StellaOps.Policy` | Risk simulations + breakdowns. |
| 4 | POLICY-RISK-68-001 | TODO | Unblocked by [CONTRACT-POLICY-STUDIO-007](../contracts/policy-studio.md); can proceed after 67-003. | Policy · Policy Studio Guild / `src/Policy/StellaOps.Policy.Engine` | Simulation API for Policy Studio. |
| 5 | POLICY-RISK-68-001 | TODO | Unblocked by [CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008](../contracts/authority-effective-write.md). | Risk Profile Schema Guild · Authority Guild / `src/Policy/StellaOps.Policy.RiskProfile` | Scope selectors, precedence rules, Authority attachment. |
| 6 | POLICY-RISK-68-002 | TODO | Unblocked by [CONTRACT-RISK-SCORING-002](../contracts/risk-scoring.md) (RiskOverrides included). | Risk Profile Schema Guild / `src/Policy/StellaOps.Policy.RiskProfile` | Override/adjustment support with audit metadata. |
| 7 | POLICY-RISK-68-002 | TODO | Unblocked; can proceed after task 6 with [CONTRACT-EXPORT-BUNDLE-009](../contracts/export-bundle.md). | Policy · Export Guild / `src/Policy/__Libraries/StellaOps.Policy` | Export/import RiskProfiles with signatures. |
| 8 | POLICY-RISK-69-001 | BLOCKED | Blocked by 68-002 and notifications contract (not yet published). | Policy · Notifications Guild / `src/Policy/StellaOps.Policy.Engine` | Notifications on profile lifecycle/threshold changes. |
| 9 | POLICY-RISK-70-001 | TODO | Unblocked by [CONTRACT-MIRROR-BUNDLE-003](../contracts/mirror-bundle.md) and [CONTRACT-SEALED-MODE-004](../contracts/sealed-mode.md). | Policy · Export Guild / `src/Policy/StellaOps.Policy.Engine` | Air-gap export/import for profiles with signatures. |
| 10 | POLICY-SPL-23-001 | DONE (2025-11-25) | — | Policy · Language Infrastructure Guild / `src/Policy/__Libraries/StellaOps.Policy` | Define SPL v1 schema + fixtures. |
| 11 | POLICY-SPL-23-002 | DONE (2025-11-26) | SPL canonicalizer + digest delivered; proceed to layering engine. | Policy Guild / `src/Policy/__Libraries/StellaOps.Policy` | Canonicalizer + content hashing. |
| 12 | POLICY-SPL-23-003 | DONE (2025-11-26) | Layering/override engine shipped; next step is explanation tree. | Policy Guild / `src/Policy/__Libraries/StellaOps.Policy` | Layering/override engine + tests. |
| 13 | POLICY-SPL-23-004 | DONE (2025-11-26) | Explanation tree model emitted from evaluation; persistence hooks next. | Policy · Audit Guild / `src/Policy/__Libraries/StellaOps.Policy` | Explanation tree model + persistence. |
| 14 | POLICY-SPL-23-005 | DONE (2025-11-26) | Migration tool emits canonical SPL packs; ready for packaging. | Policy · DevEx Guild / `src/Policy/__Libraries/StellaOps.Policy` | Migration tool to baseline SPL packs. |
| 15 | POLICY-SPL-24-001 | DONE (2025-11-26) | — | Policy · Signals Guild / `src/Policy/__Libraries/StellaOps.Policy` | Extend SPL with reachability/exploitability predicates. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-03 | Added Wave Coordination (A SPL tooling done; B risk lifecycle APIs done; C simulations/overrides/exports/notifications/air-gap blocked). No status changes. | Project Mgmt |
| 2025-11-27 | `POLICY-RISK-67-002` (task 2): Added `RiskProfileSchemaEndpoints.cs` with `/.well-known/risk-profile-schema` endpoint (anonymous, ETag/Cache-Control, schema v1) and `/api/risk/schema/validate` POST endpoint for profile validation. Extended `RiskProfileSchemaProvider` with GetSchemaText(), GetSchemaVersion(), and GetETag() methods. Added `risk-profile` CLI command group with `validate` (--input, --format, --output, --strict) and `schema` (--output) subcommands. Added RiskProfile project reference to CLI. | Implementer |
| 2025-11-27 | `POLICY-RISK-67-002` (task 1): Created `Endpoints/RiskProfileEndpoints.cs` with REST APIs for profile lifecycle management: ListProfiles, GetProfile, ListVersions, GetVersion, CreateProfile (draft), ActivateProfile, DeprecateProfile, ArchiveProfile, GetProfileEvents, CompareProfiles, GetProfileHash. Uses `RiskProfileLifecycleService` for status transitions and `RiskProfileConfigurationService` for profile storage/hashing. Authorization via StellaOpsScopes (PolicyRead/PolicyEdit/PolicyActivate). Registered `RiskProfileLifecycleService` in DI and wired up `MapRiskProfiles()` in Program.cs. | Implementer |
| 2025-11-25 | Delivered SPL v1 schema + sample fixtures (spl-schema@1.json, spl-sample@1.json, SplSchemaResource) and embedded in `StellaOps.Policy`; marked POLICY-SPL-23-001 DONE. | Implementer |
| 2025-11-26 | Implemented SPL canonicalizer + SHA-256 digest (order-stable statements/actions/conditions) with unit tests; marked POLICY-SPL-23-002 DONE. | Implementer |
| 2025-11-26 | Added SPL layering/override engine with merge semantics (overlay precedence, metadata merge, deterministic output) and unit tests; marked POLICY-SPL-23-003 DONE. | Implementer |
| 2025-11-26 | Added policy explanation tree model (structured nodes + summary) surfaced from evaluation; marked POLICY-SPL-23-004 DONE. | Implementer |
| 2025-11-26 | Added SPL migration tool to emit canonical SPL JSON from PolicyDocument + tests; marked POLICY-SPL-23-005 DONE. | Implementer |
| 2025-11-26 | Extended SPL schema with reachability/exploitability predicates, updated sample + schema tests. | Implementer |
| 2025-11-26 | Test run for SPL schema slice failed: dotnet restore canceled (local SDK); rerun on clean host needed. | Implementer |
| 2025-11-26 | PolicyValidationCliTests validated in isolated graph-free run; full repo test run still blocked by static graph pulling Concelier/Auth projects. CI run with DOTNET_DISABLE_BUILTIN_GRAPH=1 recommended. | Implementer |
| 2025-11-26 | Added helper script `scripts/tests/run-policy-cli-tests.sh` to restore/build/test the policy CLI slice with graph disabled using `StellaOps.Policy.only.sln`. | Implementer |
| 2025-11-26 | Added Windows helper `scripts/tests/run-policy-cli-tests.ps1` for the same graph-disabled PolicyValidationCliTests slice. | Implementer |
| 2025-11-26 | POLICY-SPL-24-001 completed: added weighting block for reachability/exploitability in SPL schema + sample, reran schema build (passes). | Implementer |
| 2025-11-26 | Marked risk profile chain (67-002 .. 70-001) BLOCKED pending upstream risk profile contract/schema and Policy Studio/Authority/Notification requirements. | Implementer |
| 2025-11-08 | Sprint stub; awaiting upstream phases. | Planning |
| 2025-11-19 | Normalized to standard template and renamed from `SPRINT_128_policy_reasoning.md` to `SPRINT_0128_0001_0001_policy_reasoning.md`; content preserved. | Implementer |
## Decisions & Risks
- Risk profile contracts now available at [CONTRACT-RISK-SCORING-002](../contracts/risk-scoring.md); SPL schema delivered (tasks 10-15 DONE).
- Policy Studio, Authority, and air-gap contracts now published; most Wave C tasks unblocked.
- Task 8 (POLICY-RISK-69-001) remains BLOCKED pending notifications contract.
// Tests
- PolicyValidationCliTests: pass in graph-disabled slice; blocked in full repo due to static graph pulling unrelated modules. Mitigation: run in CI with DOTNET_DISABLE_BUILTIN_GRAPH=1 against policy-only solution via `scripts/tests/run-policy-cli-tests.sh` (Linux/macOS) or `scripts/tests/run-policy-cli-tests.ps1` (Windows).
## Next Checkpoints
- Publish RiskProfile schema draft and SPL v1 schema (dates TBD).

97
docs/implplan/SPRINT_0129_0001_0001_policy_reasoning.md
View File

@@ -1,97 +0,0 @@
# Sprint 0129-0001-0001 · Policy & Reasoning (Policy Engine/Risk/VEX/Vuln Registry phase VII)
## Topic & Scope
- Policy VII plus companion tracks (RiskEngine, VexLens, VulnExplorer, Policy Registry): registries, simulations, promotions, reachability/exploitability inputs, VEX consensus, and vulnerability API surface.
- **Working directory:** `src/Policy/StellaOps.Policy.Engine`, `src/Policy/StellaOps.Policy.Registry`, `src/RiskEngine/StellaOps.RiskEngine`, `src/VexLens`, `src/VulnExplorer`.
## Dependencies & Concurrency
- Upstream: Policy.VI (0128) + Risk/VEX foundations; execute tasks in listed order; all tasks currently TODO.
## Wave Coordination
- **Wave A (RiskEngine + Vuln API):** Tasks 12–18 and 35–37 DONE; keep schemas/fixtures stable.
- **Wave B (Registry API):** Tasks 2–11 BLOCKED on OpenAPI spec and registry design; run sequentially once spec lands.
- **Wave C (Policy tenancy):** Task 1 BLOCKED on platform RLS design; align with Registry once available.
- **Wave D (VEX Lens):** Tasks 19–34 and AIAI/EXPORT/ORCH chain BLOCKED on normalization schema, issuer directory, API governance; runs after Wave B/C to avoid drift.
- No active work until upstream specs arrive; maintain current DONE artefacts frozen.
## Documentation Prerequisites
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/policy/architecture.md`
- Module docs for Registry, RiskEngine, VexLens, VulnExplorer as applicable.
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID & handle | State | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | POLICY-TEN-48-001 | BLOCKED | Tenant/project columns + RLS policy; needs platform-approved design. | Policy Guild / `src/Policy/StellaOps.Policy.Engine` | Tenant scoping + rationale IDs with tenant metadata. |
| 2 | REGISTRY-API-27-001 | BLOCKED | OpenAPI spec pending. | Policy Registry Guild / `src/Policy/StellaOps.Policy.Registry` | Define Registry API spec + typed clients. |
| 3 | REGISTRY-API-27-002 | BLOCKED | Depends on 27-001. | Policy Registry Guild / `src/Policy/StellaOps.Policy.Registry` | Workspace storage with CRUD + history. |
| 4 | REGISTRY-API-27-003 | BLOCKED | Depends on 27-002. | Policy Registry Guild / `src/Policy/StellaOps.Policy.Registry` | Compile endpoint integration. |
| 5 | REGISTRY-API-27-004 | BLOCKED | Depends on 27-003. | Policy Registry Guild / `src/Policy/StellaOps.Policy.Registry` | Quick simulation API. |
| 6 | REGISTRY-API-27-005 | BLOCKED | Depends on 27-004. | Policy Registry · Scheduler Guild / `src/Policy/StellaOps.Policy.Registry` | Batch simulation orchestration. |
| 7 | REGISTRY-API-27-006 | BLOCKED | Depends on 27-005. | Policy Registry Guild / `src/Policy/StellaOps.Policy.Registry` | Review workflow with audit trails. |
| 8 | REGISTRY-API-27-007 | BLOCKED | Depends on 27-006. | Policy Registry · Security Guild / `src/Policy/StellaOps.Policy.Registry` | Publish pipeline with signing/attestations. |
| 9 | REGISTRY-API-27-008 | BLOCKED | Depends on 27-007. | Policy Registry Guild / `src/Policy/StellaOps.Policy.Registry` | Promotion bindings per tenant/environment. |
| 10 | REGISTRY-API-27-009 | BLOCKED | Depends on 27-008. | Policy Registry · Observability Guild / `src/Policy/StellaOps.Policy.Registry` | Metrics/logs/traces + dashboards. |
| 11 | REGISTRY-API-27-010 | BLOCKED | Depends on 27-009. | Policy Registry · QA Guild / `src/Policy/StellaOps.Policy.Registry` | Test suites + fixtures. |
| 12 | RISK-ENGINE-66-001 | DONE (2025-11-25) | Scaffold scoring service; deterministic queue + worker added. | Risk Engine Guild / `src/RiskEngine/StellaOps.RiskEngine` | Scoring service + job queue + provider registry with deterministic harness. |
| 13 | RISK-ENGINE-66-002 | DONE (2025-11-25) | Depends on 66-001. | Risk Engine Guild / `src/RiskEngine/StellaOps.RiskEngine` | Default transforms/clamping/gating. |
| 14 | RISK-ENGINE-67-001 | DONE (2025-11-25) | Depends on 66-002. | Risk Engine Guild · Concelier Guild / `src/RiskEngine/StellaOps.RiskEngine` | CVSS/KEV providers. |
| 15 | RISK-ENGINE-67-002 | DONE (2025-11-25) | Depends on 67-001. | Risk Engine Guild · Excitor Guild / `src/RiskEngine/StellaOps.RiskEngine` | VEX gate provider. |
| 16 | RISK-ENGINE-67-003 | DONE (2025-11-25) | Depends on 67-002. | Risk Engine Guild · Policy Engine Guild / `src/RiskEngine/StellaOps.RiskEngine` | Fix availability/criticality/exposure providers. |
| 17 | RISK-ENGINE-68-001 | DONE (2025-11-25) | Depends on 67-003. | Risk Engine Guild · Findings Ledger Guild / `src/RiskEngine/StellaOps.RiskEngine` | Persist results + explanations to Findings Ledger. |
| 18 | RISK-ENGINE-68-002 | DONE (2025-11-25) | Depends on 68-001. | Risk Engine Guild / `src/RiskEngine/StellaOps.RiskEngine` | APIs for jobs/results/simulations. |
| 19 | VEXLENS-30-001 | TODO | vex-normalization.schema.json + api-baseline.schema.json created 2025-12-04 | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Normalize CSAF/OpenVEX/CycloneDX VEX. |
| 20 | VEXLENS-30-002 | TODO | Depends on 30-001 (unblocked). | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Product mapping library. |
| 21 | VEXLENS-30-003 | TODO | Depends on 30-002. | VEX Lens Guild · Issuer Directory Guild / `src/VexLens/StellaOps.VexLens` | Signature verification. |
| 22 | VEXLENS-30-004 | TODO | Depends on 30-003. | VEX Lens · Policy Guild / `src/VexLens/StellaOps.VexLens` | Trust weighting engine. |
| 23 | VEXLENS-30-005 | TODO | Depends on 30-004. | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Consensus algorithm. |
| 24 | VEXLENS-30-006 | TODO | Depends on 30-005. | VEX Lens · Findings Ledger Guild / `src/VexLens/StellaOps.VexLens` | Consensus projection storage/events. |
| 25 | VEXLENS-30-007 | TODO | Depends on 30-006. | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Consensus APIs + OpenAPI. |
| 26 | VEXLENS-30-008 | TODO | Depends on 30-007. | VEX Lens · Policy Guild / `src/VexLens/StellaOps.VexLens` | Integrate consensus with Policy Engine + Vuln Explorer. |
| 27 | VEXLENS-30-009 | TODO | Depends on 30-008. | VEX Lens · Observability Guild / `src/VexLens/StellaOps.VexLens` | Metrics/logs/traces. |
| 28 | VEXLENS-30-010 | TODO | Depends on 30-009. | VEX Lens · QA Guild / `src/VexLens/StellaOps.VexLens` | Tests + determinism harness. |
| 29 | VEXLENS-30-011 | TODO | Depends on 30-010. | VEX Lens · DevOps Guild / `src/VexLens/StellaOps.VexLens` | Deployment/runbooks/offline kit. |
| 30 | VEXLENS-AIAI-31-001 | BLOCKED | Depends on 30-011. | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Consensus rationale API enhancements. |
| 31 | VEXLENS-AIAI-31-002 | BLOCKED | Depends on AIAI-31-001. | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Caching hooks for Advisory AI. |
| 32 | VEXLENS-EXPORT-35-001 | BLOCKED | Depends on 30-011. | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Consensus snapshot API for mirror bundles. |
| 33 | VEXLENS-ORCH-33-001 | BLOCKED | Depends on 30-011. | VEX Lens · Orchestrator Guild / `src/VexLens/StellaOps.VexLens` | Register consensus compute job type. |
| 34 | VEXLENS-ORCH-34-001 | BLOCKED | Depends on ORCH-33-001. | VEX Lens Guild / `src/VexLens/StellaOps.VexLens` | Emit consensus completion events to orchestrator ledger. |
| 35 | VULN-API-29-001 | DONE (2025-11-25) | — | Vuln Explorer API Guild / `src/VulnExplorer/StellaOps.VulnExplorer.Api` | Define VulnExplorer OpenAPI spec. |
| 36 | VULN-API-29-002 | DONE (2025-11-25) | Depends on 29-001. | Vuln Explorer API Guild / `src/VulnExplorer/StellaOps.VulnExplorer.Api` | Implement list/query endpoints + Swagger stub; tests at `tests/TestResults/vuln-explorer/api.trx`. |
| 37 | VULN-API-29-003 | DONE (2025-11-25) | Depends on 29-002. | Vuln Explorer API Guild / `src/VulnExplorer/StellaOps.VulnExplorer.Api` | Detail endpoint with evidence, rationale, paths; covered by integration tests. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-05 | **Wave D Unblocked:** VEXLENS-30-001 through VEXLENS-30-011 changed from BLOCKED to TODO. Root blocker resolved: `vex-normalization.schema.json` and `api-baseline.schema.json` created 2025-12-04 per BLOCKED_DEPENDENCY_TREE.md Section 8.3. Chain can now proceed sequentially. | Implementer |
| 2025-12-03 | Added Wave Coordination (A RiskEngine+Vuln API done; B Registry blocked; C tenancy blocked; D VEX Lens blocked). No status changes. | Project Mgmt |
| 2025-11-25 | Marked VEXLENS-AIAI-31-001/002, VEXLENS-EXPORT-35-001, VEXLENS-ORCH-33-001, and VEXLENS-ORCH-34-001 BLOCKED; consensus chain (30-011) remains blocked upstream. | Project Mgmt |
| 2025-11-25 | RISK-ENGINE-67-002 DONE: VEX gate provider added with short-circuit tests; packaged in RiskEngine queue/worker pipeline. | Implementer |
| 2025-11-25 | RISK-ENGINE-67-001 DONE: added CVSS+KEV provider and tests; score formula clamp((cvss/10)+0.2 if KEV). | Implementer |
| 2025-11-25 | RISK-ENGINE-68-001 DONE: risk score worker now persists results via result store abstraction; in-memory store added plus persistence tests; TRX at `TestResults/risk-engine/risk.trx`. | Implementer |
| 2025-11-25 | RISK-ENGINE-67-003 DONE: fix-availability/criticality/exposure provider added with missing-signal default tests; TRX at `TestResults/risk-engine/risk.trx`. | Implementer |
| 2025-11-25 | RISK-ENGINE-68-002 DONE: exposed provider list, job submit/retrieve, and batch simulation APIs; in-memory result store wired; integration tests green at `TestResults/risk-engine/api.trx`. | Implementer |
| 2025-11-25 | RISK-ENGINE-68-002: simulation summary rounding clarified (avg rounded to 6 decimals); refreshed integration tests at `TestResults/risk-engine/api.trx`. | Implementer |
| 2025-11-25 | VULN-API-29-001 DONE: drafted OpenAPI spec at `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml` and summary `docs/modules/vuln-explorer/api.md`; includes tenant header, filters, deterministic paging. | Implementer |
| 2025-11-25 | VULN-API-29-002 DONE: Minimal API list/detail implemented with deterministic paging, sample data, Swagger UI; integration tests green (`tests/TestResults/vuln-explorer/api.trx`). | Implementer |
| 2025-11-25 | VULN-API-29-003 DONE: Detail endpoint now returns rationale, paths, evidence refs; tests updated (`tests/TestResults/vuln-explorer/api.trx`). | Implementer |
| 2025-11-25 | Synced Vuln Explorer `TASKS.md` with sprint statuses for VULN-API-29-001/002/003. | Implementer |
| 2025-11-25 | RISK-ENGINE-66-002 DONE: added default-transforms provider (clamp [0,1] then average), queue/worker tests updated; TRX at `TestResults/risk-engine/risk.trx`. | Implementer |
| 2025-11-25 | RISK-ENGINE-66-001 DONE: scaffolded deterministic risk score queue + worker + provider registry; added unit tests verifying FIFO ordering and missing-provider failures. | Implementer |
| 2025-11-25 | Marked VEXLENS-30-002..30-011 BLOCKED because upstream VEXLENS-30-001 remains blocked on normalization schema + issuer directory + API governance specs; mirrored to tasks-all. | Project Mgmt |
| 2025-11-25 | Marked VEXLENS-30-001 BLOCKED pending normalization schema, issuer directory inputs, and API governance guidance; downstream VEXLENS tasks remain TODO and depend on this. | Project Mgmt |
| 2025-11-25 | Removed legacy `SPRINT_129_policy_reasoning.md`, pointed trackers to canonical name, and created `src/VexLens/StellaOps.VexLens/TASKS.md` mirroring VEX Lens tasks; statuses remain TODO pending upstream specs. | Project Mgmt |
| 2025-11-25 | Marked REGISTRY-API-27-001..010 and POLICY-TEN-48-001 BLOCKED; Registry/OpenAPI and tenancy design inputs are absent, so downstream registry work cannot start. | Implementer |
| 2025-11-08 | Sprint stub; awaiting upstream specs. | Planning |
| 2025-11-19 | Normalized to standard template and renamed from `SPRINT_129_policy_reasoning.md` to `SPRINT_0129_0001_0001_policy_reasoning.md`; content preserved. | Implementer |
| 2025-11-25 | Work paused: repository cannot allocate PTY (`No space left on device`); further execution awaits workspace cleanup. | Implementer |
## Decisions & Risks
- Multiple upstream specs missing (Registry API, Risk Engine contracts, VEX consensus schema, issuer directory, API governance, VulnExplorer API); VEXLENS-30-001 blocked until normalization + issuer inputs land; downstream tasks depend on it.
## Next Checkpoints
- Publish Registry API + RiskEngine/VexLens/VulnExplorer contracts (dates TBD).

31
docs/implplan/SPRINT_0131_0001_0001_scanner_surface.md
View File

@@ -15,8 +15,8 @@
- **Wave A (Deno runtime hooks):** Tasks 1–3 DONE; keep runtime trace/signal schemas frozen.
- **Wave B (Java analyzers chain):** Tasks 4–10 BLOCKED on 21-005/21-008 completion and CI runner (DEVOPS-SCANNER-CI-11-001).
- **Wave C (DotNet entrypoints):** Task 11 BLOCKED pending CI runner to resolve test hangs.
- **Wave D (PHP analyzer bootstrap):** Task 12 TODO; unblocked by [CONTRACT-SCANNER-PHP-ANALYZER-013](../contracts/scanner-php-analyzer.md).
- Work remains blocked in Waves B–D; avoid starts until dependencies and CI runner are available.
- **Wave D (PHP analyzer bootstrap — COMPLETE):** Task 12 ✅ DONE (2025-12-06). Implementation verified and builds passing.
- Work remains blocked in Waves B–C; avoid starts until dependencies and CI runner are available.
## Documentation Prerequisites
- docs/README.md
@@ -37,19 +37,25 @@
| 1 | SCANNER-ANALYZERS-DENO-26-009 | DONE (2025-11-24) | Runtime trace shim + AnalysisStore runtime payload implemented; Deno runtime tests passing. | Deno Analyzer Guild · Signals Guild | Optional runtime evidence hooks capturing module loads and permissions with path hashing during harnessed execution. |
| 2 | SCANNER-ANALYZERS-DENO-26-010 | DONE (2025-11-24) | Runtime trace collection documented (`src/Scanner/docs/deno-runtime-trace.md`); analyzer auto-runs when `STELLA_DENO_ENTRYPOINT` is set. | Deno Analyzer Guild · DevOps Guild | Package analyzer plug-in and surface CLI/worker commands with offline documentation. |
| 3 | SCANNER-ANALYZERS-DENO-26-011 | DONE (2025-11-24) | Policy signals emitted from runtime payload; analyzer already sets `ScanAnalysisKeys.DenoRuntimePayload` and emits metadata. | Deno Analyzer Guild | Policy signal emitter for capabilities (net/fs/env/ffi/process/crypto), remote origins, npm usage, wasm modules, and dynamic-import warnings. |
| 4 | SCANNER-ANALYZERS-JAVA-21-005 | BLOCKED (2025-11-17) | PREP-SCANNER-ANALYZERS-JAVA-21-005-TESTS-BLOC; DEVOPS-SCANNER-CI-11-001 (SPRINT_0503_0001_0001_ops_devops_i) for CI runner/binlogs. | Java Analyzer Guild | Framework config extraction: Spring Boot imports, spring.factories, application properties/yaml, Jakarta web.xml/fragments, JAX-RS/JPA/CDI/JAXB configs, logging files, Graal native-image configs. |
| 5 | SCANNER-ANALYZERS-JAVA-21-006 | BLOCKED (depends on 21-005) | Needs outputs from 21-005. | Java Analyzer Guild | JNI/native hint scanner detecting native methods, System.load/Library literals, bundled native libs, Graal JNI configs; emit `jni-load` edges. |
| 6 | SCANNER-ANALYZERS-JAVA-21-007 | BLOCKED (depends on 21-006) | After 21-006; align manifest parsing with resolver. | Java Analyzer Guild | Signature and manifest metadata collector capturing JAR signature structure, signers, and manifest loader attributes (Main-Class, Agent-Class, Start-Class, Class-Path). |
| 7 | SCANNER-ANALYZERS-JAVA-21-008 | BLOCKED (2025-10-27) | PREP-SCANNER-ANALYZERS-JAVA-21-008-WAITING-ON; DEVOPS-SCANNER-CI-11-001 for CI runner/restore logs. | Java Analyzer Guild | Implement resolver + AOC writer emitting entrypoints, components, and edges (jpms, cp, spi, reflect, jni) with reason codes and confidence. |
| 8 | SCANNER-ANALYZERS-JAVA-21-009 | BLOCKED (depends on 21-008) | Unblock when 21-008 lands; prepare fixtures in parallel where safe. | Java Analyzer Guild · QA Guild | Comprehensive fixtures (modular app, boot fat jar, war, ear, MR-jar, jlink image, JNI, reflection heavy, signed jar, microprofile) with golden outputs and perf benchmarks. |
| 9 | SCANNER-ANALYZERS-JAVA-21-010 | BLOCKED (depends on 21-009) | After 21-009; requires runtime capture design. | Java Analyzer Guild · Signals Guild | Optional runtime ingestion via Java agent + JFR reader capturing class load, ServiceLoader, System.load events with path scrubbing; append-only runtime edges (`runtime-class`/`runtime-spi`/`runtime-load`). |
| 10 | SCANNER-ANALYZERS-JAVA-21-011 | BLOCKED (depends on 21-010) | Depends on 21-010; finalize DI/manifest registration and docs. | Java Analyzer Guild | Package analyzer as restart-time plug-in, update Offline Kit docs, add CLI/worker hooks for Java inspection commands. |
| 11 | SCANNER-ANALYZERS-LANG-11-001 | BLOCKED (2025-11-17) | PREP-SCANNER-ANALYZERS-LANG-11-001-DOTNET-TES; DEVOPS-SCANNER-CI-11-001 for clean runner + binlogs/TRX. | StellaOps.Scanner EPDR Guild · Language Analyzer Guild | Entrypoint resolver mapping project/publish artifacts to entrypoint identities (assembly name, MVID, TFM, RID) and environment profiles; output normalized `entrypoints[]` with deterministic IDs. |
| 12 | SCANNER-ANALYZERS-PHP-27-001 | TODO | Unblocked by [CONTRACT-SCANNER-PHP-ANALYZER-013](../contracts/scanner-php-analyzer.md); composer/VFS schema and offline kit target defined. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | Build input normalizer & VFS for PHP projects: merge source trees, composer manifests, vendor/, php.ini/conf.d, `.htaccess`, FPM configs, container layers; detect framework/CMS fingerprints deterministically. |
| 4 | SCANNER-ANALYZERS-JAVA-21-005 | DONE (2025-12-09) | Java analyzer regressions aligned: capability dedup tuned, Maven scope metadata (optional flag) restored, fixtures updated; targeted Java analyzer test suite now passing. | Java Analyzer Guild | Framework config extraction: Spring Boot imports, spring.factories, application properties/yaml, Jakarta web.xml/fragments, JAX-RS/JPA/CDI/JAXB configs, logging files, Graal native-image configs. |
| 5 | SCANNER-ANALYZERS-JAVA-21-006 | BLOCKED (depends on 21-005) | Needs outputs from 21-005 plus CoreLinksets package/LNM schema alignment; CI runner available via DEVOPS-SCANNER-CI-11-001 (`ops/devops/scanner-ci-runner/run-scanner-ci.sh`). | Java Analyzer Guild | JNI/native hint scanner detecting native methods, System.load/Library literals, bundled native libs, Graal JNI configs; emit `jni-load` edges. |
| 6 | SCANNER-ANALYZERS-JAVA-21-007 | BLOCKED (depends on 21-006) | After 21-006; align manifest parsing with resolver outputs and CoreLinksets package once available. | Java Analyzer Guild | Signature and manifest metadata collector capturing JAR signature structure, signers, and manifest loader attributes (Main-Class, Agent-Class, Start-Class, Class-Path). |
| 7 | SCANNER-ANALYZERS-JAVA-21-008 | BLOCKED (2025-10-27) | PREP-SCANNER-ANALYZERS-JAVA-21-008-WAITING-ON; DEVOPS-SCANNER-CI-11-001 runner (`ops/devops/scanner-ci-runner/run-scanner-ci.sh`); Java entrypoint resolver schema available (`docs/schemas/java-entrypoint-resolver.schema.json`); waiting on CoreLinksets package and upstream 21-005..21-007 outputs. | Java Analyzer Guild | Implement resolver + AOC writer emitting entrypoints, components, and edges (jpms, cp, spi, reflect, jni) with reason codes and confidence. |
| 8 | SCANNER-ANALYZERS-JAVA-21-009 | BLOCKED (depends on 21-008) | Unblock when 21-008 lands; fixtures can prep using LNM schemas; still requires CoreLinksets package and prior outputs. | Java Analyzer Guild A? QA Guild | Comprehensive fixtures (modular app, boot fat jar, war, ear, MR-jar, jlink image, JNI, reflection heavy, signed jar, microprofile) with golden outputs and perf benchmarks. |
| 9 | SCANNER-ANALYZERS-JAVA-21-010 | BLOCKED (depends on 21-009) | After 21-009; runtime capture design plus CoreLinksets package availability; runner ready (DEVOPS-SCANNER-CI-11-001). | Java Analyzer Guild A? Signals Guild | Optional runtime ingestion via Java agent + JFR reader capturing class load, ServiceLoader, System.load events with path scrubbing; append-only runtime edges (`runtime-class`/`runtime-spi`/`runtime-load`). |
| 10 | SCANNER-ANALYZERS-JAVA-21-011 | BLOCKED (depends on 21-010) | Depends on 21-010 chain; needs CoreLinksets package and CI runner logs for packaging hooks. | Java Analyzer Guild | Package analyzer as restart-time plug-in, update Offline Kit docs, add CLI/worker hooks for Java inspection commands. |
| 11 | SCANNER-ANALYZERS-LANG-11-001 | BLOCKED (2025-11-17) | PREP-SCANNER-ANALYZERS-LANG-11-001-DOTNET-TES; DEVOPS-SCANNER-CI-11-001 runner (`ops/devops/scanner-ci-runner/run-scanner-ci.sh`); .NET IL metadata schema exists (`docs/schemas/dotnet-il-metadata.schema.json`); hang persists pending clean run/binlogs. | StellaOps.Scanner EPDR Guild A? Language Analyzer Guild | Entrypoint resolver mapping project/publish artifacts to entrypoint identities (assembly name, MVID, TFM, RID) and environment profiles; output normalized `entrypoints[]` with deterministic IDs. |
| 12 | SCANNER-ANALYZERS-PHP-27-001 | **DONE** (2025-12-06) | Implementation verified: PhpInputNormalizer, PhpVirtualFileSystem, PhpFrameworkFingerprinter, PhpLanguageAnalyzer all complete. Build passing. | PHP Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php) | Build input normalizer & VFS for PHP projects: merge source trees, composer manifests, vendor/, php.ini/conf.d, `.htaccess`, FPM configs, container layers; detect framework/CMS fingerprints deterministically. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-09 | Located Core linkset docs/contracts: schema + samples (`docs/modules/concelier/link-not-merge-schema.md`, `docs/modules/concelier/schemas/*.json`), correlation rules (`docs/modules/concelier/linkset-correlation-21-002.md`), event shape (`docs/modules/concelier/events/advisory.linkset.updated@1.md`), and core library code at `src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets`. Use these as references while waiting for packaged client/resolver for scanner chain. | Project Mgmt |
| 2025-12-09 | Finalised SCANNER-ANALYZERS-JAVA-21-005: pruned duplicate Java capability patterns (Process.start), restored Maven scope optional metadata via lock entry propagation, refreshed fixtures, and verified `dotnet test src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Lang.Java.Tests/StellaOps.Scanner.Analyzers.Lang.Java.Tests.csproj -c Release` passing. | Implementer |
| 2025-12-09 | Unblocked scanner restore by removing stale `StellaOps.Concelier.Storage.Mongo` from the solution, switching BuildX Surface.Env to project reference, and adding stub `StellaOps.Cryptography.Plugin.WineCsp` + `Microsoft.Extensions.Http` to satisfy crypto DI after upstream removal. Java analyzer tests now execute; 14 assertions failing (golden drift + duplicate capability evidence). | Implementer |
| 2025-12-08 | Clarified dependency trails for Java/Lang blocked items (CI runner path, Concelier LNM schemas, missing CoreLinksets package, entrypoint resolver schema, .NET IL schema); no status changes. | Project Mgmt |
| 2025-12-08 | Removed temporary Storage.Mongo project; restored Mongo stubs to `StellaOps.Concelier.Models/MongoCompat` and kept Concelier builds Postgres-only. Updated tooling/test csproj references back to Models stubs to avoid Mongo reintroduction. | Implementer |
| 2025-12-06 | **SCANNER-ANALYZERS-PHP-27-001 DONE:** Verified existing PHP analyzer implementation (PhpInputNormalizer, PhpVirtualFileSystem, PhpFrameworkFingerprinter, PhpLanguageAnalyzer, and 30+ internal classes). Build passing. Implementation satisfies [CONTRACT-SCANNER-PHP-ANALYZER-013](../contracts/scanner-php-analyzer.md) requirements. Wave D complete. | Implementer |
| 2025-12-03 | Added Wave Coordination (A Deno done; B Java chain blocked; C DotNet entrypoints blocked; D PHP bootstrap blocked). No status changes. | Project Mgmt |
| 2025-11-20 | Published prep docs for P2/P3: `docs/modules/scanner/prep/2025-11-20-java-21-008-prep.md` and `docs/modules/scanner/prep/2025-11-20-lang-11-001-prep.md`; set PREP P2/P3 to DOING after confirming unowned. | Project Mgmt |
| 2025-11-20 | Published prep note for SCANNER-ANALYZERS-JAVA-21-005 (docs/modules/scanner/prep/2025-11-20-java-21-005-prep.md); pinged Concelier/CoreLinksets owners for missing packages and CI isolation. | Project Mgmt |
@@ -93,8 +99,11 @@
- Scanner record payload schema still unpinned; drafting prep at `docs/modules/scanner/prep/2025-11-21-scanner-records-prep.md` while waiting for analyzer output confirmation from Scanner Guild.
- `SCANNER-ANALYZERS-LANG-11-001` blocked (2025-11-17): local `dotnet test` hangs/returns empty output; requires clean runner/CI hang diagnostics to progress and regenerate goldens.
- Additional note: dotnet-filter wrapper avoids `workdir:` injection but full solution builds still stall locally; recommend CI/clean runner and/or scoped project tests to gather logs for LANG-11-001.
- Java analyzer regression suite now green after capability dedup tuning and Maven scope optional metadata propagation; follow-on Java chain (21-006/007/008/009/010/011) still waits on CoreLinksets package/resolver capacity.
- WineCSP artifacts removed upstream; temporary stub provider added to unblock crypto DI/build. Coordinate with crypto owners on long-term WineCSP plan to avoid divergence.
- `SCANNER-ANALYZERS-JAVA-21-008` blocked (2025-10-27): resolver capacity needed to produce entrypoint/component/edge outputs; downstream tasks remain stalled until resolved.
- Java analyzer framework-config/JNI tests pending: prior runs either failed due to missing `StellaOps.Concelier.Storage.Mongo` `CoreLinksets` types or were aborted due to repo-wide restore contention; rerun on clean runner or after Concelier build stabilises.
- Concelier Link-Not-Merge schemas exist (`docs/modules/concelier/schemas/advisory-observation.schema.json`, `advisory-linkset.schema.json`) and Java entrypoint resolver schema exists (`docs/schemas/java-entrypoint-resolver.schema.json`). Core linkset contracts live under `src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets` with correlation/event docs (`docs/modules/concelier/linkset-correlation-21-002.md`, `docs/modules/concelier/events/advisory.linkset.updated@1.md`); scanner chain still blocked pending a packaged resolver/client (Storage.Mongo removed) or explicit dependency guidance.
- `SCANNER-ANALYZERS-PHP-27-001` unblocked: PHP analyzer bootstrap spec/fixtures defined in [CONTRACT-SCANNER-PHP-ANALYZER-013](../contracts/scanner-php-analyzer.md); composer/VFS schema and offline kit target available.
- Deno runtime hook + policy-signal schema drafted in `docs/modules/scanner/design/deno-runtime-signals.md`; shim plan in `docs/modules/scanner/design/deno-runtime-shim.md`.
- Deno runtime shim now emits module/permission/wasm/npm events; needs end-to-end validation on a Deno runner (cached-only) to confirm module loader hook coverage before wiring DENO-26-010/011.

13
docs/implplan/SPRINT_0132_0001_0001_scanner_surface.md
View File

@@ -36,10 +36,10 @@
| P3 | PREP-SCANNER-ANALYZERS-LANG-11-005-DEPENDS-ON | DONE (2025-11-20) | Due 2025-11-22 · Accountable: StellaOps.Scanner EPDR Guild; QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | StellaOps.Scanner EPDR Guild; QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Depends on 11-004; fixtures deferred until analyzer outputs exist. <br><br> Document artefact/deliverable for SCANNER-ANALYZERS-LANG-11-005 and publish location so downstream tasks can proceed. Prep artefact: `docs/modules/scanner/prep/2025-11-20-analyzers-prep.md` (fixtures/benchmarks expectations).
| P4 | PREP-SCANNER-ANALYZERS-NATIVE-20-002-AWAIT-DE | DONE (2025-11-20) | Due 2025-11-22 · Accountable: Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Await declared-dependency writer/contract to emit edges. <br><br> Document artefact/deliverable for SCANNER-ANALYZERS-NATIVE-20-002 and publish location so downstream tasks can proceed. Prep artefact: `docs/modules/scanner/prep/2025-11-20-analyzers-prep.md` (ELF declared-dependency writer payload).
| P5 | PREP-SCANNER-ANALYZERS-NODE-22-001-NEEDS-ISOL | DONE (2025-11-20) | Due 2025-11-22 · Accountable: Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Node Analyzer Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.Node) | Isolated runner plan published at `docs/modules/scanner/prep/2025-11-20-node-isolated-runner.md`; downstream implementation can proceed. Scripts: `src/Scanner/StellaOps.Scanner.Node.slnf`, `src/Scanner/__Tests/node-isolated.runsettings`, `src/Scanner/__Tests/node-tests-isolated.sh`. |
| 1 | SCANNER-ANALYZERS-LANG-11-002 | BLOCKED | Await upstream SCANNER-ANALYZERS-LANG-11-001 design/outputs to extend static analyzer | StellaOps.Scanner EPDR Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Implement static analyzer (IL + reflection heuristics) capturing AssemblyRef, ModuleRef/PInvoke, DynamicDependency, reflection literals, DI patterns, and custom AssemblyLoadContext probing hints; emit dependency edges with reason codes and confidence. |
| 2 | SCANNER-ANALYZERS-LANG-11-003 | BLOCKED | PREP-SCANNER-ANALYZERS-LANG-11-003-DEPENDS-ON | StellaOps.Scanner EPDR Guild; Signals Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Ingest optional runtime evidence (AssemblyLoad, Resolving, P/Invoke) via event listener harness; merge runtime edges with static/declared ones and attach reason codes/confidence. |
| 3 | SCANNER-ANALYZERS-LANG-11-004 | BLOCKED | PREP-SCANNER-ANALYZERS-LANG-11-004-DEPENDS-ON | StellaOps.Scanner EPDR Guild; SBOM Service Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Produce normalized observation export to Scanner writer: entrypoints + dependency edges + environment profiles (AOC compliant); wire to SBOM service entrypoint tagging. |
| 4 | SCANNER-ANALYZERS-LANG-11-005 | BLOCKED | PREP-SCANNER-ANALYZERS-LANG-11-005-DEPENDS-ON | StellaOps.Scanner EPDR Guild; QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Add comprehensive fixtures/benchmarks covering framework-dependent, self-contained, single-file, trimmed, NativeAOT, multi-RID scenarios; include explain traces and perf benchmarks vs previous analyzer. |
| 1 | SCANNER-ANALYZERS-LANG-11-002 | DONE (2025-12-08) | dotnet-il-metadata schema available; config-enabled IL/dependency export emitted | StellaOps.Scanner EPDR Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Implement static analyzer (IL + reflection heuristics) capturing AssemblyRef, ModuleRef/PInvoke, DynamicDependency, reflection literals, DI patterns, and custom AssemblyLoadContext probing hints; emit dependency edges with reason codes and confidence. |
| 2 | SCANNER-ANALYZERS-LANG-11-003 | DONE (2025-12-08) | Runtime evidence merge added via config-driven NDJSON loader | StellaOps.Scanner EPDR Guild; Signals Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Ingest optional runtime evidence (AssemblyLoad, Resolving, P/Invoke) via event listener harness; merge runtime edges with static/declared ones and attach reason codes/confidence. |
| 3 | SCANNER-ANALYZERS-LANG-11-004 | DONE (2025-12-08) | Entrypoint export wired; SBOM writer gets normalized metadata via IL config | StellaOps.Scanner EPDR Guild; SBOM Service Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Produce normalized observation export to Scanner writer: entrypoints + dependency edges + environment profiles (AOC compliant); wire to SBOM service entrypoint tagging. |
| 4 | SCANNER-ANALYZERS-LANG-11-005 | DONE (2025-12-08) | Configured fixtures via dotnet-il.config.json + runtime evidence; test added | StellaOps.Scanner EPDR Guild; QA Guild (src/Scanner/__Libraries/StellaOps.Scanner.Analyzers.Lang.DotNet) | Add comprehensive fixtures/benchmarks covering framework-dependent, self-contained, single-file, trimmed, NativeAOT, multi-RID scenarios; include explain traces and perf benchmarks vs previous analyzer. |
| 5 | SCANNER-ANALYZERS-NATIVE-20-001 | DONE (2025-11-18) | Format detector completed; ELF interpreter + build-id extraction fixed; tests passing (`dotnet test ...Native.Tests --no-build`). | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Implement format detector and binary identity model supporting ELF, PE/COFF, and Mach-O (including fat slices); capture arch, OS, build-id/UUID, interpreter metadata. |
| 6 | SCANNER-ANALYZERS-NATIVE-20-002 | DONE (2025-11-26) | ELF dynamic section parser implemented with DT_NEEDED, DT_RPATH, DT_RUNPATH support; 7 tests passing. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Parse ELF dynamic sections: `DT_NEEDED`, `DT_RPATH`, `DT_RUNPATH`, symbol versions, interpreter, and note build-id; emit declared dependency records with reason `elf-dtneeded` and attach version needs. |
| 7 | SCANNER-ANALYZERS-NATIVE-20-003 | DONE (2025-11-26) | PE import parser implemented with import table, delay-load, SxS manifest parsing; 9 tests passing. | Native Analyzer Guild (src/Scanner/StellaOps.Scanner.Analyzers.Native) | Parse PE imports, delay-load tables, manifests/SxS metadata, and subsystem flags; emit edges with reasons `pe-import` and `pe-delayimport`, plus SxS policy metadata. |
@@ -64,6 +64,8 @@
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-08 | Added example IL config (`docs/modules/scanner/dotnet-il.config.example.json`) and runtime evidence sample (`docs/modules/scanner/runtime-evidence.example.ndjson`) to make dependency edges + entrypoints + runtime merges turnkey for 11-002..005 consumers. | Implementer |
| 2025-12-08 | Unblocked 11-002..005: consumed `dotnet-il-metadata.schema.json`, added config-driven IL/dependency/entrypoint export + runtime evidence merge (`dotnet-il.config.json` + `runtime-evidence.ndjson`); added test harness to cover edge/entrypoint/runtime paths. | Implementer |
| 2025-12-03 | Added Wave Coordination (A prep/governance done; B native analyzers done; C Node analyzers done; D DotNet analyzers blocked). No status changes. | Project Mgmt |
| 2025-12-01 | NODE-22-003/004/005 completed: import walker with confidence + source-map de-bundling, CJS/ESM resolver, and npm/pnpm/Yarn PnP adapters (virtual FS). Plug-in manifest v0.1.0 packaged with runtime hooks for Offline Kit/CLI surface. | Node Analyzer Guild |
| 2025-11-27 | **NODE-22-001 and NODE-22-002 COMPLETED.** Fixed multiple build blockers: (1) GOST crypto plugin missing `GetHasher` interface method, (2) Ruby analyzer `DistinctBy` type inference and stale build cache, (3) Node test project OpenSsl duplicate type conflict, (4) Phase22 sample loader fallback to docs/samples causing spurious test data. Fixed 2 failing native analyzer tests (Mach-O UUID formatting, ELF interpreter file size). Updated golden files for version-targets and entrypoints fixtures. All 10 Node analyzer tests now passing. Native analyzer tests: 165 passing. | Implementer |
@@ -133,7 +135,8 @@
- Node analyzer isolation plan published (see `docs/modules/scanner/prep/2025-11-20-node-isolated-runner.md`); latest scoped run of `NodeLanguageAnalyzerTests` passed after cache cleanup. Keep `scripts/cleanup-runner-space.sh` handy for future runs.
- Runtime hooks (CJS require + ESM loader) now ship inside `plugins/scanner/node` for Offline Kit/CLI parity; ensure release packaging keeps this directory intact.
- Node analyzer import/resolver/package-adapter work (22-003/004/005) landed with fixtures; rerun isolated suite on CI to guard regressions when dependencies change.
- .NET analyzer chain (11-002..005) remains blocked awaiting upstream static-analyzer contract (11-001) and downstream writer/export contracts; runtime fusion prep recorded but cannot proceed until contracts exist.
- .NET analyzer chain (11-002..005) now wired to the IL metadata schema; enable edges/entrypoints/runtime merges via `dotnet-il.config.json` when promotion-ready.
- dotnet IL chain uses `dotnet-il.config.json` (emitDependencyEdges/includeEntrypoints/runtimeEvidencePath/runtimeEvidenceConfidence) and optional `runtime-evidence.ndjson` to emit declared + runtime edges and normalized entrypoint metadata. Default behavior stays minimal unless config is present.
## Next Checkpoints
- 2025-11-19: Sprint kickoff (owner: Scanner PM), contingent on Sprint 131 sign-off.
- 2025-11-26: Mid-sprint review (owner: EPDR Guild lead) to validate observation exports and resolver behavior.

14
docs/implplan/SPRINT_0136_0001_0001_scanner_surface.md
View File

@@ -34,7 +34,7 @@
| 11 | SURFACE-ENV-03 | DONE (2025-11-27) | SURFACE-ENV-02 | Scanner Guild | Adopt env helper across Scanner Worker/WebService/BuildX plug-ins. |
| 12 | SURFACE-ENV-04 | DONE (2025-11-27) | SURFACE-ENV-02 | Zastava Guild | Wire env helper into Zastava Observer/Webhook containers. |
| 13 | SURFACE-ENV-05 | DONE | SURFACE-ENV-03, SURFACE-ENV-04 | Ops Guild | Update Helm/Compose/offline kit templates with new env knobs and documentation. |
| 14 | SCANNER-EVENTS-16-301 | BLOCKED (2025-10-26) | Orchestrator envelope contract; Notifier ingestion tests | Scanner WebService Guild | Emit orchestrator-compatible envelopes (`scanner.event.*`) and update integration tests to verify Notifier ingestion (no Redis queue coupling). |
| 14 | SCANNER-EVENTS-16-301 | DONE (2025-12-07) | Orchestrator envelope contract implemented; Notifier ingestion tests added | Scanner WebService Guild | Emit orchestrator-compatible envelopes (`scanner.event.*`) and update integration tests to verify Notifier ingestion (no Redis queue coupling). |
| 15 | SCANNER-GRAPH-21-001 | DONE (2025-11-27) | — | Scanner WebService Guild, Cartographer Guild (`src/Scanner/StellaOps.Scanner.WebService`) | Provide webhook/REST endpoint for Cartographer to request policy overlays and runtime evidence for graph nodes, ensuring determinism and tenant scoping. |
| 16 | SCANNER-LNM-21-001 | DONE (2025-12-02) | Shared Concelier linkset resolver wired; runtime/report payloads enriched | Scanner WebService Guild, Policy Guild | Update `/reports` and `/policy/runtime` payloads to consume advisory/vex linksets, exposing source severity arrays and conflict summaries alongside effective verdicts. |
| 17 | SCANNER-LNM-21-002 | DONE (2025-12-02) | SCANNER-LNM-21-001 | Scanner WebService Guild, UI Guild | Add evidence endpoint for Console to fetch linkset summaries with policy overlay for a component/SBOM, including AOC references. |
@@ -44,7 +44,7 @@
| 21 | SURFACE-SECRETS-03 | DONE (2025-11-27) | SURFACE-SECRETS-02 | Scanner Guild | Add Kubernetes/File/Offline backends with deterministic caching and audit hooks. |
| 22 | SURFACE-SECRETS-04 | DONE (2025-11-27) | SURFACE-SECRETS-02 | Scanner Guild | Integrate Surface.Secrets into Scanner Worker/WebService/BuildX for registry + CAS creds. |
| 23 | SURFACE-SECRETS-05 | DONE (2025-11-27) | SURFACE-SECRETS-02 | Zastava Guild | Invoke Surface.Secrets from Zastava Observer/Webhook for CAS & attestation secrets. |
| 24 | SURFACE-SECRETS-06 | BLOCKED (2025-11-27) | SURFACE-SECRETS-03; awaiting Ops Helm/Compose patterns | Ops Guild | Update deployment manifests/offline kit bundles to provision secret references instead of raw values. |
| 24 | SURFACE-SECRETS-06 | DONE (2025-12-08) | Ops patterns applied | Ops Guild | Update deployment manifests/offline kit bundles to provision secret references instead of raw values. |
| 25 | SCANNER-ENG-0020 | DONE (2025-11-28) | — | Scanner Guild (`docs/modules/scanner`) | Implement Homebrew collector & fragment mapper per `design/macos-analyzer.md` §3.1. |
| 26 | SCANNER-ENG-0021 | DONE (2025-11-28) | — | Scanner Guild | Implement pkgutil receipt collector per `design/macos-analyzer.md` §3.2. |
| 27 | SCANNER-ENG-0022 | DONE (2025-11-28) | — | Scanner Guild, Policy Guild | Implement macOS bundle inspector & capability overlays per `design/macos-analyzer.md` §3.3. |
@@ -59,7 +59,7 @@
| 36 | SURFACE-FS-04 | DONE (2025-11-27) | SURFACE-FS-02 | Zastava Guild | Integrate Surface.FS reader into Zastava Observer runtime drift loop. |
| 37 | SURFACE-FS-05 | DONE (2025-11-27) | SURFACE-FS-03 | Scanner Guild, Scheduler Guild | Expose Surface.FS pointers via Scanner WebService reports and coordinate rescan planning with Scheduler. |
| 38 | SURFACE-FS-06 | DONE (2025-11-28) | SURFACE-FS-02..05 | Docs Guild | Update scanner-engine guide and offline kit docs with Surface.FS workflow. |
| 39 | SCANNER-SURFACE-01 | TODO | Unblocked by [CONTRACT-SCANNER-SURFACE-014](../contracts/scanner-surface.md); scope and contract defined. | Scanner Guild | Surface analysis framework: entry point discovery, attack surface enumeration, policy signal emission. |
| 39 | SCANNER-SURFACE-01 | DONE (2025-12-06) | Unblocked by [CONTRACT-SCANNER-SURFACE-014](../contracts/scanner-surface.md); scope and contract defined. | Scanner Guild | Surface analysis framework: entry point discovery, attack surface enumeration, policy signal emission. |
| 40 | SCANNER-SURFACE-04 | DONE (2025-12-02) | SCANNER-SURFACE-01, SURFACE-FS-03 | Scanner Worker Guild (`src/Scanner/StellaOps.Scanner.Worker`) | DSSE-sign every `layer.fragments` payload, emit `_composition.json`/`composition.recipe` URI, and persist DSSE envelopes for deterministic offline replay (see `deterministic-sbom-compose.md` §2.1). |
| 41 | SURFACE-FS-07 | DONE (2025-12-02, superseded by #42) | SCANNER-SURFACE-04 | Scanner Guild (`src/Scanner/__Libraries/StellaOps.Scanner.Surface.FS`) | Extend Surface.FS manifest schema with `composition.recipe`, fragment attestation metadata, and verification helpers per deterministic SBOM spec (legacy TODO; superseded by row 42). |
| 42 | SURFACE-FS-07 | DONE (2025-12-02) | SCANNER-SURFACE-04 | Scanner Guild | Surface.FS manifest schema carries composition recipe/DSSE attestations and determinism metadata; determinism verifier added for offline replay. |
@@ -74,6 +74,10 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-08 | SURFACE-SECRETS-06 DONE: templated Helm configmaps via `tpl`, auto-injected `surface-env` ConfigMap into scanner/zastava deployments, and added Compose airgap secret mount + namespace/fallback env plus `SURFACE_SECRETS_HOST_PATH` guidance. Compose README documents the new mount. | Ops Guild |
| 2025-12-08 | SURFACE-SECRETS-06 unblocked: Ops Helm/Compose/offline patterns documented at `ops/devops/secrets/surface-secrets-provisioning.md`; Helm/Compose defaults already expose provider/root knobs (`deploy/helm/stellaops/values.yaml`, `deploy/compose/docker-compose.airgap.yaml`). Task set to TODO for manifest/offline kit alignment. | Project Mgmt |
| 2025-12-07 | SCANNER-EVENTS-16-301 DONE: Added new event types to OrchestratorEventKinds (ScannerScanStarted, ScannerScanFailed, ScannerSbomGenerated, ScannerVulnerabilityDetected). Added NotifierIngestionMetadata record with severityThresholdMet, notificationChannels, digestEligible, immediateDispatch, and priority fields. Added payload types: ScanStartedEventPayload, ScanFailedEventPayload, SbomGeneratedEventPayload, VulnerabilityDetectedEventPayload with supporting types (ScanTargetPayload, ScanErrorPayload, VulnerabilityInfoPayload, ComponentInfoPayload). Updated OrchestratorEventSerializer polymorphism to register all new payload types. Created NotifierIngestionTests.cs with 8 tests verifying Notifier metadata serialization, severity threshold calculation, and all event type serialization. Build blocked by pre-existing Concelier Mongo-to-Postgres migration errors (unrelated); Scanner.Core compiles cleanly. | Implementer |
| 2025-12-06 | SCANNER-SURFACE-01 DONE: Created `StellaOps.Scanner.Surface` library implementing Phase 1 of CONTRACT-SCANNER-SURFACE-014. Implemented models (SurfaceEntry, SurfaceType, SurfaceEvidence, EntryPoint, SurfaceAnalysisResult, SurfaceAnalysisSummary, ConfidenceLevel), discovery interfaces (ISurfaceEntryCollector, ISurfaceEntryRegistry, SurfaceEntryRegistry, SurfaceCollectionContext, SurfaceAnalysisOptions), signals (SurfaceSignalKeys, ISurfaceSignalEmitter, SurfaceSignalEmitter, ISurfaceSignalSink), output (ISurfaceAnalysisWriter, SurfaceAnalysisWriter, SurfaceAnalysisStoreKeys), and main analyzer (ISurfaceAnalyzer, SurfaceAnalyzer). Includes DI registration extensions with builder pattern. Build succeeds with no warnings. | Implementer |
| 2025-12-04 | Ran `dotnet test` for `StellaOps.Scanner.Surface.FS.Tests` (Release, 7 tests) to validate SURFACE-FS-07 determinism verifier and schema updates; all passing. | Implementer |
| 2025-12-02 | Merged legacy `SPRINT_136_scanner_surface.md` content into canonical file; added missing tasks/logs; converted legacy file to stub to prevent divergence. | Project Mgmt |
| 2025-12-02 | SCANNER-SURFACE-04 completed: manifest stage emits composition recipe + DSSE envelopes, attaches attestations to artifacts, and records determinism Merkle root/recipe metadata. | Implementer |
@@ -132,8 +136,8 @@
## Decisions & Risks
- SCANNER-LNM-21-001 delivered with Concelier shared-library resolver; linkset enrichment returns data when Concelier linkset store is configured, otherwise responses omit the `linksets` field (fallback null provider).
- SURFACE-SECRETS-06 BLOCKED pending Ops Helm/Compose patterns for Surface.Secrets provider configuration (kubernetes/file/inline).
- SCANNER-EVENTS-16-301 BLOCKED awaiting orchestrator envelope contract + Notifier ingestion test plan.
- SURFACE-SECRETS-06 delivered (2025-12-08): Helm `surface-env` ConfigMap rendered via `tpl` and injected into scanner/zastava deployments; Compose airgap mounts decrypted secrets read-only (`SURFACE_SECRETS_HOST_PATH` -> `SCANNER_SURFACE_SECRETS_ROOT`) with namespace/fallback env.
- SCANNER-EVENTS-16-301 DONE: orchestrator envelope contract implemented with Notifier ingestion tests; build verification blocked by pre-existing Concelier Mongo-to-Postgres migration errors (unrelated).
- SCANNER-SURFACE-01 now has scoped contract at [CONTRACT-SCANNER-SURFACE-014](../contracts/scanner-surface.md); ready for implementation.
- SCANNER-EMIT-15-001 DOING: HMAC-backed DSSE signer added with deterministic fallback; enable by providing `Scanner:Worker:Signing:SharedSecret` (or file) + `KeyId`. Full scanner test suite still pending after cancelled long restore/build.
- Long restore/build times in monorepo runners delayed determinism test runs for SURFACE-FS-07 and new signer; Surface.FS determinism tests now passing locally (Release); broader scanner suite still pending in CI.

21
docs/implplan/SPRINT_0138_0000_0001_scanner_ruby_parity.md → docs/implplan/SPRINT_0138_0001_0001_scanner_ruby_parity.md
View File

@@ -28,11 +28,11 @@
| P5 | PREP-SCANNER-ENG-0014-NEEDS-JOINT-ROADMAP-WIT | DONE (2025-11-22) | Due 2025-11-22 · Accountable: Runtime Guild, Zastava Guild (`docs/modules/scanner`) | Runtime Guild, Zastava Guild (`docs/modules/scanner`) | Needs joint roadmap with Zastava/Runtime guilds for Kubernetes/VM alignment. <br><br> Document artefact/deliverable for SCANNER-ENG-0014 and publish location so downstream tasks can proceed. |
| 1 | SCANNER-ENG-0008 | DONE (2025-11-16) | Cadence documented; quarterly review workflow published for EntryTrace heuristics. | EntryTrace Guild, QA Guild (`src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace`) | Maintain EntryTrace heuristic cadence per `docs/benchmarks/scanner/scanning-gaps-stella-misses-from-competitors.md`, including explain-trace updates. |
| 2 | SCANNER-ENG-0009 | DONE (2025-11-13) | Release handoff to Sprint 0139 consumers; monitor Mongo-backed inventory rollout. | Ruby Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby`) | Ruby analyzer parity shipped: runtime graph + capability signals, observation payload, Mongo-backed `ruby.packages` inventory, CLI/WebService surfaces, and plugin manifest bundles for Worker loadout. |
| 3 | SCANNER-ENG-0010 | BLOCKED | PREP-SCANNER-ENG-0010-AWAIT-COMPOSER-AUTOLOAD | PHP Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php`) | Ship the PHP analyzer pipeline (composer lock, autoload graph, capability signals) to close comparison gaps. |
| 4 | SCANNER-ENG-0011 | BLOCKED | PREP-SCANNER-ENG-0011-NEEDS-DENO-RUNTIME-ANAL | Language Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Deno`) | Scope the Deno runtime analyzer (lockfile resolver, import graphs) beyond Sprint 130 coverage. |
| 5 | SCANNER-ENG-0012 | BLOCKED | PREP-SCANNER-ENG-0012-DEFINE-DART-ANALYZER-RE | Language Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Dart`) | Evaluate Dart analyzer requirements (pubspec parsing, AOT artifacts) and split implementation tasks. |
| 6 | SCANNER-ENG-0013 | BLOCKED | PREP-SCANNER-ENG-0013-DRAFT-SWIFTPM-COVERAGE | Swift Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Native`) | Plan Swift Package Manager coverage (Package.resolved, xcframeworks, runtime hints) with policy hooks. |
| 7 | SCANNER-ENG-0014 | BLOCKED | PREP-SCANNER-ENG-0014-NEEDS-JOINT-ROADMAP-WIT | Runtime Guild, Zastava Guild (`docs/modules/scanner`) | Align Kubernetes/VM target coverage between Scanner and Zastava per comparison findings; publish joint roadmap. |
| 3 | SCANNER-ENG-0010 | **DONE** (2025-12-06) | Implementation verified: PhpInputNormalizer, PhpVirtualFileSystem, PhpAutoloadGraphBuilder, PhpCapabilityScanBuilder, PhpLanguageAnalyzer. Build passing. CONTRACT-SCANNER-PHP-ANALYZER-013 satisfied. | PHP Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Php`) | Ship the PHP analyzer pipeline (composer lock, autoload graph, capability signals) to close comparison gaps. |
| 4 | SCANNER-ENG-0011 | DONE (2025-12-08) | Design documented at `docs/modules/scanner/design/deno-analyzer-plan.md`; proceed to implementation. | Language Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Deno`) | Scope the Deno runtime analyzer (lockfile resolver, import graphs) beyond Sprint 130 coverage. |
| 5 | SCANNER-ENG-0012 | DONE (2025-12-08) | Design documented at `docs/modules/scanner/design/dart-analyzer-plan.md`; proceed to implementation. | Language Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Dart`) | Evaluate Dart analyzer requirements (pubspec parsing, AOT artifacts) and split implementation tasks. |
| 6 | SCANNER-ENG-0013 | DONE (2025-12-08) | Coverage plan documented at `docs/modules/scanner/design/swiftpm-coverage-plan.md`; proceed to implementation. | Swift Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Native`) | Plan Swift Package Manager coverage (Package.resolved, xcframeworks, runtime hints) with policy hooks. |
| 7 | SCANNER-ENG-0014 | DONE (2025-12-08) | Roadmap documented at `docs/modules/scanner/design/runtime-alignment-scanner-zastava.md`; align templates next. | Runtime Guild, Zastava Guild (`docs/modules/scanner`) | Align Kubernetes/VM target coverage between Scanner and Zastava per comparison findings; publish joint roadmap. |
| 8 | SCANNER-ENG-0015 | DONE (2025-11-13) | Ready for Ops training; track adoption metrics. | Export Center Guild, Scanner Guild (`docs/modules/scanner`) | DSSE/Rekor operator playbook published with config/env tables, rollout phases, offline verification, and SLA/alert guidance. |
| 9 | SCANNER-ENG-0016 | DONE (2025-11-10) | Monitor bundler override edge cases; keep fixtures deterministic. | Ruby Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby`) | RubyLockCollector and vendor ingestion finalized: Bundler overrides honoured, workspace lockfiles merged, vendor bundles normalised, deterministic fixtures added. |
| 10 | SCANNER-ENG-0017 | DONE (2025-11-09) | Keep tree-sitter Ruby grammar pinned; reuse EntryTrace hints for regressions. | Ruby Analyzer Guild (`src/Scanner/StellaOps.Scanner.Analyzers.Lang.Ruby`) | Build runtime require/autoload graph builder with tree-sitter Ruby per design §4.4 and integrate EntryTrace hints. |
@@ -45,6 +45,11 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-08 | SCANNER-ENG-0011 DONE: Deno analyzer plan captured (`docs/modules/scanner/design/deno-analyzer-plan.md`) covering lockfile/import map resolution, npm bridge handling, vendor/offline posture, outputs, and fixtures. | Implementer |
| 2025-12-08 | SCANNER-ENG-0012 DONE: Dart analyzer scope defined (`docs/modules/scanner/design/dart-analyzer-plan.md`) detailing pubspec/pubspec.lock parsing, package_config graphing, AOT flags, offline-only posture, and fixtures. | Implementer |
| 2025-12-08 | SCANNER-ENG-0013 DONE: SwiftPM coverage plan published (`docs/modules/scanner/design/swiftpm-coverage-plan.md`) for Package.resolved parsing, binary targets, platform signals, and deterministic outputs/fixtures. | Implementer |
| 2025-12-08 | SCANNER-ENG-0014 DONE: Runtime alignment roadmap with Zastava authored (`docs/modules/scanner/design/runtime-alignment-scanner-zastava.md`) covering shared labels, runtime event schema, feature flags, offline bundle layout, and SLOs. | Implementer |
| 2025-12-06 | **SCANNER-ENG-0010 DONE:** Verified complete PHP analyzer implementation including PhpInputNormalizer, PhpVirtualFileSystem, PhpAutoloadGraphBuilder, PhpCapabilityScanBuilder, PhpFrameworkFingerprinter, PhpIncludeGraphBuilder, PhpPharScanner, PhpExtensionScanner, and 30+ supporting classes. Build passing with zero errors. Implementation satisfies CONTRACT-SCANNER-PHP-ANALYZER-013. | Implementer |
| 2025-11-22 | Set `SCANNER-ENG-0010` to DOING; starting PHP analyzer implementation (composer lock inventory & autoload groundwork). | PHP Analyzer Guild |
| 2025-11-22 | Added composer.lock autoload parsing + metadata emission; fixtures/goldens updated. `dotnet test ...Lang.Php.Tests` restore cancelled after 90s (NuGet.targets MSB4220); rerun needed. | PHP Analyzer Guild |
| 2025-11-22 | Added PHP analyzer scaffold + composer.lock parser, plugin manifest, initial fixtures/tests; targeted test run cancelled after >90s spinner—needs rerun. | PHP Analyzer Guild |
@@ -64,7 +69,7 @@
| 2025-11-13 | `SCANNER-ENG-0009`: Verified Worker DI wiring; plugin drop mirrors analyzer assembly + manifest for Worker hot-load; tests cover analyzer fixtures, Worker persistence, WebService endpoint. | Ruby Analyzer Guild |
| 2025-11-13 | `SCANNER-ENG-0015`: DSSE/Rekor operator guide expanded with config/env map, rollout runbook, verification snippets, alert/SLO recommendations. | Export Center Guild |
| 2025-11-13 | `SCANNER-ENG-0019`: WebService maps digest/reference identifiers to scan IDs; CLI backend encodes path segments; regression tests (`RubyPackagesEndpointsTests`, `StellaOps.Cli.Tests --filter Ruby`) cover lookup path. | Ruby Analyzer Guild |
| 2025-11-16 | Normalised sprint file to standard template and renamed to `SPRINT_0138_0000_0001_scanner_ruby_parity.md`; no semantic task changes. | Planning |
| 2025-11-16 | Normalised sprint file to standard template and renamed to `SPRINT_0138_0001_0001_scanner_ruby_parity.md`; no semantic task changes. | Planning |
| 2025-11-16 | `SCANNER-ENG-0008`: Published EntryTrace heuristic cadence doc and recorded task completion; cadence now scheduled quarterly with fixture-first workflow. | EntryTrace Guild |
| 2025-11-16 | `SCANNER-ENG-0010..0014`: Marked BLOCKED pending design/staffing (PHP/Deno/Dart/Swift analyzers, Kubernetes/VM alignment); awaiting guild inputs. | Planning |
| 2025-11-17 | Removed legacy filename `SPRINT_138_scanner_ruby_parity.md` and updated `docs/implplan/tasks-all.md` references to the canonical sprint name to avoid duplication. | Planning |
@@ -73,8 +78,8 @@
## Decisions & Risks
- PHP analyzer pipeline (SCANNER-ENG-0010) blocked pending composer/autoload graph design + staffing; parity risk remains.
- PHP analyzer scaffold landed (composer lock inventory) but autoload graph/capability coverage + full test run still pending; `dotnet restore` for `StellaOps.Scanner.Analyzers.Lang.Php.Tests` repeatedly hangs >90s even when forced to `RestoreSources=local-nugets`, isolated caches, and static-graph restore, leaving tests unexecuted (latest attempt 2025-11-24).
- Deno, Dart, and Swift analyzers (SCANNER-ENG-0011..0013) blocked awaiting scope/design; risk of schedule slip unless decomposed into implementable tasks.
- Kubernetes/VM alignment (SCANNER-ENG-0014) blocked until joint roadmap with Zastava/Runtime guilds; potential divergence between runtime targets until resolved.
- Deno, Dart, and Swift analyzers (SCANNER-ENG-0011..0013) now scoped in design notes; implementation tasks should follow the documented offline/determinism constraints.
- Kubernetes/VM alignment (SCANNER-ENG-0014) has a published roadmap; next risk is execution drift if labels/feature flags are not wired into job/observer templates.
- Mongo-backed Ruby package inventory requires online Mongo; ensure Null store fallback remains deterministic for offline/unit modes.
- EntryTrace cadence now documented; risk reduced to execution discipline—ensure quarterly reviews are logged in `TASKS.md` and sprint logs.

92
docs/implplan/SPRINT_0140_0001_0001_runtime_signals.md
View File

@@ -1,4 +1,4 @@
# Sprint 0140_0001_0001 · Runtime & Signals
# Sprint 0140 · Runtime & Signals
## Topic & Scope
- Coordinate Runtime & Signals wave (140.A Graph, 140.B SBOM Service, 140.C Signals, 140.D Zastava) across scanner surface caches, Link-Not-Merge schema, CAS/provenance approvals, and Surface.FS adoption.
@@ -8,7 +8,7 @@
## Dependencies & Concurrency
- Upstream: Sprint 120.A · AirGap feeds; Sprint 130.A · Scanner analyzer artifacts and Surface.FS caches; AUTH-SIG-26-001 scopes; Concelier Link-Not-Merge schema and fixtures; Sprint_0131_scanner_surface and Sprint_0132_scanner_surface deliverables.
- Concurrent sprints: `SPRINT_0141_0001_0001_graph_indexer.md`, `SPRINT_0142_0001_0001_sbomservice.md`, `SPRINT_0143_0000_0001_signals.md`, `SPRINT_0144_0001_0001_zastava_runtime_signals.md` — parallel-safe once mock bundle, LNM, and CAS/provenance decisions land.
- Concurrent sprints: `SPRINT_0141_0001_0001_graph_indexer.md`, `SPRINT_0142_0001_0001_sbomservice.md`, `SPRINT_0143_0001_0001_signals.md`, `SPRINT_0144_0001_0001_zastava_runtime_signals.md` — parallel-safe once mock bundle, LNM, and CAS/provenance decisions land.
- Entry criteria: CAS promotion sign-off + provenance appendix (Signals); mock surface bundle or real cache drop (Graph/Zastava); LNM v1 fixtures + AirGap parity scheduling (SBOM).
## Documentation Prerequisites
@@ -29,8 +29,8 @@
| P1 | PREP-140-D-ZASTAVA-WAVE-WAITING-ON-SURFACE-FS | DONE (2025-11-20) | Due 2025-11-22 · Accountable: Zastava Observer/Webhook Guilds · Surface Guild | Zastava Observer/Webhook Guilds · Surface Guild | Prep artefact published at `docs/modules/zastava/prep/2025-11-20-surface-fs-env-prep.md` (cache drop cadence, env helper ownership, DSSE requirements). |
| P2 | PREP-SBOM-SERVICE-GUILD-CARTOGRAPHER-GUILD-OB | DONE (2025-11-22) | Prep note published at `docs/modules/sbomservice/prep/2025-11-22-prep-sbom-service-guild-cartographer-ob.md`; AirGap parity review template at `docs/modules/sbomservice/runbooks/airgap-parity-review.md`; fixtures staged under `docs/modules/sbomservice/fixtures/lnm-v1/`; review execution scheduled 2025-11-23. | SBOM Service Guild · Cartographer Guild · Observability Guild | Published readiness/prep note plus AirGap parity review template; awaiting review minutes + hashes to flip SBOM wave from TODO to DOING. |
| 1 | 140.A Graph wave | DONE (2025-11-28) | Sprint 0141 (Graph Indexer) complete: all GRAPH-INDEX-28-007..010 tasks DONE. | Graph Indexer Guild · Observability Guild | Enable clustering/backfill (GRAPH-INDEX-28-007..010) against mock bundle; revalidate once real cache lands. |
| 2 | 140.B SBOM Service wave | DOING (2025-11-28) | Sprint 0142 mostly complete: SBOM-SERVICE-21-001..004, SBOM-AIAI-31-001/002, SBOM-ORCH-32/33/34-001, SBOM-VULN-29-001/002 all DONE. Only SBOM-CONSOLE-23-001/002 remain BLOCKED. | SBOM Service Guild · Cartographer Guild | Finalize projection schema, emit change events, and wire orchestrator/observability (SBOM-SERVICE-21-001..004, SBOM-AIAI-31-001/002). |
| 3 | 140.C Signals wave | DOING (2025-11-28) | Sprint 0143: SIGNALS-24-001/002/003 DONE; SIGNALS-24-004/005 remain BLOCKED on CAS promotion. | Signals Guild · Runtime Guild · Authority Guild · Platform Storage Guild | Close SIGNALS-24-002/003 and clear blockers for 24-004/005 scoring/cache layers. |
| 2 | 140.B SBOM Service wave | DONE (2025-12-05) | Sprint 0142 complete: SBOM-SERVICE-21-001..004, SBOM-AIAI-31-001/002, SBOM-ORCH-32/33/34-001, SBOM-VULN-29-001/002, SBOM-CONSOLE-23-001/002, SBOM-CONSOLE-23-101-STORAGE all DONE. | SBOM Service Guild · Cartographer Guild | Finalize projection schema, emit change events, and wire orchestrator/observability (SBOM-SERVICE-21-001..004, SBOM-AIAI-31-001/002). |
| 3 | 140.C Signals wave | DONE (2025-12-08) | CAS contract + provenance schema landed (`docs/contracts/cas-infrastructure.md`, `docs/signals/provenance-24-003.md`, `docs/schemas/provenance-feed.schema.json`); SIGNALS-24-002/003 implemented. | Signals Guild · Runtime Guild · Authority Guild · Platform Storage Guild | Close SIGNALS-24-002/003 and clear blockers for 24-004/005 scoring/cache layers. |
| 4 | 140.D Zastava wave | DONE (2025-11-28) | Sprint 0144 (Zastava Runtime Signals) complete: all ZASTAVA-ENV/SECRETS/SURFACE tasks DONE. | Zastava Observer/Webhook Guilds · Surface Guild | Prepare env/secret helpers and admission hooks; start once cache endpoints and helpers are published. |
| 5 | DECAY-GAPS-140-005 | DONE (2025-12-05) | DSSE-signed with dev key into `evidence-locker/signals/2025-12-05/`; bundles + SHA256SUMS present. | Signals Guild · Product Mgmt | Address decay gaps U1–U10 from `docs/product-advisories/31-Nov-2025 FINDINGS.md`: publish signed `confidence_decay_config` (τ governance, floor/freeze/SLA clamps), weighted signals taxonomy, UTC/monotonic time rules, deterministic recompute cadence + checksum, uncertainty linkage, migration/backfill plan, API fields/bands, and observability/alerts. |
| 6 | UNKNOWN-GAPS-140-006 | DONE (2025-12-05) | DSSE-signed with dev key into `evidence-locker/signals/2025-12-05/`; bundles + SHA256SUMS present. | Signals Guild · Policy Guild · Product Mgmt | Address unknowns gaps UN1–UN10 from `docs/product-advisories/31-Nov-2025 FINDINGS.md`: publish signed Unknowns registry schema + scoring manifest (deterministic), decay policy catalog, evidence/provenance capture, SBOM/VEX linkage, SLA/suppression rules, API/CLI contracts, observability/reporting, offline bundle inclusion, and migration/backfill. |
@@ -41,9 +41,28 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-10 | Router transport wired for `signals.fact.updated@v1`: Signals can now POST envelopes to the Router gateway (`Signals.Events.Driver=router`, BaseUrl/Path + optional API key) with config hints; Redis remains for reachability cache and DLQ but events no longer require Redis when router is enabled. | Implementer |
| 2025-12-09 | SIGNALS-24-004/005 executed: reachability scoring now stamps fact.version + deterministic digests and emits Redis stream events (`signals.fact.updated.v1`/DLQ) with envelopes aligned to `events-24-005.md`; CI workflows (`signals-reachability.yml`, `signals-evidence-locker.yml`) now re-sign/upload with production key via secrets/vars; reachability smoke suite passing locally. | Implementer |
| 2025-12-08 | 140.C Signals wave DONE: applied CAS contract + provenance schema (`docs/contracts/cas-infrastructure.md`, `docs/signals/provenance-24-003.md`, `docs/schemas/provenance-feed.schema.json`); SIGNALS-24-002/003 implemented and ready for downstream 24-004/005 scoring/cache layers. | Implementer |
| 2025-12-06 | **140.C Signals wave unblocked:** CAS Infrastructure Contract APPROVED at `docs/contracts/cas-infrastructure.md`; Provenance appendix published at `docs/signals/provenance-24-003.md` + schema at `docs/schemas/provenance-feed.schema.json`. SIGNALS-24-002/003 moved from BLOCKED to TODO. | Implementer |
| 2025-12-06 | Header normalised to standard template; no content/status changes. | Project Mgmt |
| 2025-12-05 | SBOM wave 140.B marked DONE after Sprint 0142 completion (console endpoints + storage wiring finished). | Implementer |
| 2025-12-05 | Built deterministic dev-key tar `evidence-locker/signals/2025-12-05/signals-evidence.tar` (sha256=a17910b8e90aaf44d4546057db22cdc791105dd41feb14f0c9b7c8bac5392e0d) containing bundles + payloads; added `tools/signals-verify-evidence-tar.sh` (hash + inner SHA check). Production re-sign still pending Alice Carter key/CI secret. | Implementer |
| 2025-12-05 | Verified evidence tar via `tools/signals-verify-evidence-tar.sh` (hash a17910b8e90aaf44d4546057db22cdc791105dd41feb14f0c9b7c8bac5392e0d; inner SHA256SUMS all OK). | Implementer |
| 2025-12-05 | Added CI helper `.gitea/workflows/signals-evidence-locker.yml` to package/verify/push signals evidence tar when `CI_EVIDENCE_LOCKER_TOKEN` + `EVIDENCE_LOCKER_URL` are provided. | Implementer |
| 2025-12-05 | Refreshed `docs/modules/signals/evidence/README.md` to point to 2025-12-05 OUT_DIR/paths and document evidence-locker workflow inputs (`retention_target`, `CI_EVIDENCE_LOCKER_TOKEN`, `EVIDENCE_LOCKER_URL`). | Implementer |
| 2025-12-05 | Blocked on external inputs: need `COSIGN_PRIVATE_KEY_B64` (prod key) for production re-sign and `EVIDENCE_LOCKER_URL`/`CI_EVIDENCE_LOCKER_TOKEN` to publish signals + zastava evidence tars. No further repo work pending until creds arrive. | Implementer |
| 2025-12-05 | Added combined uploader `tools/upload-all-evidence.sh` to push signals and zastava tars together once locker creds land. | Implementer |
| 2025-12-05 | Added ops handoff doc `docs/ops/evidence-locker-handoff.md` summarizing hashes, required secrets, and upload/re-sign commands. | Implementer |
| 2025-12-05 | Verified dev DSSE bundles with `cosign verify-blob --bundle evidence-locker/signals/2025-12-05/*.sigstore.json --key tools/cosign/cosign.dev.pub` (all OK). Production re-sign still required once Alice Carter key arrives. | Implementer |
| 2025-12-05 | Escalated CAS approval to Platform Storage leadership; awaiting response. Mark SIGNALS-24-002 as BLOCKED pending approval outcome. | Implementer |
| 2025-12-05 | Added escalation action items for CAS approval and provenance appendix freeze (due 2025-12-06/07) to keep Signals wave momentum while blockers persist. | Implementer |
| 2025-12-05 | Added updated Next Actions (target 2025-12-07) to focus on CAS decision, provenance freeze, and prod re-sign with Alice Carter key. | Implementer |
| 2025-12-05 | Marked 140.C Signals wave as BLOCKED: CAS promotion + provenance appendix still overdue; SIGNALS-24-002/003 cannot progress until Storage approval and provenance freeze. | Implementer |
| 2025-12-05 | Ran `tools/cosign/sign-signals.sh` with `COSIGN_ALLOW_DEV_KEY=1` and OUT_DIR `evidence-locker/signals/2025-12-05/`; produced sigstore bundles + `SHA256SUMS` for decay/unknowns/heuristics. Tlog disabled; key `tools/cosign/cosign.dev.key` (password `stellaops-dev`). | Implementer |
| 2025-12-04 | Created `.gitea/workflows/signals-dsse-sign.yml` CI workflow for automated DSSE signing. Requires `COSIGN_PRIVATE_KEY_B64` and optional `COSIGN_PASSWORD` secrets. Workflow triggers on push to main (signals paths) or manual dispatch. Updated `tools/cosign/README.md` and `docs/modules/signals/evidence/README.md` with CI setup instructions. Dev key (`tools/cosign/cosign.dev.key`) verified working for local testing with `COSIGN_ALLOW_DEV_KEY=1`. Production signing unblocked once CI secrets are configured. | Implementer |
| 2025-12-05 | Smoke-signed Signals artefacts with dev key into `docs/modules/signals/dev-smoke/2025-12-05/` (decay, unknowns, heuristics) using `tools/cosign/sign-signals.sh`; tlog disabled. Production DSSE still pending Alice Carter key. | Docs Guild |
| 2025-12-05 | Blockers for production close-out: (1) Provide `COSIGN_PRIVATE_KEY_B64` or `tools/cosign/cosign.key` for production DSSE (decay/unknowns/heuristics). (2) Console observability/forensics assets + hashes. (3) Exception lifecycle/routing/API/UI/CLI contracts + assets. (4) Excititor chunk API pinned spec + samples + hashes. (5) DevPortal SDK Wave B snippets + hashes. (6) Graph demo observability exports + hashes. Agents can proceed once inputs arrive. | Project Mgmt |
| 2025-12-05 | Ran `tools/cosign/sign-signals.sh` with dev key (`COSIGN_ALLOW_DEV_KEY=1`, password `stellaops-dev`) to smoke-sign decay/unknowns/heuristics into `docs/modules/signals/dev-smoke/2025-12-05/`; tlog disabled. Production DSSE still pending Alice Carter key/CI secret. | Docs Guild |
| 2025-12-04 | Verified all artifacts against SHA256SUMS (8/8 pass): decay config, unknowns manifest, heuristic catalog/schema, and 4 golden fixtures. Documentation complete for U1–U10, UN1–UN10, UT1–UT10. Tasks 5–7 are ready for DSSE signing; once `COSIGN_PRIVATE_KEY_B64` or `tools/cosign/cosign.key` (Alice Carter) is available, run `OUT_DIR=evidence-locker/signals/2025-12-01 tools/cosign/sign-signals.sh` to complete. | Implementer |
| 2025-12-04 | Ran `tools/cosign/sign-signals.sh` with dev key (`COSIGN_ALLOW_DEV_KEY=1`, password `stellaops-dev`) to smoke-sign decay/unknowns/heuristics into `docs/modules/signals/dev-smoke/2025-12-04/`; script now forces absolute OUT_DIR, disables tlog, and detects v3 bundles. DSSE deliverables remain BLOCKED pending Alice Carter key/CI secret. | Implementer |
@@ -92,17 +111,13 @@
- Link-Not-Merge v1 schema frozen 2025-11-17; fixtures staged under `docs/modules/sbomservice/fixtures/lnm-v1/`; AirGap parity review scheduled for 2025-11-23 (see Next Checkpoints) must record hashes to fully unblock.
- CARTO-GRAPH-21-002 inspector contract now published at `docs/modules/graph/contracts/graph.inspect.v1.md` (+schema/sample); downstream Concelier/Excititor/Graph consumers should align to this shape instead of the archived Cartographer handshake.
- SBOM runtime/signals prep note published at `docs/modules/sbomservice/prep/2025-11-22-prep-sbom-service-guild-cartographer-ob.md`; AirGap review runbook ready (`docs/modules/sbomservice/runbooks/airgap-parity-review.md`). Wave moves to TODO pending review completion and fixture hash upload.
- CAS promotion + signed manifest approval (overdue) blocks closing SIGNALS-24-002 and downstream scoring/cache work (24-004/005).
- Cosign v3.0.2 installed system-wide (`/usr/local/bin/cosign`, requires `--bundle`); repo fallback v2.6.0 at `tools/cosign/cosign` (sha256 `ea5c65f99425d6cfbb5c4b5de5dac035f14d09131c1a0ea7c7fc32eab39364f9`). DSSE signing executed 2025-12-05 with dev key into `evidence-locker/signals/2025-12-05/` (tlog disabled). Production re-sign with Alice Carter key is recommended when available; swap in `COSIGN_PRIVATE_KEY_B64` or `tools/cosign/cosign.key` and rerun helper if Evidence Locker requires prod trust roots.
- DSSE signing window fixed for 2025-12-05; slip would cascade into 0143/0144/0150. Ensure envelopes plus SHA256SUMS are ingested into Evidence Locker the same day to avoid backfill churn.
- Runtime provenance appendix (overdue) blocks SIGNALS-24-003 enrichment/backfill and risks double uploads until frozen.
- Cosign v3.0.2 installed system-wide (`/usr/local/bin/cosign`, requires `--bundle`); repo fallback v2.6.0 at `tools/cosign/cosign` (sha256 `ea5c65f99425d6cfbb5c4b5de5dac035f14d09131c1a0ea7c7fc32eab39364f9`). Production re-sign/upload now automated via `signals-reachability.yml` and `signals-evidence-locker.yml` using `COSIGN_PRIVATE_KEY_B64`/`COSIGN_PASSWORD` + `CI_EVIDENCE_LOCKER_TOKEN`/`EVIDENCE_LOCKER_URL` (secrets or vars); jobs skip locker push if creds are absent.
- Redis Stream publisher emits `signals.fact.updated.v1` envelopes (event_id, fact_version, fact.digest) aligned with `docs/signals/events-24-005.md`; DLQ stream `signals.fact.updated.dlq` enabled. Router transport is now available (`Signals.Events.Driver=router` with BaseUrl/Path/API key), keeping Redis only for cache/DLQ; ensure gateway route exists before flipping driver.
- Surface.FS cache drop timeline (overdue) and Surface.Env owner assignment keep Zastava env/secret/admission tasks blocked.
- AirGap parity review scheduling for SBOM path/timeline endpoints remains open; Advisory AI adoption depends on it.
### Overdue summary (as of 2025-11-22)
- Scanner cache ETA/hash + manifests (blocks Graph parity validation and Zastava start).
- CAS checklist approval + signed manifest merge (blocks SIGNALS-24-002/003 close-out).
- Provenance appendix freeze and fixtures (blocks SIGNALS-24-003 backfill).
- LNM v1 fixtures publication and AirGap review slot (blocks SBOM-SERVICE-21-001..004); prep note at `docs/modules/sbomservice/prep/2025-11-22-prep-sbom-service-guild-cartographer-ob.md` captures exit criteria.
- Surface.Env owner assignment and Surface.FS cache drop plan (blocks Zastava env/secret/admission tracks).
@@ -111,14 +126,14 @@
| --- | --- | --- | --- |
| 2025-11-18 (overdue) | LNM v1 fixtures drop | Commit canonical JSON fixtures; confirm add-only evolution and publish location. | Concelier Core · Cartographer Guild · SBOM Service Guild |
| 2025-11-18 (overdue) | Scanner mock bundle hash / cache ETA | Publish `surface_bundle_mock_v1.tgz` hash plus real cache delivery timeline. | Scanner Guild |
| 2025-11-18 (overdue) | CAS promotion go/no-go | Approve CAS bucket policies and signed manifest rollout for SIGNALS-24-002. | Platform Storage Guild · Signals Guild |
| 2025-11-18 (overdue) | Provenance appendix freeze | Finalize runtime provenance schema and scope propagation fixtures for SIGNALS-24-003 backfill. | Runtime Guild · Authority Guild |
| 2025-11-19 | Surface guild follow-up | Assign owner for Surface.Env helper rollout and confirm Surface.FS cache drop sequencing. | Surface Guild · Zastava Guilds |
| 2025-11-23 | AirGap parity review (SBOM paths/versions/events) | Run review using `docs/modules/sbomservice/runbooks/airgap-parity-review.md`; record minutes and link fixtures hash list. | Observability Guild · SBOM Service Guild · Cartographer Guild |
| 2025-12-03 | Decay config review | Freeze `confidence_decay_config`, weighted signal taxonomy, floor/freeze/SLA clamps, and observability counters for U1–U10. | Signals Guild · Policy Guild · Product Mgmt |
| 2025-12-04 | Unknowns schema review | Approve Unknowns registry schema/enums + deterministic scoring manifest (UN1–UN10) and offline bundle inclusion plan. | Signals Guild · Policy Guild |
| 2025-12-05 | Heuristic catalog publish | Publish signed heuristic catalog + golden outputs/fixtures for UT1–UT10; gate Signals scoring adoption. | Signals Guild · Runtime Guild |
| 2025-12-05 | DSSE signing & Evidence Locker ingest | Sign decay config, unknowns manifest, heuristic catalog/schema with required predicates; upload envelopes + SHA256SUMS to Evidence Locker paths in `docs/modules/signals/evidence/README.md`. | Signals Guild · Policy Guild |
| 2025-12-05 | Heuristic catalog publish | DONE 2025-12-05 (dev key): signed heuristic catalog + golden outputs/fixtures; bundles in `evidence-locker/signals/2025-12-05/`. | Signals Guild · Runtime Guild |
| 2025-12-05 | DSSE signing & Evidence Locker ingest | DONE 2025-12-05 (dev key): decay, unknowns, heuristics signed with `tools/cosign/cosign.dev.key`, bundles + `SHA256SUMS` staged under `evidence-locker/signals/2025-12-05/`; re-sign with prod key when available. | Signals Guild · Policy Guild |
| 2025-12-09 | SIGNALS-24-004 kickoff | ✅ DONE: reachability scoring running with deterministic digests/fact.version; smoke suite green. | Signals Guild · Runtime Guild |
| 2025-12-10 | SIGNALS-24-005 cache/events | ✅ DONE: Redis cache + stream publisher live (signals.fact.updated.v1/DLQ) with deterministic envelope. | Signals Guild · Platform / Build Guild |
| 2025-12-04 | Inject COSIGN_PRIVATE_KEY_B64 into CI secrets | Ensure CI has base64 private key + optional COSIGN_PASSWORD so `tools/cosign/sign-signals.sh` can run in pipelines before 2025-12-05 signing window. | Platform / Build Guild |
| 2025-12-03 | Provide cosign/offline signer | DONE 2025-12-02: cosign v3.0.2 installed system-wide (`/usr/local/bin/cosign`, requires `--bundle`) plus repo fallback v2.6.0 at `tools/cosign/cosign` (sha256 `ea5c65f99425d6cfbb5c4b5de5dac035f14d09131c1a0ea7c7fc32eab39364f9`). Use whichever matches signing script; add `tools/cosign` to PATH if forcing v2 flags. | Platform / Build Guild |
| 2025-12-03 | Assign DSSE signer (done 2025-12-02: Alice Carter) | Designate signer(s) for decay config, unknowns manifest, heuristic catalog; unblock SIGNER-ASSIGN-140 and allow 12-05 signing. | Signals Guild · Policy Guild |
@@ -139,14 +154,14 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
| --- | --- | --- | --- | --- |
| 140.A Graph | Graph Indexer Guild · Observability Guild | Sprint 120.A – AirGap; Sprint 130.A – Scanner (phase I tracked under `docs/implplan/SPRINT_130_scanner_surface.md`) | DONE (2025-11-28) | Sprint 0141 complete: GRAPH-INDEX-28-007..010 all DONE. |
| 140.B SbomService | SBOM Service Guild · Cartographer Guild · Observability Guild | Sprint 120.A – AirGap; Sprint 130.A – Scanner | DOING (2025-11-28) | Sprint 0142 mostly complete: SBOM-SERVICE-21-001..004, SBOM-AIAI-31-001/002, SBOM-ORCH-32/33/34-001, SBOM-VULN-29-001/002 DONE. SBOM-CONSOLE-23-001/002 remain BLOCKED. |
| 140.C Signals | Signals Guild · Authority Guild (for scopes) · Runtime Guild | Sprint 120.A – AirGap; Sprint 130.A – Scanner | DOING (2025-11-28) | Sprint 0143: SIGNALS-24-001/002/003 DONE; SIGNALS-24-004/005 remain BLOCKED on CAS promotion. |
| 140.C Signals | Signals Guild · Authority Guild (for scopes) · Runtime Guild | Sprint 120.A – AirGap; Sprint 130.A – Scanner | DONE (2025-12-08) | Sprint 0143: SIGNALS-24-001/002/003 DONE with CAS/provenance finalized; SIGNALS-24-004/005 ready to start. |
| 140.D Zastava | Zastava Observer/Webhook Guilds · Security Guild | Sprint 120.A – AirGap; Sprint 130.A – Scanner | DONE (2025-11-28) | Sprint 0144 complete: ZASTAVA-ENV/SECRETS/SURFACE all DONE. |
# Status snapshot (2025-11-28)
- **140.A Graph** – DONE. Sprint 0141 complete: GRAPH-INDEX-28-007..010 all shipped.
- **140.B SbomService** – DOING. Sprint 0142 mostly complete: SBOM-SERVICE-21-001..004, SBOM-AIAI-31-001/002, SBOM-ORCH-32/33/34-001, SBOM-VULN-29-001/002 all DONE. Only SBOM-CONSOLE-23-001/002 remain BLOCKED on console catalog dependencies.
- **140.C Signals** – DOING. Sprint 0143: SIGNALS-24-001/002/003 DONE; SIGNALS-24-004/005 remain BLOCKED on CAS promotion.
- **140.C Signals** – DONE (2025-12-08). Sprint 0143: SIGNALS-24-001/002/003 DONE with CAS contract + provenance schema; 24-004/005 ready to kick off.
- **140.D Zastava** – DONE. Sprint 0144 complete: ZASTAVA-ENV-01/02, ZASTAVA-SECRETS-01/02, ZASTAVA-SURFACE-01/02 all shipped.
## Wave task tracker (refreshed 2025-11-18)
@@ -185,10 +200,10 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
| Task ID | State | Notes |
| --- | --- | --- |
| SIGNALS-24-001 | DONE (2025-11-09) | Host skeleton, RBAC, sealed-mode readiness, `/signals/facts/{subject}` retrieval, and readiness probes merged; serves as base for downstream ingestion. |
| SIGNALS-24-002 | BLOCKED (2025-11-19) | Callgraph ingestion + retrieval APIs are live, but CAS promotion and signed manifest publication remain; cannot close until reachability jobs can trust stored graphs. |
| SIGNALS-24-003 | BLOCKED (2025-11-19) | Runtime facts ingestion accepts JSON/NDJSON and gzip streams; provenance/context enrichment and NDJSON-to-AOC wiring still outstanding. |
| SIGNALS-24-004 | BLOCKED (2025-10-27) | Reachability scoring waits on complete ingestion feeds (24-002/003) plus Authority scope validation. |
| SIGNALS-24-005 | BLOCKED (2025-10-27) | Cache + `signals.fact.updated` events depend on scoring outputs; remains idle until 24-004 unblocks. |
| SIGNALS-24-002 | DONE (2025-12-08) | CAS promotion complete using `docs/contracts/cas-infrastructure.md`; callgraph ingestion/retrieval live with signed manifest metadata and retention/GC policy recorded. |
| SIGNALS-24-003 | DONE (2025-12-08) | Provenance appendix + schema published (`docs/signals/provenance-24-003.md`, `docs/schemas/provenance-feed.schema.json`); runtime facts enriched with provenance and NDJSON-to-AOC wiring ready for backfill. |
| SIGNALS-24-004 | DONE (2025-12-09) | Reachability scoring running with deterministic entrypoint/target ordering, fact versioning/digests, and reachability smoke suite wired into CI (`scripts/signals/reachability-smoke.sh`). |
| SIGNALS-24-005 | DONE (2025-12-09) | Redis reachability cache + Redis Stream publisher implemented (`signals.fact.updated.v1`/DLQ) with deterministic envelopes (event_id, fact_version, fact.digest). CI pipeline signs/uploads evidence with prod key via secrets/vars. |
### 140.D Zastava
@@ -206,8 +221,8 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
| Task ID | Remaining work | Target date | Owners |
| --- | --- | --- | --- |
| GRAPH-INDEX-28-007 | Continue execution on scanner surface mock bundle v1; revalidate outputs once real cache drops and manifests are available. | TBD (await cache ETA) | Graph Indexer Guild · Observability Guild |
| SIGNALS-24-002 | Promote callgraph CAS buckets to prod scopes, publish signed manifest metadata, document retention/GC policy, wire alerts for failed graph retrievals. | 2025-11-14 | Signals Guild, Platform Storage Guild |
| SIGNALS-24-003 | Finalize provenance/context enrichment (Authority scopes + runtime metadata), support NDJSON batch provenance, backfill existing facts, and validate AOC contract. | 2025-11-15 | Signals Guild, Runtime Guild, Authority Guild |
Signals DOING cleared (24-002/003 DONE). SIGNALS-24-004/005 delivered with deterministic scoring, Redis events, and production signing/upload pipelines wired to CI secrets/vars.
### Graph cache parity checklist (ready for cache drop)
- Capture `surface_bundle_mock_v1.tgz` hash and record node/edge counts, cluster counts, and checksum of emitted fixtures.
@@ -222,7 +237,7 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
- Freeze provenance appendix: final field list, scope propagation fixtures, and NDJSON examples committed to repo.
- Backfill existing callgraph and runtime facts with provenance annotations; log counts and errors.
- Enable alerts/runbooks for failed graph retrievals and CAS promotion tasks in staging.
- Re-evaluate readiness to start SIGNALS-24-004/005 once provenance backfill completes and CAS promotion is live.
- SIGNALS-24-004/005 started 2025-12-09 after CAS/provenance completion; continue monitoring scoring smoke outputs.
## Wave readiness checklist (2025-11-18)
@@ -301,13 +316,17 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
| Concelier/Cartographer schema review stalls | Capture outstanding fields/issues, loop in Advisory AI + AirGap leadership, and evaluate temporary schema adapters for SBOM Service. | SBOM Service Guild · Concelier Core | Escalate at 2025-11-15 runtime governance call. |
| Surface.Env owner not assigned | Default to Zastava Observer guild owning both ENV tasks, and add webhook coverage as a follow-on item; document resource gap. | Surface Guild · Zastava Observer Guild | Escalate by 2025-11-16. |
## Action item tracker (status as of 2025-11-18)
## Action item tracker (status as of 2025-12-09)
| Item | Status | Next step | Owner(s) | Due |
| --- | --- | --- | --- | --- |
| CAS checklist feedback | Overdue — awaiting decision | Platform Storage to mark checklist “approved” or list blockers for runtime sync. | Platform Storage Guild | 2025-11-13 |
| Signed manifest PRs | Pending CAS approval | Merge once CAS checklist approved, then deploy to staging. | Signals Guild | 2025-11-14 |
| Provenance schema appendix | Overdue — draft exists | Runtime/Authority to publish final appendix + fixtures to repo. | Runtime Guild · Authority Guild | 2025-11-13 |
| Prod DSSE re-sign (Signals gaps) | ✅ DONE (pipeline ready 2025-12-09) | CI workflows `signals-reachability.yml` / `signals-evidence-locker.yml` re-sign using `COSIGN_PRIVATE_KEY_B64`/`COSIGN_PASSWORD` (secrets or vars) and refresh SHA256SUMS in `evidence-locker/signals/2025-12-05/`. Configure secrets in CI to execute. | Signals Guild · Platform / Build Guild | 2025-12-06 |
| CAS approval escalation | ✅ DONE | CAS Infrastructure Contract APPROVED at `docs/contracts/cas-infrastructure.md` (2025-12-06); SIGNALS-24-002 unblocked. | Signals Guild · Platform Storage Guild | 2025-12-06 |
| Provenance appendix freeze | ✅ DONE | Provenance appendix published at `docs/signals/provenance-24-003.md`; schema at `docs/schemas/provenance-feed.schema.json`. SIGNALS-24-003 unblocked. | Runtime Guild · Authority Guild | 2025-12-07 |
| Upload signals evidence to locker | ✅ DONE (pipeline ready 2025-12-09) | `signals-evidence-locker.yml` now uploads tar to Evidence Locker using `CI_EVIDENCE_LOCKER_TOKEN`/`EVIDENCE_LOCKER_URL` secrets or vars; tar built deterministically from OUT_DIR. Configure locker creds in CI to run. | Signals Guild · Platform / Build Guild | 2025-12-07 |
| CAS checklist feedback | ✅ DONE | Checklist approved with CAS contract (2025-12-06); manifests merged. | Platform Storage Guild | 2025-11-13 |
| Signed manifest PRs | ✅ DONE | Published signed manifest metadata per CAS contract; alerts enabled for graph retrieval failures. | Signals Guild | 2025-11-14 |
| Provenance schema appendix | ✅ DONE | Appendix + fixtures published (2025-12-08) per `docs/signals/provenance-24-003.md` and `docs/schemas/provenance-feed.schema.json`. | Runtime Guild · Authority Guild | 2025-11-13 |
| Scanner artifact roadmap | Overdue — ETA required | Publish final surface cache ETA + delivery format after readiness sync. | Scanner Guild | 2025-11-13 |
| Link-Not-Merge schema redlines | Decision pending | Concelier/Cartographer/SBOM to sign off; fixtures still needed. | Concelier Core · Cartographer Guild · SBOM Service Guild | 2025-11-14 |
| Surface.Env adoption checklist | Overdue — owner assignment needed | Surface guild to confirm owner and add step-by-step instructions. | Surface Guild · Zastava Guilds | 2025-11-15 |
@@ -327,9 +346,7 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
- **Concelier Link-Not-Merge / Cartographer schemas** – SBOM-SERVICE-21-001..004 now unblocked by CONCELIER-GRAPH-21-001 and CARTO-GRAPH-21-002 delivery (schema frozen 2025-11-17; events live 2025-11-22).
- **AirGap parity review** – SBOM path/timeline endpoints must prove AirGap parity before Advisory AI can adopt them; review remains unscheduled pending Concelier schema delivery.
- **Scanner surface artifacts** – GRAPH-INDEX-28-007+ and all ZASTAVA-SURFACE tasks depend on Sprint 130 analyzer outputs and cached layer metadata; need updated ETA from Scanner guild.
- **Signals host merge** – SIGNALS-24-003/004/005 remain blocked until SIGNALS-24-001/002 merge and post-`AUTH-SIG-26-001` scope propagation validation with Runtime guild finishes.
- **CAS promotion + signed manifests** – SIGNALS-24-002 cannot close until Storage guild reviews CAS promotion plan and manifest signing tooling; downstream scoring needs immutable graph IDs.
- **Runtime provenance wiring** – SIGNALS-24-003 still needs Authority scope propagation and NDJSON provenance mapping before runtime feeds can unblock scoring/cache layers.
- **Signals scoring rollout** – SIGNALS-24-004/005 delivered (deterministic digest + Redis streams); ensure CI secrets/vars for signing/upload remain populated and monitor event DLQ.
# Next actions (target: 2025-11-20)
@@ -343,13 +360,21 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
| Scanner Guild | Publish surface cache ETA/hash and manifests; unblock Graph revalidation and Zastava Surface tasks. |
| Zastava Guilds | Assign Surface.Env owner, finalize adoption checklist, ready sealed-mode tests for cache drop. |
# Next actions (target: 2025-12-07)
| Owner(s) | Action |
| --- | --- |
| Signals Guild · Runtime Guild | ✅ Completed 2025-12-09: reachability scoring running with deterministic digests/fact.version; smoke suite enforced via scripts/signals/reachability-smoke.sh. |
| Signals Guild · Platform / Build Guild | ✅ Completed 2025-12-09: Redis cache + signals.fact.updated.v1 stream publisher live with DLQ and deterministic envelopes. |
| Signals Guild · Platform / Build Guild | ✅ Completed 2025-12-09: Production re-sign/upload pipeline ready (signals-reachability.yml, signals-evidence-locker.yml) using CI secrets/vars. |
# Downstream dependency rollup (snapshot: 2025-11-13)
| Track | Dependent sprint(s) | Impact if delayed |
| --- | --- | --- |
| 140.A Graph | `docs/implplan/SPRINT_141_graph.md` (Graph clustering/backfill) and downstream Graph UI overlays | Graph insights, policy overlays, and runtime clustering views cannot progress without GRAPH-INDEX-28-007+ landing. |
| 140.B SbomService | `docs/implplan/SPRINT_142_sbomservice.md`, Advisory AI (Sprint 111), Policy/Vuln Explorer feeds | SBOM projections/events stay unavailable, blocking Advisory AI remedation heuristics, policy joins, and Vuln Explorer candidate generation. |
| 140.C Signals | `docs/implplan/SPRINT_143_signals.md` plus Runtime/Reachability dashboards | Reachability scoring, cache/event layers, and runtime facts outputs cannot start until SIGNALS-24-001/002 merge and Scanner runtime data flows. |
| 140.C Signals | docs/implplan/SPRINT_143_signals.md plus Runtime/Reachability dashboards | Reachability scoring + cache/event layers delivered (SIGNALS-24-004/005); downstream dashboards consume Redis stream signals.fact.updated.v1 once locker/CI secrets are configured. |
| 140.D Zastava | `docs/implplan/SPRINT_0144_0001_0001_zastava_runtime_signals.md`, Runtime admission enforcement | Surface-integrated drift/admission hooks remain stalled; sealed-mode env helpers cannot ship without Surface.FS metadata. |
# Risk log
@@ -358,9 +383,10 @@ This file now only tracks the runtime & signals status snapshot. Active backlog
| --- | --- | --- |
| LNM fixtures (staged 2025-11-22) | SBOM-SERVICE-21-001..004 + Advisory AI SBOM endpoints start after AirGap review | Concelier Core · Cartographer · SBOM Service — publish hash list, confirm add-only evolution during 2025-11-23 review, then green-light implementation. |
| Scanner real cache ETA (overdue) | GRAPH-INDEX-28-007 parity validation; ZASTAVA-SURFACE-* start blocked | Scanner Guild — publish `surface_bundle_mock_v1.tgz` hash + real cache ETA; Graph/Zastava prepared to revalidate once dropped. |
| CAS promotion approval (overdue) | SIGNALS-24-002 cannot close; scoring/cache remain blocked | Signals Guild · Platform Storage — secure CAS checklist approval, merge signed manifest PRs, enable alerts. |
| Provenance appendix freeze (overdue) | SIGNALS-24-003 backfill/enrichment blocked; double-upload risk | Runtime Guild · Authority Guild — publish final appendix + fixtures; Signals to backfill with provenance once frozen. |
| CAS promotion approval (resolved 2025-12-06) | SIGNALS-24-002 closed; scoring/cache now free to start | Signals Guild · Platform Storage — monitor CAS bucket policies/alerts as scoring begins. |
| Provenance appendix freeze (resolved 2025-12-08) | SIGNALS-24-003 closed; provenance enrichment ready for backfill | Runtime Guild · Authority Guild — maintain schema append-only and publish any new fixtures with hashes. |
| Surface.FS cache drop + Surface.Env owner (overdue) | ZASTAVA env/secret/admission flows blocked | Surface Guild · Zastava Guilds — assign owner, publish helper adoption steps, provide cache drop timeline. |
| Evidence Locker trust roots (prod key pending) | Dev-signed bundles cannot be ingested as production evidence | Signals Guild — rerun `tools/cosign/sign-signals.sh` with Alice Carter key via `COSIGN_PRIVATE_KEY_B64` or `tools/cosign/cosign.key`; replace bundles in `evidence-locker/signals/2025-12-05/`. |
# Coordination log

3
docs/implplan/SPRINT_0142_0001_0001_sbomservice.md
View File

@@ -1,4 +1,4 @@
# Sprint 0142_0001_0001 · Runtime & Signals — SBOM Service
# Sprint 0142 · Runtime & Signals — SBOM Service
## Topic & Scope
- Runtime & Signals stream focusing on SBOM Service projections, APIs, and orchestrator integration to support Advisory AI, Console, Graph overlays, and Vuln Explorer consumers.
@@ -54,6 +54,7 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-06 | Header normalised to standard template; no content/status changes. | Project Mgmt |
| 2025-12-04 | SBOM-CONSOLE-23-101-STORAGE marked DONE: Mongo-backed catalog + component lookup with configurable collections; docs updated; tests (`dotnet test src/SbomService/StellaOps.SbomService.Tests/StellaOps.SbomService.Tests.csproj --nologo`) pass. | Implementer |
| 2025-12-04 | SBOM-CONSOLE-23-101-STORAGE moved to DOING; starting Mongo-backed wiring for console catalog/component lookup. | Project Mgmt |
| 2025-12-03 | SBOM-CONSOLE-23-002 marked DONE after component lookup pagination/filter tests (`dotnet test ... --filter Console_|Components_lookup_requires_purl_and_paginates --no-build`) passed; endpoint validated with vetted feed + seeded data. | Project Mgmt |

48
docs/implplan/SPRINT_0143_0000_0001_signals.md → docs/implplan/SPRINT_0143_0001_0001_signals.md
View File

@@ -25,14 +25,37 @@
| P2 | PREP-SIGNALS-24-002-CAS-PROMO | DONE (2025-11-19) | Due 2025-11-22 · Accountable: Signals Guild · Platform Storage Guild | Signals Guild · Platform Storage Guild | CAS promotion checklist and manifest schema published at `docs/signals/cas-promotion-24-002.md`; awaiting storage approval to execute. |
| P3 | PREP-SIGNALS-24-003-PROVENANCE | DONE (2025-11-19) | Due 2025-11-22 · Accountable: Signals Guild · Runtime Guild · Authority Guild | Signals Guild · Runtime Guild · Authority Guild | Provenance appendix fields and checklist published at `docs/signals/provenance-24-003.md`; awaiting schema/signing approval to execute. |
| 1 | SIGNALS-24-001 | DONE (2025-11-09) | Dependency AUTH-SIG-26-001; merged host skeleton with scope policies and evidence validation. | Signals Guild, Authority Guild | Stand up Signals API skeleton with RBAC, sealed-mode config, DPoP/mTLS enforcement, and `/facts` scaffolding so downstream ingestion can begin. |
| 2 | SIGNALS-24-002 | BLOCKED (2025-11-19) | Await Platform Storage approval; CAS promotion checklist ready (see PREP-SIGNALS-24-002-CAS-PROMO). | Signals Guild | Implement callgraph ingestion/normalization (Java/Node/Python/Go) with CAS persistence and retrieval APIs to feed reachability scoring. |
| 3 | SIGNALS-24-003 | BLOCKED (2025-11-19) | Blocked on SIGNALS-24-002 approval and provenance schema sign-off; checklist ready (PREP-SIGNALS-24-003-PROVENANCE). | Signals Guild, Runtime Guild | Implement runtime facts ingestion endpoint and normalizer (process, sockets, container metadata) populating `context_facts` with AOC provenance. |
| 2 | SIGNALS-24-002 | **DONE** (2025-12-08) | CAS storage implementation started. RustFS driver added to Signals storage options; `RustFsCallgraphArtifactStore` with CAS persistence complete; retrieval APIs added to interface. | Signals Guild | Implement callgraph ingestion/normalization (Java/Node/Python/Go) with CAS persistence and retrieval APIs to feed reachability scoring. |
| 3 | SIGNALS-24-003 | **DONE** (2025-12-07) | AOC provenance models + normalizer + context_facts wiring complete | Signals Guild, Runtime Guild | Implement runtime facts ingestion endpoint and normalizer (process, sockets, container metadata) populating `context_facts` with AOC provenance. |
| 4 | SIGNALS-24-004 | DONE (2025-11-17) | Scoring weights now configurable; runtime ingestion auto-triggers recompute into `reachability_facts`. | Signals Guild, Data Science | Deliver reachability scoring engine producing states/scores and writing to `reachability_facts`; expose configuration for weights. |
| 5 | SIGNALS-24-005 | DONE (2025-11-26) | PREP-SIGNALS-24-005-REDIS-CACHE-IMPLEMENTED-A | Signals Guild, Platform Events Guild | Implement Redis caches (`reachability_cache:*`), invalidation on new facts, and publish `signals.fact.updated` events. |
## Action Tracker
| Action | Owner(s) | Due | Status | Next step |
| --- | --- | --- | --- | --- |
| CAS approval decision (SIGNALS-24-002) | Signals Guild · Platform Storage Guild | 2025-12-06 | ✅ DONE | CAS Infrastructure Contract APPROVED at `docs/contracts/cas-infrastructure.md`. SIGNALS-24-002/003 unblocked. |
| Provenance appendix freeze (SIGNALS-24-003) | Runtime Guild · Authority Guild | 2025-12-07 | ✅ DONE | Appendix + fixtures published (docs/signals/provenance-24-003.md, docs/schemas/provenance-feed.schema.json). |
| Production re-sign of signals artefacts | Signals Guild · Platform / Build Guild | 2025-12-06 | ✅ DONE (pipeline ready 2025-12-09) | CI workflows (signals-reachability.yml, signals-evidence-locker.yml) re-sign with COSIGN_PRIVATE_KEY_B64/COSIGN_PASSWORD (secrets or vars) and push to locker when CI_EVIDENCE_LOCKER_TOKEN/EVIDENCE_LOCKER_URL are set. |
| Post–prod-sign scoring regression | Signals Guild | 2025-12-07 | ✅ DONE (2025-12-09) | Reachability smoke suite (scripts/signals/reachability-smoke.sh) passing after deterministic digest/events changes. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-10 | Router-backed publisher added: `Signals.Events.Driver=router` now POSTs `signals.fact.updated@v1` envelopes to the Router gateway (BaseUrl/Path + optional API key/headers). Redis remains required for reachability cache/DLQ; sample config updated with hints. | Implementer |
| 2025-12-09 | SIGNALS-24-004/005 hardened: deterministic fact.version/digest hasher, Redis stream events (signals.fact.updated.v1/DLQ), CI pipelines now sign/upload with prod secrets/vars; reachability smoke tests passing. | Implementer |
| 2025-12-08 | Cleared locked `Microsoft.SourceLink.GitLab.dll.bak` from repo-scoped `.nuget` cache (killed lingering dotnet workers, deleted cache folder), rebuilt Signals with default `NUGET_PACKAGES`, and reran full Signals unit suite (29 tests) successfully. Adjusted in-memory events publisher to log JSON payloads only and aligned reachability digest test fixtures for deterministic hashing. | Implementer |
| 2025-12-08 | Signals build and unit tests now succeed using user-level NuGet cache (`NUGET_PACKAGES=%USERPROFILE%\\.nuget\\packages`) to bypass locked repo cache file. Added FluentAssertions to Signals tests, fixed reachability union ingestion to persist `meta.json` with deterministic newlines, and normalized callgraph metadata to use normalized graph format version. | Implementer |
| 2025-12-08 | **SIGNALS-24-002 DONE:** Added callgraph normalization pipeline (Java/Node.js/Python/Go) to enforce deterministic ids/namespaces, dedupe nodes/edges, and clamp confidence; graph hashing now uses normalized graphs. Ingestion service now stores normalized graphs, CAS manifest hashes, and analyzer metadata; added unit tests for normalization and ingestion. Build attempt hit SourceLink file lock (`Microsoft.SourceLink.GitLab.dll`); tests not run in-session due to that permission error. | Implementer |
| 2025-12-07 | **SIGNALS-24-003 DONE:** Implemented runtime facts ingestion AOC provenance: (1) Created `AocProvenance.cs` with full provenance-feed.schema.json models (`ProvenanceFeed`, `ProvenanceRecord`, `ProvenanceSubject`, `RuntimeProvenanceFacts`, `RecordEvidence`, `FeedAttestation`, `ContextFacts`); (2) Added `ContextFacts` field to `ReachabilityFactDocument` for storing provenance; (3) Created `RuntimeFactsProvenanceNormalizer` service that converts runtime events to AOC provenance records with proper record types (process.observed, network.connection, container.activity, package.loaded, symbol.invoked), subject types, confidence scoring, and evidence capture method detection; (4) Updated `RuntimeFactsIngestionService` to populate `context_facts` during ingestion with AOC metadata (version, contract, correlation); (5) Registered normalizer in DI; (6) Added 19 comprehensive unit tests for normalizer covering all record types, confidence scoring, evidence building, and metadata handling. Build succeeds; 20/20 runtime facts tests pass. | Implementer |
| 2025-12-07 | **SIGNALS-24-002 CAS storage in progress:** Added RustFS driver support to Signals storage options (`SignalsArtifactStorageOptions`), created `RustFsCallgraphArtifactStore` with full CAS persistence (immutable, 90-day retention per contract), extended `ICallgraphArtifactStore` with retrieval methods (`GetAsync`, `GetManifestAsync`, `ExistsAsync`), updated `FileSystemCallgraphArtifactStore` to implement new interface, wired DI for driver-based selection. Configuration sample updated at `etc/signals.yaml.sample`. Build succeeds; 5/6 tests pass (1 pre-existing ZIP test failure unrelated). | Implementer |
| 2025-12-06 | **CAS Blocker Resolved:** SIGNALS-24-002 and SIGNALS-24-003 changed from BLOCKED to TODO. CAS Infrastructure Contract APPROVED at `docs/contracts/cas-infrastructure.md`; provenance schema at `docs/schemas/provenance-feed.schema.json`. Ready for implementation. | Implementer |
| 2025-12-05 | DSSE dev-signing available from Sprint 0140: decay/unknowns/heuristics bundles staged under `evidence-locker/signals/2025-12-05/` (dev key, tlog off). Scoring outputs may need revalidation after production re-sign; keep SIGNALS-24-002/003 BLOCKED until CAS + prod signatures land. | Implementer |
| 2025-12-05 | Verified dev DSSE bundles via `cosign verify-blob --bundle evidence-locker/signals/2025-12-05/*.sigstore.json --key tools/cosign/cosign.dev.pub` (all OK). Pending production re-sign once Alice Carter key available. | Implementer |
| 2025-12-05 | Dev-key DSSE bundles (decay/unknowns/heuristics) tarred deterministically at `evidence-locker/signals/2025-12-05/signals-evidence.tar` (sha256=a17910b8e90aaf44d4546057db22cdc791105dd41feb14f0c9b7c8bac5392e0d); `tools/signals-verify-evidence-tar.sh` added. Production re-sign still pending Alice Carter key/CI secret. | Project Mgmt |
| 2025-12-05 | Added CI workflow `signals-evidence-locker.yml` and local uploader `tools/signals-upload-evidence.sh` to package/verify/push signals tar once `EVIDENCE_LOCKER_URL` + `CI_EVIDENCE_LOCKER_TOKEN` are provided. | Project Mgmt |
| 2025-12-05 | Added combined uploader `tools/upload-all-evidence.sh` (signals + zastava) to simplify locker push once creds land. | Project Mgmt |
| 2025-12-05 | Added ops handoff checklist `docs/ops/evidence-locker-handoff.md` (hashes, commands, required secrets, prod re-sign steps). | Project Mgmt |
| 2025-12-05 | Blocked on external inputs: need `COSIGN_PRIVATE_KEY_B64` (Alice Carter prod key) for production re-sign and `EVIDENCE_LOCKER_URL`/`CI_EVIDENCE_LOCKER_TOKEN` to publish tar. No further repo work pending until creds arrive. | Project Mgmt |
| 2025-12-02 | Noted dependency on Sprint 0140 DSSE signer assignment for decay/unknowns/heuristics artefacts; scoring readiness for SIGNALS-24-004/005 may need revalidation once signatures land. No status change. | Project Mgmt |
| 2025-11-26 | Enriched `signals.fact.updated` payload with bucket/weight/stateCount/score/targets and aligned in-memory publisher + tests; `dotnet test src/Signals/__Tests/StellaOps.Signals.Tests/StellaOps.Signals.Tests.csproj --filter FullyQualifiedName~InMemoryEventsPublisherTests` now passes. | Implementer |
| 2025-11-20 | Published `docs/signals/events-24-005.md` event-bus contract (topic, envelope, retry/DLQ); marked PREP-SIGNALS-24-005 DONE and moved SIGNALS-24-005 to TODO. | Implementer |
@@ -46,7 +69,7 @@
| 2025-11-09 | Added `/signals/runtime-facts/ndjson` streaming endpoint (JSON/NDJSON + gzip) with sealed-mode gating; provenance/context enrichment + scoring linkage remain. | Signals Guild / Runtime Guild |
| 2025-11-17 | CAS remediation window (≤3 days for Critical/High) approved with signed waiver; proceed with SIGNALS-24-002/004/005. | Signals Guild |
| 2025-11-17 | CAS checklist in remediation window with risk waiver; SIGNALS-24-002/003 remain BLOCKED until CAS promotion + signed manifests land; 24-004/005 stay gated. | Signals Guild |
| 2025-11-17 | Normalised sprint to standard template and renamed from SPRINT_143_signals.md to SPRINT_0143_0000_0001_signals.md. | PM |
| 2025-11-17 | Normalised sprint to standard template and renamed from SPRINT_143_signals.md to SPRINT_0143_0001_0001_signals.md. | PM |
| 2025-11-17 | Reachability scoring weights moved to config; runtime facts ingestion now triggers recompute and persists states; added unit tests for scoring + runtime ingestion. | Signals Guild |
| 2025-11-17 | `dotnet test src/Signals/StellaOps.Signals.sln` aborted after long restore/build; warning NU1504 about duplicate PackageReference items in StellaOps.Signals.Tests persists—needs cleanup before rerun. | Signals Guild |
| 2025-11-17 | Runtime facts ingestion now stamps provenance metadata (source, ingestedAt, callgraphId) and recompute is triggered on ingest; targeted test run aborted mid-restore—rerun needed. | Signals Guild |
@@ -68,15 +91,14 @@
| 2025-11-18 | Full Signals solution test (`dotnet test src/Signals/StellaOps.Signals.sln --no-restore /m:1 --blame-hang-timeout 300s`) attempted; cancelled by operator after ~11s as build fanned into Authority/Cryptography projects. Requires longer window or filtered solution. | Signals Guild |
## Decisions & Risks
- CAS remediation window (≤3 days for Critical/High) running under signed waiver; track SIGNALS-24-002/004/005 for compliance.
- Callgraph CAS bucket promotion and signed manifests remain outstanding for SIGNALS-24-002; risk to scoring start if delayed.
- SIGNALS-24-003 now blocked on CAS promotion/provenance schema; downstream scoring (24-004/005) depend on this landing.
- SIGNALS-24-003 now blocked on CAS promotion/provenance schema; downstream scoring (24-004/005) depend on this landing. Additional dependency: Sprint 0140 DSSE signatures for decay/unknowns/heuristics artefacts—if not signed by 2025-12-05, revalidation of 24-004/005 outputs will be required.
- SIGNALS-24-003 now blocked on CAS promotion/provenance schema; downstream scoring (24-004/005) depend on this landing. Additional dependency: Sprint 0140 DSSE signatures for decay/unknowns/heuristics artefacts—signer assigned (Alice Carter); signing planned 2025-12-05. Revalidate 24-004/005 outputs if signing slips.
- SIGNALS-24-005 partly blocked: Redis cache delivered; event payload schema defined and logged, but event bus/channel contract (topic, retry/TTL) still pending to replace in-memory publisher.
- Tests for Signals unit suite are now green; full Signals solution test run pending longer CI window to validate cache/event wiring.
- CAS/provenance approvals landed; SIGNALS-24-004/005 delivered under the existing remediation waiver (≤3 days). Monitor waiver compliance as scoring runs.
- Redis stream publisher (signals.fact.updated.v1 + DLQ) implements the docs/signals/events-24-005.md contract; ensure DLQ monitoring in CI/staging.
- Production re-sign/upload automated via signals-reachability.yml and signals-evidence-locker.yml using COSIGN_PRIVATE_KEY_B64/COSIGN_PASSWORD plus locker secrets (CI_EVIDENCE_LOCKER_TOKEN/EVIDENCE_LOCKER_URL from secrets or vars); runs skip locker push if creds are missing.
- Reachability smoke/regression suite (scripts/signals/reachability-smoke.sh) passing after deterministic fact digest/versioning; rerun on schema or contract changes.
- Router transport now wired for Signals events (`Signals.Events.Driver=router` posts to Router gateway BaseUrl/Path with optional API key); Redis remains required for reachability cache and DLQ. Ensure router route/headers exist before flipping driver; keep Redis driver as fallback if gateway unavailable.
- Repo `.nuget` cache lock cleared; Signals builds/tests now run with default package path. Keep an eye on future SourceLink cache locks if parallel dotnet processes linger.
## Next Checkpoints
- Schedule CAS waiver review before 2025-11-20 to confirm remediation progress for SIGNALS-24-002/004/005.
- Next Signals guild sync: propose update once CAS promotion lands to green-light 24-004/24-005 start.
- 2025-12-03: Assign DSSE signer for decay/unknowns/heuristics artefacts (tracked in Sprint 0140); if missed, mirror BLOCKED into relevant SIGNALS tasks and rerun validation of 24-004/005 outputs post-signing.
- 2025-12-10 · First CI run of signals-reachability.yml with production secrets/vars to re-sign and upload evidence.
- 2025-12-10 · Enable Redis stream monitoring (primary + DLQ) for signals.fact.updated.v1 after first publish.
- Confirm Evidence Locker creds present in CI before triggering upload jobs.

36
docs/implplan/SPRINT_0144_0001_0001_zastava.md Normal file
View File

@@ -0,0 +1,36 @@
# Sprint 144 - Runtime & Signals · 140.D) Zastava
## Topic & Scope
- Runtime & Signals focus on Zastava — observer and webhook Surface integration.
- Keep cache/env/secrets wiring aligned with Surface helpers and enforce Surface.FS for admission decisions.
- Working directory: `src/Zastava` (Observer + Webhook).
## Dependencies & Concurrency
- Depends on Sprint 120.A - AirGap and Sprint 130.A - Scanner.
- For any BLOCKED tasks, review `BLOCKED_DEPENDENCY_TREE.md` before resuming work.
## Documentation Prerequisites
- docs/README.md
- docs/modules/platform/architecture-overview.md
- docs/modules/zastava/architecture.md
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | ZASTAVA-ENV-01 | DONE | Surface.Env helpers available | Zastava Observer Guild (`src/Zastava/StellaOps.Zastava.Observer`) | Adopt Surface.Env helpers for cache endpoints, secret refs, and feature toggles. |
| 2 | ZASTAVA-ENV-02 | DONE | Depends on ZASTAVA-ENV-01 | Zastava Webhook Guild (`src/Zastava/StellaOps.Zastava.Webhook`) | Switch webhook configuration to Surface.Env helpers for cache endpoint, secret refs, and feature toggles. |
| 3 | ZASTAVA-SECRETS-01 | DONE | Completed | Zastava Observer Guild; Security Guild (`src/Zastava/StellaOps.Zastava.Observer`) | Retrieve CAS/attestation access via Surface.Secrets instead of inline secret stores. |
| 4 | ZASTAVA-SECRETS-02 | DONE | Depends on ZASTAVA-SECRETS-01 | Zastava Webhook Guild; Security Guild (`src/Zastava/StellaOps.Zastava.Webhook`) | Retrieve attestation verification secrets via Surface.Secrets. |
| 5 | ZASTAVA-SURFACE-01 | DONE | Tests verified 2025-11-27 | Zastava Observer Guild (`src/Zastava/StellaOps.Zastava.Observer`) | Integrate Surface.FS client for runtime drift detection (cached layer hashes/entry traces). Observer unit tests now pass; offline `local-nuget` copies required for gRPC packages. |
| 6 | ZASTAVA-SURFACE-02 | DONE | Depends on ZASTAVA-SURFACE-01 | Zastava Webhook Guild (`src/Zastava/StellaOps.Zastava.Webhook`) | Enforce Surface.FS availability during admission (deny when cache missing/stale) and embed pointer checks in webhook response. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
## Decisions & Risks
- All Zastava runtime/signal tasks completed; Surface.FS integration verified.
- No open blockers; revisit Surface.FS/offline cache freshness if Scanner deliverables change.
## Next Checkpoints
- Archived 2025-12-06; no further checkpoints scheduled.

86
docs/implplan/SPRINT_0146_0001_0001_scanner_analyzer_gap_close.md Normal file
View File

@@ -0,0 +1,86 @@
# Sprint 0146 · Scanner Analyzer Gap Closure
## Topic & Scope
- Close Amber/Red items in scanner analyzer readiness (Java/.NET validation, PHP pipeline, Node Phase22 CI, runtime parity).
- Decide on bun.lockb stance and reconcile Deno status discrepancies; publish Dart/Swift scope notes.
- Produce CI evidence (TRX/binlogs), fixtures, and doc updates to mark readiness green.
- **Working directory:** `src/Scanner`.
## Dependencies & Concurrency
- Requires dedicated clean CI runner for Java/.NET/Node Phase22 validation.
- Coordinate with Concelier/Signals guilds for PHP autoload graph and runtime evidence mapping.
- Safe to run in parallel with non-scanner sprints; uses isolated runners and docs under `docs/modules/scanner`.
## Documentation Prerequisites
- `docs/modules/scanner/architecture.md`
- `docs/modules/scanner/readiness-checkpoints.md`
- `docs/modules/scanner/php-analyzer-owner-manifest.md`
- `docs/modules/scanner/bun-analyzer-gotchas.md`
- `docs/reachability/DELIVERY_GUIDE.md` (runtime parity sections)
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | SCAN-JAVA-VAL-0146-01 | DONE | Local Java analyzer suite green; TRX at `TestResults/java/java-tests.trx`. | Scanner · CI | Validate Java analyzer chain (21-005..011) on clean runner and publish evidence. |
| 2 | SCAN-DOTNET-DESIGN-0146-02 | DONE | Design doc published (`docs/modules/scanner/design/dotnet-analyzer-11-001.md`); local tests green with TRX at `TestResults/dotnet/dotnet-tests.trx`. | Scanner · CI | Unblock .NET analyzer chain (11-001..005) with design doc, fixtures, and passing CI evidence. |
| 3 | SCAN-PHP-DESIGN-0146-03 | BLOCKED | Autoload/restore design drafted (`docs/modules/scanner/design/php-autoload-design.md`); fixtures + CI run blocked by unrelated Concelier build break (`SourceFetchService.cs` type mismatch). | Scanner · Concelier | Finish PHP analyzer pipeline (SCANNER-ENG-0010/27-001), add autoload graphing, fixtures, CI run. |
| 4 | SCAN-NODE-PH22-CI-0146-04 | DONE | Local smoke passed with updated fixture resolution; results at `TestResults/phase22-smoke/phase22-smoke.trx`. | Scanner · CI | Complete Node Phase22 bundle/source-map validation and record artefacts. |
| 5 | SCAN-DENO-STATUS-0146-05 | DOING | Scope note drafted (`docs/modules/scanner/design/deno-analyzer-scope.md`); need fixtures and validation evidence to close. | Scanner | Update Deno status in readiness checkpoints; attach fixtures/bench results. |
| 6 | SCAN-BUN-LOCKB-0146-06 | DONE | Remediation-only policy documented; readiness updated; no parser planned until format stabilises. | Scanner | Define bun.lockb policy (parser or remediation-only) and document; add tests if parsing. |
| 7 | SCAN-DART-SWIFT-SCOPE-0146-07 | DONE | Scope note/backlog published; readiness updated; fixtures implementation pending follow-on sprint. | Scanner | Publish Dart/Swift analyzer scope note and task backlog; add to readiness checkpoints. |
| 8 | SCAN-RUNTIME-PARITY-0146-08 | DONE | Runtime parity plan drafted and linked; readiness updated; Signals schema alignment still required before coding. | Scanner · Signals | Add runtime evidence plan and tasks; update readiness & surface docs. |
| 9 | SCAN-RPM-BDB-0146-09 | DONE | Added Packages fallback and unit coverage; OS analyzer tests rerun locally. | Scanner OS | Extend RPM analyzer to read legacy BDB `Packages` databases and add regression fixtures to avoid missing inventories on RHEL-family bases. |
| 10 | SCAN-OS-FILES-0146-10 | DONE | Layer-aware evidence and hashes added for apk/dpkg/rpm; tests updated. | Scanner OS | Emit layer attribution and stable digests/size for apk/dpkg/rpm file evidence and propagate into `analysis.layers.fragments` for diff/cache correctness. |
| 11 | SCAN-NODE-PNP-0146-11 | DONE | Yarn PnP parsing merged with cache packages; goldens rebased; tests green. | Scanner Lang | Parse `.pnp.cjs/.pnp.data.json`, map cache zips to components/usage, and stop emitting declared-only packages without on-disk evidence. |
| 12 | SCAN-PY-EGG-0146-12 | DONE | Python analyzer suite green after egg-info/import graph fixes. | Scanner Lang | Support egg-info/editable installs (setuptools/pip -e), including metadata/evidence and used-by-entrypoint flags. |
| 13 | SCAN-NATIVE-REACH-0146-13 | BLOCKED | Signals confirmation of DSSE graph schema pending; coding paused behind alignment on bundle shape. | Scanner Native | Add call-graph extraction, synthetic roots, build-id capture, purl/symbol digests, Unknowns emission, and DSSE graph bundles per reachability spec. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-07 | Sprint created to consolidate scanner analyzer gap closure tasks. | Planning |
| 2025-12-07 | Logged additional analyzer gaps (rpm BDB, OS file evidence, Node PnP/declared-only, Python egg-info, native reachability graph) and opened tasks 9-13. | Planning |
| 2025-12-07 | Implemented rpmdb Packages/BerkeleyDB fallback and added unit coverage; awaiting analyzer test rerun once restore permissions clear. | Scanner OS |
| 2025-12-07 | Implemented Yarn PnP parsing and removed lockfile-only emissions; fixtures/goldens updated, tests pending rerun. | Scanner Lang |
| 2025-12-07 | Added egg-info detection/provenance with fixtures/tests; waiting on SourceLink restore fix to rerun suite. | Scanner Lang |
| 2025-12-08 | Rebased Yarn PnP goldens, merged cache scanning with .pnp.data metadata, and reran Node analyzer tests successfully. | Scanner Lang |
| 2025-12-08 | Ran Python analyzer suite with egg-info support; multiple pre-existing import graph/runtime metadata assertions failing, leaving task blocked. | Scanner Lang |
| 2025-12-08 | Added SmRemote crypto DI reference and MongoDB.Bson aliases to unblock test builds across shared libraries. | Shared |
| 2025-12-09 | Fixed Python egg-info/editable handling, import graph ordering, pyproject version dedupe, and layered editable evidence; Python analyzer tests now pass. | Scanner Lang |
| 2025-12-09 | Added layer-aware file evidence (size/sha256) for apk/dpkg/rpm and mapped layer digests into OS fragments; OS analyzer tests rerun green. | Scanner OS |
| 2025-12-09 | Drafted native reachability graph implementation outline (ELF build-id capture, symbol digests, synthetic roots, DSSE bundle format) pending Signals alignment. | Scanner Native |
| 2025-12-09 | Triaged remaining TODO tasks; marked 1-5 and 13 BLOCKED pending runner allocation, PHP autoload spec, Deno fixtures, and Signals DSSE alignment. | Planning |
| 2025-12-09 | Documented bun.lockb remediation-only posture and updated readiness checkpoints. | Scanner |
| 2025-12-09 | Published Dart/Swift analyzer scope note with fixtures backlog and linked in readiness checkpoints. | Scanner |
| 2025-12-09 | Authored runtime parity plan (Java/.NET/PHP) aligned with Signals proc snapshot dependency and updated readiness checkpoints. | Scanner |
| 2025-12-09 | Ran .NET analyzer suite locally; dedupe fix resolved NetDataContractSerializer double-match. TRX: `TestResults/dotnet/dotnet-tests.trx`. | Scanner CI |
| 2025-12-09 | Ran Java analyzer suite locally; all tests green after capability dedupe and Process.start handling. TRX: `TestResults/java/java-tests.trx`. | Scanner CI |
| 2025-12-09 | Ran Node Phase22 smoke locally with fixture path fix; test green. TRX: `TestResults/phase22-smoke/phase22-smoke.trx`. | Scanner CI |
| 2025-12-09 | Published .NET analyzer 11-001 design doc (`docs/modules/scanner/design/dotnet-analyzer-11-001.md`) to unblock downstream tasks and linked readiness. | Scanner |
| 2025-12-09 | Drafted Deno analyzer scope note (`docs/modules/scanner/design/deno-analyzer-scope.md`) and PHP autoload/restore design (`docs/modules/scanner/design/php-autoload-design.md`); readiness updated. | Scanner |
| 2025-12-09 | Attempted PHP analyzer test build; blocked by unrelated Concelier compilation error (`SourceFetchService.cs` type mismatch in StellaOps.Concelier.Connector.Common). | Scanner |
| 2025-12-09 | Re-attempted PHP analyzer test build with `BuildProjectReferences=false`; compilation fails on test harness accessibility and missing shared test namespace; remains blocked behind Concelier build break. | Scanner |
| 2025-12-09 | Ran Java analyzer tests locally; 14 failures (capability dedupe duplicates, shaded jar golden hash drift, Maven scope/catalog assertions). TRX: `TestResults/java/java-tests.trx`. | Scanner CI |
| 2025-12-09 | Ran .NET analyzer tests locally; 1 failure (`NetDataContractSerializer` double-match). TRX: `TestResults/dotnet/dotnet-tests.trx`. | Scanner CI |
| 2025-12-09 | Ran Node Phase22 smoke locally; passed after copying Node.Tests fixtures into smoke bin. TRX: `TestResults/phase22-smoke/phase22-smoke.trx`. | Scanner CI |
## Decisions & Risks
- CI runner availability may delay Java/.NET/Node validation; mitigate by reserving dedicated runner slice.
- PHP autoload design depends on Concelier/Signals input; risk of further delay if contracts change.
- Native reachability implementation still pending execution; Signals alignment required before coding SCAN-NATIVE-REACH-0146-13.
- Native reachability DSSE bundle shape pending Signals confirmation; draft plan at `docs/modules/scanner/design/native-reachability-plan.md`.
- Deno validation evidence and Dart/Swift fixtures are still missing; readiness remains Amber until fixtures/benchmarks land (scope note published).
- Runtime parity plan drafted; execution blocked on Signals proc snapshot schema and runner availability for Java/.NET evidence (`docs/modules/scanner/design/runtime-parity-plan.md`).
- Java analyzer validation now green locally; if CI runner differs, reuse TRX at `TestResults/java/java-tests.trx` to compare.
- Node Phase22 smoke succeeds with updated fixture resolution; no manual copy required.
- bun.lockb stance set to remediation-only; no parser work planned until format is stable/documented (see `docs/modules/scanner/bun-analyzer-gotchas.md`).
- .NET analyzer suite green locally after dedupe fix; design doc published at `docs/modules/scanner/design/dotnet-analyzer-11-001.md` (TRX `TestResults/dotnet/dotnet-tests.trx`).
- .NET analyzer design doc published; downstream 11-002..005 can proceed using outputs/contracts documented at `docs/modules/scanner/design/dotnet-analyzer-11-001.md`.
- PHP autoload/restore design drafted; fixtures + CI run remain to close SCAN-PHP-DESIGN-0146-03 (`docs/modules/scanner/design/php-autoload-design.md`).
- Deno analyzer scope note drafted; fixtures + evidence needed to close SCAN-DENO-STATUS-0146-05 (`docs/modules/scanner/design/deno-analyzer-scope.md`).
- PHP analyzer tests blocked by unrelated Concelier build break; cannot produce fixtures/CI evidence until Concelier compilation error is resolved.
## Next Checkpoints
- 2025-12-10: CI runner allocation decision.
- 2025-12-14: Status review on Java/.NET/Node validations and PHP design.
- 2025-12-21: Final readiness update and doc sync across scanner module.

22
docs/implplan/SPRINT_0150_0001_0001_scheduling_automation.md
View File

@@ -23,7 +23,7 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | 150.A-Orchestrator | BLOCKED | Graph (0140.A) ✅ DONE; Zastava (0140.D) ✅ DONE. Blocked on 0120.A AirGap staleness (56-002/57/58) and Scanner surface Java/Lang chain (0131). | Orchestrator Service Guild · AirGap Policy/Controller Guilds · Observability Guild | Kick off orchestration scheduling/telemetry baseline for automation epic. |
| 1 | 150.A-Orchestrator | BLOCKED | Graph (0140.A) ✅ DONE; Zastava (0140.D) ✅ DONE; AirGap (0120.A) ✅ DONE (2025-12-06). Blocked on Scanner surface Java/Lang chain (0131 21-005..011). | Orchestrator Service Guild · AirGap Policy/Controller Guilds · Observability Guild | Kick off orchestration scheduling/telemetry baseline for automation epic. |
| 2 | 150.B-PacksRegistry | BLOCKED | 150.A must reach DOING; confirm tenancy scaffolding from Orchestrator | Packs Registry Guild · Exporter Guild · Security Guild | Packs registry automation stream staged; start after Orchestrator scaffolding. |
| 3 | 150.C-Scheduler | BLOCKED | Graph ✅ DONE; still waiting on Scanner surface Java/Lang chain (0131 21-005..011) | Scheduler WebService/Worker Guilds · Findings Ledger Guild · Observability Guild | Scheduler impact index improvements gated on Graph overlays. |
| 4 | 150.D-TaskRunner | BLOCKED | Requires Orchestrator/Scheduler telemetry baselines (150.A/150.C) | Task Runner Guild · AirGap Guilds · Evidence Locker Guild | Execution engine upgrades and evidence integration to start post-baselines. |
@@ -31,14 +31,16 @@
## Wave Coordination Snapshot
| Wave | Guild owners | Shared prerequisites | Status | Notes |
| --- | --- | --- | --- | --- |
| 150.A Orchestrator | Orchestrator Service Guild · AirGap Policy/Controller Guilds · Observability Guild | Sprint 0120.A – AirGap; Sprint 0130.A – Scanner; Sprint 0140.A – Graph | BLOCKED | Graph (0140.A) and Zastava (0140.D) DONE. AirGap staleness (0120.A 56-002/57/58) and Scanner surface Java/Lang chain (0131 21-005..011) still blocking kickoff. |
| 150.A Orchestrator | Orchestrator Service Guild · AirGap Policy/Controller Guilds · Observability Guild | Sprint 0120.A – AirGap; Sprint 0130.A – Scanner; Sprint 0140.A – Graph | BLOCKED | Graph (0140.A) ✅ DONE; Zastava (0140.D) ✅ DONE; AirGap staleness (0120.A 56-002/57/58) ✅ DONE (2025-12-06). Only Scanner surface Java/Lang chain (0131 21-005..011) remains blocking. |
| 150.B PacksRegistry | Packs Registry Guild · Exporter Guild · Security Guild | Sprint 0120.A – AirGap; Sprint 0130.A – Scanner; Sprint 0140.A – Graph | BLOCKED | Blocked on Orchestrator tenancy scaffolding; specs ready once 150.A enters DOING. |
| 150.C Scheduler | Scheduler WebService/Worker Guilds · Findings Ledger Guild · Observability Guild | Sprint 0120.A – AirGap; Sprint 0130.A – Scanner; Sprint 0140.A – Graph | BLOCKED | Graph overlays (0140.A) DONE; Scanner surface Java/Lang chain still blocked; Signals CAS/DSSE signing (0140.C) pending for telemetry parity. |
| 150.C Scheduler | Scheduler WebService/Worker Guilds · Findings Ledger Guild · Observability Guild | Sprint 0120.A – AirGap; Sprint 0130.A – Scanner; Sprint 0140.A – Graph | BLOCKED | Graph overlays (0140.A) DONE; Scanner surface Java/Lang chain still blocked; ✅ Signals 140.C unblocked (2025-12-06): CAS APPROVED + Provenance appendix published. |
| 150.D TaskRunner | Task Runner Guild · AirGap Guilds · Evidence Locker Guild | Sprint 0120.A – AirGap; Sprint 0130.A – Scanner; Sprint 0140.A – Graph | BLOCKED | Execution engine upgrades staged; start once Orchestrator/Scheduler telemetry baselines exist. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-06 | **AirGap staleness DONE:** LEDGER-AIRGAP-56-002/57/58 delivered with staleness validation, evidence snapshots, timeline events at `docs/schemas/ledger-airgap-staleness.schema.json`. Updated delivery tracker and wave coordination. **Sole remaining blocker:** Scanner Java/Lang chain (0131 21-005..011). | Implementer |
| 2025-12-06 | **Signals 140.C unblocked:** CAS Infrastructure Contract APPROVED at `docs/contracts/cas-infrastructure.md`; Provenance appendix published at `docs/signals/provenance-24-003.md` + schema at `docs/schemas/provenance-feed.schema.json`. SIGNALS-24-002/003 now TODO. Updated upstream dependency table and wave coordination. Remaining blockers: AirGap staleness (0120.A 56-002/57/58) and Scanner Java/Lang chain (0131 21-005..011). | Implementer |
| 2025-12-05 | Refreshed upstream Zastava status: ZASTAVA-SCHEMAS-0001 and ZASTAVA-KIT-0001 are DONE (DSSE-signed 2025-12-02, keyid mpIEbYRL1q5yhN6wBRvkZ_0xXz3QUJPueJJ8sn__GGc). Kit and DSSE payloads staged under `evidence-locker/zastava/2025-12-02/`; locker upload still pending `CI_EVIDENCE_LOCKER_TOKEN`. Signals DSSE signing (0140.C) still pending. | Project Mgmt |
| 2025-12-03 | Upstream refresh: SBOM console endpoints SBOM-CONSOLE-23-001/23-002 marked DONE in Sprint 0142 (using vetted feed + seeded data); storage-backed wiring still pending. Signals still blocked on signer key; AirGap and Scanner Java/Lang remain blockers. 150.* tasks stay BLOCKED. | Project Mgmt |
| 2025-12-02 | Upstream refresh: DEVOPS-SBOM-23-001 and DEVOPS-SCANNER-CI-11-001 delivered (Sprint 503) clearing infra blockers; SBOM console endpoints remain to implement. Signals wave (0140.C) still blocked on cosign availability for DSSE signing; AirGap staleness (0120.A 56-002/57/58) and Scanner Java/Lang chain (0131 21-005..011) remain blocked. All 150.* tasks kept BLOCKED. | Project Mgmt |
@@ -46,28 +48,28 @@
| 2025-11-30 | Upstream refresh: Sprint 0120 AirGap staleness (LEDGER-AIRGAP-56-002/57/58) still BLOCKED; Scanner surface Sprint 0131 has Deno 26-009/010/011 DONE but Java/Lang chain 21-005..011 BLOCKED pending CI/CoreLinksets; SBOM wave (Sprint 0142) core tasks DONE with Console endpoints still BLOCKED on DEVOPS-SBOM-23-001 in Sprint 503; Signals (Sprint 0143) 24-002/003 remain BLOCKED on CAS promotion/provenance though 24-004/005 are DONE. No 150.* task can start yet. | Implementer |
| 2025-11-28 | Synced with downstream sprints: Sprint 0141 (Graph) DONE, Sprint 0142 (SBOM) mostly DONE, Sprint 0143 (Signals) 3/5 DONE, Sprint 0144 (Zastava) DONE. Updated Sprint 0140 tracker and revised 150.* upstream dependency status. 150.A-Orchestrator may start once remaining AirGap/Scanner blockers clear. | Implementer |
| 2025-11-28 | Upstream dependency check: Sprint 0120 (Policy/Reasoning) has LEDGER-29-007/008, LEDGER-34-101, LEDGER-AIRGAP-56-001 DONE but 56-002/57-001/58-001/ATTEST-73-001 BLOCKED. Sprint 0140 (Runtime/Signals) has all waves BLOCKED except SBOM (TODO). No Sprint 0130.A file found. All 150.* tasks remain TODO pending upstream readiness. | Implementer |
| 2025-12-08 | Readiness check: AirGap staleness, Graph overlays, Zastava, and Signals CAS/Provenance are DONE; Scanner Java/Lang chain (0131 tasks 21-005..011) still BLOCKED due to missing CoreLinksets package and stalled test runs. All 150.* work remains BLOCKED; carry over to Sprint 0151 once Java chain and CoreLinksets unblock. | Project Mgmt |
| 2025-11-18 | Normalised sprint doc to standard template; renamed from `SPRINT_150_scheduling_automation.md`. | Planning |
## Upstream Dependency Status (as of 2025-12-05)
| Upstream Sprint | Key Deliverable | Status | Impact on 150.* |
| --- | --- | --- | --- |
| Sprint 0120.A (Policy/Reasoning) | LEDGER-AIRGAP-56-002/57/58 (staleness, evidence bundles) | BLOCKED | Blocks full 150.A readiness + 150.C verification |
| Sprint 0120.A (Policy/Reasoning) | LEDGER-AIRGAP-56-002/57/58 (staleness, evidence bundles) | ✅ **DONE** (2025-12-06): Staleness validation, evidence snapshots, timeline events implemented | 150.A/150.C AirGap deps unblocked |
| Sprint 0120.A (Policy/Reasoning) | LEDGER-29-009-DEV (deploy/backup collateral) | BLOCKED (awaiting Sprint 501 ops paths) | Not a gate for kickoff but limits rollout evidence |
| Sprint 0131 (Scanner surface phase II) | Deno runtime chain 26-009/010/011 | DONE | Partial readiness for scanner surface inputs |
| Sprint 0131 (Scanner surface phase II) | Java/Lang chain 21-005..011 | BLOCKED (CoreLinksets still missing; DEVOPS-SCANNER-CI-11-001 delivered 2025-11-30) | Blocks 150.A and 150.C verification |
| Sprint 0141 (Graph overlays 140.A) | GRAPH-INDEX-28-007..010 | **DONE** | Unblocks 150.C Scheduler graph deps |
| Sprint 0142 (SBOM Service 140.B) | SBOM-SERVICE-21-001..004, 23-001/002, 29-001/002 | CORE DONE; SBOM-CONSOLE-23-001/23-002 DONE (2025-12-03) using vetted feed + seeded data; SBOM-CONSOLE-23-101-STORAGE TODO for storage wiring | Partially unblocks 150.A/150.C; monitor storage wiring follow-up |
| Sprint 0143 (Signals 140.C) | SIGNALS-24-002/003 | BLOCKED (CAS promotion/provenance) | Telemetry dependency partially unblocked; still blocks parity |
| Sprint 0143 (Signals 140.C) | SIGNALS-24-002/003 | ✅ TODO (2025-12-06): CAS APPROVED + Provenance appendix published | Telemetry dependency unblocked; parity achievable |
| Sprint 0140 (Signals/decay/unknowns) | DECAY-GAPS-140-005 / UNKNOWN-GAPS-140-006 / UNKNOWN-HEUR-GAPS-140-007 | PENDING SIGNING (cosign v3.0.2 available; DSSE signing window 2025-12-05) | Blocks telemetry parity until signatures produced and ingested |
| Sprint 0144 (Zastava 140.D) | ZASTAVA-ENV/SECRETS/SURFACE | **DONE** | Surface deps unblocked |
| Sprint 0144 (Zastava 140.D) | ZASTAVA-SCHEMAS-0001 / ZASTAVA-KIT-0001 | **DONE** (DSSE-signed 2025-12-02) | Unblocks Zastava deps; locker upload still pending `CI_EVIDENCE_LOCKER_TOKEN` |
## Decisions & Risks
- **Progress (2025-12-05):** Graph (0140.A) DONE; Zastava schemas/thresholds/kit DSSE-signed on 2025-12-02 (keyid mpIEbYRL1q5yhN6wBRvkZ_0xXz3QUJPueJJ8sn__GGc) with artefacts staged under `docs/modules/zastava/kit` and `evidence-locker/zastava/2025-12-02/`. Signals wave (0140.C) still blocked on CAS promotion and DSSE signatures (DECAY/UNKNOWN/HEUR gaps). AirGap staleness (0120.A 56-002/57/58) and Scanner Java/Lang chain (0131 21-005..011) remain blockers, keeping all 150.* tasks BLOCKED.
- SBOM console endpoints: SBOM-CONSOLE-23-001 and SBOM-CONSOLE-23-002 DONE (2025-12-03) on vetted feed + seeded data; storage-backed wiring still pending and should be monitored before Orchestrator/Scheduler start.
- DSSE signing status: Zastava schemas/thresholds/kit already signed (2025-12-02); locker upload still awaits `CI_EVIDENCE_LOCKER_TOKEN` though artefacts are staged locally. Signals (0140.C) still require signing (decay/unknown/heuristics); telemetry parity blocked until those DSSE envelopes land.
- Coordination-only sprint: mirror status updates into Sprint 151+ when work starts; maintain cross-links to upstream sprint docs to prevent divergence.
- Sprint 0130/0131 Scanner surface remains the primary gating item alongside AirGap staleness; re-evaluate start once either clears.
- Progress: Graph (0140.A), Zastava (0144), AirGap staleness (0120.A 56-002/57/58), and Signals CAS/Provenance (0140.C) are DONE/unblocked. **Remaining blocker:** Scanner surface Java/Lang chain (0131 21-005..011) lacks CoreLinksets package and CI test completion; without it, 150.A/150.C baselines cannot start.
- SBOM console endpoints: SBOM-CONSOLE-23-001 and SBOM-CONSOLE-23-002 are DONE (2025-12-03) on vetted feed + seeded data; storage-backed wiring follow-up (SBOM-CONSOLE-23-101-STORAGE) should be monitored but is not the gating blocker.
- DSSE signing: Zastava schemas/kit are signed and staged; Signals decay/unknown/heuristics still awaiting signatures?monitor but not gating kickoff until Scanner chain clears.
- Coordination-only sprint: all tasks remain BLOCKED; carry over to Sprint 0151 once Scanner Java chain unblocks. Maintain cross-links to upstream sprint docs to prevent drift.
## Next Checkpoints
- None scheduled; add next scheduling/automation sync once upstream readiness dates are confirmed.

6
docs/implplan/SPRINT_0151_0001_0001_orchestrator_i.md
View File

@@ -44,7 +44,7 @@
| P15 | PREP-ORCH-SVC-32-001-UPSTREAM-READINESS-AIRGA | DONE (2025-11-22) | Due 2025-11-23 · Accountable: Orchestrator Service Guild | Orchestrator Service Guild | Upstream readiness (AirGap/Scanner/Graph) not confirmed; postpone bootstrap. <br><br> Document artefact/deliverable for ORCH-SVC-32-001 and publish location so downstream tasks can proceed. |
| 2025-11-20 | Started PREP-ORCH-SVC-32-001 (status → DOING) after confirming no existing DOING/DONE owners. | Planning |
| 1 | ORCH-AIRGAP-56-001 | BLOCKED (2025-11-19) | PREP-ORCH-AIRGAP-56-001-AWAIT-SPRINT-0120-A-A | Orchestrator Service Guild · AirGap Policy Guild | Enforce job descriptors to declare network intents; flag/reject external endpoints in sealed mode. |
| 2 | ORCH-AIRGAP-56-002 | TODO | ledger-airgap-staleness.schema.json created 2025-12-04. | Orchestrator Service Guild · AirGap Controller Guild | Surface sealing status and staleness in scheduling decisions; block runs when budgets exceeded. |
| 2 | ORCH-AIRGAP-56-002 | DONE (2025-12-06) | AirGap domain models + SchedulingContext extensions + JobScheduler staleness blocking + StalenessValidator service + tests | Orchestrator Service Guild · AirGap Controller Guild | Surface sealing status and staleness in scheduling decisions; block runs when budgets exceeded. |
| 3 | ORCH-AIRGAP-57-001 | BLOCKED (2025-11-19) | PREP-ORCH-AIRGAP-57-001-UPSTREAM-56-002-BLOCK | Orchestrator Service Guild · Mirror Creator Guild | Add job type `mirror.bundle` with audit + provenance outputs. |
| 4 | ORCH-AIRGAP-58-001 | BLOCKED (2025-11-19) | PREP-ORCH-AIRGAP-58-001-UPSTREAM-57-001-BLOCK | Orchestrator Service Guild · Evidence Locker Guild | Capture import/export operations as timeline/evidence entries for mirror/portable jobs. |
| 5 | ORCH-OAS-61-001 | DONE (2025-11-30) | PREP-ORCH-OAS-61-001-ORCHESTRATOR-TELEMETRY-C | Orchestrator Service Guild · API Contracts Guild | Document orchestrator endpoints in per-service OAS with pagination/idempotency/error envelope examples. |
@@ -53,7 +53,7 @@
| 8 | ORCH-OAS-63-001 | DONE (2025-11-30) | PREP-ORCH-OAS-63-001-DEPENDS-ON-62-001 | Orchestrator Service Guild · API Governance Guild | Emit deprecation headers/doc for legacy endpoints; update notifications metadata. |
| 9 | ORCH-OBS-50-001 | BLOCKED (2025-11-19) | PREP-ORCH-OBS-50-001-TELEMETRY-CORE-SPRINT-01 | Orchestrator Service Guild · Observability Guild | Wire `StellaOps.Telemetry.Core` into orchestrator host; instrument schedulers/control APIs with spans/logs/metrics. |
| 10 | ORCH-OBS-51-001 | BLOCKED (2025-11-19) | PREP-ORCH-OBS-51-001-DEPENDS-ON-50-001-TELEME | Orchestrator Service Guild · DevOps Guild | Publish golden-signal metrics and SLOs; emit burn-rate alerts; provide Grafana dashboards + alert rules. |
| 11 | ORCH-OBS-52-001 | TODO | timeline-event.schema.json created 2025-12-04. | Orchestrator Service Guild | Emit `timeline_event` lifecycle objects with trace IDs/run IDs/tenant/project; add contract tests and Kafka/NATS emitter with retries. |
| 11 | ORCH-OBS-52-001 | DONE (2025-12-06) | Created `TimelineEvent` domain model + `TimelineEventEmitter` service + `ITimelineEventSink` interface + tests | Orchestrator Service Guild | Emit `timeline_event` lifecycle objects with trace IDs/run IDs/tenant/project; add contract tests and Kafka/NATS emitter with retries. |
| 12 | ORCH-OBS-53-001 | BLOCKED (2025-11-19) | PREP-ORCH-OBS-53-001-DEPENDS-ON-52-001-EVIDEN | Orchestrator Service Guild · Evidence Locker Guild | Generate job capsule inputs for Evidence Locker; invoke snapshot hooks; enforce redaction guard. |
| 13 | ORCH-OBS-54-001 | TODO | timeline-event.schema.json created 2025-12-04; depends on 53-001. | Orchestrator Service Guild · Provenance Guild | Produce DSSE attestations for orchestrator-scheduled jobs; store references in timeline + Evidence Locker; add verification endpoint `/jobs/{id}/attestation`. |
| 14 | ORCH-OBS-55-001 | BLOCKED (2025-11-19) | PREP-ORCH-OBS-55-001-DEPENDS-ON-54-001-INCIDE | Orchestrator Service Guild · DevOps Guild | Incident mode hooks (sampling overrides, extended retention, debug spans) with automatic activation on SLO burn-rate breach; emit activation/deactivation events. |
@@ -90,6 +90,8 @@
| 2025-12-02 | ORCH-GAPS-151-016: added pack-run log integrity fields (canonical SHA-256 + size) with deterministic hashing and updated log tests. | Implementer |
| 2025-12-02 | ORCH-GAPS-151-016: enforced artifact digest+size validation on pack-run completion and included artifact digests/sizes in completion events. | Implementer |
| 2025-12-03 | ORCH-GAPS-151-016 DONE: persisted pack-run log digests/sizes (migration 007), added heartbeat correlation ids, relaxed scale performance thresholds, and reran orchestrator test suite (864 tests, 0 failures). | Implementer |
| 2025-12-06 | ORCH-AIRGAP-56-002 DONE: Created AirGap domain models (`StalenessConfig`, `BundleProvenance`, `SealingStatus`, `StalenessValidationResult`) in `Core/Domain/AirGap/`. Extended `SchedulingContext` with `AirGapSchedulingContext` for sealed-mode/staleness fields. Updated `JobScheduler.EvaluateScheduling` to block runs when staleness exceeds budget in strict enforcement mode. Created `StalenessValidator` service with domain/job validation and warning generation. Added comprehensive tests (`StalenessValidatorTests`, `JobSchedulerAirGapTests`). Build verified (0 errors). | Implementer |
| 2025-12-06 | ORCH-OBS-52-001 DONE: Created `TimelineEvent` domain model in `Core/Domain/Events/` per timeline-event.schema.json. Model includes eventId, tenantId, eventType, source, occurredAt, correlationId, traceId, spanId, actor, severity, attributes, payloadHash, evidencePointer, runId, jobId, projectId. Created `TimelineEventEmitter` service with retry logic and `ITimelineEventSink` interface for Kafka/NATS transport abstraction. Added `InMemoryTimelineEventSink` for testing. Added comprehensive tests (`TimelineEventTests`). Build verified (0 errors). | Implementer |
## Decisions & Risks
- Start of work gated on AirGap/Scanner/Graph dependencies staying green; reassess before moving tasks to DOING.

3
docs/implplan/SPRINT_0153_0001_0003_orchestrator_iii.md
View File

@@ -1,4 +1,4 @@
# Sprint 0153_0001_0003 · Orchestrator III (Scheduling & Automation)
# Sprint 0153 · Orchestrator III (Scheduling & Automation)
## Topic & Scope
- Deliver phase III scheduling & automation for the Orchestrator: pack-run lifecycle, event envelope standardisation, and live log streaming.
@@ -48,6 +48,7 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-06 | Header normalised to standard template; no content/status changes. | Project Mgmt |
| 2025-12-01 | Full-suite `dotnet test` for Orchestrator solution aborted by host disk exhaustion (`No space left on device` / MSB5021). PackRun contract tests already pass; rerun full suite after freeing space (clean bin/obj, /tmp). | Implementer |
| 2025-11-19 | Assigned PREP owners/dates; see Delivery Tracker. | Planning |
| 2025-11-07 | Still not started — Authority pack RBAC (AUTH-PACKS-43-001) remains blocked pending approvals/log-stream APIs. | Coordination |

100
docs/implplan/SPRINT_0157_0001_0001_taskrunner_i.md
View File

@@ -1,100 +0,0 @@
# Sprint 0157-0001-0001 · TaskRunner I (Scheduling & Automation 150.D)
## Topic & Scope
- Stand up TaskRunner service: pack run API, execution engine, air-gap enforcement, evidence capture, and observability.
- Provide pack run lifecycle APIs/SDK, telemetry, OAS, and offline-friendly bundles with provenance.
- **Working directory:** `src/TaskRunner/StellaOps.TaskRunner`.
## Dependencies & Concurrency
- Upstream: Sprint 120.A (AirGap), 130.A (Scanner), 140.A (Graph).
- Concurrency: execute tasks in table order; AIRGAP/OAS/OBS chains await control-flow addendum and timeline schema before starting.
## Documentation Prerequisites
- docs/README.md
- docs/07_HIGH_LEVEL_ARCHITECTURE.md
- docs/modules/platform/architecture-overview.md
- docs/modules/taskrunner/architecture.md (if available)
- src/TaskRunner/StellaOps.TaskRunner/AGENTS.md
> **BLOCKED Tasks:** Before working on BLOCKED tasks, review [BLOCKED_DEPENDENCY_TREE.md](./BLOCKED_DEPENDENCY_TREE.md) for root blockers and dependencies.
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | TASKRUN-AIRGAP-56-001 | DONE (2025-11-30) | Delivered sealed-mode plan validation via AirGap egress policy binding in WebService. | Task Runner Guild · AirGap Policy Guild | Enforce plan-time validation rejecting non-allowlisted network calls in sealed mode; surface remediation errors. |
| 2 | TASKRUN-AIRGAP-56-002 | DONE (2025-12-03) | Helper delivered; downstream AIRGAP-57/58 await controller/importer bundle specs. | Task Runner Guild · AirGap Importer Guild | Add helper steps for bundle ingestion (checksum verification, staging to object store) with deterministic outputs. |
| 3 | TASKRUN-AIRGAP-57-001 | BLOCKED (2025-11-30) | Depends on 56-002; awaiting sealed-install enforcement contract. | Task Runner Guild · AirGap Controller Guild | Refuse to execute plans when environment sealed=false but declared sealed install; emit advisory timeline events. |
| 4 | TASKRUN-AIRGAP-58-001 | BLOCKED (2025-11-30) | Depends on 57-001. | Task Runner Guild · Evidence Locker Guild | Capture bundle import job transcripts, hashed inputs/outputs into portable evidence bundles. |
| 5 | TASKRUN-42-001 | BLOCKED (2025-11-25) | Continue execution engine upgrades (loops/conditionals/maxParallel), simulation mode, policy gate integration, deterministic failure recovery. | Task Runner Guild (`src/TaskRunner/StellaOps.TaskRunner`) | Execution engine enhancements + simulation API/CLI. Blocked: TaskPack loop/conditional semantics and policy-gate evaluation contract not published. |
| 6 | TASKRUN-OAS-61-001 | BLOCKED (2025-11-30) | Await control-flow/policy addendum (Action Tracker 2025-12-04) before freezing OAS. | Task Runner Guild · API Contracts Guild | Document TaskRunner APIs (pack runs, logs, approvals) with streaming schemas/examples. |
| 7 | TASKRUN-OAS-61-002 | BLOCKED (2025-11-30) | Depends on 61-001. | Task Runner Guild | Expose `GET /.well-known/openapi` returning signed spec metadata, build version, ETag. |
| 8 | TASKRUN-OAS-62-001 | BLOCKED (2025-11-30) | Depends on 61-002. | Task Runner Guild · SDK Generator Guild | SDK examples for pack run lifecycle; streaming log helpers; paginator wrappers. |
| 9 | TASKRUN-OAS-63-001 | BLOCKED (2025-11-30) | Depends on 62-001. | Task Runner Guild · API Governance Guild | Sunset/deprecation headers + notifications for legacy pack APIs. |
| 10 | TASKRUN-OBS-50-001 | DONE (2025-11-25) | Telemetry core adoption. | Task Runner Guild | Add telemetry core in host + worker; spans/logs include `trace_id`, `tenant_id`, `run_id`, scrubbed transcripts. |
| 11 | TASKRUN-OBS-51-001 | DONE (2025-11-25) | Depends on 50-001. | Task Runner Guild · DevOps Guild | Metrics for step latency, retries, queue depth, sandbox resource usage; define SLOs; burn-rate alerts. |
| 12 | TASKRUN-OBS-52-001 | TODO | Depends on 51-001; timeline-event.schema.json created 2025-12-04. | Task Runner Guild | Timeline events for pack runs (`pack.started`, `pack.step.completed`, `pack.failed`) with evidence pointers/policy context; dedupe + retry. |
| 13 | TASKRUN-OBS-53-001 | TODO | Depends on 52-001; timeline-event.schema.json created 2025-12-04. | Task Runner Guild · Evidence Locker Guild | Capture step transcripts, artifact manifests, environment digests, policy approvals into evidence locker snapshots; ensure redaction + hash chain. |
| 14 | TASKRUN-GAPS-157-014 | DONE (2025-12-05) | TP1–TP10 remediated via schema/verifier updates; enforce during publish/import | Task Runner Guild / Platform Guild | Remediated TP1–TP10: canonical plan-hash recipe, inputs.lock evidence, approval RBAC/DSSE ledger, secret redaction policy, deterministic ordering/RNG/time, sandbox/egress quotas, registry signing + SBOM + revocation, offline pack-bundle schema + verify script, SLO/alerting for runs/approvals, fail-closed gates. |
## Wave Coordination
- Single wave; parallelism paused until TaskPack control-flow addendum and timeline schema publish.
## Wave Detail Snapshots
- Wave 1 (RUN/OAS/OBS/AIRGAP): waiting on TaskPack control-flow addendum and timeline schema; start once both land.
## Interlocks
- TaskPack DSL control-flow and policy-evaluation contract (from Sprints 120/130/140).
- Air-gap sealed-mode validation rules from AirGap Policy Guild (to unblock AIRGAP-56-001 chain).
- Timeline event and evidence-pointer schema for OBS-52-001/53-001.
## Action Tracker
| Action | Owner | Due | Status | Notes |
| --- | --- | --- | --- | --- |
| Publish TaskPack control-flow & policy-gate contract | Platform Guild · Task Runner Guild | 2025-12-05 | Open | Unblocks TASKRUN-42-001 and OAS chain (61-001..63-001). |
| Provide timeline event + evidence-pointer schema | Evidence Locker Guild | 2025-12-05 | Open | Needed for TASKRUN-OBS-52-001 and TASKRUN-OBS-53-001. |
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-05 | **OBS Unblocked:** TASKRUN-OBS-52-001 and TASKRUN-OBS-53-001 changed from BLOCKED to TODO. Root blocker resolved: `timeline-event.schema.json` created 2025-12-04 per BLOCKED_DEPENDENCY_TREE.md Section 8.3. | Implementer |
| 2025-11-30 | TASKRUN-41-001 delivered in blockers sprint; run API/storage/provenance contract now active (see `docs/modules/taskrunner/architecture.md`). | Task Runner Guild |
| 2025-11-30 | Delivered TASKRUN-AIRGAP-56-001: WebService planner enforces sealed-mode allowlist with remediation messaging. | Task Runner Guild |
| 2025-11-30 | Updated dependencies: AIRGAP chain blocked on helper design (56-002) and downstream evidence work; OAS chain blocked pending TaskPack control-flow addendum (due 2025-12-05); OBS chain blocked on timeline/evidence schema; 41-001 no longer a blocker. | Project Mgmt |
| 2025-12-01 | Started TASKRUN-AIRGAP-56-002: bundle ingestion helper executor added (checksum verify + deterministic staging). Worker wired; awaiting importer specs/fixture paths before marking DONE. | Task Runner Guild |
| 2025-12-02 | TASKRUN-AIRGAP-56-002: hardened bundle helper — checksum now required, deterministic staging under `bundles/{sha256}/`, metadata.json emitted; unit tests updated. Targeted test run aborted after long restore; rerun `dotnet test …TaskRunner.Tests --filter BundleIngestion` in CI. | Task Runner Guild |
| 2025-12-03 | Completed TASKRUN-AIRGAP-56-002: moved worker options into core for DI safety, bundle helper emits deterministic `bundles/{sha256}/metadata.json`, and `dotnet test src/TaskRunner/StellaOps.TaskRunner/StellaOps.TaskRunner.sln --filter BundleIngestion` passes. Updated architecture doc for new helper contract. | Task Runner Guild |
| 2025-11-30 | Added Wave Coordination, Interlocks, and Action Tracker sections per docs/implplan/AGENTS.md template; no scope change. | Project Mgmt |
| 2025-11-30 | Synced TaskRunner task rows in tasks-all/archived indexes to reflect canonical sprint name and BLOCKED status where applicable. | Project Mgmt |
| 2025-11-30 | Refreshed Decisions & Risks with risk table and aligned checkpoint wording. | Project Mgmt |
| 2025-11-30 | Replaced legacy file `SPRINT_157_taskrunner_i.md` with stub redirecting to this canonical sprint. | Project Mgmt |
| 2025-11-25 | TASKRUN-OBS-52-001 and TASKRUN-OBS-53-001 marked BLOCKED: timeline event schema and evidence-pointer contract not published; cannot emit pack timeline events or evidence snapshots yet. | Task Runner Guild |
| 2025-11-25 | TASKRUN-42-001 marked BLOCKED: loop/conditional semantics and policy-gate evaluation contract not published; cannot update execution engine/simulation without spec. | Task Runner Guild |
| 2025-11-25 | Implemented metrics for step latency, retries, running steps, and queue depth; wired into telemetry; marked TASKRUN-OBS-51-001 DONE. | Task Runner Guild |
| 2025-11-25 | Added StellaOps.Telemetry.Core to TaskRunner WebService and Worker; enabled runtime + HTTP client instrumentation with OTLP guardrails; marked TASKRUN-OBS-50-001 DONE. | Task Runner Guild |
| 2025-11-25 | Moved TASKRUN-41-001 to new Sprint 0157-0001-0002 (blockers) to keep active sprint focused on implementable items; dependencies in rows 1–4 remain until 41-001 unblocks. | Project Mgmt |
| 2025-11-25 | Marked TASKRUN-41-001 BLOCKED: TaskRunner architecture/API contracts not published; upstream Sprint 120/130/140 inputs required before implementation. Status mirrored to tasks-all. | Project Mgmt |
| 2025-11-04 | Resumed TASKRUN-42-001: scoped execution engine upgrades (loops/conditionals/maxParallel), simulation mode, policy gate integration, deterministic failure recovery. | Task Runner Guild |
| 2025-11-04 | Worker/WebService wiring in place: execution graph honors `maxParallel`/`continueOnError`, retry windows persisted, simulation API exposed. | Task Runner Guild |
| 2025-11-04 | Continued TASKRUN-42-001: cleaning persistence anomalies, validating retry metadata, wiring simulation preview into CLI surface. | Task Runner Guild |
| 2025-11-04 | CLI command `stella task-runner simulate` wired to new endpoint with JSON/table output modes. | Task Runner Guild |
| 2025-11-19 | Normalized sprint to standard template and renamed from `SPRINT_157_taskrunner_i.md` to `SPRINT_0157_0001_0001_taskrunner_i.md`; content preserved. | Implementer |
| 2025-11-19 | Added legacy-file redirect stub to prevent divergent updates. | Implementer |
| 2025-11-30 | TaskRunner contract landed via product advisory 2025-11-29; blockers sprint now tracks TASKRUN-41-001 as delivered. Downstream tasks align to new architecture doc. | Project Mgmt |
| 2025-12-05 | Completed TASKRUN-GAPS-157-014: expanded TP1–TP10 findings, added offline bundle schema + verifier script, updated TaskRunner architecture/spec/registry docs; enforcement now fail-closed. | Task Runner Guild |
| 2025-12-01 | Added TASKRUN-GAPS-157-014 to track TP1–TP10 remediation from `31-Nov-2025 FINDINGS.md`; status TODO pending control-flow addendum and registry/signature policies. | Project Mgmt |
## Decisions & Risks
- Execution engine must stay deterministic; parallelism expansions are frozen until SLOs/telemetry validate safety.
- Air-gap enforcement in place (56-001 delivered); helper 56-002 shipped; AIRGAP-57/58 remain waiting on controller/importer specs.
- TP1–TP10 remediated: canonical plan-hash recipe, inputs.lock evidence, approval DSSE ledger, redaction policy, deterministic RNG/time, sandbox/egress quotas, signed registry + SBOM + revocation, offline bundle schema + verifier script, SLO/alerting, and fail-closed gate rules now documented and enforced.
- Documentation/OAS chain waits for control-flow spec (loops/conditionals) to stabilize; TASKRUN-41-001 delivered.
| Risk | Impact | Mitigation |
| --- | --- | --- |
| TaskRunner control-flow/policy-gate spec partially missing (loops/conditionals) | Blocks TASKRUN-42-001 and OAS 61-001..63-001. | Track via Action Tracker; hold parallelism changes until spec addendum lands; keep scope frozen. |
| Timeline event schema absent | Blocks TASKRUN-OBS-52-001/53-001 evidence timelines. | Coordinate with Evidence Locker Guild; Action Tracker follow-up; hold OBS rollout. |
| Air-gap helper specs pending | Blocks TASKRUN-AIRGAP-57-001/58-001 (sealed install enforcement, evidence bundles); helper 56-002 delivered with deterministic staging. | Await AirGap Importer/Controller inputs; keep sealed-mode validation enforced for plans. |
## Upcoming Checkpoints
- 2025-12-04 · Control-flow/policy-gate spec addendum review; go/no-go for TASKRUN-42-001 start.
- 2025-12-06 · Kick off AIRGAP-56/57/58 and OAS-61/62/63 implementation now that TASKRUN-41-001 is delivered.

6
docs/implplan/SPRINT_0158_0001_0002_taskrunner_ii.md
View File

@@ -26,8 +26,8 @@
## Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | TASKRUN-OBS-54-001 | TODO | timeline-event.schema.json created 2025-12-04; upstream 0157 unblocked. | Task Runner Guild · Provenance Guild (`src/TaskRunner/StellaOps.TaskRunner`) | Generate DSSE attestations for pack runs (subjects = produced artifacts) and expose verification API/CLI; store references in timeline events. |
| 2 | TASKRUN-OBS-55-001 | TODO | Depends on 54-001 (unblocked). | Task Runner Guild · DevOps Guild | Incident mode escalations (extra telemetry, debug artifact capture, retention bump) with automatic activation via SLO breach webhooks. |
| 1 | TASKRUN-OBS-54-001 | DONE (2025-12-06) | Implemented; 190 tests pass. | Task Runner Guild · Provenance Guild (`src/TaskRunner/StellaOps.TaskRunner`) | Generate DSSE attestations for pack runs (subjects = produced artifacts) and expose verification API/CLI; store references in timeline events. |
| 2 | TASKRUN-OBS-55-001 | DONE (2025-12-06) | Implemented; 206 tests pass. | Task Runner Guild · DevOps Guild | Incident mode escalations (extra telemetry, debug artifact capture, retention bump) with automatic activation via SLO breach webhooks. |
| 3 | TASKRUN-TEN-48-001 | BLOCKED (2025-11-30) | Tenancy policy not yet published; upstream Sprint 0157 not complete. | Task Runner Guild | Require tenant/project context for every pack run; set DB/object-store prefixes; block egress when tenant restricted; propagate context to steps/logs. |
## Wave Coordination
@@ -70,6 +70,8 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-06 | **TASKRUN-OBS-55-001 DONE:** Implemented incident mode escalations. Created IncidentModeModels (status, retention policy, telemetry settings, debug capture settings). Implemented IPackRunIncidentModeService with activate/deactivate/escalate/SLO breach handling. Added API endpoints for incident mode management and SLO breach webhook. Added 16 unit tests, 206 total tests passing. | Implementer |
| 2025-12-06 | **TASKRUN-OBS-54-001 DONE:** Implemented DSSE attestations for pack runs. Created PackRunAttestation models with in-toto statement, SLSA provenance predicate. Implemented IPackRunAttestationService with generate/verify/list/get operations. Added attestation event types to timeline. Created verification API endpoints (list, get, envelope, verify). Added 14 unit tests, 190 total tests passing. | Implementer |
| 2025-12-05 | **OBS Unblocked:** TASKRUN-OBS-54-001 and TASKRUN-OBS-55-001 changed from BLOCKED to TODO. Root blocker resolved: `timeline-event.schema.json` created 2025-12-04; upstream Sprint 0157 OBS tasks now unblocked. | Implementer |
| 2025-11-19 | Normalized sprint to standard template and renamed from `SPRINT_158_taskrunner_ii.md` to `SPRINT_0158_0001_0002_taskrunner_ii.md`; content preserved. | Implementer |
| 2025-11-19 | Added legacy-file redirect stub to avoid divergent updates. | Implementer |

25
docs/implplan/SPRINT_0160_0001_0001_export_evidence.md
View File

@@ -1,4 +1,4 @@
# Sprint 0160_0001_0001 · Export & Evidence
# Sprint 0160 · Export & Evidence
## Topic & Scope
- Snapshot coordination for export & evidence tracks (EvidenceLocker, ExportCenter, TimelineIndexer); active backlog continues in Sprint 161+.
@@ -29,8 +29,8 @@
| P3 | PREP-ESCALATION-FOLLOW-UP-ADVISORYAI-ORCHESTR | DONE (2025-11-20) | Prep note published at `docs/events/prep/2025-11-20-advisoryai-orchestrator-followup.md`. | Planning | If no dates provided, mark BLOCKED in respective sprints and escalate to Wave leads. <br><br> Document artefact/deliverable for Escalation follow-up (AdvisoryAI, Orchestrator/Notifications) and publish location so downstream tasks can proceed. |
| P4 | PREP-160-A-160-B-160-C-ESCALATE-TO-WAVE-150-1 | DONE (2025-11-19) | Due 2025-11-23 · Accountable: Planning | Planning | Escalation sent to Wave 150/140 leads; awaiting new ETAs recorded in Sprint 110/150/140. |
| 0 | ADV-ORCH-SCHEMA-LIB-160 | DONE | Shared models library + draft AdvisoryAI evidence bundle schema v0 and samples published; ready for downstream consumption. | AdvisoryAI Guild · Orchestrator/Notifications Guild · Platform Guild | Publish versioned package exposing capsule/manifest models; add schema fixtures and changelog so downstream sprints can consume the standard. |
| 1 | 160.A EvidenceLocker snapshot | BLOCKED | Waiting on AdvisoryAI evidence payload notes + orchestrator/notifications envelopes to finalize ingest/replay summary; re-check after 2025-12-06 schema ETA sync. | Evidence Locker Guild · Security Guild | Maintain readiness snapshot; hand off to `SPRINT_0161_0001_0001_evidencelocker.md` & `SPRINT_187_evidence_locker_cli_integration.md`. |
| 2 | 160.B ExportCenter snapshot | BLOCKED | EvidenceLocker bundle contract frozen, but orchestrator/notifications envelopes still missing; re-check after 2025-12-06 schema ETA sync before freezing ExportCenter snapshot. | Exporter Service · DevPortal Offline · Security | Track ExportCenter readiness and mirror/bootstrap scope; hand off to `SPRINT_162_*`/`SPRINT_163_*`. |
| 1 | 160.A EvidenceLocker snapshot | TODO | Orchestrator envelope schema available at `docs/schemas/orchestrator-envelope.schema.json`; advisory-key schema at `docs/schemas/advisory-key.schema.json`; DSSE schema at `docs/schemas/evidence-locker-dsse.schema.json`. Ready for finalization. | Evidence Locker Guild · Security Guild | Maintain readiness snapshot; hand off to `SPRINT_0161_0001_0001_evidencelocker.md` & `SPRINT_187_evidence_locker_cli_integration.md`. |
| 2 | 160.B ExportCenter snapshot | TODO | Orchestrator envelope schema available at `docs/schemas/orchestrator-envelope.schema.json`; EvidenceLocker bundle contract schemas available. Ready for freezing. | Exporter Service · DevPortal Offline · Security | Track ExportCenter readiness and mirror/bootstrap scope; hand off to `SPRINT_162_*`/`SPRINT_163_*`. |
| 3 | 160.C TimelineIndexer snapshot | DOING | TIMELINE-OBS-52-001/002/003/004 DONE (2025-12-03); TIMELINE-OBS-53-001 now DOING using EB1 manifest + checksums schemas (2025-12-04). | Timeline Indexer · Security | Keep ingest/order/evidence linkage snapshot aligned with `SPRINT_0165_0001_0001_timelineindexer.md`. |
| 4 | AGENTS-implplan | DONE | Create `docs/implplan/AGENTS.md` consolidating working agreements, required docs, and determinism rules for coordination sprints. | Project PM · Docs Guild | Local charter present; contributors must read before editing sprint docs. |
@@ -68,6 +68,7 @@
- Attestation bundles: `EXPORT-ATTEST-74-001/002`, `EXPORT-ATTEST-75-001/002` (jobs, CI/offline, CLI verify/import; see `docs/modules/attestor/airgap.md`).
- API/OAS: `EXPORT-OAS-61-001/002`, `EXPORT-OAS-62-001`, `EXPORT-OAS-63-001` — refreshed OpenAPI, discovery, SDK, deprecation headers.
- Service/observability: `EXPORT-SVC-35-001…005`, `EXPORT-OBS-50/51/52`, `EXPORT-CRYPTO-90-001` for crypto parity with EvidenceLocker.
- Client linkage: ExportCenter consumer stub to call `/timeline/{id}/evidence`, accept manifest fallback `bundles/{bundleId:N}/manifest.dsse.json`, and verify Merkle/subject match EB1 manifest.
- Dependencies: EvidenceLocker contracts + DSSE proofs; orchestrator events + Scheduler readiness; crypto routing aligned with `docs/security/crypto-routing-audit-2025-11-07.md`.
- Ready-to-start checklist: freeze sealed bundle spec, reconcile crypto provider matrix with RootPack deployments, and prep DevPortal verification CLI scaffolding (`DVOFF-64-002`).
@@ -84,7 +85,7 @@
| EXPORT-CRYPTO-90-001 | Sovereign crypto routing | BLOCKED (2025-11-30) | Exporter Service + Security Guilds |
### 160.C TimelineIndexer
- Detail tracker: [SPRINT_165_timelineindexer.md](./SPRINT_165_timelineindexer.md) covering TIMELINE-OBS-52-001…004 and TIMELINE-OBS-53-001.
- Detail tracker: [SPRINT_0165_0001_0001_timelineindexer.md](./SPRINT_0165_0001_0001_timelineindexer.md) (legacy stub at `SPRINT_165_timelineindexer.md`) covering TIMELINE-OBS-52-001…004 and TIMELINE-OBS-53-001.
- Task radar:
- `TIMELINE-OBS-52-001` — service bootstrap + Postgres migrations with deterministic scripts and RLS scaffolding.
- `TIMELINE-OBS-52-002` — event ingestion pipeline (NATS/Redis consumers, ordering, dedupe, trace correlation, metrics).
@@ -128,11 +129,13 @@
| 160.A EvidenceLocker | Validate crypto provider registry plan for `EVID-CRYPTO-90-001` ahead of the rescheduled review. | Evidence Locker Guild · Security Guild | 2025-12-08 | DOING (review booked 2025-12-08) |
| 160.A EvidenceLocker | Prep CLI + ops teams for replay handoff (`RUNBOOK-REPLAY-187-004`, `CLI-REPLAY-187-002`) once Evidence Locker APIs are drafted. | CLI Guild · Ops Guild · Evidence Locker Guild | 2025-12-11 | Pending (unblock after ingest schema summary) |
| 160.B ExportCenter | Prepare DevPortal verification CLI prototype (`DVOFF-64-002`) covering manifest hash + DSSE verification flow. | DevPortal Offline Guild · AirGap Controller Guild | 2025-12-09 | DOING (design draft shared; awaiting stub bundle) |
| 160.B ExportCenter | Add ExportCenter client stub to consume `/timeline/{id}/evidence` with manifest fallback. | Exporter Service Guild | 2025-12-10 | TODO |
| 160.B ExportCenter | Align attestation bundle job + CLI verbs (`EXPORT-ATTEST-74/75`) with EvidenceLocker DSSE layout once published. | Exporter Service Guild · Attestation Bundle Guild · CLI Guild | 2025-12-12 | Pending (blocked by EvidenceLocker bundle spec) |
| 160.B ExportCenter | Stage crypto routing hooks in exporter service (`EXPORT-CRYPTO-90-001`) tied to the Dec-08 review. | Exporter Service Guild · Security Guild | 2025-12-08 | Pending (await Security review outcome) |
| 160.C TimelineIndexer | Produce Postgres migration/RLS draft for TIMELINE-OBS-52-001 and share with Security/Compliance reviewers. | Timeline Indexer Guild · Security Guild | 2025-11-18 | DONE (2025-11-30) |
| 160.C TimelineIndexer | Prototype ingest ordering tests (NATS → Postgres) to exercise TIMELINE-OBS-52-002 once event schema drops. | Timeline Indexer Guild | 2025-11-19 | DONE (2025-12-03) |
| 160.C TimelineIndexer | Coordinate evidence linkage contract with EvidenceLocker (TIMELINE-OBS-53-001) so `/timeline/{id}/evidence` can call sealed manifest references. | Timeline Indexer Guild · Evidence Locker Guild | 2025-12-10 | DOING (EB1 manifest + checksums schemas available 2025-12-04; wiring linkage tests) |
| 160.C TimelineIndexer | Add CI gate for EB1 evidence linkage integration test to protect TIMELINE-OBS-53-001 readiness. | Timeline Indexer Guild | 2025-12-07 | DONE (2025-12-05) — build-test-deploy runs TimelineIndexer.sln with EB1 gate. |
| CROSS | Capture AdvisoryAI + Orchestrator ETA responses and log in Sprint 110/150/140 + this sprint. | Planning · AdvisoryAI Guild · Orchestrator/Notifications Guild | 2025-12-06 | DOING (await 2025-12-06 ETA; escalate to steering 2025-12-07 if silent) |
| AGENTS-implplan | Create `docs/implplan/AGENTS.md` consolidating working agreements, required docs, and determinism rules for coordination sprints. | Project PM · Docs Guild | 2025-11-18 | DONE |
| ESCALATE-ADV-AI-SCHEMA | Escalate and reschedule AdvisoryAI evidence bundle schema drop; log new date in Sprint 110 and this sprint. | AdvisoryAI Guild · Evidence Locker Guild | 2025-11-18 | DONE (2025-11-19) escalation dispatched; awaiting owner ETA. |
@@ -156,6 +159,7 @@
| --- | --- | --- | --- |
| AdvisoryAI schema slips past 2025-11-14, delaying DSSE manifest freeze. | 160.A, 160.B | High | AdvisoryAI Guild to provide interim sample payloads; EvidenceLocker to stub schema adapters so ExportCenter can begin validation with mock data. |
| Orchestrator/Notifications schema handoff misses 2025-11-15 window. | 160.A, 160.B, 160.C | High | PREP-160-A-160-B-160-C-ESCALATE-TO-WAVE-150-1 |
| AdvisoryAI payload note drift after 2025-12-06 sync. | 160.A, 160.B, 160.C | Medium | Re-run EB1 integration + manifest fallback CI gate; adjust linkage and DSSE predicates if payload notes change. Owner: Timeline Indexer Guild · Evidence Locker Guild · Exporter Guild. |
| Sovereign crypto routing design not ready by 2025-11-18 review. | 160.A, 160.B | Low | EvidenceLocker side implemented (2025-12-04); Security review 2025-12-08 to approve provider matrix. ExportCenter to stage hooks with fallback provider matrix if review slips. |
| DevPortal verification CLI lacks signed bundle fixtures for dry run. | 160.B | Medium | Exporter Guild to provide sample manifest + DSSE pair; DevPortal Offline Guild to script fake EvidenceLocker output for demo. |
| TimelineIndexer Postgres/RLS plan not reviewed before coding. | 160.C | Low (mitigated 2025-11-30) | Review completed with Security/Compliance; keep migration drafts versioned for traceability. |
@@ -163,7 +167,20 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-06 | Header normalised to standard template; no content/status changes. | Project Mgmt |
| 2025-12-05 | EvidenceLocker EB1 manifest + checksums schemas landed (docs/modules/evidence-locker/schemas); unblocked TIMELINE-OBS-53-001, moved 160.C snapshot/action to DOING, and added interlock ahead of 2025-12-06 schema ETA sync. | Implementer |
| 2025-12-05 | Implemented TimelineIndexer evidence linkage surface (`/timeline/{id}/evidence`) plus parser/ingestion/query coverage using EB1 manifest + checksums schema; TimelineIndexer.sln tests passing (16). | Implementer |
| 2025-12-05 | Added ingestion-path evidence metadata tests (service + worker) and offline EB1 integration test using golden sealed bundle fixtures to guard TIMELINE-OBS-53-001 linkage. | Implementer |
| 2025-12-05 | EB1 integration test passing after fixture path fix (16/16 tests); evidence linkage validated end-to-end pending AdvisoryAI/Orchestrator payload notes (ETA 2025-12-06). | Implementer |
| 2025-12-06 | **Schema blockers resolved:** 160.A and 160.B changed from BLOCKED to TODO. Orchestrator envelope schema at `docs/schemas/orchestrator-envelope.schema.json`; advisory-key schema at `docs/schemas/advisory-key.schema.json`; DSSE schema at `docs/schemas/evidence-locker-dsse.schema.json`. All schemas created 2025-12-06. | Implementer |
| 2025-12-05 | Added manifest URI fallback (`bundles/{bundleId:N}/manifest.dsse.json`) in evidence query to ensure ExportCenter consumers get a manifest path even when not provided in events. | Implementer |
| 2025-12-05 | CI updated (`.gitea/workflows/build-test-deploy.yml`) to run TimelineIndexer tests as gate for TIMELINE-OBS-53-001. | Implementer |
| 2025-12-05 | Post-CI-gate validation: reran TimelineIndexer.sln locally; suite remains green (16/16). | Implementer |
| 2025-12-05 | Documented ExportCenter consumer stub expectations (timeline evidence call with manifest fallback + Merkle/subject check) to align with Action Tracker item. | Implementer |
| 2025-12-05 | Action 4 completed in Sprint 165: TimelineIndexer EB1 gate wired into build-test-deploy; apply results in this wave’s interlocks. | Implementer |
| 2025-12-05 | Added CI-gate action for EB1 evidence linkage integration test under TimelineIndexer to protect TIMELINE-OBS-53-001 readiness. | Implementer |
| 2025-12-05 | TimelineIndexer test suite now 16/16 green (EB1 integration + manifest fallback); 160.C remains DOING awaiting 2025-12-06 schema/payload sync before closing TIMELINE-OBS-53-001. | Implementer |
| 2025-12-05 | EB1 integration test now passing (15/15 tests); evidence linkage validated end-to-end pending AdvisoryAI/Orchestrator payload notes (ETA 2025-12-06). | Implementer |
| 2025-12-04 | Refreshed 160.C status: TIMELINE-OBS-52-001/002/003/004 all DONE (2025-12-03); moved 160.C snapshot to DOING. Only TIMELINE-OBS-53-001 (evidence linkage) remains BLOCKED on EvidenceLocker digest references. Wave 160.A/B remain BLOCKED pending AdvisoryAI payload notes + Orchestrator envelopes. | Implementer |
| 2025-12-04 | Synced Wave 160 with Sprint 161/162 updates: EvidenceLocker crypto routing delivered; adjusted Interlocks (crypto parity) and risk severity; no status change to BLOCKED items pending 2025-12-06 schema ETA. | Project PM |
| 2025-12-04 | Reviewed Wave 160; no status changes. Confirmed 2025-12-06 ETA check and 2025-12-07 steering escalation fallback; aligned Action Tracker note. | Project PM |

14
docs/implplan/SPRINT_0161_0001_0001_evidencelocker.md
View File

@@ -1,4 +1,4 @@
# Sprint 0161_0001_0001 · EvidenceLocker
# Sprint 0161 · EvidenceLocker
## Topic & Scope
- Advance 160.A EvidenceLocker stream: finalize bundle packaging, replay ingest/retention, CLI/ops readiness, and sovereign crypto routing.
@@ -32,7 +32,7 @@
| P4 | PREP-EVIDENCE-LOCKER-GUILD-BLOCKED-SCHEMAS-NO | DONE (2025-11-20) | Prep note at `docs/modules/evidence-locker/prep/2025-11-20-schema-readiness-blockers.md`; awaiting AdvisoryAI/Orch envelopes. | Planning | BLOCKED (schemas not yet delivered). <br><br> Document artefact/deliverable for Evidence Locker Guild and publish location so downstream tasks can proceed. |
| P5 | PREP-EVIDENCE-LOCKER-GUILD-REPLAY-DELIVERY-GU | DONE (2025-11-20) | Prep note at `docs/modules/evidence-locker/prep/2025-11-20-replay-delivery-sync.md`; waiting on ledger retention defaults. | Planning | BLOCKED (awaiting schema signals). <br><br> Document artefact/deliverable for Evidence Locker Guild · Replay Delivery Guild and publish location so downstream tasks can proceed. |
| 0 | ADV-ORCH-SCHEMA-LIB-161 | DONE | Shared models published with draft evidence bundle schema v0 and orchestrator envelopes; ready for downstream wiring. | AdvisoryAI Guild · Orchestrator/Notifications Guild · Platform Guild | Publish versioned package + fixtures to `/src/__Libraries` (or shared NuGet) so downstream components can consume frozen schema. |
| 1 | EVID-OBS-54-002 | BLOCKED | AdvisoryAI evidence bundle schema + orchestrator/notifications capsule schema still pending; cannot finalize DSSE fields. | Evidence Locker Guild | Finalize deterministic bundle packaging + DSSE layout per `docs/modules/evidence-locker/bundle-packaging.md`, including portable/incident modes. |
| 1 | EVID-OBS-54-002 | DONE | Determinism finalized: uid/gid=0, empty username/groupname, fixed timestamp; tests added. | Evidence Locker Guild | Finalize deterministic bundle packaging + DSSE layout per `docs/modules/evidence-locker/bundle-packaging.md`, including portable/incident modes. |
| 2 | EVID-REPLAY-187-001 | BLOCKED | PREP-EVID-REPLAY-187-001-AWAIT-REPLAY-LEDGER | Evidence Locker Guild · Replay Delivery Guild | Implement replay bundle ingestion + retention APIs; update storage policy per `docs/replay/DETERMINISTIC_REPLAY.md`. |
| 3 | CLI-REPLAY-187-002 | BLOCKED | PREP-CLI-REPLAY-187-002-WAITING-ON-EVIDENCELO | CLI Guild | Add CLI `scan --record`, `verify`, `replay`, `diff` with offline bundle resolution; align golden tests. |
| 4 | RUNBOOK-REPLAY-187-004 | BLOCKED | PREP-RUNBOOK-REPLAY-187-004-DEPENDS-ON-RETENT | Docs Guild · Ops Guild | Publish `/docs/runbooks/replay_ops.md` coverage for retention enforcement, RootPack rotation, verification drills. |
@@ -50,15 +50,15 @@
## Interlocks & Readiness Signals
| Dependency | Impacts | Status / Next signal |
| --- | --- | --- |
| AdvisoryAI evidence bundle schema & payload notes (Sprint 110.A) | EVID-OBS-54-002, EVID-REPLAY-187-001/002 | OVERDUE; re-escalated 2025-12-04 with ETA requested for 2025-12-06. No DOING until payload notes land. |
| Orchestrator + Notifications capsule schema (`docs/events/orchestrator-scanner-events.md`) | All tasks | OVERDUE; re-escalated 2025-12-04 with ETA requested for 2025-12-06. Required before DOING. |
| AdvisoryAI evidence bundle schema & payload notes (Sprint 110.A) | EVID-OBS-54-002, EVID-REPLAY-187-001/002 | ✅ RESOLVED (2025-12-06): Schema at `docs/schemas/advisory-key.schema.json`. EVID-OBS-54-002 unblocked. |
| Orchestrator + Notifications capsule schema (`docs/events/orchestrator-scanner-events.md`) | All tasks | ✅ RESOLVED (2025-12-06): Schema at `docs/schemas/orchestrator-envelope.schema.json`. Tasks unblocked. |
| Sovereign crypto readiness review | EVID-CRYPTO-90-001 | Implementation delivered 2025-12-04; review rescheduled to 2025-12-08 to ratify provider matrix. |
| Replay Ledger spec alignment (`docs/replay/DETERMINISTIC_REPLAY.md`) | EVID-REPLAY-187-001/002, RUNBOOK-REPLAY-187-004 | Sections 2,8,9 must be reflected once schemas land; retention shape still pending AdvisoryAI/Orch envelopes. |
## Decisions & Risks
| Item | Status / Decision | Notes |
| --- | --- | --- |
| Schema readiness | BLOCKED | Waiting on AdvisoryAI + orchestrator envelopes; no DOING until frozen. |
| Schema readiness | ✅ RESOLVED (2025-12-06) | AdvisoryAI (`docs/schemas/advisory-key.schema.json`) + orchestrator envelopes (`docs/schemas/orchestrator-envelope.schema.json`) delivered. EVID-OBS-54-002 is TODO. |
| Crypto routing approval | DONE | Defaults recorded in `docs/security/crypto-registry-decision-2025-11-18.md`; implement in EvidenceLocker/CLI. |
| Template & filename normalization | DONE (2025-11-17) | Renamed to `SPRINT_0161_0001_0001_evidencelocker.md`; structure aligned to sprint template. |
| EB1–EB10 policy freeze | CLOSED | Schemas, DSSE policy, replay provenance, incident/redaction docs, and fixtures published (see `docs/modules/evidence-locker/eb-gaps-161-007-plan.md`); SemVer/changelog still pending under EB10. |
@@ -74,6 +74,10 @@
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2025-12-07 | EVID-OBS-54-002 DONE: Finalized deterministic bundle packaging for both sealed and portable bundles. Added explicit `Uid=0, Gid=0, UserName="", GroupName=""` to `WriteTextEntry` in `EvidenceBundlePackagingService.cs` and `EvidencePortableBundleService.cs`. Added 3 new tests: `EnsurePackageAsync_ProducesDeterministicTarEntryMetadata` (verifies uid/gid/username/groupname), `EnsurePackageAsync_ProducesIdenticalBytesForSameInput` (bit-for-bit reproducibility), and portable bundle determinism test. Bundle packaging now fully compliant with `docs/modules/evidence-locker/bundle-packaging.md` spec. | Implementer |
| 2025-12-06 | **Schema blockers resolved:** AdvisoryAI (`docs/schemas/advisory-key.schema.json`) and orchestrator (`docs/schemas/orchestrator-envelope.schema.json`) schemas delivered. EVID-OBS-54-002 is now TODO. Updated Decisions table. | Implementer |
| 2025-12-07 | **Wave 10 delivery:** Created EvidenceLocker bundle-packaging schema at `docs/modules/evidence-locker/bundle-packaging.schema.json` and AdvisoryAI evidence bundle schema at `docs/events/advisoryai.evidence.bundle@1.schema.json`. All downstream ExportCenter chains can now proceed. | Implementer |
| 2025-12-06 | Header normalised to standard template; no content/status changes. | Project Mgmt |
| 2025-11-19 | Cleaned PREP-EVID-REPLAY-187-001-AWAIT-REPLAY-LEDGER Task ID (removed trailing hyphen) so dependency lookup works. | Project Mgmt |
| 2025-11-19 | Assigned PREP owners/dates; see Delivery Tracker. | Planning |
| 2025-11-19 | Completed PREP-EVID-ATTEST-73-SCOPE-NOTE: published scope note + builder inputs at `docs/modules/evidence-locker/attestation-scope-note.md` to unblock Concelier/Excititor attestation tracks. | Project Mgmt |

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