NeuroSploit/TUTORIAL.md

NeuroSploit — Tutorial & User Guide (v4.1.0)

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
7. Mission Control TUI
8. Web console
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.1.0
neurosploit agents             # {"vulns":241,...,"ai":30,...,"total":430}
neurosploit models             # all providers & models

---

3. Authentication: API key vs subscription

You pick per run. They're 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-*
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)
@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
/tempmail on|off    opt-in disposable inbox (mail.tm) for a register confirmation code
/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

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

---

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

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   # once
node web/server.js                            # → http://localhost:4173

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 435-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, 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) — click any node or row for the full finding detail, including any PoC script written to pocs/. A page refresh reattaches to the same live stream instead of resetting to the wizard.

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

---

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        # 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 tui <url>             # Mission Control TUI (--repo for greybox)
neurosploit agents                # library counts
neurosploit models                # providers & models
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)
--offline                pipeline self-test, no model calls
-v, --verbose            log each agent, recon, votes

---

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