AI Summary: NeuroSploit v3 is an AI-powered penetration testing platform designed for autonomous security assessments, offering support for 100 vulnerability types within isolated Kali Linux containers. Key features include an autonomous agent for parallel testing, an exploit chain engine, anti-hallucination controls, real-time monitoring via a modern web interface, and multi-provider LLM integration for adaptive scanning strategies. The tool provides efficient scanning capabilities and detailed reporting, making it suitable for comprehensive security evaluations.

README

NeuroSploit v3

AI-Powered Autonomous Penetration Testing Platform

NeuroSploit v3 is an advanced security assessment platform that combines AI-driven autonomous agents with 100 vulnerability types, per-scan isolated Kali Linux containers, false-positive hardening, exploit chaining, and a modern React web interface with real-time monitoring.

Highlights

• 100 Vulnerability Types across 10 categories with AI-driven testing prompts
• Autonomous Agent - 3-stream parallel pentest (recon + junior tester + tool runner)
• Per-Scan Kali Containers - Each scan runs in its own isolated Docker container
• Anti-Hallucination Pipeline - Negative controls, proof-of-execution, confidence scoring
• Exploit Chain Engine - Automatically chains findings (SSRF->internal, SQLi->DB-specific, etc.)
• WAF Detection & Bypass - 16 WAF signatures, 12 bypass techniques
• Smart Strategy Adaptation - Dead endpoint detection, diminishing returns, priority recomputation
• Multi-Provider LLM - Claude, GPT, Gemini, Ollama, LMStudio, OpenRouter
• Real-Time Dashboard - WebSocket-powered live scan progress, findings, and reports
• Sandbox Dashboard - Monitor running Kali containers, tools, health checks in real-time

Table of Contents

• Quick Start
• Architecture
• Autonomous Agent
• 100 Vulnerability Types
• Kali Sandbox System
• Anti-Hallucination & Validation
• Web GUI
• API Reference
• Configuration
• Development
• Security Notice

Quick Start

Option 1: Docker (Recommended)

# Clone repository
git clone https://github.com/your-org/NeuroSploitv2.git
cd NeuroSploitv2

# Copy environment file and add your API keys
cp .env.example .env
nano .env  # Add ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY

# Build the Kali sandbox image (first time only, ~5 min)
./scripts/build-kali.sh

# Start backend
uvicorn backend.main:app --host 0.0.0.0 --port 8000

Option 2: Manual Setup

# Backend
pip install -r requirements.txt
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

# Frontend (new terminal)
cd frontend
npm install
npm run dev

Build Kali Sandbox Image

# Normal build (uses Docker cache)
./scripts/build-kali.sh

# Full rebuild (no cache)
./scripts/build-kali.sh --fresh

# Build + run health check
./scripts/build-kali.sh --test

# Or via docker-compose
docker compose -f docker/docker-compose.kali.yml build

Access the web interface at http://localhost:8000 (production build) or http://localhost:5173 (dev mode).

Architecture

