# joasasantos/neurosploit architecture

> Architecture diagram of the GitHub repository joasasantos/neurosploit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joasasantos/neurosploit
- Repository: https://github.com/joasasantos/neurosploit

## Overview

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: [`neurosploit-rs/crates/harness/src/lib.rs`](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/lib.rs) (Harness), [`neurosploit-rs/crates/harness/src/agents.rs`](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/agents.rs) (Agents), [`scripts/build_methodology_v352.py`](https://github.com/joasasantos/neurosploit/blob/main/scripts/build_methodology_v352.py) (Build Scripts), [`neurosploit-rs/crates/harness/src/pipeline.rs`](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/pipeline.rs) (Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Rust Runtime"]
  node_cli["CLI<br/>tokio app<br/>[main.rs]"]
  node_repl["REPL<br/>interactive shell<br/>[repl.rs]"]
  node_tui["TUI<br/>terminal ui<br/>[tui.rs]"]
  node_harness{{"Harness<br/>orchestrator<br/>[lib.rs]"}}
  node_pipeline["Pipeline<br/>run flow<br/>[pipeline.rs]"]
  node_agents_mod["Agents<br/>selector<br/>[agents.rs]"]
  node_models["Models<br/>llm access<br/>[models.rs]"]
  node_graph(("Attack Graph<br/>finding graph<br/>[attack_graph.rs]"))
  node_belief{{"Belief Gate<br/>validation gate<br/>[belief.rs]"}}
  node_grounding["Grounding<br/>evidence checks<br/>[grounding.rs]"]
  node_pool["Tool Pool<br/>tool routing<br/>[pool.rs]"]
  node_integrations["Integrations<br/>external systems<br/>[integrations.rs]"]
  node_report["Reporting<br/>artifact renderer<br/>[report.rs]"]
  node_rl[("RL Feedback<br/>learning store<br/>[rl.rs]")]
  node_types["Core Types<br/>shared schema<br/>[types.rs]"]
end

subgraph group_agents["Agent Corpus"]
  node_recon_md["Recon<br/>agent pack<br/>[subdomain_enum.md]"]
  node_vulns_md["Vulns<br/>agent pack<br/>[ssrf.md]"]
  node_code_md["Code Review<br/>agent pack<br/>[code_sqli.md]"]
  node_chains_md["Chains<br/>agent pack"]
  node_meta_md["Meta<br/>agent pack<br/>[orchestrator.md]"]
end

subgraph group_ops["State & Ops"]
  node_state[("Project State<br/>local persistence<br/>[.env.example]")]
  node_run_outputs["Run Outputs<br/>engagement artifacts<br/>[README.md]"]
  node_release["Release Workflow<br/>ci pipeline<br/>[release.yml]"]
  node_scripts["Build Scripts<br/>agent generation"]
  node_installer["Installers<br/>distribution<br/>[setup.sh]"]
end

node_cli -->|"dispatches"| node_harness
node_repl -->|"uses"| node_harness
node_tui -->|"uses"| node_harness
node_harness -->|"orchestrates"| node_pipeline
node_pipeline -->|"selects"| node_agents_mod
node_pipeline -->|"calls"| node_models
node_pipeline -->|"executes"| node_pool
node_pipeline -->|"builds"| node_graph
node_graph -->|"filters"| node_belief
node_belief -->|"verifies"| node_grounding
node_harness -->|"renders"| node_report
node_harness -->|"syncs"| node_integrations
node_harness -->|"learns"| node_rl
node_harness -->|"shares"| node_types
node_agents_mod -->|"loads"| node_recon_md
node_agents_mod -->|"loads"| node_vulns_md
node_agents_mod -->|"loads"| node_code_md
node_agents_mod -->|"loads"| node_chains_md
node_agents_mod -->|"loads"| node_meta_md
node_harness -->|"persists"| node_state
node_harness -->|"emits"| node_run_outputs
node_release -->|"packages"| node_installer
node_scripts -->|"generates"| node_recon_md
node_scripts -->|"generates"| node_vulns_md
node_scripts -->|"generates"| node_code_md
node_scripts -->|"generates"| node_chains_md
node_scripts -->|"generates"| node_meta_md

click node_cli "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/app/src/main.rs"
click node_repl "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/app/src/repl.rs"
click node_tui "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/app/src/tui.rs"
click node_harness "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/lib.rs"
click node_pipeline "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/pipeline.rs"
click node_agents_mod "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/agents.rs"
click node_models "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/models.rs"
click node_graph "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/attack_graph.rs"
click node_belief "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/belief.rs"
click node_grounding "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/grounding.rs"
click node_pool "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/pool.rs"
click node_integrations "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/integrations.rs"
click node_report "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/report.rs"
click node_rl "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/rl.rs"
click node_types "https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/types.rs"
click node_recon_md "https://github.com/joasasantos/neurosploit/blob/main/agents_md/recon/subdomain_enum.md"
click node_vulns_md "https://github.com/joasasantos/neurosploit/blob/main/agents_md/vulns/ssrf.md"
click node_code_md "https://github.com/joasasantos/neurosploit/blob/main/agents_md/code/code_sqli.md"
click node_chains_md "https://github.com/joasasantos/neurosploit/blob/main/agents_md/chains/chain_ssrf_to_rce.md"
click node_meta_md "https://github.com/joasasantos/neurosploit/blob/main/agents_md/meta/orchestrator.md"
click node_state "https://github.com/joasasantos/neurosploit/blob/main/.env.example"
click node_run_outputs "https://github.com/joasasantos/neurosploit/blob/main/README.md"
click node_release "https://github.com/joasasantos/neurosploit/blob/main/.github/workflows/release.yml"
click node_scripts "https://github.com/joasasantos/neurosploit/blob/main/scripts/build_methodology_v352.py"
click node_installer "https://github.com/joasasantos/neurosploit/blob/main/setup.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_repl,node_tui,node_harness,node_pipeline,node_agents_mod,node_models,node_graph,node_belief,node_grounding,node_pool,node_integrations,node_report,node_rl,node_types toneBlue
class node_recon_md,node_vulns_md,node_code_md,node_chains_md,node_meta_md toneAmber
class node_state,node_run_outputs,node_release,node_scripts,node_installer toneMint
```

## Components

### Rust Runtime

CLI entrypoints and the core execution engine

- [CLI](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/app/src/main.rs): tokio app · Top-level command runtime with TUI and REPL entrypoints · `neurosploit-rs/app/src/main.rs`
- [REPL](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/app/src/repl.rs): interactive shell · Interactive command loop for operator-driven runs · `neurosploit-rs/app/src/repl.rs`
- [TUI](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/app/src/tui.rs): terminal ui · Terminal interface for guiding and observing runs · `neurosploit-rs/app/src/tui.rs`
- [Harness](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/lib.rs): orchestrator · Central execution boundary for agent selection, validation, and reporting · `neurosploit-rs/crates/harness/src/lib.rs`
- [Pipeline](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/pipeline.rs): run flow · Coordinates recon, agent execution, chaining, and evidence collection · `neurosploit-rs/crates/harness/src/pipeline.rs`
- [Agents](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/agents.rs): selector · Loads and matches markdown agents against the discovered target surface · `neurosploit-rs/crates/harness/src/agents.rs`
- [Models](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/models.rs): llm access · API and local model connectivity used by the harness · `neurosploit-rs/crates/harness/src/models.rs`
- [Attack Graph](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/attack_graph.rs): finding graph · Represents exploit paths and linked claims across stages · `neurosploit-rs/crates/harness/src/attack_graph.rs`
- [Belief Gate](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/belief.rs): validation gate · Belief and value-of-information layer that filters ungrounded findings · `neurosploit-rs/crates/harness/src/belief.rs`
- [Grounding](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/grounding.rs): evidence checks · Anchors claims to receipts, files, lines, or other evidence · `neurosploit-rs/crates/harness/src/grounding.rs`
- [Tool Pool](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/pool.rs): tool routing · Dispatches available external tools and fallbacks for execution · `neurosploit-rs/crates/harness/src/pool.rs`
- [Integrations](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/integrations.rs): external systems · GitHub, GitLab, and Jira connectors for repo and ticket workflows · `neurosploit-rs/crates/harness/src/integrations.rs`
- [Reporting](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/report.rs): artifact renderer · Builds structured findings and renders Markdown, HTML, Typst, and PDF · `neurosploit-rs/crates/harness/src/report.rs`
- [RL Feedback](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/rl.rs): learning store · Stores run feedback and biases future prioritization · `neurosploit-rs/crates/harness/src/rl.rs`
- [Core Types](https://github.com/joasasantos/neurosploit/blob/main/neurosploit-rs/crates/harness/src/types.rs): shared schema · 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](https://github.com/joasasantos/neurosploit/blob/main/agents_md/recon/subdomain_enum.md): agent pack · Discovery and surface-mapping agents · `agents_md/recon/subdomain_enum.md`
- [Vulns](https://github.com/joasasantos/neurosploit/blob/main/agents_md/vulns/ssrf.md): agent pack · Vulnerability-specific exploitation agents · `agents_md/vulns/ssrf.md`
- [Code Review](https://github.com/joasasantos/neurosploit/blob/main/agents_md/code/code_sqli.md): agent pack · White-box source analysis agents · `agents_md/code/code_sqli.md`
- [Chains](https://github.com/joasasantos/neurosploit/blob/main/agents_md/chains/chain_ssrf_to_rce.md): agent pack · Multi-stage attack path agents · `agents_md/chains/chain_ssrf_to_rce.md`
- [Meta](https://github.com/joasasantos/neurosploit/blob/main/agents_md/meta/orchestrator.md): agent pack · Orchestration, validation, scoring, reporting, and role prompts · `agents_md/meta/orchestrator.md`

### State & Ops

Persistence, outputs, releases, and helper tooling

- [Project State](https://github.com/joasasantos/neurosploit/blob/main/.env.example): local persistence · Per-project session state and run history under .neurosploit · `.env.example`
- [Run Outputs](https://github.com/joasasantos/neurosploit/blob/main/README.md): engagement artifacts · Self-contained per-run folders with recon data, transcripts, and reports · `README.md`
- [Release Workflow](https://github.com/joasasantos/neurosploit/blob/main/.github/workflows/release.yml): ci pipeline · GitHub Actions release automation and packaging · `.github/workflows/release.yml`
- [Build Scripts](https://github.com/joasasantos/neurosploit/blob/main/scripts/build_methodology_v352.py): agent generation · Helpers that generate and refresh the markdown corpus · `scripts/build_methodology_v352.py`
- [Installers](https://github.com/joasasantos/neurosploit/blob/main/setup.sh): distribution · Shell and PowerShell installation entrypoints · `setup.sh`

## Connections

- 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
