stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions Releases Wiki Activity
Files
main
git.stella-ops.org/docs/modules/vexer/implementation_plan.md
master 8da4e12a90 Align AOC tasks for Excititor and Concelier
2025-10-31 18:50:15 +02:00

4.4 KiB
Raw Permalink Blame History

Implementation plan — Vexer

Delivery phases

  • Phase 1 – Connectors & normalization
    Build connectors for OpenVEX, CSAF VEX, CycloneDX VEX, OCI attestations; capture provenance, signatures, and source metadata; normalise into VexClaim.
  • Phase 2 – Mapping & trust registry
    Implement product mapping (CPE → purl/version), issuer registry (trust tiers, signatures), scope scoring, and justification taxonomy.
  • Phase 3 – Consensus & projections
    Deliver consensus computation, conflict preservation, projections (vex_consensus, history, provider snapshots), and DSSE events.
  • Phase 4 – APIs & integrations
    Expose REST/CLI endpoints for claims, consensus, conflicts, exports; integrate Policy Engine, Vuln Explorer, Advisory AI, Export Center.
  • Phase 5 – Observability & offline
    Ship metrics, logs, traces, dashboards, incident runbooks, Offline Kit bundles, and performance tuning (10M claims/tenant).

Work breakdown

  • Connectors
    • Fetchers for vendor feeds, CSAF repositories, OpenVEX docs, OCI referrers.
    • Signature verification (PGP, cosign, PKI) per source; schema validation; rate limiting.
    • Source configuration (trust tier, fetch cadence, blackout windows) stored in metadata registry.
  • Normalization
    • Canonical VexClaim schema with deterministic IDs, provenance, supersedes chains.
    • Product tree parsing, mapping to canonical product keys and environments.
    • Justification and scope scoring derived from source semantics.
  • Consensus & projections
    • Lattice join with precedence rules, conflict tracking, confidence scores, recency decay.
    • Append-only history, conflict queue, DSSE events (vex.consensus.updated).
    • Export-ready JSONL & DSSE bundles for Offline Kit and Export Center.
  • APIs & UX
    • REST endpoints (/claims, /consensus, /conflicts, /providers) with tenant RBAC.
    • CLI commands stella vex claims|consensus|conflicts|export.
    • Console modules (list/detail, conflict diagnostics, provider health, simulation hooks).
  • Integrations
    • Policy Engine trust knobs, Vuln Explorer consensus badges, Advisory AI narrative generation, Notify alerts for conflicts.
    • Orchestrator jobs for recompute/backfill triggered by Excitator deltas.
  • Observability & Ops
    • Metrics (ingest latency, signature failure rate, conflict rate, consensus latency).
    • Logs/traces with tenant/issuer/provenance context.
    • Runbooks for mapping failures, signature errors, recompute storms, quota exhaustion.

Acceptance criteria

  • Connectors ingest validated VEX statements with signed provenance, deterministic mapping, and tenant isolation.
  • Consensus outputs reproducible, include conflicts, and integrate with Policy Engine/Vuln Explorer/Export Center.
  • CLI/Console provide evidence inspection, conflict analysis, and exports; Offline Kit bundles replay verification offline.
  • Observability dashboards/alerts capture ingest health, trust anomalies, conflict spikes, and performance budgets.
  • Recompute pipeline handles policy changes and new evidence without dropping deterministic outcomes.

Risks & mitigations

  • Mapping ambiguity: maintain scope scores, manual overrides, highlight warnings.
  • Signature trust gaps: issuer registry with auditing, fallback trust policies, tenant overrides.
  • Evidence surges: orchestrator backpressure, prioritised queues, shardable workers.
  • Performance regressions: indexing, caching, load tests, budget enforcement.
  • Tenant leakage: strict RBAC/filters, fuzz tests, compliance reviews.

Test strategy

  • Unit: connector parsers, normalization, mapping conversions, lattice operations.
  • Property: randomised evidence ensuring commutative consensus and deterministic digests.
  • Integration: end-to-end pipeline from Excitator to consensus export, policy simulation, conflict handling.
  • Performance: large feed ingestion, recompute stress, CLI export throughput.
  • Security: signature tampering, issuer revocation, RBAC.
  • Offline: export/import verification, DSSE bundle validation.

Definition of done

  • Connectors, normalization, consensus, APIs, and integrations deployed with telemetry, runbooks, and Offline Kit parity.
  • Documentation (overview, architecture, algorithm, issuer registry, API/CLI, runbooks) updated with imposed rule compliance.
  • ./TASKS.md and ../../TASKS.md reflect active status and dependencies.