NeuroSploit/TUTORIAL.md

NeuroSploit — Tutorial & User Guide (v4.3.1)

A complete, hands-on guide to installing, configuring and running NeuroSploit — the autonomous, multi-model penetration-testing harness.

⚠️ Authorized testing only. Every agent is instructed to stay in scope and never run destructive/DoS actions. You are responsible for having written permission for any target you point it at.

---

Table of contents

1. Concepts in 60 seconds
2. Install
3. Authentication: API key vs subscription
4. Choosing models
5. Engagement modes
   • Black-box (URL)
   • White-box (source repo)
   • Grey-box (code + live app)
   • Host / Infra (Linux / Windows / AD)
6. The interactive REPL
   • Scope — three ways
   • Get the most out of a run
7. Mission Control TUI
8. NeuroSploit as an MCP server
   • Mobile / binary testing
   • Web console
   • Attack graph & Neo4j (graph memory)
   • Wire-bound evidence & report redaction
9. Credentials (creds.yaml)
10. Steering the tests (focus & instructions)
11. Outputs, reports & artifacts
12. Per-project memory & resume
13. How it decides: POMDP, grounding, chaining
14. The agent library
15. Playwright MCP & extra tools
16. Tips, tuning & troubleshooting
17. Assurance & authorization (v4.1.0)
18. Command & flag reference

---

1. Concepts in 60 seconds

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

1. Recons the target with real tools (curl/nmap/…).
2. Intelligently selects only the agents whose preconditions match the recon (it does not blindly run all 430).
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→LPE, 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).

---

2. Install

One-liner

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

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

Agents degrade gracefully: if rustscan is absent they use nmap; if neither, curl. With Playwright MCP present they drive a real browser; otherwise curl.

Verify

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

---

3. Authentication: API key vs subscription

You pick per run. They're independent.

First-time configuration

Absolute first run, in order:

1. Install (section 2) and confirm neurosploit --version prints neurosploit 4.3.1.
2. Give it a model to talk to — one of:
   • API key: export the provider key, e.g. export ANTHROPIC_API_KEY=sk-ant-... (full list below), then run without --subscription; or
   • Subscription: install and log into a local agentic CLI (e.g. claude → /login), then pass --subscription.
3. Run it — neurosploit with no arguments opens the interactive session and asks for everything; or go straight in with neurosploit run <url> --subscription --model anthropic:claude-opus-4-8 -v.
4. Per-project state lives in <cwd>/.neurosploit/ (session, run history, command history) and each engagement's output in runs/ns-<ts>-<target>/. No database is required. Run from the directory you want to keep that state in.

Everything else — credentials for the target, scope, focus, Neo4j, the web console — is optional and layered on top. The rest of this section covers the two auth paths in detail.

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-*
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:*
# ollama: no key (local)
# LiteLLM proxy: point at your gateway and route any model through it:
export LITELLM_BASE_URL=http://localhost:4000/v1   # your LiteLLM proxy
export LITELLM_API_KEY=sk-...                       # litellm:<model the proxy routes>

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-... (it lists which providers your selected models need).

B) Via subscription (no API key)

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

--model prefix	CLI	Login
anthropic:	Claude Code (claude)	claude → /login
openai:	Codex (codex)	codex login
gemini:	Gemini (gemini)	gemini login
xai:	Grok (grok) — incl. xai:grok-4.7	grok login

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

---

4. 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 → 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 incl. Opus 5 & Sonnet 5, GPT-5.x incl. Codex, Gemini 3/2.5, Grok, NVIDIA NIM, DeepSeek, Mistral, Qwen, Groq, Together, Moonshot/Kimi K3, OpenRouter, Ollama).

---

5. Engagement modes

5.1 Black-box (URL)

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

5.2 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, language-specific sinks (PHP/Java/.NET/Go/Node/Python), and more.

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

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

# focus a specific 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.

Tips

• No --mcp is used in white-box (there's no live app to browse).
• For huge repos, narrow with --focus or point at a subdirectory.
• Each finding's endpoint field is the file:line; evidence quotes the code; payload is the PoC / vulnerable snippet — view it all with /finding.

5.3 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).

# code repo + the URL where that code is actually running
neurosploit greybox /tmp/DVWA --url http://localhost:8080/ \
  --creds creds.yaml --focus "auth and IDOR" \
  --subscription --model anthropic:claude-opus-4-8 --mcp -v

