How joasasantos/neurosploit works
1. Repository shape
This repo is split into a Rust application in neurosploit-rs/ and a large markdown agent corpus in agents_md/. The Rust side is the execution engine; the markdown side is the knowledge base that drives recon, exploitation, validation, and reporting.
2. Primary runtime
The main runtime is a Rust CLI built on tokio. The top-level binary lives in neurosploit-rs/app, with the harness logic factored into neurosploit-rs/crates/harness. The architecture is command-driven: black-box, white-box, grey-box, host/infra, TUI, REPL, and utilities all route through the same core harness.
3. Core orchestration boundary
crates/harness is the central subsystem. It coordinates target state, agent selection, model calls, attack-graph construction, belief/validation, reporting, RL feedback, and integrations. This is the boundary that separates “engine” concerns from the UI/CLI wrappers.
4. Agent execution model
The engine does not contain hardcoded attack logic for most cases; it loads behavior from markdown agents in agents_md/. These are grouped into:
- recon/ for surface discovery
- vulns/ for vulnerability-specific exploitation
- code/ for white-box source review
- chains/ for multi-stage attack paths
- meta/ for orchestration, scoring, validation, reporting, and RL
This makes the system content-driven rather than code-driven.
5. Target-to-agent flow
A run starts with a target description such as a URL, repository, or host/IP. The harness performs recon first, then selects only agents that match the discovered surface, then runs them in parallel. Findings are chained into deeper impact where applicable, and each claim is supposed to be backed by a receipt or file/line evidence depending on mode.
6. Validation and anti-hallucination layer
A major architectural boundary is the validation pipeline. Findings are not accepted directly from a single model; they go through cross-model voting, grounding checks, and a belief-based gate derived from the POMDP/value-of-information design described in the README. This layer reduces false positives before anything reaches the final report.
7. State and persistence
The tool is designed to run without a database. Per-project state lives under <cwd>/.neurosploit/, including session state, command history, and run history. Each engagement also emits a self-contained runs/ns-<ts>-<target>/ folder containing recon output, transcripts, validated findings, and final reports.
8. Reporting pipeline
Report generation is its own subsystem. The harness produces structured findings and then renders them into multiple artifacts: Markdown, HTML, Typst source, and PDF. The report is both human-readable and machine-reusable, with findings.json and recon.json acting as intermediate structured outputs.
9. Model and tool connectivity
The harness supports both API-key-based model access and local subscription/CLI-based access. It also optionally uses browser automation via Playwright MCP when available, and falls back to simpler tools like curl, nmap, or ffuf-style workflows when richer tooling is absent. This makes tool availability part of the execution graph.
10. Integrations boundary
The newer integrations layer connects the engine to external systems: GitHub, GitLab, and Jira. GitHub/GitLab are used for private repo cloning, PR review, and branch watching; Jira is used to create one card per finding. The repo explicitly stores only environment variable names, not token values.
11. RL feedback loop
The system includes a reinforcement-learning feedback store in data/rl_state_rs.json and RL-related modules in the harness. This creates a closed loop where previous runs bias future agent selection and prioritization, making the architecture adaptive rather than static.
12. Build, release, and installer tooling
The repo includes a GitHub Actions release workflow, platform installers (setup.sh, install.ps1), and helper scripts under scripts/ that generate or refresh the agent corpus. These are build-time and distribution concerns, separate from the runtime engine, but they matter because the final product is a compiled Rust CLI plus a large markdown knowledge base.
Main entry points: lib.rs Harness · agents.rs Agents · build_methodology_v352.py Build Scripts · pipeline.rs Pipeline
Components 25
Rust Runtime
CLI entrypoints and the core execution engine
- CLI · Top-level command runtime with TUI and REPL entrypoints
neurosploit-rs/app/src/main.rs - REPL · Interactive command loop for operator-driven runs
neurosploit-rs/app/src/repl.rs - TUI · Terminal interface for guiding and observing runs
neurosploit-rs/app/src/tui.rs - Harness · Central execution boundary for agent selection, validation, and reporting
neurosploit-rs/crates/harness/src/lib.rs - Pipeline · Coordinates recon, agent execution, chaining, and evidence collection
neurosploit-rs/crates/harness/src/pipeline.rs - Agents · Loads and matches markdown agents against the discovered target surface
neurosploit-rs/crates/harness/src/agents.rs - Models · API and local model connectivity used by the harness
neurosploit-rs/crates/harness/src/models.rs - Attack Graph · Represents exploit paths and linked claims across stages
neurosploit-rs/crates/harness/src/attack_graph.rs - Belief Gate · Belief and value-of-information layer that filters ungrounded findings
neurosploit-rs/crates/harness/src/belief.rs - Grounding · Anchors claims to receipts, files, lines, or other evidence
neurosploit-rs/crates/harness/src/grounding.rs - Tool Pool · Dispatches available external tools and fallbacks for execution
neurosploit-rs/crates/harness/src/pool.rs - Integrations · GitHub, GitLab, and Jira connectors for repo and ticket workflows
neurosploit-rs/crates/harness/src/integrations.rs - Reporting · Builds structured findings and renders Markdown, HTML, Typst, and PDF
neurosploit-rs/crates/harness/src/report.rs - RL Feedback · Stores run feedback and biases future prioritization
neurosploit-rs/crates/harness/src/rl.rs - Core Types · Common run, finding, and target data structures
neurosploit-rs/crates/harness/src/types.rs
Agent Corpus
Markdown knowledge base that drives recon and exploitation
- Recon · Discovery and surface-mapping agents
agents_md/recon/subdomain_enum.md - Vulns · Vulnerability-specific exploitation agents
agents_md/vulns/ssrf.md - Code Review · White-box source analysis agents
agents_md/code/code_sqli.md - Chains · Multi-stage attack path agents
agents_md/chains/chain_ssrf_to_rce.md - Meta · Orchestration, validation, scoring, reporting, and role prompts
agents_md/meta/orchestrator.md
State & Ops
Persistence, outputs, releases, and helper tooling
- Project State · Per-project session state and run history under .neurosploit
.env.example - Run Outputs · Self-contained per-run folders with recon data, transcripts, and reports
README.md - Release Workflow · GitHub Actions release automation and packaging
.github/workflows/release.yml - Build Scripts · Helpers that generate and refresh the markdown corpus
scripts/build_methodology_v352.py - Installers · Shell and PowerShell installation entrypoints
setup.sh
Connections 27
- CLI → Harness: dispatches · Command modes all route into the core engine
- REPL → Harness: uses · Interactive shell drives the same orchestrator
- TUI → Harness: uses · Terminal UI wraps the shared execution boundary
- Harness → Pipeline: orchestrates · Coordinates the end-to-end run flow
- Pipeline → Agents: selects · Matches discovered surface to applicable agents
- Pipeline → Models: calls · Invokes model providers for reasoning and generation
- Pipeline → Tool Pool: executes · Uses available tools and fallbacks during assessment
- Pipeline → Attack Graph: builds · Links findings into exploit and impact paths
- Attack Graph → Belief Gate: filters · Candidate claims are gated before acceptance
- Belief Gate → Grounding: verifies · Checks claims against evidence and receipts
- Harness → Reporting: renders · Structured findings become final human-readable reports
- Harness → Integrations: syncs · Pushes findings and cloned repository workflows outward
- Harness → RL Feedback: learns · Run feedback updates future prioritization
- Harness → Core Types: shares · Common schemas are used across orchestrator subsystems
- Agents → Recon: loads · Recon stage behavior is content-driven
- Agents → Vulns: loads · Vulnerability exploitation behavior comes from markdown
- Agents → Code Review: loads · White-box review agents are sourced from markdown
- Agents → Chains: loads · Multi-stage exploit paths are defined in markdown
- Agents → Meta: loads · Meta orchestration and validation prompts live in markdown
- Harness → Project State: persists · Session and run state are stored locally without a database
- Harness → Run Outputs: emits · Each engagement writes a self-contained run directory
- Release Workflow → Installers: packages · Build and distribution workflows support installation
- Build Scripts → Recon: generates · Helper scripts refresh the agent corpus
- Build Scripts → Vulns: generates · Helper scripts refresh the agent corpus
- Build Scripts → Code Review: generates · Helper scripts refresh the agent corpus
- Build Scripts → Chains: generates · Helper scripts refresh the agent corpus
- Build Scripts → Meta: generates · Helper scripts refresh the agent corpus