Run NeuroSploit

Concepts in 60 seconds #

You give NeuroSploit a target — a URL, repo, app, or host/IP. It then:

1. Recons the target with real tools (curl / nmap / ffuf…).
2. Intelligently selects only the agents whose preconditions match the recon — it does not blindly run all 486.
3. Exploits in parallel — each agent works in a ReAct loop and must prove its claim with a tool receipt (raw output).
4. Validates every candidate by cross-model voting (a different model adjudicates) and a grounding gate (no claim without a receipt).
5. Chains confirmed findings into deeper impact (SQLi→RCE, SSRF→cloud…).
6. Reports — HTML + Typst PDF + JSON/MD, with an attack-graph / kill-chain mapped to OWASP / CWE / MITRE ATT&CK.

It runs on a pool of LLMs you choose, authenticated either by API key or your local subscription (Claude Code / Codex / Gemini / Grok CLI).

Install #

One-liner

curl -fsSL https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/setup.sh | bash

irm https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/install.ps1 | iex

The installer detects your OS/arch, installs the Rust toolchain if needed, clones the repo, builds the release binary and puts neurosploit on your PATH. Re-run it any time to update. Env knobs: NEUROSPLOIT_REF (branch/tag), NEUROSPLOIT_DIR, PREFIX.

Manual build

git clone https://github.com/JoasASantos/NeuroSploit
cd NeuroSploit/neurosploit-rs
cargo build --release        # → target/release/neurosploit

Recommended runtime

Run inside Kali Linux (or the Docker image) so the offensive tools the agents use are already present:

docker run -it --rm kalilinux/kali-rolling
apt update && apt install -y curl nmap ffuf nodejs npm
# optional: cargo install rustscan ; cargo install typst-cli

Verify

neurosploit --version          # neurosploit 4.4.0
neurosploit agents             # {"vulns":255,...,"ai":30,...,"total":480}
neurosploit models             # all providers & models

Authentication: API key vs subscription #

You pick per run — the two paths are independent.

A) Via API key

Export the key for each provider you'll use, then run without --subscription:

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-*
# … deepseek, mistral, qwen, groq, together, moonshot, openrouter, nvidia_nim
# ollama: no key (local) · LiteLLM proxy via LITELLM_BASE_URL + LITELLM_API_KEY

neurosploit run http://testphp.vulnweb.com/ --model anthropic:claude-opus-4-8 --vote-n 3 -v

Or put them in a .env and source it (cp .env.example .env; edit; set -a; . ./.env; set +a). In the REPL you can also run /key anthropic sk-ant-....

B) Via subscription (no API key)

Install and log into a local agentic CLI, then pass --subscription:

neurosploit run http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 --mcp -v

Choosing models #

--model provider:model is repeatable. The first model is the primary (does recon & exploitation); the rest fail over if it errors and form the validator voting jury — a different model adjudicates each finding, which means fewer false positives.

# single model
--model anthropic:claude-opus-4-8

# voting panel (Opus finds, GPT-5.5 + Gemini-3 adjudicate)
--model anthropic:claude-opus-4-8 --model openai:gpt-5.5 --model gemini:gemini-3-pro

A built-in router sends fast/cheap models to recon & triage and the strongest to exploitation, to save tokens. See neurosploit models for the full list (Claude 5 / 4.x, GPT-5.x incl. Codex, Gemini 3 / 2.5, Grok, NVIDIA NIM, DeepSeek, Mistral, Qwen, Groq, Together, Moonshot / Kimi K3, OpenRouter, Ollama).

Black-box (URL) #

Recon → select → exploit → vote → report, against a live URL.

neurosploit run http://testphp.vulnweb.com/ \
  --subscription --model anthropic:claude-opus-4-8 \
  --focus "injection and broken access control" --mcp -v

White-box (source repo) #

Reviews a local code repository with the 78 source-review (SAST) agents: SQLi, command injection, SSRF, XSS, path traversal, insecure deserialization, hardcoded secrets, weak crypto, auth/IDOR, XXE, SSTI, and language-specific sinks (PHP / Java / .NET / Go / Node / Python).

