stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
08b27b8a266c82960c7653797460e1e1d17ecd45
git.stella-ops.org/docs/implplan/SPRINT_119_excititor_i.md
master 61f963fd52
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Implement ledger metrics for observability and add tests for Ruby packages endpoints 
- Added `LedgerMetrics` class to record write latency and total events for ledger operations.
- Created comprehensive tests for Ruby packages endpoints, covering scenarios for missing inventory, successful retrieval, and identifier handling.
- Introduced `TestSurfaceSecretsScope` for managing environment variables during tests.
- Developed `ProvenanceMongoExtensions` for attaching DSSE provenance and trust information to event documents.
- Implemented `EventProvenanceWriter` and `EventWriter` classes for managing event provenance in MongoDB.
- Established MongoDB indexes for efficient querying of events based on provenance and trust.
- Added models and JSON parsing logic for DSSE provenance and trust information.
2025-11-13 09:29:09 +02:00

13 KiB
Raw Blame History

Sprint 119 - Ingestion & Evidence · 110.C) Excititor.I

Active items only. Completed/historic work now resides in docs/implplan/archived/tasks.md (updated 2025-11-08).

[Ingestion & Evidence] 110.C) Excititor.I Depends on: Sprint 100.A - Attestor Summary: Ingestion & Evidence focus on Excititor (phase I).

Prep: Read docs/modules/excititor/architecture.md and the relevant Excititor AGENTS.md files (per component directory) before working any tasks below; this preserves the guidance that previously lived in the component boards.

Task ID State Task description Owners (Source)
EXCITITOR-AIAI-31-001 Justification enrichment DONE (2025-11-12) Expose normalized VEX justifications, product scope trees, and paragraph/JSON-pointer anchors via VexObservation projections so Advisory AI can cite raw evidence without invoking any consensus logic. Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
EXCITITOR-AIAI-31-002 VEX chunk API TODO Ship /vex/evidence/chunks with tenant/policy filters that streams raw statements, signature metadata, and scope scores for Retrieval-Augmented Generation clients; response must stay aggregation-only and reference observation/linkset IDs. Depends on EXCITITOR-AIAI-31-001. Excititor WebService Guild (src/Excititor/StellaOps.Excititor.WebService)
EXCITITOR-AIAI-31-003 Telemetry & guardrails IN REVIEW (2025-11-13) Instrument the new evidence APIs with request counters, chunk sizes, signature verification failure meters, and AOC guard violations so Lens/Advisory AI teams can detect misuse quickly. Depends on EXCITITOR-AIAI-31-002. Excititor WebService Guild, Observability Guild (src/Excititor/StellaOps.Excititor.WebService)
EXCITITOR-AIAI-31-004 Schema & docs alignment TODO Update OpenAPI/SDK/docs to codify the Advisory-AI evidence contract (fields, determinism guarantees, pagination) and describe how consumers map observation IDs back to raw storage. Excititor WebService Guild, Docs Guild (src/Excititor/StellaOps.Excititor.WebService)
EXCITITOR-AIRGAP-56-001 Mirror-first ingestion TODO Wire mirror bundle ingestion paths that preserve upstream digests, bundle IDs, and provenance metadata exactly so offline Advisory-AI/Lens deployments can replay evidence with AOC parity. Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
EXCITITOR-AIRGAP-57-001 Sealed-mode enforcement TODO Enforce sealed-mode policies that disable external connectors, emit actionable remediation errors, and record staleness annotations that Advisory AI can surface as “evidence freshness” signals. Depends on EXCITITOR-AIRGAP-56-001. Excititor Core Guild, AirGap Policy Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
EXCITITOR-AIRGAP-58-001 Portable evidence bundles TODO Package tenant-scoped VEX evidence (raw JSON, normalization diff, provenance) into portable bundles tied to timeline events so Advisory AI can hydrate contexts in sealed environments. Depends on EXCITITOR-AIRGAP-57-001. Excititor Core Guild, Evidence Locker Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
EXCITITOR-ATTEST-01-003 Verification suite & observability TODO (2025-11-06) Finish IVexAttestationVerifier, wire structured diagnostics/metrics, and prove we can verify DSSE bundles for every evidence batch without touching consensus results (see EXCITITOR-ATTEST-01-003-plan.md). Excititor Attestation Guild (src/Excititor/__Libraries/StellaOps.Excititor.Attestation)
EXCITITOR-ATTEST-73-001 VEX attestation payloads TODO Emit attestation payloads that capture supplier identity, justification summary, and scope metadata so downstream Lens/Policy jobs can chain trust without Excititor interpreting the evidence. Depends on EXCITITOR-ATTEST-01-003. Excititor Core Guild, Attestation Payloads Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
EXCITITOR-ATTEST-73-002 Chain provenance TODO Provide APIs that link attestation IDs back to observation/linkset/product tuples, enabling Advisory AI to cite provenance without any derived verdict. Depends on EXCITITOR-ATTEST-73-001. Excititor Core Guild (src/Excititor/__Libraries/StellaOps.Excititor.Core)
EXCITITOR-CONN-TRUST-01-001 Connector provenance parity TODO Update MSRC, Oracle, Ubuntu, and Stella mirror connectors to emit signer fingerprints, issuer tiers, and bundle references while remaining aggregation-only; document how Lens consumers should interpret these hints. Excititor Connectors Guild (src/Excititor/__Libraries/StellaOps.Excititor.Connectors.*)

