stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules

Browse Source 
- 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.
This commit is contained in:
master
2025-10-30 00:09:39 +02:00
parent 3154c67978
commit 7b5bdcf4d3
503 changed files with 16136 additions and 54638 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/modules/policy/implementation_plan.md Normal file
View File

@@ -0,0 +1,67 @@
# 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.