How it works

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

Notes

• Pass --creds creds.yaml so agents test authenticated flows (login / JWT / cookie) — essential for IDOR/BOLA/auth findings.
• --mcp enables the Playwright browser for client-side proof (e.g. XSS firing).
• In the REPL: set both /repo <path> and /target <url> → grey-box is auto-selected; /show displays mode: greybox (code + live).

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

5.5 AI / LLM red-teaming (agents, jailbreaks & prompt injection)

Point NeuroSploit at a live AI system — an LLM chat/API endpoint, an AI agent, or an MCP server — and it red-teams it the way hackagent.dev-style tooling does: 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.

Plus the OWASP-category agents: LLM01 prompt injection, LLM02 sensitive-info disclosure, LLM05 improper output handling, LLM06 excessive agency, LLM07 system-prompt leak, LLM08 RAG/embedding weakness, LLM09 misinformation, LLM10 unbounded consumption, and MCP tool-poisoning / excessive-permissions / unsafe execution.

In the REPL, run /onboard and pick AI Agents & LLMs, set /target <endpoint> (and /auth if needed), then /run. To audit Skill/plugin or n8n definition files white-box instead of a live endpoint, use neurosploit skills <file|folder> (or the AI Skills / Plugins / n8n onboarding scope).

All AI testing is authorized, non-destructive — demonstrations stay benign and redacted; the goal is to prove the guardrail bypass, not to cause harm.

5.6 Test accounts, form analysis & 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: GET for CSRF+cookies, then POST) or the Playwright browser (JS-rendered / multi-step forms, e.g. Juice Shop). The deterministic probe now extracts each <form>'s action/method/fields/kind, so the agents know exactly what to submit.

• Anti-flood guardrail (hard): at most 2 accounts per engagement (1 user; a 2nd only when a test needs two users, e.g. horizontal IDOR). Agents never loop / script / batch the register endpoint or flood the database; they reuse the account they made. A test that would need many sign-ups is reported as a lead and stopped.
• Credential vault: every account/credential the run generates is written to .neurosploit/vault/<run-id>.json so you can consult the passwords later. 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 exactly how it was created — so you can remove them when done.
• Finding labels: every finding is tagged Auth: authenticated / unauthenticated and Account: (which test user/role proved it) — so in grey-box you see which findings needed a login, and in black-box you see what the agent did to create the user.
• Disposable email (opt-in, off by default): if registration requires an email confirmation code, enable /tempmail on (REPL) — agents may then use the free mail.tm API (no key) to create a throwaway inbox and read the code. Off by default: a required confirmation is otherwise reported as a blocker, not bypassed.

neurosploit› /target http://localhost:3001     # e.g. a local Juice Shop
neurosploit› /tempmail on                       # only if signup needs email confirmation
neurosploit› /run                               # analyzes forms, self-registers, tests authenticated
neurosploit› /report                            # see the vault-backed "Test accounts (DELETE after)" section

---

6. The interactive REPL

Run with no arguments for a persistent session:

neurosploit

A context bar shows model auth · cwd · mode▸target. Key commands:

/model [a:b,..]     set models (no arg → arrow-key multi-select)
/key [prov key]     configure API keys for your models (no arg → guided)
/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,…) — pins the matching agents
/only <agents>      run EXACTLY these named agents (skips recon-based selection)
@path  @dir  @f:1-20   attach a file/folder/line-range to context (Tab → menu)
/mcp on|off   /offline on|off   /votes <n>   /agents <n>   /theme color|mono
/quick              economy preset (1 voter · 1 chain round · light recon · ≤6 agents)
/compliance <f,…>   map findings onto frameworks (pci-dss, hipaa, soc2, gdpr); /compliance none clears
/budget <mode>      reasoning budget: eco|balanced|aggressive|unlimited; /budget token <N> caps tokens
/research on|off    whitebox/greybox: hunt a NOVEL, CVE-reportable bug (dedup + patch-diff)
/tempmail on|off    opt-in disposable inbox (mail.tm) for a register confirmation code
── scope & authorization ──
/authorize <a b c>  direct engagement: declare the whole authorized scope in one line
                    (hosts / *.domains / CIDRs / URL-prefixes) — no program needed