# clone or point at the code you own
git clone https://github.com/digininja/DVWA /tmp/DVWA

# review it (subscription or --model with an API key)
neurosploit whitebox /tmp/DVWA --subscription --model anthropic:claude-opus-4-8 -v

# focus a class, cap agents, raise the voting bar
neurosploit whitebox /tmp/DVWA --focus "injection and access control" \
  --max-agents 8 --vote-n 2 --model openai:gpt-5.5

How it works

1. Collects source context — walks the repo (skips .git/node_modules/target/vendor), reads supported source files into a bounded review context.
2. Selects code agents for the languages / frameworks it sees.
3. Each agent traces source → sink dataflow and must quote the exact vulnerable lines as file:line.
4. Grounding is symbolic: a finding is only kept if its file:line / quoted code actually exists in the reviewed source — no hallucinated locations.
5. Validated by cross-model voting, then reported with the code reference, CWE/OWASP, PoC and remediation.

Grey-box (code + live app) #

The strongest mode: review the source and exploit the running app together. Code-review findings become leads that the live agents confirm against the deployed application — so a SQLi spotted in code is proven exploitable on the running endpoint.

neurosploit greybox /tmp/DVWA --url http://localhost:8080/ \
  --creds creds.yaml --focus "auth and IDOR" \
  --subscription --model anthropic:claude-opus-4-8 --mcp -v

1. Recon the live app (--url).
2. Review the source → produces a list of leads (suspected vulns with file:line).
3. Live exploitation runs with those leads injected as context — agents go straight for the proven-in-code weaknesses and prove them on the live app (empirical receipt).
4. Validate (cross-model) → chain → report.

Host / Infra (Linux / Windows / AD) #

Target an IP/host with SSH or Windows/AD credentials from creds.yaml:

neurosploit host 10.0.0.10 --creds creds.yaml \
  --focus "privilege escalation and AD" --subscription --model anthropic:claude-opus-4-8 -v

Runs infra agents: port/service scan, SMB enum, Linux privesc (sudo / cron / SSH), Windows privesc (SMB-signing / WinRM), and AD kerberoasting / AS-REP / ACL abuse / DCSync / default-creds.

AI / LLM red-teaming #

Point NeuroSploit at a live AI system — an LLM chat/API endpoint, an AI agent, or an MCP server — and it red-teams it: jailbreaks and prompt injection across many scenarios, plus the full OWASP LLM Top 10 (2025), MCP threats and OWASP AI Exchange.

neurosploit aitest https://your-ai-app.example/api/chat \
  --auth "Authorization: Bearer <key>" \
  --focus "jailbreaks and indirect prompt injection" \
  --subscription --model anthropic:claude-opus-4-8 -v

It runs an attacker→judge loop per technique: capture the baseline refusal, apply the technique across several scenarios/variants, then use an LLM-judge criterion to confirm whether the guardrail was actually bypassed — proving it with a benign, redacted prompt+response receipt (never real harm).

Jailbreak technique agents

AdvPrefix (adversarial prefix/suffix), PAIR (automated iterative refinement), TAP (tree-of-attacks), Crescendo (multi-turn escalation), many-shot, persona/DAN roleplay, encoding/obfuscation (base64 / ROT13 / zero-width / low-resource-language), and refusal-suppression.

Prompt-injection & hijacking scenarios

Direct injection, indirect injection via RAG doc / web page / email / tool output, goal hijacking, agentic tool/function-call abuse, and system-prompt / secret exfiltration.

Mobile / binary testing #

neurosploit mobile <app.apk | app.ipa | binary> --subscription --model anthropic:claude-opus-4-8 -v

