e8537460a3
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
66 lines
4.4 KiB
Markdown
66 lines
4.4 KiB
Markdown
# 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.
|