master
7b5bdcf4d3
- 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.
68 lines
4.8 KiB
Markdown
68 lines
4.8 KiB
Markdown
# Implementation plan — Policy Engine
|
||
|
||
## Delivery phases
|
||
- **Phase 1 – Deterministic evaluation core**
|
||
Finalise DSL compiler, runtime guardrails, evaluation workers, change-stream integration (advisories, VEX, SBOM), and append-only effective findings.
|
||
- **Phase 2 – Orchestration & incremental runs**
|
||
Implement run scheduler, incremental deltas, change-stream replay, simulation hooks, and determinism hashing.
|
||
- **Phase 3 – Policy Studio workflows**
|
||
Deliver policy registry, versioning, approvals, explain trace API, client editor integration, and signed promotion pipelines.
|
||
- **Phase 4 – Simulation & approvals**
|
||
Provide diff/simulation APIs, approval queues, change management, and integration with CLI/Console.
|
||
- **Phase 5 – Exports & offline parity**
|
||
Produce policy bundles, explain archives, Offline Kit assets, and deterministic manifests; integrate with Export Center.
|
||
- **Phase 6 – Observability & hardening**
|
||
Ship metrics, logs, traces, incident response runbooks, guardrail analyzers, and compliance attestations.
|
||
|
||
## Work breakdown
|
||
- **Evaluation engine**
|
||
- DSL compiler with caching, static analysis, and guard rails (no wall-clock/random/network outside allowlist).
|
||
- Batch evaluator with deterministic ordering, change-stream inputs, policy IR caching.
|
||
- Explain trace generation, evidence linking, storage in object store.
|
||
- **Run orchestration**
|
||
- Scheduler for incremental runs, job leasing, fair-share per tenant/policy.
|
||
- Determinism hash + replay verification, time-travel snapshots, resume cursors.
|
||
- Simulation endpoints returning diff summaries, rationale breakdown, exit codes.
|
||
- **Policy Studio**
|
||
- Policy registry (draft→review→approved), signed promotion pipeline, approvals workflow (multi-step).
|
||
- Console integration (editor, simulation, approvals, explain viewer) and CLI parity.
|
||
- **Integrations**
|
||
- Inputs: Concelier, Excititor, SBOM Service, VEX Lens, runtime signals.
|
||
- Outputs: Findings ledger, Vuln Explorer, Notify (policy events), Export Center (policy bundles).
|
||
- Authority scopes, tenancy enforcement, RBAC for policy author/reviewer/operator.
|
||
- **Observability & compliance**
|
||
- Metrics: run duration, evaluation verdict counts, simulation latency, guard violations.
|
||
- Logs/traces with trace ID propagation, policy version references, tenant scoping.
|
||
- Guard analyzers (static + runtime), unit/property tests, compliance reports.
|
||
- **Docs & tooling**
|
||
- Update DSL guide, policy lifecycle/runbooks, simulation manual, CLI reference, Offline Kit instructions.
|
||
- Provide sample policies, fixtures, and analyzer rules.
|
||
|
||
## Acceptance criteria
|
||
- Evaluation engine deterministic across runs; effective findings materialised only by Policy Engine; guardrails prevent forbidden IO.
|
||
- Incremental runs handle advisory/VEX/SBOM deltas within ≤5 min SLA; determinism hash and replay verification succeed.
|
||
- Policy Studio supports draft/review/approval, signed promotions, simulation diffing, and explain traces in UI/CLI.
|
||
- Exports (policy bundles, explain archives) reproducible with signed manifests; Offline Kit packages deliver same tooling.
|
||
- Observability dashboards show run metrics, guard violations, simulation usage; alerts trigger on determinism hash mismatch or backlog.
|
||
- CLI/Console parity for policy management, simulation, approvals, and export workflows.
|
||
|
||
## Risks & mitigations
|
||
- **Non-determinism:** strict static analysis, runtime guard, determinism hash, replay tests.
|
||
- **Policy drift vs reality:** simulation diff previews, approval workflow, history/audit trail.
|
||
- **Scaling evaluations:** sharded workers, incremental deltas, caching, job queue fairness.
|
||
- **Guard bypass:** analyzers integrated into CI, runtime guard rejects forbidden operations.
|
||
- **Offline compliance:** deterministic exports, manifest verification, documentation for sealed-mode deployments.
|
||
|
||
## Test strategy
|
||
- **Unit:** DSL parsing, guard analyzer, evaluation pipeline, simulation diff calculations.
|
||
- **Property:** randomised policy inputs verifying determinism and guard enforcement.
|
||
- **Integration:** Concelier/Excititor/SBOM feeds → Policy Engine → findings ledger, simulation, approvals.
|
||
- **Performance:** evaluation throughput, change-stream backlog recovery, simulation under load.
|
||
- **Security/compliance:** RBAC/tenancy, analyzer enforcement, audit logging, signed promotions.
|
||
- **Offline:** export/import of policy bundles, explain archives, CLI verification.
|
||
|
||
## Definition of done
|
||
- Policy Engine core, orchestration, Policy Studio workflows, exports, and observability delivered with runbooks and Offline Kit parity.
|
||
- Documentation suite (overview, architecture, DSL, lifecycle, Studio, simulation, CLI) updated with imposed rule statements.
|
||
- ./TASKS.md and ../../TASKS.md reflect status; analyzers integrated into CI; compliance evidence captured.
|