v3.5.1: robust README + detailed TUTORIAL.md + cross-platform install (Linux/macOS/Windows · x64/arm64)

- README rewritten: engagement-modes table, highlights, supported-platforms matrix, agents 329, links to the tutorial. - TUTORIAL.md: full user guide — concepts, install, auth (API/subscription), models, all modes (black/white/grey/host), REPL, TUI, creds.yaml, steering, outputs/reports, per-project memory, POMDP/grounding/chaining, agent library, MCP, troubleshooting, command/flag reference. - setup.sh: detect OS (Linux/macOS/Windows) + arch (x64/arm64); v3.5.1 banner. - install.ps1: native Windows PowerShell one-liner (winget/rustup, build, PATH). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-29 23:05:30 +02:00 · 2026-06-24 22:39:10 -03:00
parent 3f78a2b686
commit 16e45eb0a3
4 changed files with 606 additions and 40 deletions
@@ -11,8 +11,9 @@
  <img src="https://img.shields.io/badge/Version-3.5.1-blue?style=flat-square">
  <img src="https://img.shields.io/badge/Harness-Rust%20%7C%20tokio-e6b673?style=flat-square">
  <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square">
-  <img src="https://img.shields.io/badge/MD%20Agents-303-red?style=flat-square">
+  <img src="https://img.shields.io/badge/MD%20Agents-329-red?style=flat-square">
  <img src="https://img.shields.io/badge/Models-12%20providers-success?style=flat-square">
+  <img src="https://img.shields.io/badge/Modes-Black%20%7C%20White%20%7C%20Grey%20%7C%20Host-9cf?style=flat-square">
  <img src="https://img.shields.io/badge/Auth-API%20key%20%7C%20Subscription-orange?style=flat-square">
 </p>

@@ -20,59 +21,84 @@
 <i>by Joas A Santos &amp; Red Team Leaders</i></p>

 > ⭐ If this is useful, **star the repo** — it helps a lot.
+>
+> 📖 **New here? Read the [full Tutorial & User Guide →](TUTORIAL.md)** — every mode, flag, config and example explained.

 ---

-## 🆕 v3.5.1 — POMDP belief & grounded anti-hallucination
+**NeuroSploit** turns a URL, a source repository, a running app, or a host/IP into
+an autonomous security engagement. A Rust harness (`tokio`) drives a **pool of
+LLMs** — via **API key** or local **subscription** (Claude Code / Codex / Gemini /
+Grok) — recons the target, **intelligently selects only the agents that match the
+discovered surface**, runs them in parallel, **chains** findings into deeper
+impact, and **validates every claim by cross-model voting + tool-receipt
+grounding** before reporting. It ships **329 markdown agents** and a **Mission
+Control TUI**.

-The target is only **partially observable**, so v3.5.1 stops treating findings as
-booleans and tracks a **belief**:
+### Engagement modes

- **Belief world model** (`belief.rs`) — a property graph whose nodes
-  (host / service / vuln / exploit / credential) each carry a *probability*, not a
-  boolean. Observations update them with a Bayesian step; per-node **Shannon
-  entropy** measures how diffuse the belief still is.
- **Value-of-information planner** (`pomdp.rs`) — "scan more vs exploit now" is
-  not a heuristic: when a node's belief is diffuse, the expected value of an
-  observation (recon) exceeds the risk-adjusted value of an exploit. The
-  `may_assert` gate is the **mathematical anti-hallucination rule** — the agent
-  may not claim exploitability while the belief is diffuse; it must observe first.
- **Grounding / verification engine** (`grounding.rs`) — a hard rule: **no claim
-  enters the world model without a tool receipt** (raw tool output, not the LLM's
-  paraphrase). Black-box grounding is *empirical* (a real HTTP response / OOB
-  callback / error oracle); white-box is *symbolic* (a `file:line` into the
-  reviewed source). Ungrounded claims are demoted and flagged `receipt_missing`.
- **Regimes** — black-box runs a true POMDP (diffuse priors that sharpen with
-  observation); white-box collapses toward a near-deterministic MDP (the world
-  model is built from SAST/dataflow, so uncertainty migrates to *path
-  reachability*, not state).
+| Mode | Command | What it does |
+|------|---------|-------------|
+| **Black-box** | `neurosploit run <url>` | recon → select → exploit → vote → report |
+| **White-box** | `neurosploit whitebox <repo>` | source/SAST review (file:line evidence) |
+| **Grey-box** | `neurosploit greybox <repo> --url <app>` | code review **+** live exploitation together |
+| **Host/Infra** | `neurosploit host <ip> --creds creds.yaml` | Linux / Windows / Active Directory testing |
+| **Mission Control** | `neurosploit tui <url>` | live TUI panels + composer during the run |
+| **Interactive** | `neurosploit` | persistent REPL session (resumes per project) |

