NeuroSploit v3.2 - Autonomous AI Penetration Testing Platform

116 modules | 100 vuln types | 18 API routes | 18 frontend pages Major features: - VulnEngine: 100 vuln types, 526+ payloads, 12 testers, anti-hallucination prompts - Autonomous Agent: 3-stream auto pentest, multi-session (5 concurrent), pause/resume/stop - CLI Agent: Claude Code / Gemini CLI / Codex CLI inside Kali containers - Validation Pipeline: negative controls, proof of execution, confidence scoring, judge - AI Reasoning: ReACT engine, token budget, endpoint classifier, CVE hunter, deep recon - Multi-Agent: 5 specialists + orchestrator + researcher AI + vuln type agents - RAG System: BM25/TF-IDF/ChromaDB vectorstore, few-shot, reasoning templates - Smart Router: 20 providers (8 CLI OAuth + 12 API), tier failover, token refresh - Kali Sandbox: container-per-scan, 56 tools, VPN support, on-demand install - Full IA Testing: methodology-driven comprehensive pentest sessions - Notifications: Discord, Telegram, WhatsApp/Twilio multi-channel alerts - Frontend: React/TypeScript with 18 pages, real-time WebSocket updates
2026-07-01 01:05:31 +02:00 · 2026-02-22 17:58:12 -03:00
commit e0935793c5
271 changed files with 132462 additions and 0 deletions
@@ -0,0 +1,289 @@
+# NeuroSploit v3 - Quick Start Guide
+
+Get NeuroSploit running in under 5 minutes.
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum | Recommended |
+|-------------|---------|-------------|
+| **Python** | 3.10+ | 3.12 |
+| **Node.js** | 18+ | 20 LTS |
+| **Docker** | 24+ | Latest (for Kali sandbox) |
+| **RAM** | 4 GB | 8 GB+ |
+| **Disk** | 2 GB | 5 GB (with Kali image) |
+| **LLM API Key** | 1 provider | Claude recommended |
+
+---
+
+## Step 1: Clone & Configure
+
+```bash
+git clone https://github.com/your-org/NeuroSploitv2.git
+cd NeuroSploitv2
+
+# Create your environment file
+cp .env.example .env
+```
+
+Edit `.env` and add at least one API key:
+
+```bash
+# Pick one (or more):
+ANTHROPIC_API_KEY=sk-ant-...        # Claude (recommended)
+OPENAI_API_KEY=sk-...               # GPT-4
+GEMINI_API_KEY=AI...                 # Gemini Pro
+OPENROUTER_API_KEY=sk-or-...        # OpenRouter (any model)
+```
+
+> **No API key?** Use a local LLM (Ollama or LM Studio) -- see [Local LLM Setup](#local-llm-setup) below.
+
+---
+
+## Step 2: Install Dependencies
+
+### Backend
+
+```bash
+pip install -r backend/requirements.txt
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+cd ..
+```
+
+---
+
+## Step 3: Build Kali Sandbox Image (Optional but Recommended)
+
+The Kali sandbox enables isolated tool execution (Nuclei, Nmap, SQLMap, etc.) in Docker containers.
+
+```bash
+# Requires Docker Desktop running
+./scripts/build-kali.sh --test
+```
+
+This builds a Kali Linux image with 28 pre-installed security tools. Takes ~5 min on first build.
+
+> **No Docker?** NeuroSploit works without it -- the agent uses HTTP-only testing. Docker adds tool-based scanning (Nuclei, Nmap, etc.).
+
+---
+
+## Step 4: Start NeuroSploit
+
+### Option A: Development Mode (hot reload)
+
+Terminal 1 -- Backend:
+```bash
+uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Terminal 2 -- Frontend:
+```bash
+cd frontend
+npm run dev
+```
+
+Open: **http://localhost:5173**
+
+### Option B: Production Mode
+
+```bash
+# Build frontend
+cd frontend && npm run build && cd ..
+
+# Start backend (serves frontend too)
+uvicorn backend.main:app --host 0.0.0.0 --port 8000
+```
+
+Open: **http://localhost:8000**
+
+### Option C: Quick Start Script
+
+```bash
+./start.sh
+```
+
+---
+
+## Step 5: Verify Setup
+
+### Check API Health
+
+```bash
+curl http://localhost:8000/api/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "app": "NeuroSploit",
+  "version": "3.0.0",
+  "llm": {
+    "status": "configured",
+    "provider": "claude",
+    "message": "AI agent ready"
+  }
+}
+```
+
+### Check Swagger Docs
+
+Open **http://localhost:8000/api/docs** for interactive API documentation.
+
+---
+
+## Your First Scan
+
+### Option 1: Auto Pentest (Recommended)
+
+1. Open the web interface
+2. Click **Auto Pentest** in the sidebar
+3. Enter a target URL (e.g., `http://testphp.vulnweb.com`)
+4. Click **Start Auto Pentest**
+5. Watch the 3-stream parallel scan in real-time
+
+### Option 2: Via API
+
+```bash
+curl -X POST http://localhost:8000/api/v1/agent/run \
+  -H "Content-Type: application/json" \
+  -d '{
+    "target": "http://testphp.vulnweb.com",
+    "mode": "auto_pentest"
+  }'
+```
+
+### Option 3: Vuln Lab (Single Type)
+
+1. Click **Vuln Lab** in the sidebar
+2. Pick a vulnerability type (e.g., `xss_reflected`)
+3. Enter target URL
+4. Click **Run Test**
+
+---
+
+## Pages Overview
+
+| Page | What it does |
+|------|-------------|
+| **Dashboard** (`/`) | Stats, severity charts, recent activity |
+| **Auto Pentest** (`/auto`) | One-click full autonomous pentest |
+| **Vuln Lab** (`/vuln-lab`) | Test specific vuln types (100 available) |
+| **Terminal Agent** (`/terminal`) | AI chat + command execution |
+| **Sandboxes** (`/sandboxes`) | Monitor Kali containers in real-time |
+| **Scheduler** (`/scheduler`) | Schedule recurring scans |
+| **Reports** (`/reports`) | View/download generated reports |
+| **Settings** (`/settings`) | Configure LLM providers, features |
+
+---
+
+## Local LLM Setup
+
+### Ollama (Easiest)
+
+```bash
+# Install Ollama
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Pull a model
+ollama pull llama3.1
+
+# Add to .env
+echo "OLLAMA_BASE_URL=http://localhost:11434" >> .env
+```
+
+### LM Studio
+
+1. Download from [lmstudio.ai](https://lmstudio.ai)
+2. Load any model (e.g., Mistral, Llama)
+3. Start the server on port 1234
+4. Add to `.env`:
+   ```
+   LMSTUDIO_BASE_URL=http://localhost:1234
+   ```
+
+---
+
+## Kali Sandbox Commands
+
+```bash
+# Build image
+./scripts/build-kali.sh
+
+# Rebuild from scratch
+./scripts/build-kali.sh --fresh
+
+# Build + verify tools work
+./scripts/build-kali.sh --test
+
+# Check running containers (via API)
+curl http://localhost:8000/api/v1/sandbox/
+
+# Monitor via web UI
+# Open http://localhost:8000/sandboxes
+```
+
+### Pre-installed tools (28)
+
+nuclei, naabu, httpx, subfinder, katana, dnsx, uncover, ffuf, gobuster, dalfox, waybackurls, nmap, nikto, sqlmap, masscan, whatweb, curl, wget, git, python3, pip3, go, jq, dig, whois, openssl, netcat, bash
+
+### On-demand tools (28 more)
+
+Installed inside the container automatically when first needed:
+
+wpscan, dirb, hydra, john, hashcat, testssl, sslscan, enum4linux, dnsrecon, amass, medusa, crackmapexec, gau, gitleaks, anew, httprobe, dirsearch, wfuzz, arjun, wafw00f, sslyze, commix, trufflehog, retire, fierce, nbtscan, responder
+
+---
+
+## Troubleshooting
+
+### "AI agent not configured"
+
+Check your `.env` has at least one valid API key:
+```bash
+curl http://localhost:8000/api/health | python3 -m json.tool
+```
+
+### "Kali sandbox image not found"
+
+Build the Docker image:
+```bash
+./scripts/build-kali.sh
+```
+
+### "Docker daemon not running"
+
+Start Docker Desktop, then retry.
+
+### "Port 8000 already in use"
+
+```bash
+lsof -i :8000
+kill <PID>
+```
+
+### Frontend not loading
+
+Dev mode: ensure frontend is running (`npm run dev` in `/frontend`).
+Production: ensure `frontend/dist/` exists (`cd frontend && npm run build`).
+
+---
+
+## What's Next
+
+- Read the full [README.md](README.md) for architecture details
+- Explore the **100 vulnerability types** in Vuln Lab
+- Set up **scheduled scans** for continuous monitoring
+- Try the **Terminal Agent** for interactive AI-guided testing
+- Check the **Sandbox Dashboard** to monitor container health
+
+---
+
+**NeuroSploit v3** - *AI-Powered Autonomous Penetration Testing Platform*