From 79f20b145642f26324730935620d178f4983f2c7 Mon Sep 17 00:00:00 2001 From: CyberSecurityUP Date: Wed, 24 Jun 2026 23:26:57 -0300 Subject: [PATCH] docs: detailed white-box & grey-box instructions (TUTORIAL + README + /help) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - TUTORIAL 5.2 white-box: how source review works (context collection, agent selection, source→sink dataflow, file:line symbolic grounding, validation), examples and tips. - TUTORIAL 5.3 grey-box: code review leads → live exploitation flow, auth via creds.yaml, MCP, REPL repo+target = greybox. - README quick-start gains white-box / grey-box / host one-liners + tutorial link. - REPL /help shows the MODES line (black/white/grey/host) and Ctrl-O hint. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 13 ++++++++ TUTORIAL.md | 58 +++++++++++++++++++++++++++++++--- neurosploit-rs/app/src/repl.rs | 3 +- 3 files changed, 68 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 18675c0..81c8f0a 100755 --- a/README.md +++ b/README.md @@ -120,11 +120,24 @@ neurosploit # or one-liner (subscription login, no API key needed): neurosploit run http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 -v +# white-box — review a source repository (SAST agents, file:line evidence): +git clone https://github.com/digininja/DVWA /tmp/DVWA +neurosploit whitebox /tmp/DVWA --subscription --model anthropic:claude-opus-4-8 -v + +# grey-box — review the code AND exploit the running app together: +neurosploit greybox /tmp/DVWA --url http://localhost:8080/ --creds creds.yaml \ + --subscription --model anthropic:claude-opus-4-8 --mcp -v + +# host / infra — Linux / Windows / Active Directory (SSH/Win creds in creds.yaml): +neurosploit host 10.0.0.10 --creds creds.yaml --subscription --model anthropic:claude-opus-4-8 -v + # 🛰 Mission Control TUI — live panels (header/feed/findings/targets) + a composer # you can type in WHILE the run streams (summary · pause · errors · notes): neurosploit tui http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 --mcp ``` +> Full step-by-step for every mode (black/white/grey/host) is in **[TUTORIAL.md](TUTORIAL.md)**. + No login? Use an **API key** instead — see [Authentication](#authentication--run-via-api-key-or-subscription). --- diff --git a/TUTORIAL.md b/TUTORIAL.md index b4b5246..689e8ce 100644 --- a/TUTORIAL.md +++ b/TUTORIAL.md @@ -188,24 +188,72 @@ neurosploit run http://testphp.vulnweb.com/ \ ### 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 ``` -Findings carry `file:line` evidence; grounding is **symbolic** (the location must -exist in the reviewed source). +**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) -Best of both: review the source **and** prove issues against the running app — -code findings become *leads* for live exploitation. +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 -v + --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 ` and `/target ` → 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`: diff --git a/neurosploit-rs/app/src/repl.rs b/neurosploit-rs/app/src/repl.rs index 15dbce2..edafad7 100644 --- a/neurosploit-rs/app/src/repl.rs +++ b/neurosploit-rs/app/src/repl.rs @@ -948,7 +948,8 @@ fn help() { h("/votes ", "validator votes /agents cap agents"); h("/theme color|mono", "/show (config) /clear /quit"); - println!("\n \x1b[2m↑/↓ history · Tab completes commands & @paths · Ctrl-A/E/K edit · \\ for multiline\x1b[0m\n"); + println!("\n \x1b[2mMODES — black-box: set /target · white-box: set /repo · grey-box: set BOTH /repo + /target · host: /target + /creds\x1b[0m"); + println!(" \x1b[2m↑/↓ history · Tab completes commands & @paths · Ctrl-A/E/K edit · Ctrl-O full cmd · \\ for multiline\x1b[0m\n"); } /// Scan a line for @path tokens, attach each referenced file/dir to context.