NeuroSploitv3/
├── backend/                         # FastAPI Backend
│   ├── api/v1/                      # REST API (13 routers)
│   │   ├── scans.py                 # Scan CRUD + pause/resume/stop
│   │   ├── agent.py                 # AI Agent control
│   │   ├── agent_tasks.py           # Scan task tracking
│   │   ├── dashboard.py             # Stats + activity feed
│   │   ├── reports.py               # Report generation (HTML/PDF/JSON)
│   │   ├── scheduler.py             # Cron/interval scheduling
│   │   ├── vuln_lab.py              # Per-type vulnerability lab
│   │   ├── terminal.py              # Terminal agent (10 endpoints)
│   │   ├── sandbox.py               # Sandbox container monitoring
│   │   ├── targets.py               # Target validation
│   │   ├── prompts.py               # Preset prompts
│   │   ├── vulnerabilities.py       # Vulnerability management
│   │   └── settings.py              # Runtime settings
│   ├── core/
│   │   ├── autonomous_agent.py      # Main AI agent (~7000 lines)
│   │   ├── vuln_engine/             # 100-type vulnerability engine
│   │   │   ├── registry.py          # 100 VULNERABILITY_INFO entries
│   │   │   ├── payload_generator.py # 526 payloads across 95 libraries
│   │   │   ├── ai_prompts.py        # Per-vuln AI decision prompts
│   │   │   ├── system_prompts.py    # 12 anti-hallucination prompts
│   │   │   └── testers/             # 10 category tester modules
│   │   ├── validation/              # False-positive hardening
│   │   │   ├── negative_control.py  # Benign request control engine
│   │   │   ├── proof_of_execution.py # Per-type proof checks (25+ methods)
│   │   │   ├── confidence_scorer.py # Numeric 0-100 scoring
│   │   │   └── validation_judge.py  # Sole authority for finding approval
│   │   ├── request_engine.py        # Retry, rate limit, circuit breaker
│   │   ├── waf_detector.py          # 16 WAF signatures + bypass
│   │   ├── strategy_adapter.py      # Mid-scan strategy adaptation
│   │   ├── chain_engine.py          # 10 exploit chain rules
│   │   ├── auth_manager.py          # Multi-user auth management
│   │   ├── xss_context_analyzer.py  # 8-context XSS analysis
│   │   ├── poc_generator.py         # 20+ per-type PoC generators
│   │   ├── execution_history.py     # Cross-scan learning
│   │   ├── access_control_learner.py # Adaptive BOLA/BFLA/IDOR learning
│   │   ├── response_verifier.py     # 4-signal response verification
│   │   ├── agent_memory.py          # Bounded dedup agent memory
│   │   └── report_engine/           # OHVR report generator
│   ├── models/                      # SQLAlchemy ORM models
│   ├── db/                          # Database layer
│   ├── config.py                    # Pydantic settings
│   └── main.py                      # FastAPI app entry
│
├── core/                            # Shared core modules
│   ├── llm_manager.py               # Multi-provider LLM routing
│   ├── sandbox_manager.py           # BaseSandbox ABC + legacy shared sandbox
│   ├── kali_sandbox.py              # Per-scan Kali container manager
│   ├── container_pool.py            # Global container pool coordinator
│   ├── tool_registry.py             # 56 tool install recipes for Kali
│   ├── mcp_server.py                # MCP server (12 tools, stdio)
│   ├── scheduler.py                 # APScheduler scan scheduling
│   └── browser_validator.py         # Playwright browser validation
│
├── frontend/                        # React + TypeScript Frontend
│   ├── src/
│   │   ├── pages/
│   │   │   ├── HomePage.tsx             # Dashboard with stats
│   │   │   ├── AutoPentestPage.tsx      # 3-stream auto pentest
│   │   │   ├── VulnLabPage.tsx          # Per-type vulnerability lab
│   │   │   ├── TerminalAgentPage.tsx    # AI terminal chat
│   │   │   ├── SandboxDashboardPage.tsx # Container monitoring
│   │   │   ├── ScanDetailsPage.tsx      # Findings + validation
│   │   │   ├── SchedulerPage.tsx        # Cron/interval scheduling
│   │   │   ├── SettingsPage.tsx         # Configuration
│   │   │   └── ReportsPage.tsx          # Report management
│   │   ├── components/              # Reusable UI components
│   │   ├── services/api.ts          # API client layer
│   │   └── types/index.ts           # TypeScript interfaces
│   └── package.json
│
├── docker/
│   ├── Dockerfile.kali              # Multi-stage Kali sandbox (11 Go tools)
│   ├── Dockerfile.sandbox           # Legacy Debian sandbox
│   ├── Dockerfile.backend           # Backend container
│   ├── Dockerfile.frontend          # Frontend container
│   ├── docker-compose.kali.yml      # Kali sandbox build
│   └── docker-compose.sandbox.yml   # Legacy sandbox
│
├── config/config.json               # Profiles, tools, sandbox, MCP
├── data/
│   ├── vuln_knowledge_base.json     # 100 vuln type definitions
│   ├── execution_history.json       # Cross-scan learning data
│   └── access_control_learning.json # BOLA/BFLA adaptive data
│
├── scripts/
│   └── build-kali.sh               # Build/rebuild Kali image
├── tools/
│   └── benchmark_runner.py          # 104 CTF challenges
├── agents/base_agent.py             # BaseAgent class
├── neurosploit.py                   # CLI entry point
└── requirements.txt