-> Roadmap (in progress on this branch): infra targets (IP + SSH/Windows/AD) with
-> Linux/Windows/AD host agents, a contextual-bandit tool router, and
-> value-of-information reward shaping.
+### Highlights

---
+- 🧠 **POMDP belief + value-of-information** — the target is partially observable,
+  so findings aren't booleans: a property-graph **belief** carries probabilities,
+  and "scan more vs exploit now" falls out of belief entropy. The `may_assert`
+  gate is a **mathematical anti-hallucination rule** (don't claim exploitability
+  while the belief is diffuse).
+- 🧾 **Grounding** — hard rule: **no claim without a tool receipt** (raw tool
+  output, not paraphrase). Empirical for black-box, symbolic (`file:line`) for
+  white-box; ungrounded claims are demoted.
+- 🔗 **Attack chaining** — 12 multi-stage chain agents (SQLi→RCE→LPE, SSRF→AWS
+  creds, upload→LFI→RCE→LPE, default-creds→domain, …); each stage proven before
+  advancing.
+- 🗺️ **Attack graph & kill chain** — findings mapped to OWASP / CWE / MITRE
+  ATT&CK / stage; rendered as a Mermaid graph in the report.
+- ✅ **Cross-model validation** — a different model adjudicates each finding;
+  RL-weighted, recon-aware agent selection.
+- 🛰️ **Mission Control TUI** — live header/feed/findings/targets panels + a
+  composer you can type in *while the run streams* (`summary`, `pause`, …).
+- 💾 **Per-project memory** — `<cwd>/.neurosploit/` keeps session, run history and
+  command history; the REPL **resumes** on reopen. No database required.
+- 🪙 **Token/cost telemetry**, per-agent attribution, graceful Ctrl-C → report or
+  discard, Typst/HTML/JSON/MD reports.

-**Autonomous, multi-model penetration-testing harness — Rust, CLI-only.**
-
-This branch is the **slim, Rust-only** distribution: the `neurosploit-rs/` workspace
-plus the `agents_md/` agent library. It turns a URL (black-box) or a code
-repository (white-box) into an autonomous engagement that drives a pool of LLMs
-— via **API key** or local **subscription** (Claude Code / Codex / Gemini / Grok)
-— recons the target, **intelligently selects only the agents matching the
-discovered surface**, runs them in parallel, then validates every finding by
-**cross-model voting** before reporting.
-
-> The full project (Python engine, web GUIs, history) lives on the `main` branch.
+> This is the **slim, Rust-only** distribution (`neurosploit-rs/` + `agents_md/`).
+> The earlier Python engine and web GUIs live on the older `v3.4.0` branch.

 ---

 ## 📦 Install (one line)

+**Linux / macOS** (x64 & arm64):
 ```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
+```
+
+### Supported platforms
+
+| OS | x64 | arm64 |
+|----|-----|-------|
+| **Linux** (Kali recommended) | ✅ | ✅ |
+| **macOS** | ✅ | ✅ (Apple Silicon) |
+| **Windows** | ✅ | ✅ |
+
+Pure Rust + stdlib, so it builds natively everywhere a stable Rust toolchain runs.
+The installer auto-detects OS/arch and installs Rust if missing. On native Windows
+use `install.ps1`; under WSL2 / Git Bash the `setup.sh` one-liner also works.
+
 The installer auto-installs Rust if needed, clones the repo to `~/.neurosploit`,
 builds the release binary, and links `neurosploit` into `~/.local/bin`. Re-run it
 any time to update. Tweak with env vars: `NEUROSPLOIT_REF` (branch/tag),
