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

- 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:
2025-10-30 00:09:39 +02:00
parent 3154c67978
commit 7b5bdcf4d3
503 changed files with 16136 additions and 54638 deletions

View File

@@ -0,0 +1,57 @@
# Risk Scoring Profiles
> Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
## Overview
Risk Scoring Profiles define customizable formulas that convert raw evidence (CVSS, EPSS-like exploit likelihood, KEV exploited lists, VEX status, reachability, runtime evidence, fix availability, asset criticality, provenance trust) into normalized risk scores (0100) with severity buckets. Profiles are authored in Policy Studio, simulated, versioned, and executed by the scoring engine with full explainability.
- **Primary components:** Policy Engine, Findings Ledger, Conseiller, Excitator, Console, Policy Studio, CLI, Export Center, Authority & Tenancy, Observability.
- **Surfaces:** policy documents, scoring engine, factor providers, explainability artefacts, APIs, CLI, UI.
Aggregation-Only Contract remains in force: Conseiller and Excitator never merge or mutate source records. Risk scoring consumes linked evidence and preserves provenance for explainability.
## Core workflow
1. **Profile authoring:** Policy Studio exposes declarative DSL to define factors, weights, thresholds, and severity buckets.
2. **Simulation:** operators preview profiles against historical findings/SBOMs, compare with existing policies, and inspect factor breakdowns.
3. **Activation:** Policy Engine evaluates profiles on change streams, producing scores and detailed factor contributions per finding and per asset.
4. **Explainability:** CLI/Console display math traces, provenance IDs, and rationale for each factor. Export Center packages reports for auditors.
5. **Versioning:** profiles carry semantic versions, promotion workflows, and rollback hooks; Authority scopes enforce who can publish or edit.
## Factor model
| Factor | Description | Typical signal source |
| --- | --- | --- |
| Exploit likelihood | EPSS/KEV or internal intel | Conseiller enrichment |
| VEX status | not_affected / affected / fixed | Excitator (VEX Lens) |
| Reachability | entrypoint closure, runtime observations | Scanner + Zastava |
| Fix availability | patch released, vendor guidance | Conseiller, Policy Engine |
| Asset criticality | business context, tenant overrides | Policy Studio inputs |
| Provenance trust | signed evidence, attestation status | Attestor, Authority |
Factors feed into a weighted scoring engine with per-factor contribution reporting.
## Governance & guardrails
- Profiles live in Policy Studio with draft/review/approval workflows.
- Policy Engine enforces deterministic evaluation; simulations and production runs share the same scoring code.
- CLI parity enables automated promotion, export/import, and simulation from pipelines.
- Observability records scoring latency, factor distribution, and profile usage.
- Offline support: profiles, factor plugins, and explain bundles ship inside mirror bundles for air-gapped environments.
## Deliverables
- Policy language reference and examples.
- Simulation APIs/CLI with diff output.
- Scoring engine implementation with explain traces and determinism checks.
- Console visualizations (severity heatmaps, contribution waterfalls).
- Export Center reports with risk scoring sections.
- Observability dashboards for profile health and scoring throughput.
## References
- Policy core: `docs/modules/policy/architecture.md`
- Findings ledger: `docs/modules/vuln-explorer/architecture.md`
- VEX consensus: `docs/modules/vex-lens/architecture.md`
- Offline operations: `docs/airgap/airgap-mode.md`