CalvinBackup/NeuroSploit
1
0 Fork 0
mirror of https://github.com/CyberSecurityUP/NeuroSploit.git synced 2026-09-30 13:09:36 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add files via upload

Browse Source
This commit is contained in:
Joas A Santos authored and GitHub committed 2026-02-11 10:56:31 -03:00
1 parent f0fa49a06a
commit e861cd667a
1 file changed
+219 -264
Download Patch File Download Diff File Expand all files Collapse all files
QUICKSTART.md
+219 -264
View File
@@ -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**
---
## 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
``` ```
--- ---
## 🎯 Advanced Examples ## Kali Sandbox Commands
### Custom Agent Workflow
```bash ```bash
# 1. Web Application Pentest # Build image
python neurosploit.py \ ./scripts/build-kali.sh
--agent-role owasp_expert \
--input "Analyze https://testphp.vulnweb.com for OWASP Top 10 vulnerabilities"
# 2. Network Reconnaissance # Rebuild from scratch
python neurosploit.py \ ./scripts/build-kali.sh --fresh
--agent-role red_team_agent \
--input "Plan a network penetration test for 192.168.1.0/24"
# 3. Malware Analysis # Build + verify tools work
python neurosploit.py \ ./scripts/build-kali.sh --test
--agent-role malware_analyst \
--input "Analyze this malware sample: /path/to/sample.exe" # Check running containers (via API)
curl http://localhost:8000/api/v1/sandbox/
# Monitor via web UI
# Open http://localhost:8000/sandboxes
``` ```
### Using Different LLM Profiles ### Pre-installed tools (28)
```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 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
python neurosploit.py \
--llm-profile ollama_llama3_default \ ### On-demand tools (28 more)
--agent-role bug_bounty_hunter \
--input "Quick scan of example.com" 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"
## 📚 Next Steps Build the Docker image:
```bash
./scripts/build-kali.sh
```
1. **Read the Full Documentation:** Check `README.md` ### "Docker daemon not running"
2. **Explore Agent Prompts:** Look at `prompts/md_library/`
3. **Review Improvements:** Read `IMPROVEMENTS.md` Start Docker Desktop, then retry.
4. **Customize Config:** Edit `config/config.json`
5. **Create Custom Agents:** Use `custom_agents/example_agent.py` as template ### "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`).
--- ---
## 🔐 Important Security Notes ## What's Next
1. **Always get authorization** before testing systems - Read the full [README.md](README.md) for architecture details
2. **Use in isolated environments** for learning - Explore the **100 vulnerability types** in Vuln Lab
3. **Never test production systems** without permission - Set up **scheduled scans** for continuous monitoring
4. **Review all AI-generated commands** before execution - Try the **Terminal Agent** for interactive AI-guided testing
5. **Keep API keys secure** (use environment variables) - Check the **Sandbox Dashboard** to monitor container health
--- ---
## 💡 Pro Tips **NeuroSploit v3** - *AI-Powered Autonomous Penetration Testing Platform*
1. **Interactive Mode is Fastest:** Use `-i` for quick iterations
2. **Tool Chaining Saves Time:** Let AI orchestrate multiple tools
3. **Local LLMs are Free:** Use LM Studio or Ollama for unlimited usage
4. **Results are Logged:** Check `results/` and `reports/` directories
5. **Custom Prompts:** Modify `prompts/md_library/` for specialized behavior
---
**Happy Pentesting! 🎯**
For more help: `python neurosploit.py --help`