Analyses a local artifact with the mobile agent set — 12 reverse-engineering skills: static triage, APK/IPA analysis, RASP/anti-tamper mapping, root/jailbreak, TLS pinning, anti-debug, deobfuscation, integrity checks, secret extraction, insecure storage and traffic analysis. Every tool runs headless (Ghidra analyzeHeadless, MobSF, Frida, apktool, jadx, radare2). Best run with --sandbox (Kali container) so the heavy toolchain installs off your host.

Container #

neurosploit container <image:tag>     # OCI image scan + SBOM (trivy / grype / syft)

The interactive REPL #

Run with no arguments for a persistent session. A context bar shows model auth · cwd · mode▸target.

/model [a:b,..]     set models (no arg → arrow-key multi-select)
/key [prov key]     configure API keys for your models
/sub on|off        use subscription login instead of API key
/target <url>      black-box target     /repo <path>  add a repo (repo+target = greybox)
/auth <value>      send an auth header   /creds <file>  load creds.yaml
/focus <text>      steer the tests (or just type the instruction)
/class <a,b,..>    focus on vuln CLASSES (idor,sqli,xss,ssrf,…)
/only <agents>     run EXACTLY these named agents (skips recon selection)
@path @dir @f:1-20  attach a file/folder/line-range to context (Tab → menu)
/mcp on|off   /votes <n>   /agents <n>   /recon <1-4>   /chain <n>
/quick              economy preset (1 voter · light recon · ≤6 agents)
/compliance <f,…>   map onto pci-dss, hipaa, soc2, gdpr
/run                launch the engagement (non-blocking)
/status  /stop  /results [n]  /report [n]  /diff  /retest [n]  /quit

Runs are non-blocking

/run launches the engagement in the background and returns the prompt immediately — you keep typing while it streams above. /status shows a live phase and progress bar; /stop gives a 3-way choice (validate-then-report · raw report now · discard).

Scope & authorization #

Hard scope is the safety boundary: a request whose host isn't authorized is refused before it leaves. Declaring scope is frictionless, and no bug-bounty program or capability token is required for a normal client engagement with written authorization.

1. Just point at the target

/target app.client.com        # authorized against app.client.com
/target *.client.com          # apex + ALL subdomains (recon enumerates them)
/run

2. Declare the whole scope in one line

/authorize app.client.com *.client.com 10.0.0.0/24 https://api.client.com/v2
/run

Tune limits any time with /guardrail (e.g. /guardrail destructive on, /guardrail rate 60, /guardrail accounts 2), exclude with /scope-out.

3. Import a ready config file

# scope (the safety boundary — the one thing you must set)
hard:
  - "*.client.com"            # apex + every subdomain
  - 10.0.0.0/24               # an internal range
exclude:
  - billing.client.com        # carve-outs always beat the allowlist
soft:
  allow_destructive_methods: false
  allow_account_creation: true
  max_accounts: 3
  max_requests_per_minute: 240
  forbidden_payloads: ["drop table", "rm -rf /", "shutdown"]

# optional — define the rest of the engagement in the same file:
target: "*.client.com"
models:
  - anthropic:claude-opus-5-5
classes: idor, sqli, ssrf
focus: "prioritize access control and SSRF"
authorization: "<SOW / contract reference, or a program URL>"

The potent run recipe #

A black-box run against a real, hardened target (behind a WAF/CDN) is only as good as how you set it up. This is the recipe that gives the strongest, most-reproducible results — paste it into the REPL before /run:

# 1) A cross-model jury — the finder AND independent validators
/model anthropic:claude-opus-5-5, openai:gpt-6-astra

# 2) A realistic browser User-Agent — a scanner UA gets WAF-blocked (false negatives)
/ua browser

# 3) Deep recon — more rounds, active enum, subdomain discovery (1 quick…4 exhaustive)
/recon 4

# 4) Scope + authorization in one step
/scope-file examples/scopes/engagement.example.yaml
/authorization https://hackerone.com/<program>     # context only, never widens scope

# 5) Point the hunt — in ANY language
focus on auth, OAuth/OIDC, IDOR/BOLA and business logic on less-hardened subdomains

