🧠 NeuroSploit v3.5.3

Stars Forks Issues Last commit

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

> ⭐ If this is useful, **star the repo** β€” it helps a lot. > > πŸ“– **New here? Read the [full Tutorial & User Guide β†’](TUTORIAL.md)** β€” every mode, flag, config and example explained. > πŸ†• **New in v3.5.3 β€” Integrations:** connect **GitHub / GitLab** (clone private > repos, review a **Pull Request's** code, **watch** a branch and re-review on > every commit) and **Jira** (open a vulnerability **card per finding**). Toggle > them with **`/integrations`** in the REPL or `neurosploit integrations`. Full > setup in **[TUTORIAL-INTEGRATION.md](TUTORIAL-INTEGRATION.md)**. > *(v3.5.2 added the DEPTH doctrine + report-hygiene pass β€” see [RELEASE.md](RELEASE.md).)* --- **NeuroSploit** turns a URL, a source repository, a running app, or a host/IP into an autonomous security engagement. A Rust harness (`tokio`) drives a **pool of LLMs** β€” via **API key** or local **subscription** (Claude Code / Codex / Gemini / Grok) β€” recons the target, **intelligently selects only the agents that match the discovered surface**, runs them in parallel, **chains** findings into deeper impact, and **validates every claim by cross-model voting + tool-receipt grounding** before reporting. It ships **329 markdown agents** and a **Mission Control TUI**. ### Engagement 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 / Active Directory testing | | **Mission Control** | `neurosploit tui ` | live TUI panels + composer during the run | | **Interactive** | `neurosploit` | persistent REPL session (resumes per project) | ### Highlights - 🧠 **POMDP belief + value-of-information** β€” the target is partially observable, so findings aren't booleans: a property-graph **belief** carries probabilities, and "scan more vs exploit now" falls out of belief entropy. The `may_assert` gate is a **mathematical anti-hallucination rule** (don't claim exploitability while the belief is diffuse). - 🧾 **Grounding** β€” hard rule: **no claim without a tool receipt** (raw tool output, not paraphrase). Empirical for black-box, symbolic (`file:line`) for white-box; ungrounded claims are demoted. - πŸ”— **Attack chaining** β€” 12 multi-stage chain agents (SQLiβ†’RCEβ†’LPE, SSRFβ†’AWS creds, uploadβ†’LFIβ†’RCEβ†’LPE, default-credsβ†’domain, …); each stage proven before advancing. - πŸ—ΊοΈ **Attack graph & kill chain** β€” findings mapped to OWASP / CWE / MITRE ATT&CK / stage; rendered as a Mermaid graph in the report. - βœ… **Cross-model validation** β€” a different model adjudicates each finding; RL-weighted, recon-aware agent selection. - πŸ›°οΈ **Mission Control TUI** β€” live header/feed/findings/targets panels + a composer you can type in *while the run streams* (`summary`, `pause`, …). - πŸ’Ύ **Per-project memory** β€” `/.neurosploit/` keeps session, run history and command history; the REPL **resumes** on reopen. No database required. - πŸͺ™ **Token/cost telemetry**, per-agent attribution, graceful Ctrl-C β†’ report or discard, Typst/HTML/JSON/MD reports. > This is the **slim, Rust-only** distribution (`neurosploit-rs/` + `agents_md/`). > The earlier Python engine and web GUIs live on the older `v3.4.0` branch. --- ## πŸ“¦ Install (one line) **Linux / macOS** (x64 & arm64): ```bash curl -fsSL https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/setup.sh | bash ``` **Windows** (PowerShell, x64 & arm64): ```powershell irm https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/install.ps1 | iex ``` ### Supported platforms | OS | x64 | arm64 | |----|-----|-------| | **Linux** (Kali recommended) | βœ… | βœ… | | **macOS** | βœ… | βœ… (Apple Silicon) | | **Windows** | βœ… | βœ… | Pure Rust + stdlib, so it builds natively everywhere a stable Rust toolchain runs. The installer auto-detects OS/arch and installs Rust if missing. On native Windows use `install.ps1`; under WSL2 / Git Bash the `setup.sh` one-liner also works. The installer auto-installs Rust if needed, clones the repo to `~/.neurosploit`, builds the release binary, and links `neurosploit` into `~/.local/bin`. Re-run it any time to update. Tweak with env vars: `NEUROSPLOIT_REF` (branch/tag), `NEUROSPLOIT_DIR`, `PREFIX`. Prefer to build by hand? ```bash git clone https://github.com/JoasASantos/NeuroSploit && cd NeuroSploit/neurosploit-rs cargo build --release # β†’ target/release/neurosploit ``` ## ⚑ Quick start (60 seconds) ```bash # easiest path β€” just run it; the interactive session asks everything: neurosploit # or one-liner (subscription login, no API key needed): neurosploit run http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 -v # white-box β€” review a source repository (SAST agents, file:line evidence): git clone https://github.com/digininja/DVWA /tmp/DVWA neurosploit whitebox /tmp/DVWA --subscription --model anthropic:claude-opus-4-8 -v # grey-box β€” review the code AND exploit the running app together: neurosploit greybox /tmp/DVWA --url http://localhost:8080/ --creds creds.yaml \ --subscription --model anthropic:claude-opus-4-8 --mcp -v # host / infra β€” Linux / Windows / Active Directory (SSH/Win creds in creds.yaml): neurosploit host 10.0.0.10 --creds creds.yaml --subscription --model anthropic:claude-opus-4-8 -v # πŸ›° Mission Control TUI β€” live panels (header/feed/findings/targets) + a composer # you can type in WHILE the run streams (summary Β· pause Β· errors Β· notes): neurosploit tui http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 --mcp ``` > Full step-by-step for every mode (black/white/grey/host) is in **[TUTORIAL.md](TUTORIAL.md)**. No login? Use an **API key** instead β€” see [Authentication](#authentication--run-via-api-key-or-subscription). --- ## πŸ”Œ Integrations (GitHub Β· GitLab Β· Jira) Wire NeuroSploit into your SDLC. Toggle from the REPL (`/integrations`) or the CLI (`neurosploit integrations enable github|gitlab|jira`). **Tokens are never stored** β€” only the *name* of the env var is saved; the value is read from your environment. ```bash export GITHUB_TOKEN=ghp_... # PAT with `repo` scope (private repos) neurosploit integrations enable github # Review a Pull Request's code (clones the PR head, white-box) and comment back: neurosploit pr digininja/DVWA 42 --subscription --model anthropic:claude-opus-4-8 --comment # Watch a branch and re-review on every new commit: neurosploit watch myorg/private-app --branch main --subscription --model anthropic:claude-opus-4-8 # Private GitLab repo (token-injected clone) β€” works in whitebox/greybox: export GITLAB_TOKEN=glpat-... ; neurosploit integrations enable gitlab neurosploit whitebox https://gitlab.com/myorg/private-svc --subscription --model anthropic:claude-opus-4-8 # Open a Jira card per finding (any engagement): export JIRA_EMAIL=you@org.com JIRA_API_TOKEN=... # set base/project once: /integrations setup jira neurosploit whitebox https://github.com/myorg/app --jira --subscription --model anthropic:claude-opus-4-8 ``` | Integration | What you get | Env vars | |-------------|--------------|----------| | **GitHub** | private clone Β· `pr` review + comment Β· `watch` branch | `GITHUB_TOKEN` | | **GitLab** | private clone for whitebox/greybox | `GITLAB_TOKEN` | | **Jira** | one card per finding (`--jira`) | `JIRA_EMAIL`, `JIRA_API_TOKEN` | πŸ“– Step-by-step setup for each tool: **[TUTORIAL-INTEGRATION.md](TUTORIAL-INTEGRATION.md)**. --- ## Build ```bash cd neurosploit-rs cargo build --release # β†’ target/release/neurosploit ``` Requires a Rust toolchain (`rustup`). **Recommended: run on Kali Linux** (or the Kali Docker image) so the offensive tools the agents use are already present: ```bash docker run -it --rm kalilinux/kali-rolling apt update && apt install -y curl nmap ffuf nodejs npm # rustscan (faster port scan): cargo install rustscan (or grab a release from GitHub) ``` The agents degrade gracefully: if `rustscan` isn't installed they use `nmap`; if neither, they probe with `curl`. If a Playwright MCP browser is available they use it for JS-heavy pages, otherwise they fall back to `curl`. --- ## Usage Run with **no arguments** for an interactive wizard: ```bash ./target/release/neurosploit ``` Or drive it directly: ```bash # Black-box β€” subscription (no API key), Opus, browser via Playwright if present, verbose ./target/release/neurosploit run http://testphp.vulnweb.com/ \ --subscription --model anthropic:claude-opus-4-8 --mcp -v # Black-box β€” API keys, multi-model voting panel (1st finds, others adjudicate) ./target/release/neurosploit run http://testphp.vulnweb.com/ \ --model anthropic:claude-opus-4-8 --model openai:gpt-5.1 --vote-n 3 # White-box β€” clone a vulnerable app and review its source git clone https://github.com/digininja/DVWA /tmp/DVWA ./target/release/neurosploit whitebox /tmp/DVWA \ --subscription --model anthropic:claude-opus-4-8 -v # Offline pipeline self-test (no keys/login needed) ./target/release/neurosploit run http://testphp.vulnweb.com/ --offline # Utilities ./target/release/neurosploit agents # library counts ./target/release/neurosploit models # providers & models ./target/release/neurosploit --help # full help with examples ``` ### Options (`run` / `whitebox`) | Flag | Meaning | |------|---------| | `--model provider:model` | Repeatable. First = primary; the rest fail over **and** form the voting jury. | | `--subscription` | Use the local CLI login (Claude/Codex/Gemini/Grok) instead of an API key. | | `--mcp` | Enable Playwright MCP (auto-provisioned via `npx`; backends without MCP use built-in tools). | | `--vote-n N` | How many models must agree a finding is real (default 3 / 2 for whitebox). | | `--max-agents N` | Cap agents run (`0` = all matching the recon). | | `--offline` | Exercise the full pipeline without calling any model. | | `-v, --verbose` | Log each agent as it launches, recon, and votes. | ### Authentication β€” run via API key *or* subscription You can run NeuroSploit two ways. They're independent: pick per run. #### 1) Via API (provider API key) Export the key(s) for the providers in your model panel, then run **without** `--subscription`. Any OpenAI-compatible provider works. ```bash # pick one or more, depending on the models you select export ANTHROPIC_API_KEY=sk-ant-... # anthropic:claude-* export OPENAI_API_KEY=sk-... # openai:gpt-* export GEMINI_API_KEY=AIza... # gemini:gemini-* export XAI_API_KEY=xai-... # xai:grok-* export NVIDIA_NIM_API_KEY=nvapi-... # nvidia_nim:* export DEEPSEEK_API_KEY=... # deepseek:* export MISTRAL_API_KEY=... # mistral:* export DASHSCOPE_API_KEY=... # qwen:* (Alibaba DashScope) export GROQ_API_KEY=... # groq:* export TOGETHER_API_KEY=... # together:* export OPENROUTER_API_KEY=... # openrouter:* # ollama needs no key (local) # then run via API (note: NO --subscription) ./target/release/neurosploit run http://testphp.vulnweb.com/ \ --model anthropic:claude-opus-4-8 --vote-n 3 -v # multi-provider voting panel via API (1st finds, the others adjudicate) ./target/release/neurosploit run http://testphp.vulnweb.com/ \ --model anthropic:claude-opus-4-8 --model openai:gpt-5.1 --model gemini:gemini-2.5-pro ``` Or put the keys in a `.env` and source it (`cp .env.example .env`; edit; `set -a; . ./.env; set +a`). **Provider β†’ env var β†’ endpoint** (all OpenAI-compatible): | `--model` prefix | Env var | Base URL | |------------------|---------|----------| | `anthropic:` | `ANTHROPIC_API_KEY` | api.anthropic.com | | `openai:` | `OPENAI_API_KEY` | api.openai.com | | `gemini:` | `GEMINI_API_KEY` | generativelanguage.googleapis.com | | `xai:` | `XAI_API_KEY` | api.x.ai | | `nvidia_nim:` | `NVIDIA_NIM_API_KEY` | integrate.api.nvidia.com | | `deepseek:` | `DEEPSEEK_API_KEY` | api.deepseek.com | | `mistral:` | `MISTRAL_API_KEY` | api.mistral.ai | | `qwen:` | `DASHSCOPE_API_KEY` | dashscope-intl.aliyuncs.com | | `groq:` | `GROQ_API_KEY` | api.groq.com | | `together:` | `TOGETHER_API_KEY` | api.together.xyz | | `openrouter:` | `OPENROUTER_API_KEY` | openrouter.ai | | `ollama:` | _(none)_ | localhost:11434 | Run `./target/release/neurosploit models` for the full provider/model list. #### 2) Via subscription (no API key) `--subscription` drives your local agentic-CLI login instead of an API key β€” install and log into one of the CLIs first: | `--model` prefix | CLI used | Login | |------------------|----------|-------| | `anthropic:` | `claude` (Claude Code) | `claude` then `/login` | | `openai:` | `codex` | `codex` login | | `gemini:` | `gemini` | `gemini` login | | `xai:` | `grok` | `grok` login | ```bash ./target/release/neurosploit run http://testphp.vulnweb.com/ \ --subscription --model anthropic:claude-opus-4-8 --mcp -v ``` --- ## How it works ``` target ─▢ recon (curl/nmap/…) ─▢ INTELLIGENT agent selection (recon-aware) ─▢ parallel exploitation ─▢ cross-model validation vote ─▢ severity/score ─▢ report (HTML + Typst PDF) ─▢ RL reward update ``` Every run writes a self-contained folder `runs/ns--/`: | File | Contents | |------|----------| | `status.json` | `running` β†’ `complete` with a summary | | `recon.json` / `recon.md` | mapped attack surface | | `exploitation.md` | raw per-agent transcript | | `findings.json` / `findings.md` | validated findings (reuse by other tools/AIs) | | `report.html`, `report.typ`, `report.pdf` | final report (PDF via the Typst engine) | A reinforcement-learning reward store (`data/rl_state_rs.json`) biases agent selection on future runs. ## Agent library β€” `agents_md/` (303) | Category | Count | Purpose | |----------|-------|---------| | `vulns/` | 196 | Exploit a specific vulnerability class | | `recon/` | 12 | Information gathering / attack surface | | `code/` | 78 | White-box source-code (SAST) review | | `meta/` | 17 | Orchestrator, validator, scorers, reporter, RL | Each agent is a self-contained markdown playbook (`## User Prompt` methodology + `## System Prompt` strict anti-false-positive rules). Drop a new `.md` into the matching folder and the harness picks it up. --- ## Safety For **authorized** testing only. Agents are instructed to stay in scope, never run destructive/DoS actions, and require proof-of-exploitation. You are responsible for having permission for any target. ## Credits **Joas A Santos** & **Red Team Leaders**. ## License MIT.