Task clusters & readiness

Advisory-AI evidence APIs

  • Delivered: EXCITITOR-AIAI-31-001 (/v1/vex/observations/{vulnerabilityId}/{productKey} projection API) landed 2025-11-12 with normalized justifications and anchors.
  • In flight: EXCITITOR-AIAI-31-003 (instrumentation + guardrails) and EXCITITOR-AIAI-31-004 (OpenAPI/SDK/docs alignment).
  • Dependencies: Needs EXCITITOR-AIAI-31-002 (projection service plumbing) — confirmed completed via architecture doc; observability pipeline requires Ops dashboards.
  • Ready-to-start checklist: finalize request/response examples in OpenAPI, add replayable telemetry fixtures, and attach Advisory-AI contract summary to this sprint doc.

AirGap ingestion & portable bundles

  • Scope: EXCITITOR-AIRGAP-56/57/58 (mirror-first ingestion, sealed-mode enforcement, portable evidence bundles).
  • Dependencies: relies on Attestor DSSE verification (Sprint 100.A) and AirGap policy toggles; Evidence Locker partnership needed for portable bundle format.
  • Ready-to-start checklist:
    1. Secure mirror bundle schema from Export Center (Sprint 162) and attach sample manifests.
    2. Document sealed-mode error catalog + diagnostics surfaced to Advisory AI/Lens during offline enforcement.
    3. Define bundle manifest → timeline ID mapping for Advisory AI, referencing Export Center + TimelineIndexer contracts.

Attestation & provenance chain

  • Tasks: EXCITITOR-ATTEST-01-003, EXCITITOR-ATTEST-73-001, EXCITITOR-ATTEST-73-002.
  • Dependencies: Attestor service readiness (Sprint 100.A) plus DSSE payload contract; requires IVexAttestationVerifier plan doc referenced in repo.
  • Ready-to-start checklist:
    1. Finish verifier test harness & deterministic diagnostics.
    2. Capture sample attestation payload spec (supplier identity, justification summary, scope metadata) and attach here.
    3. Describe provenance linkage for /v1/vex/attestations/{id} + observation/linkset/product tuples in docs.

Connector provenance parity

  • Task: EXCITITOR-CONN-TRUST-01-001 (MSRC/Oracle/Ubuntu/Stella connectors).
  • Dependencies: Source feeds must already emit signer metadata; align with AOC aggregator guardrails; ensure docs outline how Lens consumes trust hints.
  • Ready-to-start checklist:
    1. Inventory current connector coverage + signer metadata availability.
    2. Define signer fingerprint + issuer tier schema shared across connectors (document in module README).
    3. Update acceptance tests under src/Excititor/__Libraries/StellaOps.Excititor.Connectors.* to assert provenance payload.

Dependencies & blockers

  • Attestor DSSE verification (EXCITITOR-ATTEST-01-003, Sprint 100.A) gates EXCITITOR-ATTEST-73-001/002 and portable bundles.
  • Export Center mirror bundle schema (Sprint 162) and EvidenceLocker portable bundle format (Sprint 160/161) must land before EXCITITOR-AIRGAP-56/58 can proceed; target sync 2025-11-15.
  • Observability stack (Ops/Signals wave) must expose span/metric sinks before EXCITITOR-AIAI-31-003 instrumentation merges; waiting on Ops telemetry MR.
  • Security review pending for connector provenance fingerprints to ensure no secrets leak in aggregation-only mode; Docs/Security review scheduled 2025-11-18.

