🧠 NeuroSploit v4.0.0

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 → — every mode, flag, config and example explained. Version-by-version changes live in 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 435 markdown agents and a Mission Control TUI.

Engagement modes

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 receipt (evidence, not paraphrase). Empirical (raw tool output) for black-box/host/AI, symbolic (file:line into the reviewed source — a code citation is the receipt) for white-box SAST & skills audits, and either for grey-box; ungrounded claims are demoted.
• 🔬 Deterministic HTTP probe — before the model recon, the harness runs a real request/response analysis (status/redirects, security headers, cookie flags, CORS reflection, tech fingerprint, linked JS, 404 baseline, high-signal paths) and feeds those observed facts into recon, so agent selection and exploitation decisions are grounded in evidence — not the model's guess.
• 🔗 Attack chaining — any primitive pivots. 13 multi-stage chain agents (SQLi→RCE→LPE, SSRF→cloud creds, upload→LFI→RCE→LPE, CVE→RCE→pivot, …) plus a chaining doctrine that turns any confirmed foothold into the next step: reduce it to a primitive (exec / read / write / request-forgery / identity / secret) and pivot — file-upload→RCE, SSRF→metadata creds, IDOR→takeover — reusing looted creds and reasoning about business logic (payment/tenancy/workflow abuse). Each stage proven; strictly non-destructive (no data loss, no DB overwrite, no DoS).
• ☁️ Cloud testing — AWS / GCP / Azure agents that drive the provider CLIs (aws/gcloud/az). Connect via creds.yaml: AWS keys, a Google service-account JSON, or an Azure service principal — see .

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):

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

Windows (PowerShell, x64 & arm64):

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

Supported platforms

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?

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

⚡ Quick start (60 seconds)

# 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.

No login? Use an API key instead — see Authentication.

🖥️ Web console (NEW in v4.0.0)

A browser UI for the same harness — every action spawns the real compiled CLI and parses its output; nothing about the harness logic is reimplemented in the browser.

cd neurosploit-rs && cargo build --release   # once
node web/server.js                            # → http://localhost:4173

Zero npm dependencies (Node built-ins only).

• 5-step engagement wizard — Asset (mode + target/repo) → Scope & Auth (objective, focus, out-of-scope) → Leads (the 435-agent board below) → Model & Run (provider/model picker, API-key vs. subscription toggle, votes/chain-depth/recon) → Review. Every engagement is named up front, so runs are identifiable in history instead of by raw target string.
• Lead board — all 435 agents auto-categorized (Business Logic, Broken Access Control, Injection, LLM Application, Auth & Session, SSRF & Network, Cloud & Infra, …). Toggle a single lead, a whole category (indeterminate when partially selected), or use Select all / Clear all — respects the active search filter. Leave everything off to let the harness's own recon-driven selection choose.
• Custom lead → real agent — "+ Custom lead" doesn't just add a text hint: it calls the claude CLI (Opus, your Anthropic subscription) to generate an actual specialist-agent markdown file into agents_md/vulns/, in the same format every built-in agent uses, pinnable immediately. Falls back to a plain focus-text hint if Claude isn't available.
• Live run view — phase/progress streamed over SSE from the CLI's own stdout, a findings table, and Generative Attack Path Chaining: a node/edge graph (root = target, one node per confirmed finding, positioned by kill-chain stage, edges from chains_from when the harness set one) instead of a flat list — click any node or row for the full finding detail, including any PoC script the exploiting agent wrote to pocs/.
• Auth & Keys (one menu) — target auth header + named roles for IDOR/BOLA/BFLA testing (materializes an ephemeral creds.yaml for the run), and per-provider API keys held in the server process's memory only — never written to disk.
• Survives a page refresh: an in-progress run reattaches to the same live stream instead of resetting to the wizard.

Full API reference: web/API.md · quick start: web/README.md.

🔌 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.

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

# Same, but BLOCK the merge on a confirmed critical: fails the check, sets a
# `neurosploit/security` commit status, and posts a REQUEST_CHANGES review.
neurosploit pr digininja/DVWA 42 --model anthropic:claude-opus-4-8 --comment --fail-on critical

# 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 [email protected] 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

Automations (GitHub Actions)

Two ready-made workflows ship in examples/github-actions/ — copy them into your repo:

