From 61c6eab54ecd74c6d0785be77502bee1653b2c83 Mon Sep 17 00:00:00 2001 From: Sharang Parnerkar <30073382+mighty840@users.noreply.github.com> Date: Mon, 31 Aug 2026 15:12:41 +0200 Subject: [PATCH] docs: document Nuclei/ZAP as decided deterministic detectors under the agentic DAST (not yet implemented) Spec v0.2.1 decision (2026-08-31): keep the agentic DAST/pentest layer, integrate Nuclei then ZAP baseline underneath as deterministic detectors feeding the control-map LUT; offline vuln DB (Trivy/Grype) on the on-prem runner trigger. Clearly marked as planned so the docs stay truthful until the code lands. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EgxGHn22YEfQz5fLHSHkLv --- docs/features/control-mapping.md | 2 +- docs/features/dast.md | 4 ++++ docs/reference/tools.md | 11 +++++++++++ 3 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/features/control-mapping.md b/docs/features/control-mapping.md index 7f1d77a..d39b56d 100644 --- a/docs/features/control-mapping.md +++ b/docs/features/control-mapping.md @@ -6,7 +6,7 @@ Control mapping connects the scanner's raw output — deterministic tool finding The design has one rule, borrowed from the ZeroFalse / IRIS line of research: **deterministic tools are the detectors; the LLM is only ever a grounded false-positive filter, never the thing that finds the issue.** -- A tool (semgrep, gitleaks, syft/osv, the DAST agents, the PLC linter) detects deterministically. +- A tool (semgrep, gitleaks, syft/osv, the PLC linter; the DAST agents today, with **Nuclei and ZAP planned** as deterministic web/OT detectors underneath them — see [Tools & Scanners](/reference/tools#planned-integrations-decided-2026-08-31-not-yet-in-the-code)) detects. - An **authored, human-reviewed lookup table** (`control-map`) maps that detection to the control(s) it's evidence for. - The LLM enters last, to *confirm or refute* the mapping against the actual code — and every surviving verdict is anchored to a verbatim snippet by the grounding gate. diff --git a/docs/features/dast.md b/docs/features/dast.md index 2d5de87..5e5b547 100644 --- a/docs/features/dast.md +++ b/docs/features/dast.md @@ -92,3 +92,7 @@ Filters can be combined. A count indicator shows how many findings match the cur ::: tip Findings marked as **Confirmed** exploitable were verified with a successful attack payload. **Unconfirmed** findings show suspicious behavior that may indicate a vulnerability but could not be fully exploited. ::: + +## Deterministic detectors (planned) + +The DAST engine above is agentic: an LLM drives crawler, browser and testing tools and decides what to try next. That gives depth and code-aware exploitation, but not run-to-run reproducibility. The next step (decided 2026-08-31, not yet implemented) adds two deterministic open-source detectors **under** the agents: **Nuclei** (template checks incl. ICS/OT and default-credential templates) first, then an **OWASP ZAP** baseline scan. Their findings will appear alongside agent findings, carry CWE + compliance `control_refs`, and seed the agent's context so it verifies and chains instead of rediscovering. See [Tools & Scanners](/reference/tools#planned-integrations-decided-2026-08-31-not-yet-in-the-code). \ No newline at end of file diff --git a/docs/reference/tools.md b/docs/reference/tools.md index e99cce6..f0284da 100644 --- a/docs/reference/tools.md +++ b/docs/reference/tools.md @@ -96,3 +96,14 @@ When you mark findings as false positives or provide developer feedback, this in ::: tip The AI triage is a starting point, not a final verdict. Always review the rationale and code evidence before acting on a finding. See [Understanding Findings](/guide/findings#human-in-the-loop) for more on the human-in-the-loop workflow. ::: + +## Planned integrations (decided 2026-08-31, not yet in the code) + +The product spec keeps an **OSS-only** tooling policy and a control-mapping rule of *tools detect, the LLM judges*. Two deterministic detectors are therefore being added **underneath** the agentic DAST/pentest layer — the agents stay on top for context-seeded exploitation, chaining and explanation: + +| Tool | Role | Status | +|------|------|--------| +| [Nuclei](https://github.com/projectdiscovery/nuclei) | Template-driven checks (CVE probes, default credentials, exposed panels, misconfigurations) including ICS/OT templates for WebVisu / OpenPLC / HMI endpoints. Runs as a DAST phase and as a Werkbank job with vendored templates so it works on-prem. | Planned — tracked as an issue | +| [OWASP ZAP](https://www.zaproxy.org/) | Baseline (passive) and, behind the destructive-tests flag, active scan for reproducible spider + rule coverage; results seed the pentest agent. | Planned — follows Nuclei | + +Both feed the same `control-map` lookup table as Semgrep, so their findings receive compliance `control_refs` through the grounded judge. An **offline vulnerability database** (Trivy preferred, Grype as alternative) is planned for the on-prem Werkbank runner, which cannot reach the OSV.dev / NVD APIs. Until these land, DAST findings come exclusively from the in-house agents described above. \ No newline at end of file