mirror of
https://github.com/CyberSecurityUP/NeuroSploit.git
synced 2026-07-08 04:17:56 +02:00
Add files via upload
This commit is contained in:
Joas A Santos
+215
-260
@@ -1,334 +1,289 @@
|
|||||||
# NeuroSploitv2 - Quick Start Guide
|
# NeuroSploit v3 - Quick Start Guide
|
||||||
|
|
||||||
## 🚀 Fast Track Setup (5 minutes)
|
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
|
||||||
|
|
||||||
### 1. Install Dependencies
|
|
||||||
```bash
|
```bash
|
||||||
pip install -r requirements.txt
|
git clone https://github.com/your-org/NeuroSploitv2.git
|
||||||
|
cd NeuroSploitv2
|
||||||
|
|
||||||
|
# Create your environment file
|
||||||
|
cp .env.example .env
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Set Up API Keys (Choose One)
|
Edit `.env` and add at least one API key:
|
||||||
|
|
||||||
#### Option A: Using Gemini (Free Tier Available)
|
|
||||||
```bash
|
```bash
|
||||||
export GEMINI_API_KEY="your_gemini_api_key_here"
|
# Pick one (or more):
|
||||||
```
|
ANTHROPIC_API_KEY=sk-ant-... # Claude (recommended)
|
||||||
Get your key at: https://makersuite.google.com/app/apikey
|
OPENAI_API_KEY=sk-... # GPT-4
|
||||||
|
GEMINI_API_KEY=AI... # Gemini Pro
|
||||||
#### Option B: Using LM Studio (Fully Local, No API Key)
|
OPENROUTER_API_KEY=sk-or-... # OpenRouter (any model)
|
||||||
```bash
|
|
||||||
# Download and install LM Studio from: https://lmstudio.ai/
|
|
||||||
# Start LM Studio and load a model
|
|
||||||
# Start the local server on port 1234
|
|
||||||
|
|
||||||
# Update config/config.json:
|
|
||||||
{
|
|
||||||
"llm": {
|
|
||||||
"default_profile": "lmstudio_default"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Option C: Using Ollama (Fully Local, No API Key)
|
> **No API key?** Use a local LLM (Ollama or LM Studio) -- see [Local LLM Setup](#local-llm-setup) below.
|
||||||
```bash
|
|
||||||
# Install Ollama: https://ollama.ai/
|
|
||||||
ollama pull llama3:8b
|
|
||||||
ollama serve
|
|
||||||
|
|
||||||
# Update config/config.json:
|
---
|
||||||
{
|
|
||||||
"llm": {
|
## Step 2: Install Dependencies
|
||||||
"default_profile": "ollama_llama3_default"
|
|
||||||
}
|
### Backend
|
||||||
}
|
|
||||||
|
```bash
|
||||||
|
pip install -r backend/requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Test Installation
|
### Frontend
|
||||||
```bash
|
|
||||||
# List available agents
|
|
||||||
python neurosploit.py --list-agents
|
|
||||||
|
|
||||||
# List available LLM profiles
|
```bash
|
||||||
python neurosploit.py --list-profiles
|
cd frontend
|
||||||
|
npm install
|
||||||
|
cd ..
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📝 Basic Usage Examples
|
## Step 3: Build Kali Sandbox Image (Optional but Recommended)
|
||||||
|
|
||||||
|
The Kali sandbox enables isolated tool execution (Nuclei, Nmap, SQLMap, etc.) in Docker containers.
|
||||||
|
|
||||||
### Example 1: OSINT Reconnaissance
|
|
||||||
```bash
|
```bash
|
||||||
python neurosploit.py \
|
# Requires Docker Desktop running
|
||||||
--agent-role bug_bounty_hunter \
|
./scripts/build-kali.sh --test
|
||||||
--input "Perform OSINT reconnaissance on example.com"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**What it does:**
|
This builds a Kali Linux image with 28 pre-installed security tools. Takes ~5 min on first build.
|
||||||
- Uses OSINT Collector to gather public information
|
|
||||||
- Resolves IP addresses
|
|
||||||
- Detects web technologies
|
|
||||||
- Generates email patterns
|
|
||||||
- Identifies potential social media accounts
|
|
||||||
|
|
||||||
### Example 2: Subdomain Enumeration
|
> **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
|
```bash
|
||||||
python neurosploit.py \
|
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
|
||||||
--agent-role pentest_generalist \
|
|
||||||
--input "Find all subdomains for example.com"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**What it does:**
|
Terminal 2 -- Frontend:
|
||||||
- Queries Certificate Transparency logs
|
|
||||||
- Brute-forces common subdomain names
|
|
||||||
- Validates discovered subdomains via DNS
|
|
||||||
|
|
||||||
### Example 3: DNS Enumeration
|
|
||||||
```bash
|
```bash
|
||||||
python neurosploit.py \
|
cd frontend
|
||||||
--agent-role pentest_generalist \
|
npm run dev
|
||||||
--input "Enumerate all DNS records for example.com"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**What it does:**
|
Open: **http://localhost:5173**
|
||||||
- Discovers A records (IPv4)
|
|
||||||
- Discovers AAAA records (IPv6)
|
### Option B: Production Mode
|
||||||
- Finds MX records (mail servers)
|
|
||||||
- Identifies NS records (name servers)
|
|
||||||
- Extracts TXT records
|
|
||||||
|
|
||||||
### Example 4: Interactive Mode
|
|
||||||
```bash
|
```bash
|
||||||
python neurosploit.py -i
|
# Build frontend
|
||||||
|
cd frontend && npm run build && cd ..
|
||||||
|
|
||||||
|
# Start backend (serves frontend too)
|
||||||
|
uvicorn backend.main:app --host 0.0.0.0 --port 8000
|
||||||
```
|
```
|
||||||
|
|
||||||
**Commands available:**
|
Open: **http://localhost:8000**
|
||||||
```
|
|
||||||
> list_roles
|
### Option C: Quick Start Script
|
||||||
> run_agent pentest_generalist "scan example.com"
|
|
||||||
> config
|
```bash
|
||||||
> exit
|
./start.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🧪 Testing the New Features
|
## Step 5: Verify Setup
|
||||||
|
|
||||||
### Test 1: OSINT Collector
|
### Check API Health
|
||||||
```python
|
|
||||||
python3 << 'EOF'
|
|
||||||
from tools.recon.osint_collector import OSINTCollector
|
|
||||||
|
|
||||||
collector = OSINTCollector({})
|
|
||||||
results = collector.collect("google.com")
|
|
||||||
|
|
||||||
print("IP Addresses:", results['ip_addresses'])
|
|
||||||
print("Technologies:", results['technologies'])
|
|
||||||
print("Email Patterns:", results['email_patterns'][:3])
|
|
||||||
print("Social Media:", results['social_media'])
|
|
||||||
EOF
|
|
||||||
```
|
|
||||||
|
|
||||||
**Expected Output:**
|
|
||||||
```
|
|
||||||
IP Addresses: ['142.250.xxx.xxx', ...]
|
|
||||||
Technologies: {'server': 'gws', 'status_code': 200, ...}
|
|
||||||
Email Patterns: ['info@google.com', 'contact@google.com', ...]
|
|
||||||
Social Media: {'twitter': 'https://twitter.com/google', ...}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Test 2: Subdomain Finder
|
|
||||||
```python
|
|
||||||
python3 << 'EOF'
|
|
||||||
from tools.recon.subdomain_finder import SubdomainFinder
|
|
||||||
|
|
||||||
finder = SubdomainFinder({})
|
|
||||||
subdomains = finder.find("github.com")
|
|
||||||
|
|
||||||
print(f"Found {len(subdomains)} subdomains")
|
|
||||||
print("First 5:", subdomains[:5])
|
|
||||||
EOF
|
|
||||||
```
|
|
||||||
|
|
||||||
**Expected Output:**
|
|
||||||
```
|
|
||||||
Found 15+ subdomains
|
|
||||||
First 5: ['api.github.com', 'www.github.com', 'gist.github.com', ...]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Test 3: DNS Enumerator
|
|
||||||
```python
|
|
||||||
python3 << 'EOF'
|
|
||||||
from tools.recon.dns_enumerator import DNSEnumerator
|
|
||||||
|
|
||||||
enumerator = DNSEnumerator({})
|
|
||||||
records = enumerator.enumerate("github.com")
|
|
||||||
|
|
||||||
print("A Records:", records['records']['A'])
|
|
||||||
print("MX Records:", records['records']['MX'])
|
|
||||||
print("NS Records:", records['records']['NS'])
|
|
||||||
EOF
|
|
||||||
```
|
|
||||||
|
|
||||||
### Test 4: LM Studio Integration
|
|
||||||
```bash
|
|
||||||
# 1. Start LM Studio server
|
|
||||||
# 2. Load a model (e.g., Llama 3, Mistral, Phi-3)
|
|
||||||
# 3. Start the server
|
|
||||||
|
|
||||||
# 4. Test connection
|
|
||||||
curl http://localhost:1234/v1/models
|
|
||||||
|
|
||||||
# 5. Run NeuroSploit with LM Studio
|
|
||||||
python neurosploit.py \
|
|
||||||
--llm-profile lmstudio_default \
|
|
||||||
--agent-role pentest_generalist \
|
|
||||||
--input "Explain the OWASP Top 10"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 Testing Tool Chaining
|
|
||||||
|
|
||||||
Create a test script to see tool chaining in action:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python neurosploit.py -i
|
curl http://localhost:8000/api/health
|
||||||
```
|
```
|
||||||
|
|
||||||
Then enter:
|
Expected response:
|
||||||
```
|
|
||||||
run_agent pentest_generalist "Perform complete reconnaissance: DNS enumeration, subdomain discovery, and OSINT collection for example.com"
|
|
||||||
```
|
|
||||||
|
|
||||||
The AI will automatically chain multiple tools:
|
|
||||||
1. DNS Enumerator → finds DNS records
|
|
||||||
2. Subdomain Finder → discovers subdomains
|
|
||||||
3. OSINT Collector → gathers intelligence
|
|
||||||
|
|
||||||
All results are combined and analyzed by the AI.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 View Results
|
|
||||||
|
|
||||||
### JSON Results
|
|
||||||
```bash
|
|
||||||
ls -lt results/
|
|
||||||
cat results/campaign_*.json | jq '.'
|
|
||||||
```
|
|
||||||
|
|
||||||
### HTML Reports
|
|
||||||
```bash
|
|
||||||
ls -lt reports/
|
|
||||||
open reports/report_*.html # macOS
|
|
||||||
xdg-open reports/report_*.html # Linux
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛠️ Troubleshooting
|
|
||||||
|
|
||||||
### Issue: "No module named 'anthropic'"
|
|
||||||
```bash
|
|
||||||
pip install anthropic openai google-generativeai requests
|
|
||||||
```
|
|
||||||
|
|
||||||
### Issue: LM Studio Connection Error
|
|
||||||
```bash
|
|
||||||
# Verify LM Studio server is running
|
|
||||||
curl http://localhost:1234/v1/models
|
|
||||||
|
|
||||||
# Check logs in LM Studio console
|
|
||||||
# Ensure model is loaded and server is started
|
|
||||||
```
|
|
||||||
|
|
||||||
### Issue: "Tool not found"
|
|
||||||
Edit `config/config.json` and update tool paths:
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"tools": {
|
"status": "healthy",
|
||||||
"nmap": "/usr/bin/nmap",
|
"app": "NeuroSploit",
|
||||||
"metasploit": "/usr/bin/msfconsole"
|
"version": "3.0.0",
|
||||||
|
"llm": {
|
||||||
|
"status": "configured",
|
||||||
|
"provider": "claude",
|
||||||
|
"message": "AI agent ready"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Issue: DNS Enumeration Shows Limited Results
|
### 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
|
```bash
|
||||||
# Install nslookup
|
curl -X POST http://localhost:8000/api/v1/agent/run \
|
||||||
# macOS: Already included
|
-H "Content-Type: application/json" \
|
||||||
# Linux: sudo apt-get install dnsutils
|
-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**
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 Advanced Examples
|
## 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)
|
||||||
|
|
||||||
### Custom Agent Workflow
|
|
||||||
```bash
|
```bash
|
||||||
# 1. Web Application Pentest
|
# Install Ollama
|
||||||
python neurosploit.py \
|
curl -fsSL https://ollama.ai/install.sh | sh
|
||||||
--agent-role owasp_expert \
|
|
||||||
--input "Analyze https://testphp.vulnweb.com for OWASP Top 10 vulnerabilities"
|
|
||||||
|
|
||||||
# 2. Network Reconnaissance
|
# Pull a model
|
||||||
python neurosploit.py \
|
ollama pull llama3.1
|
||||||
--agent-role red_team_agent \
|
|
||||||
--input "Plan a network penetration test for 192.168.1.0/24"
|
|
||||||
|
|
||||||
# 3. Malware Analysis
|
# Add to .env
|
||||||
python neurosploit.py \
|
echo "OLLAMA_BASE_URL=http://localhost:11434" >> .env
|
||||||
--agent-role malware_analyst \
|
|
||||||
--input "Analyze this malware sample: /path/to/sample.exe"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using Different LLM Profiles
|
### LM Studio
|
||||||
```bash
|
|
||||||
# High-quality reasoning with Claude
|
|
||||||
python neurosploit.py \
|
|
||||||
--llm-profile claude_opus_default \
|
|
||||||
--agent-role exploit_expert \
|
|
||||||
--input "Generate an exploitation strategy for CVE-2024-XXXX"
|
|
||||||
|
|
||||||
# Fast local processing with Ollama
|
1. Download from [lmstudio.ai](https://lmstudio.ai)
|
||||||
python neurosploit.py \
|
2. Load any model (e.g., Mistral, Llama)
|
||||||
--llm-profile ollama_llama3_default \
|
3. Start the server on port 1234
|
||||||
--agent-role bug_bounty_hunter \
|
4. Add to `.env`:
|
||||||
--input "Quick scan of example.com"
|
```
|
||||||
|
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)
|
||||||
|
|
||||||
## 📚 Next Steps
|
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
|
||||||
|
|
||||||
1. **Read the Full Documentation:** Check `README.md`
|
### On-demand tools (28 more)
|
||||||
2. **Explore Agent Prompts:** Look at `prompts/md_library/`
|
|
||||||
3. **Review Improvements:** Read `IMPROVEMENTS.md`
|
Installed inside the container automatically when first needed:
|
||||||
4. **Customize Config:** Edit `config/config.json`
|
|
||||||
5. **Create Custom Agents:** Use `custom_agents/example_agent.py` as template
|
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
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔐 Important Security Notes
|
## Troubleshooting
|
||||||
|
|
||||||
1. **Always get authorization** before testing systems
|
### "AI agent not configured"
|
||||||
2. **Use in isolated environments** for learning
|
|
||||||
3. **Never test production systems** without permission
|
Check your `.env` has at least one valid API key:
|
||||||
4. **Review all AI-generated commands** before execution
|
```bash
|
||||||
5. **Keep API keys secure** (use environment variables)
|
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`).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 💡 Pro Tips
|
## What's Next
|
||||||
|
|
||||||
1. **Interactive Mode is Fastest:** Use `-i` for quick iterations
|
- Read the full [README.md](README.md) for architecture details
|
||||||
2. **Tool Chaining Saves Time:** Let AI orchestrate multiple tools
|
- Explore the **100 vulnerability types** in Vuln Lab
|
||||||
3. **Local LLMs are Free:** Use LM Studio or Ollama for unlimited usage
|
- Set up **scheduled scans** for continuous monitoring
|
||||||
4. **Results are Logged:** Check `results/` and `reports/` directories
|
- Try the **Terminal Agent** for interactive AI-guided testing
|
||||||
5. **Custom Prompts:** Modify `prompts/md_library/` for specialized behavior
|
- Check the **Sandbox Dashboard** to monitor container health
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Happy Pentesting! 🎯**
|
**NeuroSploit v3** - *AI-Powered Autonomous Penetration Testing Platform*
|
||||||
|
|
||||||
For more help: `python neurosploit.py --help`
|
|
||||||
|
|||||||
Reference in New Issue
Block a user