# 6) Go — runs in the background; watch with /status, /logs, /finding
/run

Credentials (creds.yaml) #

One file covers web auth, multiple roles (for access-control testing), SSH, Windows/AD and cloud (AWS/GCP/Azure). Mix only the blocks you need.

Web auth (single identity)

# --- pick one ---
jwt: eyJhbGciOi...                 # → Authorization: Bearer <jwt>
# header: "X-Api-Key: abc123"      # any raw header, sent as-is
# cookie: "session=deadbeef"       # → Cookie: session=deadbeef

# --- OR an automated login the harness performs (real HTTP) ---
login:
  url: http://localhost:8080/login
  method: POST
  username_field: username
  password_field: password
  username: admin
  password: password
  success: Logout                  # text shown on a successful login

Multiple identities — access control (IDOR / BOLA / BFLA / privesc)

Define two or more named roles. With ≥2 roles the harness authenticates as each and tests cross-role access, proving each with the authorized-vs-unauthorized request pair. Per role: jwt · header · cookie · apikey · or login+username+password.

admin:
  jwt: eyJhbGciOi...
user:
  apikey: abc123                   # → X-Api-Key: abc123
victim:
  cookie: "session=deadbeef"
tester:                            # a role can log in itself instead
  login: https://app.example/api/login
  username: tester
  password: Passw0rd!

Linux host (SSH), Windows/AD & cloud

ssh:
  host: 10.0.0.5
  user: ubuntu
  password: s3cret                 # or: key: /home/op/id_ed25519
windows:
  host: 10.0.0.10
  domain: CORP
  user: jdoe
  password: Winter2026!            # or hash: <LM:NT> for pass-the-hash
aws:
  access_key_id: AKIA...
  secret_access_key: ...
  region: us-east-1
gcp:
  service_account_json: /path/to/sa.json
  project: my-project-id
azure:
  tenant_id: ...
  client_id: ...
  client_secret: ...
  subscription_id: ...

Test accounts & the credential vault #

To reach the high-impact authenticated surface, NeuroSploit can analyze the app's forms and create its own test account when you don't supply credentials — with curl (plain HTML/API forms) or the Playwright browser (JS-rendered / multi-step forms).

• Anti-flood guardrail (hard): at most 2 accounts per engagement. Agents never loop / script / batch the register endpoint; they reuse the account they made.
• Credential vault: every account/credential is written to .neurosploit/vault/<run-id>.json; secrets are masked in the report and live only in the vault.
• Cleanup list: the report includes an Info finding "Test accounts created (DELETE after)" listing each account and how it was created.
• Finding labels: every finding is tagged Auth: authenticated / unauthenticated and Account: (which test user proved it).
• Disposable email (opt-in): /tempmail on enables the free mail.tm API to read a registration confirmation code. Off by default.

Mission Control TUI #

A live dashboard with concurrent panels and a composer you can type into while the run streams:

neurosploit tui http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 --mcp
# greybox: add --repo /path/to/repo

• Header: target · mode · model · phase · elapsed · 🪙 tokens/cost · findings
• Activity feed (color-coded), Findings panel (live), Targets map
• Composer (non-blocking): summary, pause, errors, clear, or a free-text note
• Esc / Ctrl-C → graceful stop; the report is generated on exit

Web console #

A browser UI for the same harness — one node process serves the SPA and drives the compiled neurosploit binary; nothing about the harness logic is reimplemented in the browser. Zero npm dependencies (Node ≥18 built-ins only).

cd neurosploit-rs && cargo build --release   # build the binary once
cd ../web && npm start                        # → http://localhost:4173

The 5-step wizard