/scope-file <path>  import a ready scope/engagement config (see §6.1)
/inscope <entry>    add one more host/*.domain/CIDR to scope · /scope-out <entry> exclude
/guardrail <k> <v>  tune limits: destructive on|off · accounts <n|off> · rate <req/min>
/authorization <url>  record the program/authorization (e.g. a bug-bounty URL) — context only
/run                launch the engagement
/runs   /results [n]   /report [n]   /status [n]
/diff               what changed vs the previous run
/retest [n]         re-verify a past run's findings
/quit

Any language. You don't have to use slash-commands — just describe the engagement in plain text, in any language (the REPL interprets it): test https://shop.com with opus, focus on SQLi, out of scope /admin, run. The output and help are English; your input can be Portuguese, Spanish, etc.

Line editing: ↑/↓ history, Tab completes commands & @paths, Ctrl-A/E/K, end a line with \ for multiline.

Runs are non-blocking

/run launches the engagement in the background and immediately returns the prompt — you keep typing while it streams live above the prompt. While it runs:

• /status — live phase, a progress bar (agents done / total), elapsed time, token/cost and the possible findings so far.
• /stop — stop with a 3-way choice: [1] validate the findings found so far, then report · [2] raw report now without validating · [3] discard. Choices 2 and 3 abort in-flight agents immediately (running commands are killed); choice 1 stops launching new agents but lets validation finish.
• Findings are color-coded by severity (Critical = red … Info = grey), and a confirmed vote shows green ✓.
• When it finishes you get ◀ run #n done — N validated finding(s) · /results n · /report n.

Findings survive a crash/quit. Every finding is checkpointed live to .neurosploit/active_run.json. If the REPL is closed (or crashes) mid-run, the next launch recovers them into /runs automatically (↻ recovered interrupted run …), so /results, /finding and /report still work.

If your tokens/quota run out, the run pauses instead of dying. When every candidate model is rate-limited/out of quota, the run parks (keeping all state) and prints ⏸ token/quota exhausted … PAUSED. Then either:

• wait for your quota to renew and type /continue to retry the same model, or
• switch model first — /model <provider:model> (or /model for the arrow-select menu) — then /continue to resume on the new model.

(When stdin is piped/non-interactive, /run falls back to blocking mode.)

6.1 Scope — three ways, from quick to a full config

Hard scope is the safety boundary: a request whose host isn't authorized is refused before it leaves. You must declare what you're allowed to test — but that's 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 (the target is the grant):

/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 (direct engagement, multiple assets):

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

You assert written authorization for those assets. 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 (large scope, version-controlled, or reusable):

/scope-file examples/scopes/engagement.example.yaml
/run

A scope config is a single YAML that can define the whole engagement — scope plus target, models, focus, objective, authorization and vuln classes:

# 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   # true only if the authorization covers it
  allow_account_creation: true
  max_accounts: 3
  max_requests_per_minute: 240       # raise for a lab, lower for fragile prod
  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 the run on these classes
focus: "prioritize access control and SSRF"
authorization: "<SOW / contract reference, or a program URL>"

Importing it sets everything in one step; if a stale target left over from a previous session falls outside the new scope, it's reset to a host inside it. Ready templates live in examples/scopes/ (engagement.example.yaml for a direct client test; nasa.yaml as a VDP example). On the CLI the same file works with --scope-file (which reads the scope portion):

neurosploit run "*.client.com" --scope-file examples/scopes/engagement.example.yaml --subscription

A capability token (--capability-token, verified with NEUROSPLOIT_CAPABILITY_KEY) is a separate, optional layer for when a lead must hand a tester a scope they cannot widen. Everyday engagements don't need it.

6.2 Get the most out of a run (recommended potent setup)

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. The single
#    biggest quality lever: one model validating its own findings is weak.
/model anthropic:claude-opus-5-5, openai:gpt-6-astra
#    (one model is fine too; two+ enables real cross-validation and voting)

# 2) A realistic browser User-Agent — a self-declaring scanner UA gets
#    blocked/challenged by a WAF/CDN and causes FALSE NEGATIVES. Attribution
#    stays in the X-NeuroSploit-Scan header.
/ua browser

# 3) Deep recon — more rounds, active enumeration, subdomain discovery inside
#    the wildcard scope (1 quick · 2 standard · 3 deep · 4 exhaustive).
/recon 4

# 4) Scope + authorization in one step (see §6.1). For a program, record it:
/scope-file examples/scopes/engagement.example.yaml
/authorization https://hackerone.com/<program>     # context only, never widens scope

# 5) Point the hunt — in ANY language. Steers the LLM to the high-value surface
#    (it is NOT boxed in one vuln class; this focuses WHERE it spends effort).
focus on auth, OAuth/OIDC, IDOR/BOLA and business logic on the less-hardened subdomains

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

A broad focus to cover the whole surface (paste as /focus …, or just type it — any language). Use this when you want maximum breadth rather than a narrow hunt; it complements the default OWASP/ASVS/CWE objective:

/focus Cover the full web attack surface and prove impact: map every route/endpoint/parameter from the app and its JS bundles, then test each applicable class — injection (SQL/NoSQL/command/SSTI/LDAP/XPath), XSS (reflected/stored/DOM), access control (IDOR/BOLA/BFLA/privesc/forced browsing), authentication & session (login, signup, password reset, MFA, OAuth/OIDC/SAML, JWT alg/kid/jku), SSRF, XXE, insecure deserialization, CSRF, open redirect, CORS, file upload/download & path traversal, business-logic & multi-step flow abuse, mass assignment, request smuggling, info disclosure & security misconfiguration, cryptographic failures, and known-CVE components. Prioritise the authenticated surface and less-hardened subdomains, chain footholds into higher impact, and confirm every finding with a reproducible request/response receipt.

objective vs focus. The objective (set by default, OWASP/ASVS/CWE) is the framing — why the test runs and what counts as impact. The focus steers where effort goes. Neither boxes the run into one class — the agents still report any class they can prove; these just prioritise. To deliberately narrow to specific classes, use /class idor,ssrf,auth.

Other high-value knobs:

Command	When to use
/class idor,sqli,ssrf,auth	Force a run onto specific vuln classes (pins the matching agents).
/chain 3	More post-exploitation chaining rounds (pivot a foothold into deeper impact).
/votes 2	Require 2 models to agree before a finding is confirmed (fewer false positives; needs ≥2 models).
/proxy http://127.0.0.1:8080	Route all traffic through Burp/ZAP to inspect & replay.
/creds creds.yaml	Authenticated testing — the authenticated surface is where the high-impact bugs live.
/research	Whitebox/greybox: hunt a novel, CVE-reportable bug (dedup + patch-diff).
/quick	The opposite — a fast, cheap, low-token pass.

Reality check. A mature external surface (a big publisher behind Cloudflare) mostly yields hygiene/info-disclosure findings on black-box — that's the target being hardened, not a tool failure. The high/critical bugs live on the authenticated surface and less-hardened subdomains; point recon and your focus there. For a measurable benchmark, run against a seeded lab (OWASP Juice Shop, crAPI, VAmPI) where "found X of Y known bugs" is countable.

---

7. Mission Control TUI

A live dashboard with concurrent panels and a composer you can type in 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 (partial summary), pause (graceful stop), errors (filter), clear, or a free-text note
• Esc / Ctrl-C → graceful stop; the report is generated on exit

---

8. 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, from inside your normal agent session.

neurosploit mcp        # speaks MCP over stdio

Install in Claude Code

claude mcp add neurosploit -- neurosploit mcp

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

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

Install in Codex / Cursor / generic MCP client

Point the client at the command neurosploit mcp (stdio transport). For Codex, add to its MCP config:

[mcp_servers.neurosploit]
command = "neurosploit"
args = ["mcp"]

Tools it exposes

Tool	What it does
neurosploit_run	Launch an engagement (target, mode, model, focus, scope-file, sandbox, typesafe)
neurosploit_list_runs	List finished runs
neurosploit_findings	Read a run's findings JSON
neurosploit_report	Read a run's Markdown report
neurosploit_rebuild	Rebuild a run's report (no model calls)
neurosploit_internal	Internal / AD attack-graph analysis
neurosploit_compliance	Map a run onto PCI-DSS / HIPAA / SOC 2 / GDPR

Each tool shells out to the same neurosploit binary, so authorization, scope and safety are identical to the CLI. The MCP server needs neurosploit on PATH (or use an absolute path in the config) and, for a run, whatever the engagement needs (a model API key or --subscription).

---

8a. 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 covering static triage, APK/IPA analysis, RASP/anti-tamper mapping, root/jailbreak, TLS pinning, anti-debug, obfuscation deobfuscation, integrity checks, secret extraction, insecure storage and traffic analysis. Every tool runs HEADLESS (Ghidra analyzeHeadless, MobSF REST/Docker, Frida, apktool, jadx, radare2) and is provisioned on demand. Best run with --sandbox (Kali container) so the heavy toolchain installs off your host. Findings are proven from the artifact itself, non-destructively.

---

8b. 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.

cd neurosploit-rs && cargo build --release   # build the binary once
cd ../web && npm start                        # → http://localhost:4173
# (node web/server.js from the repo root works too)

Zero npm dependencies (Node ≥18 built-ins only). Override the port with NEUROSPLOIT_WEB_PORT (or PORT).

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, and a link into the Auth & Keys menu (target auth header, named roles for IDOR/BOLA/BFLA, per-provider API keys — kept in the server process's memory only, never written to disk).
3. Leads — the 486-agent board, auto-categorized (Business Logic, Broken Access Control, Injection, LLM Application, Auth & Session, SSRF & Network, Cloud & Infra, …). Toggle a single lead, a whole category, or Select all / Clear all (respects the active search filter). Leave everything off to let the harness's own recon-driven selection choose. + Custom lead calls the claude CLI to generate a real specialist-agent markdown file into agents_md/vulns/, pinnable immediately.
4. Model & Run — provider/model picker from the live catalog, API-key vs. subscription toggle, votes / chain-depth / recon intensity.
5. Review — confirm the plan, then Start Exploitation.

What actually runs run / whitebox / greybox: the wizard's config is turned into a scripted interactive REPL session (/target or /repo, /model, /sub, /mcp, /votes, /chain, /recon, /focus, /objective, /scope-out, /creds, /only <agents>, /run) — the same session described in §6 — instead of a one-shot CLI invocation, because that's the only harness path that keeps reading stdin while the engagement streams. That's why the live-run view's Activity log tab grows a ❭ prompt box: type /status, /stop, /continue, or a plain-language instruction and it goes straight into the running session. host / aitest / skills engagements stay one-shot (their onboarding scope picker is an interactive arrow-key menu that silently skips itself over piped stdin).

Live run view — phase/progress over SSE and a findings table, updated as the run streams. A page refresh reattaches to the same live stream instead of resetting to the wizard.

Tabs (mounted in both the live view and the finished-run detail view):

• Findings — the table; click a row for the full finding detail (see the modal below).
• Attack graph — the run's graph memory rendered as a graph: host → service → finding → credential → impact. Every edge is marked confirmed / needs-validation / hypothesis, and findings are laid out in kill-chain stage order (recon → … → impact). Click a finding node to open it. This replaces the old flat "attack path" view.
• Chains — the attack chains as text, each with its status, severity, steps, and the engine's next moves.
• Dependencies — the step-by-step dependency todolist for each open chain (done / ready / blocked), the same list the chaining rounds dispatch from.
• Traffic — the recorded HTTP flows from flows.jsonl (present when the recording interceptor ran), searchable by host / method / URL.
• Traces — the shared agent traces. Search spans every agent at once; click one agent to open a transcript viewer that splits its run into navigable, collapsible blocks at each tool-call / HTTP-request boundary.
• Deliverables — the extra artifacts written beside the report (detection content, exploit-as- test, custody, personas).

Finding modal — "Wire evidence": each finding opens to show the real request/response pairs the harness measured, not the model's prose — baseline vs. attack, the identity pair (owner vs. other identity), authorization-matrix probes, and the non-destructive oracle. Each exchange is tagged with its wire provenance (wire:replay = the harness re-sent it, wire:recorded = the interceptor saw it, wire:harness = the harness made the original request, or agent-reported). Above the exchanges sits the wire-check summary (how many reproduced / corroborated / contradicted) and any recorded flows on the same endpoint.

Re-test one finding: the ⟳ Re-test this finding button in the modal re-runs just that finding's recorded proof through the scope-guarded replay engine and appends a dated entry to its history — reproduced / changed / gone / unverifiable — so you can watch a finding drift to "gone" over time. Nothing is written back to findings.json; it is a read-only check.

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

---

8c. 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 (black-box, grey-box, host/infra, container, mobile, AI). At each checkpoint the graph:

• directs agent selection — e.g. an SSRF lead pulls in ssrf_cloud, identities/authz pull in authorization_matrix, a yielded secret pulls in session_lifecycle, PostgreSQL + SQLi pulls in postgres_superuser_rce, a datastore technology pulls in exposed_datastore; and
• feeds every exploit and chaining prompt a live context: the surface, the top chains with their status, the next moves, and the dependency todolist.

It spans web and the internal network / AD in one typed schema (hosts, services, endpoints, findings, credentials, identities, impact), so a web foothold and an internal pivot continue the same path.

It works without Neo4j

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

file	what
graph/attack-chains.md	chains in the analyst format, plus next moves
graph/chains.json · graph/todo.json	chains and the dependency todolist as JSON
graph/todo.md	the dependency todolist, readable
graph/graph.cypher	idempotent MERGE script (cypher-shell -f graph.cypher)
graph/graph.json	nodes/edges as JSON
graph/queries.cypher	ready-made analyst queries

While a run is in progress it also writes graph/live-chains.md and graph/live.json so you can watch the graph evolve (the web console's Attack graph tab reads these).

Enabling Neo4j (optional)

Point the run at a Neo4j and the graph is MERGEd in at the end, and accumulated paths from earlier runs are read back:

# one-time: a local Neo4j in Docker
docker run -d --name neo4j -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/please-change-me neo4j:5

# 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

--neo4j <uri> (or NEO4J_URI) accepts bolt://, neo4j://, neo4j+s:// (mapped to the HTTP transactional endpoint on 7474/7473) and http(s):// (used as-is). Only NEO4J_USER (or NEO4J_USERNAME), NEO4J_PASSWORD and NEO4J_DATABASE are read for credentials.

After a run

# offline: recompute chains / todolist / next moves from the saved graph
neurosploit graph <run-id|dir> [--top 10]

# with --push (or NEO4J_URI set): MERGE into Neo4j and reason over accumulated paths
neurosploit graph <run-id> --push

# merge an internal-network / AD graph in too (see §17)
neurosploit internal --graph ad.json --from <node> --save runs/<id>/internal-graph.json
neurosploit graph <run-id> --internal runs/<id>/internal-graph.json

Data minimisation. No raw secret, token, cookie, password, response body or model narrative ever becomes a graph property. Secrets are stored as salted fingerprints (salt from NEUROSPLOIT_GRAPH_SALT, or ~/.neurosploit/graph-salt; share one value across a team that shares a Neo4j so credential reuse still correlates). Cross-run memory is scoped to the target — another engagement's history never enters this one.

---

8d. 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; an identity only when its credentials were recorded) and checked against recorded traffic when the recording interceptor ran. 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 disagreement is recorded and the finding cannot stand as confirmed. What cannot be checked (a mutating verb, out of scope, missing credentials, a network error) stays as reported and is counted as unverifiable. The web console surfaces all of this in the finding's Wire-evidence section (§8b).

Report redaction. Credentials the agents observed become $SECRET_n placeholders in every human-facing report — report.md, report.html, report.json, report.sarif, report.typ / report.pdf, and findings.md. The same secret gets the same placeholder throughout, so an attack chain stays readable ("logged in as admin with $SECRET_1, which also unlocked $SECRET_1 on the API"). The raw values are kept only in findings.json and the run's vault.json, so the per-finding Re-test and any re-run still have the real material.

---

9. 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. It's a small YAML subset — flat key: value plus one-level nested blocks (2-space indent), # comments, values optionally quoted.

9.1 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) to capture a session ---
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

• jwt/header/cookie are used as-is.
• A login: block is executed (real HTTP) to capture a live session cookie/token; if it fails, agents are told to authenticate themselves.

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

Define two or more named roles. With ≥2 roles the harness authenticates as each and tests cross-role access (a low-priv role reaching another user's object or an admin-only function = finding), proving each with the authorized-vs-unauthorized request pair. The name is free-form (admin, user, victim, low, …); give each role one credential type:

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

Per role you may use: jwt · header (raw) · cookie · apikey · or login + username + password. The first role also becomes the default session for normal (non-access-control) tests.

9.3 Linux host (SSH) & Windows/AD

ssh:
  host: 10.0.0.5
  port: 22
  user: ubuntu
  password: s3cret                 # or:
  key: /home/op/id_ed25519

windows:
  host: 10.0.0.10
  domain: CORP
  user: jdoe
  password: Winter2026!            # or pass-the-hash:
  hash: aad3b435b51404eeaad3b435b51404ee:NThashhere

ssh: / windows: tell host-mode agents how to authenticate (Linux enum / privesc, Windows/AD via crackmapexec/impacket/evil-winrm/bloodhound).

9.4 Cloud (AWS / GCP / Azure)

Exports the right env vars so the aws / gcloud / az CLIs authenticate automatically (read-only-first, non-destructive):

aws:
  access_key_id: AKIA...
  secret_access_key: ...
  # session_token: ...             # for temporary creds
  region: us-east-1
  # profile: my-sso-profile        # alternative to keys

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

azure:                             # service principal (best for automation)
  tenant_id: ...
  client_id: ...
  client_secret: ...
  subscription_id: ...

9.5 Using it

neurosploit run https://app.example --creds creds.yaml \
  --subscription --model anthropic:claude-opus-4-8 -v
# host mode uses ssh:/windows:/cloud: — neurosploit host <ip> --creds creds.yaml

Or /creds creds.yaml in the REPL. Secrets stay in your file — nothing is written elsewhere (inline GCP JSON is copied to a temp file only for the SDK).

---

10. Steering the tests

Tell the harness what to prioritise — it biases both agent selection and execution:

--focus "find injection and broken access control"

In the REPL just type the instruction (no slash) or use /focus. Attach scope or a stack trace with @file, @folder, or @file:10-40.

---

11. Outputs, reports & artifacts

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

File	Contents
status.json	running → complete/stopped with a summary
recon.json / recon.md	mapped attack surface
exploitation.md	raw per-agent transcript (the receipts)
findings.json / findings.md	validated findings (reuse by other tools/AIs)
report.html	HTML report + Mermaid attack-graph / kill-chain
report.typ / report.pdf	Typst source + compiled PDF (if typst installed)

The CLI prints a severity summary, an ASCII kill-chain, and the token/cost total.

---

12. Per-project memory & resume

When you launch the REPL in a project directory, NeuroSploit creates <cwd>/.neurosploit/:

.neurosploit/
  session.json     # your config (models, target, repo, auth, focus)
  runs.json        # run history (for /runs, /results, /report, /diff, /retest)
  active_run.json  # live checkpoint of an in-flight run (auto-recovered if interrupted)
  history.txt      # command history (↑/↓)

Close and reopen in the same folder → it resumes automatically (↻ resumed project session). If a run was interrupted mid-flight, its checkpointed findings are recovered into /runs (↻ recovered interrupted run). No database needed — it's structured state.

---

13. 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 (real HTTP/OOB/error output), symbolic for white-box SAST & skills audits (a file:line reference into the reviewed source — the code citation is the receipt, no live target needed), and either for grey-box. Ungrounded claims are demoted and flagged.
• 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.

---

14. The agent library

agents_md/ holds 430 markdown agents in categories:

Category	Dir	Count	Purpose
Vulnerability specialists	vulns/	241	exploit a specific class · incl. account registration & form analysis
Recon	recon/	12	information gathering
Code (SAST)	code/	78	white-box source review
Infra	infra/	34	Linux / Windows / AD host testing
Chains	chains/	12	multi-stage exploitation chains
AI / LLM	ai/	30	LLM red-teaming — OWASP LLM Top 10, MCP, Skills/n8n, jailbreak & prompt-injection techniques
Meta	meta/	23	orchestrator, validator, scorers, reporter, RL

Each agent is a self-contained playbook (## 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.

---

15. Playwright MCP & extra tools

--mcp (subscription path) drives a real Playwright browser for JS-heavy pages and to prove client-side issues (XSS firing, DOM, screenshots). It's auto-provisioned via npx when available; backends that don't support MCP fall back to curl. You can add more MCP servers by placing a mcp.servers.json ({ "mcpServers": { ... } }) in the project root — they're merged into the run.

---

16. Tips, tuning & troubleshooting

• No findings on a live target? It may be unreachable from your network, 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; if you hit your 5-hour quota, 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.

---

17. Assurance & authorization

v4.1.0 adds a layer of controls that make a run defensible, not just productive. All are enforced in code (not prompt text) and every decision lands 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:

# mint a grant for one host, then run against a different one → refused
neurosploit capability issue --scope app.example.com --issuer you --subject op --hours 8
neurosploit run https://other.example.com --capability-token <tok>
#   ⛔ DENY_TARGET_OUTSIDE_GRANT — other.example.com is outside the authorized scope
#   (non-zero exit; nothing was tested; the denial is audited)

Loopback (localhost/127.0.0.1) is exempt — it is unambiguous.

Hard scope from a file

neurosploit run https://app.example.com --scope-file scope.yaml

# scope.yaml — enforced in code; a capability token still caps it
hard:    [ app.example.com, "*.staging.example.com", 10.20.30.0/24 ]
exclude: [ payments.example.com ]
soft:
  observe_only: [ cdn.example.com ]
  allow_destructive_methods: false
  max_requests_per_minute: 240
  forbidden_payloads: [ "drop table", "rm -rf /" ]
  notes: [ "SOW-2026-0142; window 02:00-06:00 UTC" ]

Alt-IP encodings (0x7f000001, 2130706433, 0177.0.0.1, ::ffff:127.0.0.1) all normalize to dotted-quad, so an exclude can't be dodged by re-spelling; redirects to a private/loopback address are refused; 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 in the report.

Audit anchoring & the assurance bundle

neurosploit audit <run> --anchor        # chain + signed anchors: catch truncation/rebuild/forgery
neurosploit assurance <run>             # P1–P5 in one manifest (authorization/enforcement/evidence/integrity/provenance)
neurosploit assurance <run> --verify    # re-hash every artifact + check the signature

Set NEUROSPLOIT_ANCHOR_DIR to also write anchors to external append-only (ideally WORM) storage, and NEUROSPLOIT_PROVENANCE_KEY to sign them.

Tooling: sandbox · proxy · PoC re-validation · compliance

--sandbox                              # run agent commands in a Kali container (docker/podman)
--intercept burp|caido|zap|mitmproxy   # route through a tool …
--intercept own | own+burp             # … or the harness's own recording interceptor
--revalidate-poc                       # re-run each PoC; demote what no longer reproduces
--compliance pci-dss,hipaa,soc2,gdpr   # map findings onto control requirements in the report

TypeSafe System One (calibrated confirmation)

export TYPESAFE_API_KEY=...            # then:
neurosploit run https://app --typesafe on     # calibrated adjudication + confirmation loop
neurosploit run https://app --typesafe off    # the identical pipeline, no TypeSafe (for A/B)

--typesafe auto (default) turns it on when the key is set. Choose the engine with --decision-backend typesafe (hosted) or --decision-backend laya (local, free, downloads the model on first use — evidence never leaves the box; see tools/laya_shim.py). It adjudicates each finding with a calibrated {confirmed/needs-review/rejected} judgment over the evidence, re-grades CVSS when impact isn't demonstrated, prunes irrelevant agents, and runs a code-owned confirmation loop over enumerable classes. It is additive — a deterministic validator still rules; TypeSafe can only lower confidence or flag for review, never resurrect a rejected claim. Run it with --typesafe on and --typesafe off against the same target to measure the difference (meta.json records which mode ran).

Internal network / AD & reasoning budget

neurosploit internal --graph g.json --scaffold corp.local --from foothold --mermaid
neurosploit run https://app --budget eco|balanced|aggressive   # ration reasoning; default unlimited

The internal graph models an engagement as Asset → Exposure → Weakness → Credential → Privilege → Movement → Crown Jewel and answers the question a CVSS-sorted list can't: which single edge, removed, cuts the most paths to the crown jewels (choke_points).

---

18. 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 a run 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

Common flags (run / greybox / host / tui):

--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)
--authz-matrix <file>    role × route authorization matrix to validate against
--offline                pipeline self-test, no model calls
-v, --verbose            log each agent, recon, votes

--neo4j and --authz-matrix are global flags (valid on any mode). Neo4j credentials are read only from NEO4J_USER / NEO4J_PASSWORD / NEO4J_DATABASE — never passed on the command line. See §8c.

---

NeuroSploit — by Joas A Santos & Red Team Leaders. MIT licensed. Authorized testing only.