# 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](#1-concepts-in-60-seconds)
2. [Install](#2-install)
3. [Authentication: API key vs subscription](#3-authentication-api-key-vs-subscription)
4. [Choosing models](#4-choosing-models)
5. [Engagement modes](#5-engagement-modes)
   - [Black-box (URL)](#51-black-box-url)
   - [White-box (source repo)](#52-white-box-source-repo)
   - [Grey-box (code + live app)](#53-grey-box-code--live-app)
   - [Host / Infra (Linux / Windows / AD)](#54-host--infra-linux--windows--ad)
6. [The interactive REPL](#6-the-interactive-repl)
   - [Scope — three ways](#61-scope--three-ways-from-quick-to-a-full-config)
   - [Get the most out of a run](#62-get-the-most-out-of-a-run-recommended-potent-setup)
7. [Mission Control TUI](#7-mission-control-tui)
8. [NeuroSploit as an MCP server](#8-neurosploit-as-an-mcp-server)
   - [Mobile / binary testing](#8a-mobile--binary-testing)
   - [Web console](#8b-web-console)
   - [Attack graph & Neo4j (graph memory)](#8c-attack-graph--neo4j-graph-memory)
   - [Wire-bound evidence & report redaction](#8d-wire-bound-evidence--report-redaction)
9. [Credentials (`creds.yaml`)](#9-credentials-credsyaml)
10. [Steering the tests (focus & instructions)](#10-steering-the-tests)
11. [Outputs, reports & artifacts](#11-outputs-reports--artifacts)
12. [Per-project memory & resume](#12-per-project-memory--resume)
13. [How it decides: POMDP, grounding, chaining](#13-how-it-decides)
14. [The agent library](#14-the-agent-library)
15. [Playwright MCP & extra tools](#15-playwright-mcp--extra-tools)
16. [Tips, tuning & troubleshooting](#16-tips-tuning--troubleshooting)
17. [Assurance & authorization (v4.1.0)](#17-assurance--authorization)
18. [Command & flag reference](#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):
```bash
curl -fsSL https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/setup.sh | bash
```

**Windows** (PowerShell, x64 & arm64):
```powershell
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

```bash
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:

```bash
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

```bash
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`:

```bash
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 |

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

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

```bash
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.

```bash
# 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).

```bash
# 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`:

```bash
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.

```bash
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:

```bash
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:

```yaml
# 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):

```bash
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**:

```bash
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.

```bash
neurosploit mcp        # speaks MCP over stdio
```

### Install in Claude Code

```bash
claude mcp add neurosploit -- neurosploit mcp
```

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

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

```toml
[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

```bash
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.

```bash
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](#6-the-interactive-repl) — 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`](web/API.md) · quick start: [`web/README.md`](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:

```bash
# 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

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

```yaml
# --- 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:

```yaml
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

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

```yaml
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

```bash
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**:

```bash
--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:

```bash
# 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

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

```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

```bash
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

```bash
--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)

```bash
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

```bash
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](#8c-attack-graph--neo4j-graph-memory).

---

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