Documentation references

  • docs/modules/excititor/architecture.md — authoritative data model, APIs, and guardrails for Excititor.
  • docs/modules/excititor/README.md#latest-updates — consensus beta + Advisory-AI integration context.
  • docs/modules/excititor/mirrors.md — AirGap/mirror ingestion checklist referenced by EXCITITOR-AIRGAP-56/57.
  • docs/modules/excititor/operations/* — observability + sealed-mode runbooks feeding EXCITITOR-AIAI-31-003 instrumentation requirements.
  • docs/modules/excititor/implementation_plan.md — per-module workstream alignment table (mirrors Sprint 200 documentation process).

Action tracker

Focus Action Owner(s) Due Status
Advisory-AI APIs Publish finalized OpenAPI schema + SDK notes for projection API (EXCITITOR-AIAI-31-004). Excititor WebService Guild · Docs Guild 2025-11-15 In review (draft shared 2025-11-13)
Observability Wire metrics/traces for /v1/vex/observations/** and document dashboards (EXCITITOR-AIAI-31-003). Excititor WebService Guild · Observability Guild 2025-11-16 Blocked (code + ops runbook ready; waiting on Ops span sink deploy)
AirGap Capture mirror bundle schema + sealed-mode toggle requirements for EXCITITOR-AIRGAP-56/57. Excititor Core Guild · AirGap Policy Guild 2025-11-17 Pending
Portable bundles Draft bundle manifest + EvidenceLocker linkage notes for EXCITITOR-AIRGAP-58-001. Excititor Core Guild · Evidence Locker Guild 2025-11-18 Pending
Attestation Complete verifier suite + diagnostics for EXCITITOR-ATTEST-01-003. Excititor Attestation Guild 2025-11-16 In progress (verifier harness 80% complete)
Connectors Inventory signer metadata + plan rollout for MSRC/Oracle/Ubuntu/Stella connectors (EXCITITOR-CONN-TRUST-01-001). Excititor Connectors Guild 2025-11-19 Pending (schema draft expected 2025-11-14)

Upcoming checkpoints (UTC)

Date Session / Owner Goal Fallback
2025-11-14 Connector provenance schema review (Connectors + Security Guilds) Approve signer fingerprint + issuer tier schema for EXCITITOR-CONN-TRUST-01-001. If schema not ready, keep task blocked and request interim metadata list from connectors.
2025-11-15 Export Center mirror schema sync (Export Center + Excititor + AirGap) Receive mirror bundle manifest to unblock EXCITITOR-AIRGAP-56/57 (schema still pending). If delayed, escalate to Sprint 162 leads and use placeholder spec with clearly marked TODO.
2025-11-16 Attestation verifier rehearsal (Excititor Attestation Guild) Demo IVexAttestationVerifier harness + diagnostics to unblock EXCITITOR-ATTEST-73-*. If issues persist, log BLOCKED status in attestation plan and re-forecast completion.
2025-11-18 Observability span sink deploy (Ops/Signals Guild) Enable telemetry pipeline needed for EXCITITOR-AIAI-31-003. If deploy slips, implement temporary counters/logs and keep action tracker flagged as blocked.

Risks & mitigations

Risk Severity Impact Mitigation
Observability sinks not ready for EXCITITOR-AIAI-31-003 Medium Advisory-AI misuse would go undetected Coordinate with Ops to reuse Signals dashboards; ship log-only fallback.
Mirror bundle schema slips (Export Center/AirGap) High Blocks sealed-mode + portable bundles Use placeholder schema from docs/modules/export-center/architecture.md and note deltas; escalate to Export Center leads.
Attestation verifier misses 2025-11-16 target High Attestation payload tasks cannot start Daily stand-ups with Attestation Guild; parallelize diagnostics while verifier finalizes.
Connector signer metadata incomplete Medium Trust parity story delayed Stage connector-specific TODOs; allow partial rollout with feature flags.

Status log

  • 2025-11-12 — Snapshot refreshed; EXCITITOR-AIAI-31-001 marked DONE, remaining tasks pending on observability, AirGap bundle schemas, and attestation verifier completion.
  • 2025-11-13 — Added readiness checklists per task cluster plus action tracker; awaiting outcomes from Export Center mirror schema delivery and Attestor verifier rehearsals before flipping AirGap/Attestation tasks to DOING.
  • 2025-11-13 (EOD) — OpenAPI draft for EXCITITOR-AIAI-31-004 shared for review; Observability wiring blocked until Ops deploys span sink, noted above.
  • 2025-11-14 — Connector provenance schema review scheduled; awaiting schema draft delivery before meeting. Export Center mirror schema still pending, keeping EXCITITOR-AIRGAP-56/57 blocked.
  • 2025-11-14 — EXCITITOR-AIAI-31-003 instrumentation (request counters, chunk histogram, signature failure + guard-violation meters) merged into Excititor WebService; telemetry export remains blocked on Ops span sink rollout.
  • 2025-11-14 (PM) — Published docs/modules/excititor/operations/observability.md documenting the new evidence metrics so Ops/Lens can hook dashboards while waiting for the span sink deployment.

2025-11-12: EXCITITOR-AIAI-31-001 delivered /v1/vex/observations/{vulnerabilityId}/{productKey} backed by the new IVexObservationProjectionService, returning normalized statements (scope tree, anchors, document metadata) so Advisory AI and Console can cite raw VEX evidence without touching consensus logic.