Skip to content

Latest commit

 

History

History
executable file
·
289 lines (199 loc) · 6.06 KB

QUICKSTART.md

File metadata and controls

executable file
·
289 lines (199 loc) · 6.06 KB

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

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:

# 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 below.

Step 2: Install Dependencies

Backend

pip install -r backend/requirements.txt

Frontend

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.

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

uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

Terminal 2 -- Frontend:

cd frontend
npm run dev

Open: http://localhost:5173

Option B: Production Mode

# 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

./start.sh

Step 5: Verify Setup

Check API Health

curl http://localhost:8000/api/health

Expected response:

{
  "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

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)

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

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

curl http://localhost:8000/api/health | python3 -m json.tool

"Kali sandbox image not found"

Build the Docker image:

./scripts/build-kali.sh

"Docker daemon not running"

Start Docker Desktop, then retry.

"Port 8000 already in use"

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