PentestGPT Web Interface

AI-powered penetration testing tool with interactive follow-up capabilities.

🚀 Quick Start (One-Click Launch)

Double-click start-pentestgpt.bat to:

• ✅ Check Python installation
• ✅ Verify project structure
• ✅ Check/install dependencies
• ✅ Start backend server (port 8000)
• ✅ Start frontend server (port 8080)
• ✅ Open browser automatically

🛑 Stopping the Application

Double-click stop-pentestgpt.bat to stop all services.

Or simply close both console windows (Backend & Frontend).

📋 Manual Setup (First Time)

1. Install Dependencies

cd backend
pip install -r requirements.txt

2. Configure Environment

Create backend/.env file:

OPENROUTER_API_KEY=your_api_key_here
DEFAULT_MODEL=google/gemini-2.0-flash-exp:free

3. Run Manually

Backend:

cd backend
python -m uvicorn app:app --reload --host 0.0.0.0 --port 8000

Frontend:

cd frontend
python -m http.server 8080

Open: http://localhost:8080

✨ Features

Core Scanning

• Automated Reconnaissance - Domain/IP analysis
• Port Scanning - Nmap-powered service detection
• Web Vulnerability Assessment - Directory enumeration, security headers
• AI Analysis - Vulnerability prioritization and recommendations
• Report Generation - Downloadable JSON reports

🆕 Interactive Follow-up (NEW!)

After initial scan completes:

• AI Suggestions - Context-aware next step recommendations
• Natural Language Commands - "brute force SSH on port 22"
• 10+ Security Tools - hydra, sqlmap, nikto, nmap, dirb, etc.
• Real-time Results - Live command execution and output
• Command History - Track all interactive testing

🎯 Usage Example

1. Create Session

• Click "New Session"
• Enter target: 127.0.0.1 or any IP/domain
• Click "Start"

2. Wait for Scan

Watch the real-time activity feed as the scan progresses.

3. Interactive Commands (After Completion)

Look for the "🤖 Continue Testing" section:

• Click "💡 Show Suggestions" for AI recommendations
• Or type commands like:
  • "scan port 80 for vulnerabilities"
  • "brute force SSH with common passwords"
  • "enumerate web directories"
  • "check for SQL injection"

🔧 Backend Console Logs

The backend terminal shows detailed operations:

[AI_INTERPRETER] Received command: 'brute force SSH'
[COMMAND] Executing: hydra -l root -P wordlist.txt ssh://127.0.0.1:22
[COMMAND] ✅ Completed: hydra
[TOOL_EXECUTOR] ✅ 'hydra' execution completed successfully

Visual indicators:

• ✅ Success
• ❌ Errors
• ⏱️ Timeouts

📁 Project Structure

pentestgpt-web/
├── backend/
│   ├── app.py                    # FastAPI application
│   ├── session_manager.py        # Session management
│   ├── config.py                 # Configuration
│   ├── pentest_engine/
│   │   ├── orchestrator.py       # Main pentest orchestrator
│   │   ├── ai_client.py          # AI integration
│   │   ├── command_interpreter.py # NEW: AI command parser
│   │   ├── tool_executor.py      # NEW: Security tool executor
│   │   └── ...
│   └── .env                      # Environment variables
├── frontend/
│   ├── index.html                # Main UI
│   ├── app.js                    # Application logic (with interactive chat)
│   └── styles.css                # Styling
├── start-pentestgpt.bat          # One-click launcher
└── stop-pentestgpt.bat           # Shutdown script

🔒 Security Tools Supported

Tool	Purpose	Risk Level
nmap	Port scanning	Low
nikto	Web vulnerability scanning	Low
dirb	Directory enumeration	Low
gobuster	Directory/DNS bruteforcing	Low
wpscan	WordPress scanning	Low
sqlmap	SQL injection testing	Medium
hydra	Password bruteforcing	Medium
enum4linux	SMB enumeration	Low
smbclient	SMB share access	Low
metasploit	Exploitation (manual only)	High

🛡️ Safety Features

• Timeouts - All commands have max execution time
• Resource Limits - Brute force limited to 4 threads
• No Auto-Exploit - Metasploit shows manual commands only
• Tool Checks - Graceful failure with install prompts

📊 API Endpoints

Endpoint	Method	Purpose
/api/sessions	GET	List all sessions
/api/sessions	POST	Create new session
/api/sessions/{id}	GET	Get session details
/api/sessions/{id}/command	POST	Execute interactive command
/api/sessions/{id}/suggestions	GET	Get AI suggestions
/api/sessions/{id}/commands	GET	Get command history
/ws/sessions/{id}	WebSocket	Real-time updates

🐛 Troubleshooting

Python not found?

• Install Python 3.11+ from https://python.org
• Make sure to check "Add to PATH" during installation

Dependencies fail to install?

• Run as administrator
• Update pip: python -m pip install --upgrade pip

Backend won't start?

• Check if port 8000 is already in use
• Verify .env file has API key

API connection errors?

• Verify OpenRouter API key in backend/.env
• Check internet connection

📝 Requirements

• Python 3.11+
• Windows OS (for .bat files, Linux users can run commands manually)
• OpenRouter API key (for AI features)
• Internet connection

🎓 Documentation

• Implementation Plan: See brain/implementation_plan.md
• Walkthrough: See brain/walkthrough.md
• Task Checklist: See brain/task.md

⚖️ Legal Notice

For authorized testing only. Only use this tool on systems you have explicit permission to test. Unauthorized penetration testing is illegal.

---

Version: 2.0 (with Interactive Follow-up)
License: MIT
Author: AI-Assisted Development