docs consolidation
This commit is contained in:
StellaOps Bot
@@ -1,27 +0,0 @@
|
||||
# Excititor · Consensus Removal Prep (AOC-19-004)
|
||||
|
||||
- **Date:** 2025-11-20
|
||||
- **Working directory:** `src/Excititor/__Libraries/StellaOps.Excititor.Core` + `src/Excititor/StellaOps.Excititor.WebService`
|
||||
- **Scope:** PREP-EXCITITOR-CORE-AOC-19-004-REMOVE-CONSENS
|
||||
|
||||
## Objective
|
||||
Define the cutover plan to remove legacy consensus/severity merge logic so Excititor remains aggregation-only and emits raw facts for downstream Policy/Concelier consumers.
|
||||
|
||||
## Required changes (contract)
|
||||
- **API/Storage:**
|
||||
- Deprecate/disable any fields representing merged severity/status (`mergedSeverity`, `consensusScore`, `computedStatus`).
|
||||
- Retain raw source fields: `status`, `justification`, `impact`, `affects`, `references`, `notes`, `provenance`, `reconciledFrom`.
|
||||
- Add boolean `consensusDisabled: true` to existing documents during migration for audit.
|
||||
- **Ingestion pipeline:**
|
||||
- When dual/conflicting statuses arrive, store both observations; no reconciliation beyond stable ordering.
|
||||
- Maintain deterministic ordering when multiple observations share `(tenant, advisoryId, component)` — sort by `ingestedAt`, then `source`, then `evidenceHash`.
|
||||
- **Feature flag:** `excititor:aoc:disableConsensus` default `true`; only temporary `false` allowed for rollback during migration.
|
||||
- **Telemetry:** counter `excititor.ingest.consensus.disabled` tagged by `tenant`, `source`, `connectorId`; increment once per batch after flag applied.
|
||||
|
||||
## Migration outline
|
||||
- Backfill step sets `consensusDisabled=true` where merged fields exist, and clears merged fields without touching raw observations.
|
||||
- Tests must assert merged fields are absent/null after migration and ingestion flows do not write them.
|
||||
|
||||
## Acceptance for prep completion
|
||||
- Cutover rules, telemetry, and migration outline frozen here; implementation tasks must follow or update this note and sprint risks.
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
# Console Cache & RBAC Prep — PREP-EXCITITOR-CONSOLE-23-003-DEPENDS-ON-23-001
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Excititor WebService Guild
|
||||
Scope: Capture caching, RBAC, and precedence-context requirements for console VEX lookups once the base contract (23-001) is defined.
|
||||
|
||||
## Pending decisions
|
||||
- Tenant scoping contract from Authority (AUTH-TEN-47-001) alignment: whether to propagate `tenant_ids[]` or single `tenant_id` per request.
|
||||
- Caching TTLs and cache key shape: proposed key = hash of `(tenant_id, advisory_id, component_purl, version_range, include_precedence)`; TTL to follow Policy overlay freshness once defined.
|
||||
- Precedence trace payload (links to Policy Engine overlays) depends on POLICY-ENGINE-30-001/002.
|
||||
|
||||
## Proposed endpoints (draft)
|
||||
- `GET /console/vex/cache/entries?tenant_id=&component_purl=&advisory_id=` → returns cache metadata (`ttl_seconds`, `hits`, `last_refresh_at`, `materialization_version`).
|
||||
- `DELETE /console/vex/cache/entries/{materialization_version}` → force eviction for specific tenant/advisory/component.
|
||||
|
||||
## RBAC sketch
|
||||
- Roles: `console.viewer`, `console.operator`, `console.admin`.
|
||||
- Permissions:
|
||||
- viewer: read-only to `/console/vex` + counters.
|
||||
- operator: can invalidate cache and request refresh.
|
||||
- admin: can set cache policy per tenant/project.
|
||||
|
||||
## Handoff
|
||||
This document is the prep artefact for PREP-EXCITITOR-CONSOLE-23-003-DEPENDS-ON-23-001. Fill in TTLs, cache key fields, and precedence trace format once 23-001 and Policy overlay schemas land, then finalize and move task to DONE.
|
||||
@@ -1,23 +0,0 @@
|
||||
# Console Counters Prep — PREP-EXCITITOR-CONSOLE-23-002-DEPENDS-ON-23-001
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Excititor WebService Guild
|
||||
Scope: Define the counter surfaces required for console delta cards, pending the `/console/vex` contract.
|
||||
|
||||
## Inputs still pending
|
||||
- Final `/console/vex` contract (23-001) including status buckets and justification categories.
|
||||
- Source-of-truth metrics/telemetry names from Policy Engine overlays (POLICY-ENGINE-30-001 once available).
|
||||
|
||||
## Proposed counter contract (to validate once 23-001 lands)
|
||||
- Endpoint: `GET /console/vex/counters?tenant_id=&component_purl=&advisory_id=&since=`
|
||||
- Response fields:
|
||||
- `total`, `affected`, `not_affected`, `under_investigation`, `mitigated`, `unknown`
|
||||
- `delta_since` (ISO-8601) and `window_seconds`
|
||||
- `evidence_refs[]` (DSSE hashes or linkset ids) optional
|
||||
- Metrics to emit:
|
||||
- Gauge `console_vex_active_total{tenant,status}`
|
||||
- Counter `console_vex_delta_total{tenant,status}` with `delta_since` label
|
||||
- Determinism: counters computed from immutable materialized views keyed by `(tenant, advisory_id, component_purl)`; avoid wall-clock beyond `since` parameter.
|
||||
|
||||
## Handoff
|
||||
Treat this as the prep artefact for PREP-EXCITITOR-CONSOLE-23-002-DEPENDS-ON-23-001. Update once status buckets are frozen in 23-001 and Policy metrics are published; then finalize endpoints and samples.
|
||||
@@ -1,25 +0,0 @@
|
||||
# Console / VEX Contract Prep — PREP-EXCITITOR-CONSOLE-23-001-AWAITING-CONCRE
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Excititor WebService Guild · BE-Base Platform Guild
|
||||
Scope: Capture the required `/console/vex` API contract inputs so downstream tasks can proceed once the concrete spec lands.
|
||||
|
||||
## Missing inputs blocking final contract
|
||||
- LNM 21-* view specification (grouping, sorting, pagination) to align with Console UI cards.
|
||||
- Final status chip taxonomy and precedence rules from Policy/Concelier overlays.
|
||||
- SSE channel naming + retry/heartbeat semantics shared with Scheduler/Policy streams.
|
||||
|
||||
## Expectations for the final artefact
|
||||
- OpenAPI snippet covering endpoints:
|
||||
- `GET /console/vex` with filters: `component_purl`, `advisory_id`, `tenant_id`, `status`, `justification`, `page`, `page_size`, `sort` (stable ordering by `(tenant_id, component_purl, advisory_id, status, updated_at)`).
|
||||
- `GET /console/vex/{advisory_id}` returning grouped statements, precedence trace pointer, provenance links (DSSE hash + linkset id), and tenant scoping.
|
||||
- Response envelope: standard console error schema once WEB-OAS-61-002 is frozen; until then use draft shape with `error`, `message`, `trace_id`.
|
||||
- Determinism: results ordered by `(tenant_id, advisory_id, component_purl, version_range)`; pagination stable under new data.
|
||||
- Counters: return aggregate status counters `{status -> count}` in the response to power delta chips without extra queries.
|
||||
- Caching: allow short-lived (≤30s) in-memory cache keyed by tenant+filters for Console views; include `hasMore`+`cursor` to keep pagination stable.
|
||||
|
||||
## Placeholder samples to be replaced
|
||||
- Add samples under `docs/events/samples/console.vex@draft.json` once view spec is provided.
|
||||
|
||||
## Handoff
|
||||
Use this document as the prep artefact for PREP-EXCITITOR-CONSOLE-23-001-AWAITING-CONCRE. Update once LNM view spec and SSE envelope land; then freeze the OpenAPI excerpt and move the sprint task to DONE. (Initial implementation now live with caching + counters; SSE still pending.)
|
||||
@@ -1,32 +0,0 @@
|
||||
# Excititor · Graph Linkouts Prep (GRAPH-21-001)
|
||||
|
||||
- **Date:** 2025-11-20
|
||||
- **Scope:** PREP-EXCITITOR-GRAPH-21-001-NEEDS-CARTOGRAPHE
|
||||
- **Working directory:** `src/Excititor/__Libraries/StellaOps.Excititor.Core` + `src/Excititor/StellaOps.Excititor.WebService`
|
||||
|
||||
## Goal
|
||||
Define the Cartographer-facing contract for batched VEX/advisory reference fetches by PURL to unblock inspector linkouts.
|
||||
|
||||
## Batch request
|
||||
- Endpoint (to be hosted in Excititor WebService): `POST /internal/graph/linkouts`
|
||||
- Body:
|
||||
- `tenant` (string, required)
|
||||
- `purls` (array, required, max 500) — normalized PURL strings.
|
||||
- `includeJustifications` (bool, default false)
|
||||
- `includeProvenance` (bool, default true)
|
||||
- Idempotency key: `tenant` + SHA256 of sorted `purls` list.
|
||||
|
||||
## Response shape
|
||||
- `items[]` ordered by input PURL list:
|
||||
- `purl`
|
||||
- `advisories[]` — entries with `advisoryId`, `source`, `status`, `justification?`, `modifiedAt`, `evidenceHash`, `connectorId`, `dsseEnvelopeHash?`.
|
||||
- `conflicts[]` — optional disagreements (status/justification) with `source`, `observedAt`, `evidenceHash`.
|
||||
- `notFound[]` — PURLs with no VEX observations.
|
||||
|
||||
## Determinism & limits
|
||||
- Response ordering stable: by input PURL order, then `advisoryId`, then `source`.
|
||||
- Max rows: cap `advisories` to 200 per PURL; truncate with `truncated: true` flag and `nextCursor` (advisoryId, source).
|
||||
|
||||
## Acceptance for prep completion
|
||||
- Request/response contract frozen; Cartographer can stub to this interface. Downstream GRAPH-21-001 implementation must adhere or update doc + sprint risks.
|
||||
|
||||
@@ -1,23 +0,0 @@
|
||||
# Excititor · Graph Overlay Prep (GRAPH-21-002)
|
||||
|
||||
- **Date:** 2025-11-20
|
||||
- **Depends on:** GRAPH-21-001 linkout contract
|
||||
- **Working directory:** `src/Excititor/StellaOps.Excititor.WebService`
|
||||
|
||||
## Overlay payload
|
||||
- Aggregates output of GRAPH-21-001 into overlay items for inspectors:
|
||||
- `purl`
|
||||
- `summary`: `open`, `not_affected`, `under_investigation`, `no_statement` counts
|
||||
- `latestModifiedAt` (ISO-8601 UTC)
|
||||
- `justifications[]` (optional) — unique justification codes present for the PURL
|
||||
- `provenance` — `sources[]` (unique source IDs), `lastEvidenceHash`
|
||||
- Endpoint: `GET /v1/graph/overlays?purl=<purl>[&purl=...]&includeJustifications=true|false`
|
||||
- Sorting: results ordered by input PURL list; within overlays, `justifications` sorted ascending.
|
||||
|
||||
## Caching
|
||||
- Cache key: tenant + sorted PURL list + `includeJustifications` flag; ttl 5 minutes default, configurable `excititor:graph:overlayTtlSeconds`.
|
||||
- Cache metadata returned: `cached: true|false`, `cacheAgeMs`.
|
||||
|
||||
## Acceptance for prep completion
|
||||
- Overlay shape and caching contract defined; implementation can proceed once GRAPH-21-001 is available.
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
# Excititor · Graph Indexes Prep (GRAPH-21-005)
|
||||
|
||||
- **Date:** 2025-11-20
|
||||
- **Depends on:** GRAPH-21-002 overlays
|
||||
- **Working directory:** `src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo`
|
||||
|
||||
## Index plan
|
||||
- Collection: `vex_observations`
|
||||
- Compound index `{ tenant: 1, component.purl: 1, advisoryId: 1, source: 1, modifiedAt: -1 }` (supports overlay queries and truncation cursor).
|
||||
- Sparse index `{ tenant: 1, component.purl: 1, status: 1 }` for summary counts.
|
||||
- Collection: `vex_overlays` (materialized cache, optional)
|
||||
- Index `{ tenant: 1, purl: 1 }` unique.
|
||||
- TTL index on `cachedAt` configurable via `excititor:graph:overlayTtlSeconds`.
|
||||
|
||||
## Determinism
|
||||
- Materialization job must sort observations as per GRAPH-21-001 ordering before writing overlays so pagination/cursors align.
|
||||
- TTL applied identically across tenants; default 300s, override allowed via config but must be documented.
|
||||
|
||||
## Acceptance for prep completion
|
||||
- Index keys and TTL knobs defined; downstream storage tasks can implement without further contract churn.
|
||||
|
||||
@@ -1,18 +0,0 @@
|
||||
# Linkset Extraction Prep — PREP-EXCITITOR-CORE-AOC-19-002-LINKSET-EXTRAC
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Excititor Core Guild
|
||||
Scope: Identify the extraction rules and ordering needed to produce linksets from VEX/advisory inputs before idempotent raw upsert work starts.
|
||||
|
||||
## Required content to unblock
|
||||
- Canonical linkset schema version (pending Cartographer/Concelier alignment); need field list and conflict markers.
|
||||
- Source ranking/precedence table shared with Concelier LNM 21-002 fixtures.
|
||||
|
||||
## Proposed extraction rules (draft)
|
||||
- Inputs: advisory documents (component PURLs, version ranges, references, severities, CVSS vectors); output: linkset entries with `advisory_id`, `component_purl`, `version_range`, `references[]`, `severity`, `cvss`.
|
||||
- Ordering: sort entries by `(component_purl, advisory_id, version_range)`; within references, sort lexicographically.
|
||||
- Conflict handling: if multiple sources disagree, emit `conflicts[]` with `source`, `field`, `reason`; never collapse values.
|
||||
- Determinism: no wall-clock; timestamps only from source payloads (UTC ISO-8601) and preserved as-is.
|
||||
|
||||
## Handoff
|
||||
Treat this as the prep artefact for PREP-EXCITITOR-CORE-AOC-19-002-LINKSET-EXTRAC. Once the shared linkset schema and precedence table land, finalize the rules and move the sprint task to DONE.
|
||||
@@ -1,18 +0,0 @@
|
||||
# Raw Upsert Idempotency Prep — PREP-EXCITITOR-CORE-AOC-19-003-BLOCKED-ON-19
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Excititor Core Guild
|
||||
Scope: Document the idempotent raw upsert and versioning requirements once linkset extraction (19-002) is defined.
|
||||
|
||||
## Pending inputs
|
||||
- Linkset schema and conflict markers from 19-002.
|
||||
- Storage model choice (Mongo vs Postgres) and required unique keys per tenant/advisory/component/version_range.
|
||||
|
||||
## Proposed rules (draft)
|
||||
- Unique key: `(tenant_id, advisory_id, component_purl, version_range, source)`; store a monotonic `revision` and `ingested_at` (UTC) for traceability.
|
||||
- Idempotency: compute content hash over canonicalized payload; if identical, no-op; otherwise append new revision with `supersedes` pointer.
|
||||
- Append-only log: keep prior revisions for audit; consumers read latest by hash or highest revision per key.
|
||||
- Determinism: canonical JSON ordering; stable sorting by `(tenant_id, advisory_id, component_purl, version_range, revision)`.
|
||||
|
||||
## Handoff
|
||||
Use this as the prep artefact for PREP-EXCITITOR-CORE-AOC-19-003-BLOCKED-ON-19. Finalize once 19-002 freezes schema and storage choice; then wire migrations/indexes accordingly.
|
||||
@@ -1,23 +0,0 @@
|
||||
# Excititor · Tenant-Aware Authority Prep (AOC-19-013)
|
||||
|
||||
- **Date:** 2025-11-20
|
||||
- **Scope:** PREP-EXCITITOR-CORE-AOC-19-013-SEED-TENANT-AW
|
||||
- **Working directory:** `src/Excititor/StellaOps.Excititor.WebService`, `src/Excititor/StellaOps.Excititor.Worker`, `src/Excititor/__Libraries/StellaOps.Excititor.Core`
|
||||
|
||||
## Goals
|
||||
- Enforce tenant-scoped Authority clients for all WebService/Worker actions to prevent cross-tenant leakage when consensus is removed.
|
||||
- Provide deterministic fixture/seed guidance for e2e tests.
|
||||
|
||||
## Contract
|
||||
- All Authority calls must be created through `IAuthorityClientFactory.Create(tenantId)`; factories that lack tenant must throw.
|
||||
- Configuration: `excititor:authority:baseUrl`, `excititor:authority:audience`, per-tenant `clientId/clientSecret` retrieved via internal secret resolver (no cross-tenant cache).
|
||||
- Headers: include `X-Tenant` on every outbound request; reject response lacking matching `tenant` claim.
|
||||
- Telemetry: meter `StellaOps.Excititor.Auth` counters `authority.call` tagged `tenant`, `operation`, `result` (`ok|unauthorized|forbidden|error`).
|
||||
|
||||
## Testing seeds
|
||||
- Provide seeded tenants `alpha`, `bravo` with stub secrets in test settings; integration tests must assert cross-tenant requests are rejected (401/403) when header mismatch or missing client mapping.
|
||||
- Fake Authority server returns tenant claim; tests validate enforcement and logs.
|
||||
|
||||
## Acceptance for prep completion
|
||||
- Tenant-scoped client contract, config keys, and test seeds documented; downstream tasks 19-013 can proceed using this as authority.
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# Excititor Air-Gap Prep (56-001, 57-001, 58-001)
|
||||
|
||||
Status: **Ready for implementation** (2025-11-22)
|
||||
Owners: Excititor Core Guild · AirGap Policy Guild · Evidence Locker Guild
|
||||
Scope: Define ingestion/egress contracts for Excititor when operating in sealed/offline environments and align with mirror bundle + Evidence Locker artifacts.
|
||||
|
||||
## Inputs
|
||||
- Mirror bundle schema (thin) from `docs/modules/mirror/assembler.md`.
|
||||
- Evidence Locker attestation contract: `docs/modules/evidence-locker/attestation-contract.md`.
|
||||
- Link-Not-Merge schema for advisory evidence: `docs/modules/concelier/link-not-merge-schema.md`.
|
||||
|
||||
## Deliverables
|
||||
- Ingestion envelope for `POST /airgap/vex/import`:
|
||||
- Fields: `bundleId`, `mirrorGeneration`, `signedAt`, `publisher`, `payloadHash`, `payloadUrl?` (offline tar path), `signature`, `transparencyLog?`.
|
||||
- Validation: deterministic hash of NDJSON payloads; must reject mixed tenants; clock-skew tolerance ±5s.
|
||||
- Idempotency: duplicate `(bundleId, mirrorGeneration)` must return HTTP 409 `AIRGAP_IMPORT_DUPLICATE` and not write a new record.
|
||||
- Sealed-mode error catalog (57-001): `AIRGAP_EGRESS_BLOCKED`, `AIRGAP_PAYLOAD_STALE`, `AIRGAP_SIGNATURE_MISSING`, `AIRGAP_SOURCE_UNTRUSTED`; each with HTTP 4xx mapping and remediation text.
|
||||
- Notification hooks (58-001): timeline events `airgap.import.started/completed/failed` with attributes `{tenantId,bundleId,generation,stalenessSeconds}`; link to Evidence Locker bundle ID for audit.
|
||||
- Determinism rules: sort imported observations by `advisoryKey` then `productKey`; write timeline events in the same order; all timestamps UTC ISO-8601.
|
||||
- Connector trust (CONN-TRUST-01-001):
|
||||
- Trusted signer manifests reuse `docs/modules/excititor/schemas/connector-signer-metadata.schema.json`; require `fingerprint`, `issuer`, `validFrom/To`, `allowedProfiles`, `bundleHash`.
|
||||
- Validation: fail import with `AIRGAP_SOURCE_UNTRUSTED` when signer fingerprint not in manifest, signature algorithm not in `{rsa-pss-sha256, ecdsa-p256-sha256, gost-r3410-2012-256}`, or bundle hash mismatch.
|
||||
- Offline parity: store signer manifests alongside mirror bundle under `mirror/signers/` and include SHA256 in `SHA256SUMS.dsse`.
|
||||
|
||||
## Acceptance Criteria
|
||||
- API shapes captured in this prep are referenced from Sprint 0119 Delivery Tracker; no further blockers for Excititor AirGap tasks.
|
||||
- Error catalog and timeline events documented and consumed by downstream Policy/AirGap controller work.
|
||||
- Import path validated against mirror bundle schema; mismatch should raise `AIRGAP_PAYLOAD_STALE`.
|
||||
|
||||
## Notes
|
||||
- Satisfies PREP-EXCITITOR-AIRGAP-56-001, PREP-EXCITITOR-AIRGAP-57-001, and PREP-EXCITITOR-AIRGAP-58-001.
|
||||
@@ -1,27 +0,0 @@
|
||||
# Attestation Verifier Rehearsal — Excititor
|
||||
|
||||
Status: **Ready for implementation** (2025-11-22)
|
||||
Owners: Excititor Attestation Guild · Evidence Locker Guild
|
||||
Scope: Dry-run `IVexAttestationVerifier` against current Evidence Locker bundles to ensure Excititor attestation endpoints ship with deterministic verification.
|
||||
|
||||
## Test Matrix
|
||||
- Inputs: Evidence Bundle v1 sample (`docs/samples/evidence-bundle/*`), mirror bundle thin sample (`out/mirror/thin/mirror-thin-m0-sample.tar.gz`).
|
||||
- Verification steps:
|
||||
1. Validate DSSE envelope signature and Rekor entry (if present); offline mode skips transparency but records `rekorSkipped=true`.
|
||||
2. Verify manifest hash tree against payload NDJSON files; fail on first mismatch.
|
||||
3. Assert policy hash matches Policy Engine overlay hash (placeholder `policyHash` captured for now).
|
||||
4. Emit structured result JSON: `{bundleId, verified, dsseVerified, transparencyChecked, manifestRoot, failures[]}`.
|
||||
- Determinism: sorted failure list, timestamps set to supplied `--as-of` flag.
|
||||
|
||||
## Deliverables
|
||||
- Harness entry point: `tools/attestation/verifier-rehearsal.sh` (script stub path reserved).
|
||||
- Sample output recorded at `docs/modules/excititor/prep/artifacts/2025-11-22-attestation-rehearsal.json` (to be produced in implementation).
|
||||
- Logging fields to surface in Excititor: `attestationBundleId`, `evidenceBundleId`, `verified`, `failureCode`, `tenantId`.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Rehearsal script runs offline using bundled samples and exits non-zero on any verification failure.
|
||||
- Output schema above is referenced by Excititor API tests and Policy attest replay tasks.
|
||||
- Downstream tasks EXCITITOR-GRAPH-21-00x and attestation endpoints can rely on this contract.
|
||||
|
||||
## Notes
|
||||
- Satisfies PREP-ATTESTATION-VERIFIER-REHEARSAL-EXCITITOR.
|
||||
Reference in New Issue
Block a user