๐Ÿง  NeuroSploit v4.3.0

Stars Forks Issues

Autonomous, multi-model penetration-testing harness โ€” Rust, CLI-first.
by Joas A Santos & Red Team Leaders

--- ## What is NeuroSploit? **NeuroSploit is an autonomous penetration-testing tool.** You point it at a target; it does the security assessment on its own and hands you a report โ€” recon, exploitation, chaining findings into real impact, and validation, with no human driving each step. The key idea: **the harness is the pentester, not the model.** Instead of asking one LLM to "hack this", a Rust engine runs the methodology โ€” it picks the right specialist agents for what it finds, runs them in parallel, re-sends every claim over the wire to confirm it's real, and has a second model check each finding before it's reported. The LLMs are the hands; the harness is the discipline that keeps them honest. That's why it finds more and invents less than running a model directly. It's **CLI-first** (with a web console and a TUI), **open source (MIT)**, and runs on **your own API keys or a local subscription** โ€” nothing about your targets leaves your machine unless you send it. --- Give NeuroSploit a **URL, a source repo, a running app, or a host/IP**. A Rust harness (`tokio`) drives a **pool of LLMs** โ€” via **API key** or local **subscription** (Claude Code / Codex / Gemini / Grok) โ€” and runs the whole engagement for you: ``` recon โ”€โ–ถ pick only the agents that fit the surface โ”€โ–ถ exploit in parallel โ”€โ–ถ wire-check every claim โ”€โ–ถ cross-model vote โ”€โ–ถ chain into deeper impact โ”€โ–ถ report ``` It won't invent findings: **every claim needs a receipt** (raw tool output or a `file:line`), is **re-sent by the harness itself** to confirm it reproduces, and is adjudicated by a **second model** before it reaches the report. > โญ Useful? **Star the repo.** > ๐Ÿ“– Deep dive: **[TUTORIAL.md](TUTORIAL.md)** ยท changelog: **[RELEASE.md](RELEASE.md)** ยท honest comparison: **[BENCHMARK.md](BENCHMARK.md)** ## Install **Linux / macOS** (x64 & arm64): ```bash curl -fsSL https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/setup.sh | bash ``` **Windows** (PowerShell): ```powershell irm https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/install.ps1 | iex ``` The installer sets up Rust if missing, builds the release binary, and links `neurosploit` onto your PATH. Build by hand instead: ```bash git clone https://github.com/JoasASantos/NeuroSploit && cd NeuroSploit/neurosploit-rs cargo build --release # โ†’ target/release/neurosploit ``` ## Quick start ```bash # just run it โ€” the interactive session asks everything, in plain language: neurosploit # black-box, subscription login (no API key): neurosploit run http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 -v # white-box โ€” review a source repo (file:line evidence): neurosploit whitebox /path/to/repo --subscription --model anthropic:claude-opus-4-8 -v # web console โ€” a browser UI over the same CLI: cd web && npm start # โ†’ http://localhost:4173 ``` No subscription? Use an **API key** for any provider instead โ€” see [TUTORIAL.md](TUTORIAL.md#authentication). ## Modes | Mode | Command | What it does | |------|---------|-------------| | **Black-box** | `neurosploit run ` | recon โ†’ select โ†’ exploit โ†’ vote โ†’ report | | **White-box** | `neurosploit whitebox ` | source / SAST review (file:line evidence) | | **Grey-box** | `neurosploit greybox --url ` | code review **+** live exploitation together | | **Host / Infra** | `neurosploit host --creds creds.yaml` | Linux / Windows / AD + cloud (AWS/GCP/Azure) | | **AI / LLM** | `neurosploit aitest ` | jailbreaks, prompt injection, OWASP LLM Top 10 / MCP | | **Mobile / Binary** | `neurosploit mobile ` | RE a local artifact (Ghidra / MobSF / Frida) | | **Container** | `neurosploit container ` | OCI image scan + SBOM (trivy/grype/syft) | | **Mission Control** | `neurosploit tui ` | live TUI panels + a composer you type in mid-run | ## What makes it different - **The harness is the pentester.** Agent selection is recon-driven; findings **chain** (reduce a foothold to a primitive โ€” exec / read / write / SSRF / identity / secret โ€” then pivot), each stage proven and non-destructive. - **Wire-bound evidence** โ€” every reported exchange is re-sent through a scope-guarded replay engine and checked against recorded traffic. A claim the wire contradicts can't stand as confirmed. - **Attack knowledge graph (Neo4j optional)** โ€” the run is a typed graph of hosts, services, findings, credentials and impact, spanning **web and internal network**. It directs the next move during the run and is written to `graph/` even without a database. - **Deterministic validation** โ€” per-CWE validators judge the measured request/response bytes, not the model's prose. Grounding gate, POMDP belief and an anti-hallucination check demote anything the evidence doesn't support. - **Secrets never leak the report** โ€” credentials the agents observe become `$SECRET_n` in every human-facing report; raw values stay in the run's vault for re-testing only. - **486 markdown agents** across web, code (SAST), AI, infra/AD/cloud, chains and recon โ€” each a self-contained playbook you can read, edit or add to. - **Run via API key or subscription**, 19 providers, including local & CPU-only (`ollama:` / `llamacpp:`) with no data leaving the host. ## Web console ```bash cd web && npm start # โ†’ http://localhost:4173 ``` A browser UI that drives the **same CLI** โ€” no second engine. Launch and watch a run live, then per finding: - **Attack graph** โ€” host โ†’ service โ†’ finding โ†’ credential โ†’ impact, every edge marked confirmed / needs-validation / hypothesis, ordered by kill-chain stage. - **Wire evidence** โ€” the real request/response pairs behind a finding (baseline vs. attack, the identity pair, matrix probes, the oracle), each tagged with its wire provenance โ€” the proof as bytes, not prose. - **Re-test one finding** โ€” re-run its proof through the replay engine; the dated history shows a finding drift to "gone" over time. - **Transcript viewer** โ€” any agent's run, split into navigable blocks; search spans every agent. - Chains, dependency todolist, recorded traffic, deliverables, PDF export. ## What a run leaves behind Every run is a self-contained folder, `runs/ns--/`: | File | Contents | |------|----------| | `report.html` ยท `report.pdf` ยท `report.md` | the report (PDF via Typst), secrets redacted | | `findings.json` / `findings.md` | validated findings (raw, for tools & re-testing) | | `report.sarif` | SARIF 2.1.0 for CI code-scanning | | `graph/` | attack chains, dependency todolist, Cypher + JSON export | | `recon.json` ยท `exploitation.md` ยท `traces/` | surface, transcript, per-agent traces | | `pocs/` ยท `evidence/` | runnable PoCs and proof screenshots | ## Integrations GitHub / GitLab PR review gate (`neurosploit pr --fail-on critical`), `@neurosploit` mention bot, one Jira card per finding, MCP server (`neurosploit mcp`), compliance mapping (PCI-DSS / HIPAA / SOC 2 / GDPR). See **[TUTORIAL.md](TUTORIAL.md)**. ## Safety For **authorized** testing only. Agents stay in scope, never run destructive / DoS actions, and require proof of exploitation. You are responsible for having permission for every target. ## Credits & license **Joas A Santos** & **Red Team Leaders** โ€” MIT. > This is the slim, **Rust-only** distribution (`neurosploit-rs/` + `agents_md/`). > The older Python engine and web GUIs live on the `v3.4.0` branch.