• neurosploit-pr-gate.yml — reviews every PR and blocks the merge on a confirmed critical. Make it enforcing: Settings → Branches → require the neurosploit-pr-gate status check (and/or require review to honor the REQUEST_CHANGES). Set ANTHROPIC_API_KEY (or swap the model) in Actions secrets; the built-in GITHUB_TOKEN covers statuses/reviews.
• neurosploit-mention.yml — comment @neurosploit on a PR or issue to trigger a scan (only repo writers can). Text after the mention is the instruction (any language): @neurosploit focus SQLi and IDOR, or @neurosploit scan https://staging.app for a black-box run.

📖 Step-by-step setup for each tool: TUTORIAL-INTEGRATION.md.

☁️ Cloud credentials (AWS/GCP/Azure)

Add a cloud block to creds.yaml and the harness exports the right env vars so the AWS/GCP/Azure agents can drive aws / gcloud / az. Secrets stay in your file/secret-manager; agents do read-only enumeration first, never destructive.

# --- AWS: static keys (or a named profile) ---
aws:
  access_key_id: AKIA...
  secret_access_key: ...
  # session_token: ...        # if using temporary creds
  region: us-east-1
  # profile: my-sso-profile   # alternative to keys

# --- GCP: service-account JSON (path recommended; inline single-line also works) ---
gcp:
  service_account_json: /path/to/sa.json
  project: my-project-id

# --- Azure: service principal (recommended for automation) ---
azure:
  tenant_id: ...
  client_id: ...
  client_secret: ...
  subscription_id: ...

neurosploit host my-cloud-account --creds creds.yaml \
  --subscription --model anthropic:claude-opus-4-8 -v

Agents cover IAM privilege-escalation, storage exposure (S3/GCS/Blob), compute & network exposure, secrets (Secrets Manager / Secret Manager / Key Vault), service-account/SP abuse, and identity enumeration (Entra ID). Best-practice auth: AWS access keys or profile; GCP a service-account JSON (GOOGLE_APPLICATION_CREDENTIALS); Azure a service principal (az login --service-principal).

👥 Multiple identities — access-control testing (IDOR / BOLA / BFLA)

Give NeuroSploit two or more named roles in creds.yaml and it authenticates as each and tests cross-role access (a low-priv role reaching another user's object or an admin function is a finding):

admin:
  jwt: eyJ...                 # per role: jwt | header (raw) | cookie | apikey | login+username+password
user:
  apikey: abc123              # → X-Api-Key: abc123
victim:
  cookie: "session=deadbeef"

neurosploit run https://app.example --creds creds.yaml \
  --subscription --model anthropic:claude-opus-4-8 -v

Each finding is proven with the authorized vs unauthorized request pair, under the data-safety guardrail (read-only, PII masked).

🏷️ Identification & attribution (anti-plagiarism)

Every request is tagged with an identifying User-Agent (default NeuroSploit/<ver> …, change with /ua or NEUROSPLOIT_UA) plus an X-NeuroSploit-Scan header, and every finding is stamped "Identified and validated by NeuroSploit" — so provenance travels in the traffic, the finding text, findings.json and the report footer.

Build

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:

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:

./target/release/neurosploit

Or drive it directly:

# 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)

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.

# 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 MOONSHOT_API_KEY=...                # moonshot:*  (Kimi K3/K2)
export OPENROUTER_API_KEY=...              # openrouter:*
export OPENCODE_API_KEY=...                # opencode:*  (OpenCode Zen gateway)
export NOUS_API_KEY=...                    # nous:*  (Nous Portal — Hermes)
export LITELLM_API_KEY=...                 # litellm:*  (your LiteLLM proxy)
export AZURE_OPENAI_API_KEY=...            # azure:<deployment>  (also set AZURE_OPENAI_ENDPOINT)
# ollama / llamacpp need 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):

Run ./target/release/neurosploit models for the full provider/model list.

Local, uncensored & CPU-only — ollama: and llamacpp: run entirely on your box with no API key and no data leaving the host. llamacpp: targets a llama-server OpenAI-compatible endpoint (override with LLAMACPP_BASE_URL); the model is whatever gguf you loaded. Ideal for offline engagements and unfiltered offensive prompting.

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:

opencode: also gets the Playwright MCP (--mcp) like anthropic/openai do. nous: relies on Hermes's own built-in toolsets (web/terminal/computer-use) instead — it has no CLI-level MCP hook.

./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-<ts>-<target>/:

A reinforcement-learning reward store (data/rl_state_rs.json) biases agent selection on future runs.

Agent library — agents_md/ (435)

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 — or generate one from the web console's "+ Custom lead" (see above) — and the harness picks it up; neurosploit agents shows live counts.

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.