@@ -0,0 +1,460 @@
+# NeuroSploit — Tutorial & User Guide (v3.5.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)
+7. [Mission Control TUI](#7-mission-control-tui)
+8. [Credentials (`creds.yaml`)](#8-credentials-credsyaml)
+9. [Steering the tests (focus & instructions)](#9-steering-the-tests)
+10. [Outputs, reports & artifacts](#10-outputs-reports--artifacts)
+11. [Per-project memory & resume](#11-per-project-memory--resume)
+12. [How it decides: POMDP, grounding, chaining](#12-how-it-decides)
+13. [The agent library](#13-the-agent-library)
+14. [Playwright MCP & extra tools](#14-playwright-mcp--extra-tools)
+15. [Tips, tuning & troubleshooting](#15-tips-tuning--troubleshooting)
+16. [Command & flag reference](#16-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 329).
+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 3.5.1
+neurosploit agents             # {"vulns":196,...,"chains":12,"total":329}
+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`:
+
+```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 OPENROUTER_API_KEY=...            # openrouter:*
+# ollama: no key (local)
+
+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`) | 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 4.x, GPT-5.x incl. Codex, Gemini 3/2.5, Grok, NVIDIA NIM, DeepSeek,
+Mistral, Qwen, Groq, Together, 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)
+
+```bash
+git clone https://github.com/digininja/DVWA /tmp/DVWA
+neurosploit whitebox /tmp/DVWA --subscription --model anthropic:claude-opus-4-8 -v
+```
+
+Findings carry `file:line` evidence; grounding is **symbolic** (the location must
+exist in the reviewed source).
+
+### 5.3 Grey-box (code + live app)
+
+Best of both: review the source **and** prove issues against the running app —
+code findings become *leads* for live exploitation.
+
+```bash
+neurosploit greybox /tmp/DVWA --url http://localhost:8080/ \
+  --creds creds.yaml --focus "auth and IDOR" --subscription --model anthropic:claude-opus-4-8 -v
+```
+
+### 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.
+
+---
+
+## 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)
+@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
+/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.
+
+---
+
+## 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. Credentials (`creds.yaml`)
+
+One file covers web auth, SSH and Windows/AD. See `neurosploit-rs/creds.example.yaml`.
+
+```yaml
+# --- web auth (pick one) ---
+jwt: eyJhbGciOi...                 # → Authorization: Bearer <jwt>
+# header: "X-Api-Key: abc123"
+# cookie: "session=deadbeef"
+
+# --- OR an automated login the harness performs to capture a live 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
+
+# --- Linux host (SSH) ---
+ssh:
+  host: 10.0.0.5
+  port: 22
+  user: ubuntu
+  password: s3cret                 # or:
+  key: /home/op/id_ed25519
+
+# --- Windows / Active Directory ---
+windows:
+  host: 10.0.0.10
+  domain: CORP
+  user: jdoe
+  password: Winter2026!            # or pass-the-hash:
+  hash: aad3b435b51404eeaad3b435b51404ee:NThashhere
+```
+
+- `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.
+- `ssh:` / `windows:` tell host agents how to authenticate.
+
+Use with `--creds creds.yaml` on `run` / `greybox` / `host`, or `/creds` in the REPL.
+
+---
+
+## 9. 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`.
+
+---
+
+## 10. 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.
+
+---
+
+## 11. 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)
+  history.txt    # command history (↑/↓)
+```
+
+Close and reopen in the same folder → it **resumes** automatically
+(`↻ resumed project session`). No database needed — it's structured state.
+
+---
+
+## 12. 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 tool receipt**: empirical for black-box
+  (real HTTP/OOB/error output), symbolic (`file:line`) for white-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.
+
+---
+
+## 13. The agent library
+
+`agents_md/` holds **329** markdown agents in categories:
+
+| Category | Dir | Count | Purpose |
+|----------|-----|-------|---------|
+| Vulnerability specialists | `vulns/` | 196 | exploit a specific class |
+| Recon | `recon/` | 12 | information gathering |
+| Code (SAST) | `code/` | 78 | white-box source review |
+| Infra | `infra/` | 14 | Linux / Windows / AD host testing |
+| Chains | `chains/` | 12 | multi-stage exploitation chains |
+| Meta | `meta/` | 17 | 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.
+
+---
+
+## 14. 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.
+
+---
+
+## 15. 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.
+
+---
+
+## 16. 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.*
@@ -0,0 +1,61 @@
+# NeuroSploit installer for Windows (PowerShell) — by Joas A Santos & Red Team Leaders
+#
+#   irm https://raw.githubusercontent.com/JoasASantos/NeuroSploit/main/install.ps1 | iex
+#
+# Installs the Rust toolchain if needed, clones the repo, builds the release
+# binary, and adds it to your PATH. Works on x64 and arm64.
+$ErrorActionPreference = "Stop"
+
+function Say($m) { Write-Host "  > $m" -ForegroundColor Magenta }
+function Ok ($m) { Write-Host "  + $m" -ForegroundColor Green }
+function Warn($m){ Write-Host "  ! $m" -ForegroundColor Yellow }
+
+Write-Host ""
+Write-Host "  NeuroSploit installer (Windows) — v3.5.1" -ForegroundColor Cyan
+$arch = $env:PROCESSOR_ARCHITECTURE
+Say "Platform: Windows / $arch"
+
+$dir    = if ($env:NEUROSPLOIT_DIR) { $env:NEUROSPLOIT_DIR } else { Join-Path $HOME ".neurosploit-src" }
+$ref    = if ($env:NEUROSPLOIT_REF) { $env:NEUROSPLOIT_REF } else { "main" }
+
+# 1) git
+if (-not (Get-Command git -ErrorAction SilentlyContinue)) { throw "git is required (install Git for Windows) and re-run." }
+
+# 2) Rust (rustup) — winget if available, else the rustup-init bootstrap
+if (-not (Get-Command cargo -ErrorAction SilentlyContinue)) {
+  Say "Rust not found — installing rustup..."
+  if (Get-Command winget -ErrorAction SilentlyContinue) {
+    winget install -e --id Rustlang.Rustup --accept-source-agreements --accept-package-agreements
+  } else {
+    $ri = Join-Path $env:TEMP "rustup-init.exe"
+    Invoke-WebRequest "https://win.rustup.rs/$arch" -OutFile $ri
+    & $ri -y --default-toolchain stable --profile minimal
+  }
+  $env:Path = "$HOME\.cargo\bin;$env:Path"
+}
+Ok ("Rust: " + (cargo --version))
+
+# 3) clone or update
+if (Test-Path (Join-Path $dir ".git")) {
+  Say "Updating $dir..."; git -C $dir fetch --depth 1 origin $ref; git -C $dir reset --hard "origin/$ref"
+} else {
+  Say "Cloning to $dir..."; git clone --depth 1 --branch $ref "https://github.com/JoasASantos/NeuroSploit.git" $dir
+}
+
+# 4) build
+Say "Building release binary (first build downloads crates)..."
+Push-Location (Join-Path $dir "neurosploit-rs"); cargo build --release; Pop-Location
+$bin = Join-Path $dir "neurosploit-rs\target\release\neurosploit.exe"
+if (-not (Test-Path $bin)) { throw "build did not produce $bin" }
+Ok ("Built: " + (& $bin --version))
+
+# 5) add to PATH (user)
+$binDir = Split-Path $bin
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+if ($userPath -notlike "*$binDir*") {
+  [Environment]::SetEnvironmentVariable("Path", "$userPath;$binDir", "User")
+  Ok "Added $binDir to your PATH (open a new terminal)."
+}
+Write-Host ""
+Ok "Done. Launch:  neurosploit"
+Write-Host "      neurosploit run http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 -v"
@@ -25,14 +25,33 @@ cat <<'BANNER'

   ███╗   ██╗███████╗██╗   ██╗██████╗  ██████╗
   ████╗  ██║██╔════╝██║   ██║██╔══██╗██╔═══██╗   NeuroSploit installer
-   ██╔██╗ ██║█████╗  ██║   ██║██████╔╝██║   ██║   v3.5.0 — Rust harness
+   ██╔██╗ ██║█████╗  ██║   ██║██████╔╝██║   ██║   v3.5.1 — Rust harness
   ██║╚██╗██║██╔══╝  ██║   ██║██╔══██╗██║   ██║   by Joas A Santos
   ██║ ╚████║███████╗╚██████╔╝██║  ██║╚██████╔╝   & Red Team Leaders
   ╚═╝  ╚═══╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝ ╚═════╝
 BANNER

-OS="$(uname -s)"
-say "Detected OS: $OS"
+# ---- platform detection (Linux / macOS / Windows-via-WSL/MSYS · x64 / arm64) ----
+OS_RAW="$(uname -s)"
+ARCH_RAW="$(uname -m)"
+case "$OS_RAW" in
+  Linux*)             OS="Linux" ;;
+  Darwin*)            OS="macOS" ;;
+  MINGW*|MSYS*|CYGWIN*) OS="Windows" ;;
+  *)                  OS="$OS_RAW" ;;
+esac
+case "$ARCH_RAW" in
+  x86_64|amd64)   ARCH="x64" ;;
+  arm64|aarch64)  ARCH="arm64" ;;
+  *)              ARCH="$ARCH_RAW" ;;
+esac
+say "Platform: $OS / $ARCH"
+if [ "$OS" = "Windows" ]; then
+  warn "On native Windows, run this in WSL2, Git Bash or MSYS2. (Or build with: cargo build --release)"
+fi
+if [ "$OS" != "Linux" ] && [ "$OS" != "macOS" ] && [ "$OS" != "Windows" ]; then
+  warn "Unrecognized OS '$OS_RAW' — attempting a generic Rust build anyway."
+fi

 # 1) git
 command -v git >/dev/null 2>&1 || die "git is required. Install git and re-run."