stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
108d1c64b323808d6085fca05818fc581c6b003a
git.stella-ops.org/docs/modules/vex-lens/implementation_plan.md
StellaOps Bot 17d45a6d30
Some checks failed
Airgap Sealed CI Smoke / sealed-smoke (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
feat: Implement Filesystem and MongoDB provenance writers for PackRun execution context 
- Added `FilesystemPackRunProvenanceWriter` to write provenance manifests to the filesystem.
- Introduced `MongoPackRunArtifactReader` to read artifacts from MongoDB.
- Created `MongoPackRunProvenanceWriter` to store provenance manifests in MongoDB.
- Developed unit tests for filesystem and MongoDB provenance writers.
- Established `ITimelineEventStore` and `ITimelineIngestionService` interfaces for timeline event handling.
- Implemented `TimelineIngestionService` to validate and persist timeline events with hashing.
- Created PostgreSQL schema and migration scripts for timeline indexing.
- Added dependency injection support for timeline indexer services.
- Developed tests for timeline ingestion and schema validation.
2025-11-30 15:38:14 +02:00

4.9 KiB
Raw Blame History

Implementation plan — VEX Consensus Lens

Delivery phases

  • Phase 1 – Core lens service
    Build normalisation pipeline (CSAF/OpenVEX/CycloneDX), product mapping library, trust weighting functions, consensus algorithm, and persistence (vex_consensus, history, conflicts).
  • Phase 2 – API & integrations
    Expose /vex/consensus query/detail/simulate/export endpoints, integrate Policy Engine thresholds, Vuln Explorer UI chips, and VEX Lens change events.
  • Phase 3 – Issuer Directory & signatures
    Deliver issuer registry, key management, signature verification, RBAC, audit logs, and tenant overrides.
  • Phase 4 – Console & CLI experiences
    Ship Console module (lists, evidence table, quorum bar, conflicts, simulation drawer) and CLI commands (stella vex consensus ...) with export support.
  • Phase 5 – Recompute & performance
    Implement recompute scheduling (policy activation, Excitor deltas), caching, load tests (10M records/tenant), observability dashboards, and Offline Kit exports.

Work breakdown

  • VEX Lens service
    • Normalise VEX payloads, maintain scope scores, compute consensus digest.
    • Trust weighting functions (issuer tier, freshness decay, scope quality) ingest the new vex.provenance.* contract emitted by Excititor connectors (provider weight/tier, cosign metadata, fingerprints) so connector-tuned trust flows all the way to consensus.
    • Idempotent workers for consensus projection and history tracking.
    • Conflict handling queue for manual review and notifications.
  • Integrations
    • Excitor: enrich VEX events with issuer hints, signatures, product trees, and now connector-supplied trust weights/tiers that Lens consumes directly.
    • Policy Engine: trust knobs, simulation endpoints, policy-driven recompute.
    • Vuln Explorer & Advisory AI: consensus badges, conflict surfacing.
  • Issuer Directory
    • CRUD for issuers/keys, audit logs, import CSAF publishers, tenant overrides.
    • Signature verification endpoints consumed by Lens.
  • APIs & UX
    • REST endpoints for query/detail/conflict export, trust weight updates.
    • Console module with filters, saved views, evidence table, simulation drawer.
    • CLI commands for list/show/simulate/export with JSON/CSV output.
  • Observability & Ops
    • Metrics (consensus latency, conflict rate, signature failures, cache hit rate), logs, traces.
    • Dashboards + runbooks for recompute storms, mapping failures, signature errors, quota breaches.
    • Offline exports for Export Center/Offline Kit.

Acceptance criteria

  • Consensus results reproducible across supported VEX formats with deterministic digests and provenance.
  • Signature verification influences trust weights; unverifiable evidence is down-weighted without pipeline failure.
  • Policy simulations show quorum shifts without persisting state; Vuln Explorer consumes consensus signals.
  • Issuer Directory enforces RBAC, audit logs, and key rotation; CLI & Console parity achieved.
  • Recompute pipeline handles Excitor deltas and policy activations with backpressure and incident surfacing.
  • Observability dashboards/alerts cover ingestion lag, conflict spikes, signature failures, performance budgets (P95 < 500 ms for 100-row pages at 10M records/tenant).

Risks & mitigations

  • Product mapping ambiguity: conservative scope scoring, manual overrides, surfaced warnings, policy review hooks.
  • Issuer compromise: signature verification, trust weighting, tenant overrides, revocation runbooks.
  • Evidence storms: batching, worker sharding, orchestrator rate limiting, priority queues.
  • Performance degradation: caching, indexing, load tests, quota enforcement.
  • Offline gaps: deterministic exports, manifest hashes, Offline Kit tests.

Test strategy

  • Unit: normalisers, mapping, trust weights, consensus lattice, signature verification.
  • Property: randomised evidence sets verifying lattice commutativity and determinism.
  • Integration: Excitor → Lens → Policy/Vuln Explorer flow, issuer overrides, simulation.
  • Performance: large tenant datasets, cache behaviour, concurrency tests.
  • Security: RBAC, tenant scoping, signature tampering, issuer revocation.
  • Offline: export/import verification, CLI parity.

Definition of done

  • Lens service, issuer directory, API/CLI/Console components deployed with telemetry and runbooks.
  • Documentation set (overview, algorithm, issuer directory, API, console, policy trust) updated with imposed rule statements.
  • ./TASKS.md and ../../TASKS.md reflect current status; Offline Kit parity confirmed.

Sprint alignment (2025-11-30)

  • Docs refresh tracked in docs/implplan/SPRINT_0332_0001_0001_docs_modules_vex_lens.md; statuses mirrored in docs/modules/vex-lens/TASKS.md.
  • Observability evidence lives in runbooks/observability.md with Grafana JSON stub under runbooks/dashboards/.
  • Keep future doc/ops updates mirrored across sprint, TASKS, and module front doors to avoid drift.