Autonomous Agent

The AI agent (autonomous_agent.py) orchestrates the entire penetration test autonomously.

3-Stream Parallel Architecture

                    ┌─────────────────────┐
                    │   Auto Pentest      │
                    │   Target URL(s)     │
                    └────────┬────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  Stream 1    │ │  Stream 2    │ │  Stream 3    │
   │  Recon       │ │  Junior Test │ │  Tool Runner │
   │  ─────────── │ │  ─────────── │ │  ─────────── │
   │  Crawl pages │ │  Test target │ │  Nuclei scan │
   │  Find params │ │  AI-priority │ │  Naabu ports │
   │  Tech detect │ │  3 payloads  │ │  AI decides  │
   │  WAF detect  │ │  per endpoint│ │  extra tools │
   └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
          │                │                │
          └────────────────┼────────────────┘
                           ▼
              ┌─────────────────────┐
              │  Deep Analysis      │
              │  100 vuln types     │
              │  Full payload sets  │
              │  Chain exploitation │
              └─────────┬───────────┘
                        ▼
              ┌─────────────────────┐
              │  Report Generation  │
              │  AI executive brief │
              │  PoC code per find  │
              └─────────────────────┘

Agent Autonomy Modules

Scan Features

• Pause / Resume / Stop with checkpoints
• Manual Validation - Confirm or reject AI findings
• Screenshot Capture on confirmed findings (Playwright)
• Cross-Scan Learning - Historical success rates influence future priorities
• CVE Testing - Regex detection + AI-generated payloads

100 Vulnerability Types

Categories

Payload Engine

• 526 payloads across 95 libraries
• 73 XSS stored payloads + 5 context-specific sets
• Per-type AI decision prompts with anti-hallucination directives
• WAF-adaptive payload transformation (12 techniques)

Kali Sandbox System

Each scan runs in its own isolated Kali Linux Docker container, providing:

• Complete Isolation - No interference between concurrent scans
• On-Demand Tools - 56 tools installed only when needed
• Auto Cleanup - Containers destroyed when scan completes
• Resource Limits - Per-container memory (2GB) and CPU (2 cores) limits

Pre-Installed Tools (28)

On-Demand Tools (28 more)

Installed automatically inside the container when first requested:

• APT: wpscan, dirb, hydra, john, hashcat, testssl, sslscan, enum4linux, dnsrecon, amass, medusa, crackmapexec, etc.
• Go: gau, gitleaks, anew, httprobe
• Pip: dirsearch, wfuzz, arjun, wafw00f, sslyze, commix, trufflehog, retire

Container Pool

ContainerPool (global coordinator, max 5 concurrent)
  ├── KaliSandbox(scan_id="abc") → docker: neurosploit-abc
  ├── KaliSandbox(scan_id="def") → docker: neurosploit-def
  └── KaliSandbox(scan_id="ghi") → docker: neurosploit-ghi

• TTL enforcement - Containers auto-destroyed after 60 min
• Orphan cleanup - Stale containers removed on server startup
• Graceful fallback - Falls back to shared container if Docker unavailable

Anti-Hallucination & Validation

NeuroSploit uses a multi-layered validation pipeline to eliminate false positives:

Validation Pipeline

Finding Candidate
    │
    ▼
┌─────────────────────┐
│ Negative Controls    │  Send benign/empty requests as controls
│ Same behavior = FP   │  -60 confidence if same response
└─────────┬───────────┘
          ▼
┌─────────────────────┐
│ Proof of Execution   │  25+ per-vuln-type proof methods
│ XSS: context check   │  SSRF: metadata markers
│ SQLi: DB errors       │  BOLA: data comparison
└─────────┬───────────┘
          ▼
