What needed solving.
Make repeatable network inventory and vulnerability triage easier without hiding scanner commands, losing raw evidence or conflating scanner severity with analyst exploitability.
- 01Authorized scan plan
- 02Native scanner + raw evidence
- 03Stable findings + analyst review
Simplified from the implementation and project notes.
How it fits together.
A scan profile becomes an explicit, reviewable command plan
The CLI resolves a named target and profile into native scanner steps, retaining each command, working directory, scanner version and timing. Quick/standard/deep profiles differ in coverage; risky recipes require an explicit intrusive flag, while normal Nuclei tags exclude disruptive checks. Native arguments can pass through so the harness does not hide scanner behavior. Tests cover profile construction, CLI validation and scanner invocation; failure cases include invalid target/profile combinations, missing tools and timeouts.
Raw evidence is durable even when parsing or import fails
Each run captures stdout, stderr, native reports and a manifest with command, version, timestamps, exit code and artifact hashes. SQLite links runs and artifacts to stable host/service identities and records changes over time, rather than treating each scan as a disconnected report. Parsing is attempted for expected scanner exit codes, but a parser error is recorded separately so raw evidence survives unfamiliar output. Tests verify exact command/output capture, timeout status and stable database records.
DefectDojo and AI are optional interpretation layers
Findings can be imported or reimported to DefectDojo API v2 with stable context; an outage defers sync while local evidence remains available. Optional Codex analysis is operator-triggered, cached by evidence hash and constrained to a schema and allowlisted non-destructive probes; its commands and output are recorded. Tests cover API mapping, finding state and AI boundaries. The calibration fixture is a local Docker Compose service configured with no network, no published ports and a read-only root; it is a safe route for a controlled screenshot, not evidence of scanning arbitrary assets.
Inside the software.
Local security assessment harness that turns authorized scan requests into reviewable native commands, retains raw evidence, tracks host/service changes and synchronizes findings with DefectDojo. Dojo is the harness; it does not embed the upstream product.
Reviewable scan profiles and recipes
Resolve named targets into quick, standard or deep scanner plans, with native arguments visible and disruptive recipes gated.
CLI builds scanner steps, records command context, excludes disruptive Nuclei tags by default and requires an explicit intrusive option for risky recipes.
Present in the reviewed source.
Implementation references
dojo/README.mddojo/src/dojo_harness/cli.pydojo/src/dojo_harness/runner.pydojo/config/recipes/web-safe.yamldojo/config/recipes/intrusive-web.yamldojo/tests/test_runner.py
Raw evidence and run manifests
Keep scanner output even when parsing or downstream import fails, with enough provenance to reproduce and review a run.
Stores stdout, stderr, native reports, command/version/timing/exit status and artifact hashes; parser errors are separated from scan completion.
Source includes automated tests; those scanner tests were not rerun for this writeup.
Implementation references
dojo/src/dojo_harness/runner.pydojo/src/dojo_harness/db.pydojo/tests/test_runner.pydojo/tests/test_db.py
Stable host and service inventory
Track host/service identity across runs and expose changes over time instead of treating reports as disconnected scans.
SQLite records stable assets, run links, observations and DefectDojo finding references; finding identity and state can be compared across imports.
UI captured locally. Data and integration limits are noted above.
Implementation references
dojo/src/dojo_harness/db.pydojo/src/dojo_harness/scanners.pydojo/tests/test_db.py
Native scanner integrations
Coordinate Greenbone/OpenVAS, Nmap, Nuclei, ZAP and testssl.sh through native tools while preserving their output.
Scanner adapters resolve tool availability, arguments and reports; Greenbone has a dedicated runner and configured safe/intrusive recipes.
Implemented; installed scanner availability varies by machine.
Implementation references
dojo/src/dojo_harness/scanners.pydojo/src/dojo_harness/greenbone_runner.pydojo/config/recipes/web-safe.yamldojo/config/recipes/intrusive-web.yamldojo/tests/test_scanners.py
DefectDojo finding synchronization
Import or reimport findings through DefectDojo API v2 with stable context; defer sync during outages while retaining local evidence.
Maps scanner output and finding identity to API v2 entities and triage state; integration tests cover mapping and state handling.
Implemented; requires a configured DefectDojo service for live synchronization.
Implementation references
dojo/src/dojo_harness/defectdojo.pydojo/tests/test_defectdojo.pydojo/README.md
Evidence-centered findings and triage
Review findings with affected location, evidence, remediation, references and scanner provenance, then synchronize triage controls.
Web UI surfaces finding context and status backed by the local database and DefectDojo integration.
UI captured locally. Data and integration limits are noted above.
Implementation references
dojo/src/dojo_harness/web.pydojo/tests/test_web.pydojo/README.md
Optional bounded AI interpretation
Allow an operator to request a constrained interpretation of evidence and limited non-destructive probes, with commands and output retained.
Analysis is opt-in, cached by evidence hash and schema constrained; probe execution is allowlisted and logged.
Implemented as optional operator-triggered feature; requires model configuration to generate new analysis.
Implementation references
dojo/src/dojo_harness/ai.pydojo/tests/test_ai.pydojo/src/dojo_harness/runner.py
Isolated scanner calibration fixture
Provide a local service for controlled calibration and UI demonstration without scanning arbitrary network assets.
Docker Compose fixture has no network, no published ports and read-only root; calibration module supports checking expected findings.
Implemented; fixture safety properties are documented in project record.
Implementation references
dojo/services/calibration/fixture/app.pydojo/src/dojo_harness/calibration.pydojo/tests/test_calibration.pydojo/README.md
Building and checking it.
Operator selects authorized targets, previews/explains a plan, runs a profile or recipe, inspects inventory/findings and can verify a specific finding. Results import/reimport to DefectDojo with stable context.
The UI offers evidence, affected location, remediation, references, scanner provenance, related findings and synchronized triage controls.
The harness keeps analyst exploitability judgments separate from scanner severity. It talks to official DefectDojo services through API v2 rather than embedding or patching the upstream product.
Source notes
Based on repository code and project records reviewed on October 30, 2026. Historical checks are described as recorded, not rerun for this article. Screenshots, renders, and mockups are labeled individually.
dojo/README.mddojo/pyproject.tomldojo/src/dojo_harness/runner.pydojo/src/dojo_harness/db.pydojo/src/dojo_harness/defectdojo.pydojo/src/dojo_harness/ai.pydojo/tests/test_runner.pydojo/tests/test_db.pydojo/tests/test_defectdojo.pydojo/services/calibration/fixture/app.pydojo/src/dojo_harness/calibration.py