1. Asset — pick black/white/grey-box, host/infra, or AI/LLM, then the target URL or repo path.
2. Scope & Auth — objective, focus, out-of-scope, named roles for IDOR/BOLA, per-provider API keys (kept in the server process's memory only, never written to disk).
3. Leads — the 486-agent board, auto-categorized. Toggle a lead, a category, or Select/Clear all. Leave everything off to let recon-driven selection choose. + Custom lead generates a real specialist-agent markdown file.
4. Model & Run — provider/model picker, API-key vs. subscription toggle, votes / chain-depth / recon intensity.
5. Review — confirm the plan, then Start Exploitation.

Tabs (live & finished-run): Findings, Attack graph (host → service → finding → credential → impact), Chains, Dependencies, Traffic, Traces (transcript viewer), Deliverables. The finding modal shows Wire evidence — the real request/response pairs — and a ⟳ Re-test this finding button that re-runs the proof through the replay engine.

NeuroSploit as an MCP server #

Run NeuroSploit as a Model Context Protocol server and any MCP client (Claude Code, Codex, Cursor…) can drive it as tools.

neurosploit mcp                           # speaks MCP over stdio
claude mcp add neurosploit -- neurosploit mcp   # install in Claude Code

Or add it by hand to ~/.claude.json / a project .mcp.json:

{
  "mcpServers": {
    "neurosploit": { "command": "neurosploit", "args": ["mcp"] }
  }
}

Attack graph & Neo4j (graph memory) #

The attack graph is part of the test, not a post-run drawing. A graph checkpoint runs after recon, at validation, at each chaining round, and at the end — in every mode. At each checkpoint it directs agent selection (an SSRF lead pulls in ssrf_cloud, PostgreSQL + SQLi pulls in postgres_superuser_rce…) and feeds every exploit prompt a live context: the surface, the top chains, the next moves, and the dependency todolist.

It works without Neo4j

Every run writes a graph/ folder next to the report — no database needed:

Enabling Neo4j (optional)

# credentials ONLY via env — never on the command line, never written to disk
export NEO4J_USER=neo4j NEO4J_PASSWORD='please-change-me'
neurosploit run https://app.example --neo4j bolt://localhost:7687

Wire-bound evidence & report redaction #

Two safeguards that are always on — no flag, part of the process.

Wire-bound evidence

Before validation, every exchange an agent reports is re-sent by the harness itself through the scope-guarded replay engine (non-mutating verbs only) and checked against recorded traffic. When the wire reproduces the agent's account, the harness's own observation replaces it and the deterministic validators judge real bytes (marked [wire-verified]). When the wire contradicts it, the finding can't stand as confirmed. What can't be checked stays unverifiable.

Report redaction

Credentials become $SECRET_n placeholders in every human-facing report — the same secret gets the same placeholder throughout, so an attack chain stays readable. Raw values are kept only in findings.json and the run's vault.json.

How it decides #

NeuroSploit treats the target as partially observable (a POMDP):

• Belief world model — a property graph whose nodes (host/service/vuln/exploit/credential) carry probabilities, updated by observations.
• Value-of-information — "scan more vs exploit now" falls out of belief entropy: when a node's belief is diffuse, recon is worth more than exploiting.
• Anti-hallucination gate (may_assert) — the agent may not claim exploitability while the belief is diffuse; it must observe more first.
• Grounding — no claim without a receipt: empirical for black-box / host / AI, symbolic (file:line) for white-box SAST, and either for grey-box.
• Chaining — confirmed findings are chained into deeper impact, each stage proven before advancing.

White-box collapses the POMDP toward a near-deterministic MDP (the world model is built from SAST/dataflow), so uncertainty becomes path reachability, not state.

The agent library #

agents_md/ holds the markdown agents in categories. Each is a self-contained playbook (a ## User Prompt methodology + ## System Prompt strict anti-false-positive rules). Add your own by dropping a .md into the matching folder — it's picked up automatically.

Assurance & authorization #

A layer of controls that make a run defensible, not just productive — all enforced in code (not prompt text), every decision landing in the hash-chained audit trail.

Target authorization gate (default-deny)

Before any recon, the target is checked against the capability grant — protocol, host, port, URL prefix. A signed token that does not cover the target refuses the run and exits non-zero. Loopback (localhost/127.0.0.1) is exempt. Alt-IP encodings (0x7f000001, 2130706433…) all normalize, so an exclude can't be dodged, and a DNS-rebinding guard refuses a name that re-resolves to a new internal address.

Evidence-graded CVSS

The score is computed from the FIRST v3.1 equation, and each impact metric is graded against a receipt. SQLi that reached the interpreter but extracted nothing scores demonstrated 0 / potential 9.8 — never a manufactured critical. The vector travels with the number.

Tooling

--sandbox                              # run agent commands in a Kali container
--intercept burp|caido|zap|mitmproxy   # route through a tool …
--intercept own | own+burp             # … or the harness's own interceptor
--revalidate-poc                       # re-run each PoC; demote what no longer reproduces
--compliance pci-dss,hipaa,soc2,gdpr   # control mapping in the report
--typesafe on|off|auto                 # calibrated adjudication + confirmation loop

Outputs, reports & artifacts #

Every run writes a self-contained folder runs/ns-<ts>-<target>/:

Per-project memory & resume: launching the REPL in a project directory creates <cwd>/.neurosploit/ (session.json, runs.json, active_run.json, history.txt). Reopen in the same folder → it resumes automatically. An interrupted run's checkpointed findings are recovered into /runs.

Integrations: GitHub / GitLab PR review gate (neurosploit pr <repo> <n> --fail-on critical), @neurosploit mention bot, one Jira card per finding, MCP server, compliance mapping (PCI-DSS / HIPAA / SOC 2 / GDPR).

Tips & troubleshooting #

• No findings on a live target? It may be unreachable, or the app is genuinely static — the harness refuses to fabricate. Check recon.md.
• Quick smoke test: neurosploit run http://x --offline exercises the pipeline without calling any model.
• Cost control: start with --max-agents 4 --vote-n 1; scale up later. The router already routes cheap models to recon.
• Rate limits (subscription): the harness retries with backoff and caps parallel CLI processes; add more models to the panel or switch to an API key.
• Run as root: the harness sets IS_SANDBOX=1 so Claude Code's autonomy works.
• Stuck? Ctrl-C once for a graceful stop (→ keep/discard report); twice aborts.

Command & flag reference #

neurosploit                       # interactive REPL (resumes per project)
neurosploit run <url>             # black-box
neurosploit whitebox <repo>       # white-box source review
neurosploit greybox <repo> --url <app>   # code + live
neurosploit host <ip>             # Linux/Windows/AD (with --creds)
neurosploit aitest <ai-url>       # AI / LLM red-teaming
neurosploit mobile <app>          # APK / IPA / binary reverse engineering
neurosploit container <image>     # OCI image scan + SBOM
neurosploit tui <url>             # Mission Control TUI (--repo for greybox)
neurosploit graph <run> [--push]  # attack graph for a finished run (± Neo4j)
neurosploit compliance <run>      # map onto PCI-DSS/HIPAA/SOC2/GDPR
neurosploit sarif <run>           # (re)emit report.sarif
neurosploit poc <run>             # re-validate every finding's recorded proof
neurosploit agents               # library counts
neurosploit models               # providers & models
neurosploit mcp                   # run as an MCP server
neurosploit --help                # full help

--model provider:model   repeatable; 1st = primary, rest = failover + voting jury
--subscription           use local CLI login instead of an API key
--mcp                    enable Playwright MCP browser (subscription path)
--creds <file.yaml>      jwt/header/cookie/login + ssh/windows credentials
--focus "<text>"         steer agent selection & execution
--vote-n <n>             validator votes per finding (default 3)
--max-agents <n>         cap agents (0 = all matching)
--scope-file <yaml>      import scope + target/models/focus/classes from one file
--compliance <list>      pci-dss,hipaa,soc2,gdpr — control mapping in the report
--neo4j <uri>            sync the attack graph to Neo4j (creds via NEO4J_* env)
--offline                pipeline self-test, no model calls
-v, --verbose            log each agent, recon, votes