┌─────────────────────┐
│ AI Interpretation    │  LLM with anti-hallucination prompts
│ Per-type system msgs │  12 composable prompt templates
└─────────┬───────────┘
          ▼
┌─────────────────────┐
│ Confidence Scorer    │  0-100 numeric score
│ ≥90 = confirmed      │  +proof, +impact, +controls
│ ≥60 = likely          │  -baseline_only, -same_behavior
│ <60 = rejected        │  Breakdown visible in UI
└─────────┬───────────┘
          ▼
┌─────────────────────┐
│ Validation Judge     │  Final verdict authority
│ approve / reject     │  Records for adaptive learning
└─────────────────────┘

Anti-Hallucination System Prompts

12 composable prompts applied across 7 task contexts:

• anti_hallucination - Core truthfulness directives
• proof_of_execution - Require concrete evidence
• negative_controls - Compare with benign requests
• anti_severity_inflation - Accurate severity ratings
• access_control_intelligence - BOLA/BFLA data comparison methodology

Access Control Adaptive Learning

• Records TP/FP outcomes per domain for BOLA/BFLA/IDOR
• 9 default response patterns, 6 known FP patterns (WSO2, Keycloak, etc.)
• Historical FP rate influences future confidence scoring

Web GUI

Pages

Sandbox Dashboard

Real-time monitoring of per-scan Kali containers:

• Pool stats - Active/max containers, Docker status, TTL
• Capacity bar - Visual utilization indicator
• Per-container cards - Name, scan link, uptime, installed tools, status
• Actions - Health check, destroy (with confirmation), cleanup expired/orphans
• 5-second auto-polling for real-time updates

API Reference

Base URL

http://localhost:8000/api/v1

Endpoints

Scans

AI Agent

Sandbox

Scheduler

Vulnerability Lab

Reports & Dashboard

WebSocket

ws://localhost:8000/ws/scan/{scan_id}

Events: scan_started, progress_update, finding_discovered, scan_completed, scan_error

API Docs

Interactive docs available at:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

Configuration

Environment Variables

# LLM API Keys (at least one required)
ANTHROPIC_API_KEY=your-key
OPENAI_API_KEY=your-key
GEMINI_API_KEY=your-key

# Local LLM (optional)
OLLAMA_BASE_URL=http://localhost:11434
LMSTUDIO_BASE_URL=http://localhost:1234
OPENROUTER_API_KEY=your-key

# Database
DATABASE_URL=sqlite+aiosqlite:///./data/neurosploit.db

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=false

config/config.json

{
  "llm": {
    "default_profile": "gemini_pro_default",
    "profiles": { ... }
  },
  "agent_roles": {
    "pentest_generalist": { "vuln_coverage": 100 },
    "bug_bounty_hunter": { "vuln_coverage": 100 }
  },
  "sandbox": {
    "mode": "per_scan",
    "kali": {
      "enabled": true,
      "image": "neurosploit-kali:latest",
      "max_concurrent": 5,
      "container_ttl_minutes": 60
    }
  },
  "mcp_servers": {
    "neurosploit_tools": {
      "transport": "stdio",
      "command": "python3",
      "args": ["-m", "core.mcp_server"]
    }
  }
}

Development

Backend

pip install -r requirements.txt
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# API docs: http://localhost:8000/api/docs

Frontend

cd frontend
npm install
npm run dev        # Dev server at http://localhost:5173
npm run build      # Production build

Build Kali Sandbox

./scripts/build-kali.sh --test    # Build + health check

MCP Server

python3 -m core.mcp_server        # Starts stdio MCP server (12 tools)

Security Notice

This tool is for authorized security testing only.

• Only test systems you own or have explicit written permission to test
• Follow responsible disclosure practices
• Comply with all applicable laws and regulations
• Unauthorized access to computer systems is illegal

License

MIT License - See LICENSE for details.

Tech Stack

NeuroSploit v3 - AI-Powered Autonomous Penetration Testing Platform