🧠 NeuroSploit v3.5.5

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.

🆕 New in v3.5.5 — Cloud testing + REPL navigation + deeper recon: AWS/GCP/Azure agents (+17 → 375 total) with credentials wired through creds.yaml; a more navigable REPL — /timeout idle guardrail, multi-target /target a,b,c (sequential), an interactive /results browser (target → vuln → detail, Esc to go back) and /report picker; and deeper recon that downloads & analyzes JavaScript (endpoints, secrets, source maps) and does request/response differential analysis. Interactive line-editing prompt bug fixed. (v3.5.4 added robust attack chaining + false-positive reduction; v3.5.3 GitHub/GitLab/Jira integrations; v3.5.2 the DEPTH doctrine + report-hygiene — see 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 389 markdown agents and a Mission Control TUI.

Engagement modes

Mode	Command	What it does
Black-box	neurosploit run <url>	recon → select → exploit → vote → report
White-box	neurosploit whitebox <repo>	source/SAST review (file:line evidence)
Grey-box	neurosploit greybox <repo> --url <app>	code review + live exploitation together
Host/Infra	neurosploit host <ip> --creds creds.yaml	Linux / Windows / AD and cloud (AWS/GCP/Azure) testing
Mission Control	neurosploit tui <url>	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.
• 🔬 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 — 12 multi-stage chain agents (SQLi→RCE→LPE, SSRF→AWS creds, upload→LFI→RCE→LPE, default-creds→domain, …); each stage proven before advancing.
• ☁️ 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 Cloud credentials.
• 🧰 Misconfig & CVE hunting, safely — dedicated agents for absurd misconfigs (exposed .git/.env, debug/actuator, default creds, dashboards, CORS), a CVE Hunter (smart, targeted nuclei), a PoC Developer (writes reproducible scripts to the run's pocs/), and rate-limit testing — all under a strict data-safety/PII guardrail (no destructive or state-changing actions; PII proven with a masked sample, never dumped).
• 🕵️ Burp/ZAP proxy — /proxy <url> (or /burp) routes agent traffic through your local intercepting proxy so you can inspect & replay in Burp.
• 🗺️ 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 — <cwd>/.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):

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

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?

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.

---

🔌 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

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

---

☁️ 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, th