Skip to content
BranchesTags

Repository files navigation

LLM-Safe-Exploit-Generator

Final Year Project (FYP)

LLM-Powered Automated Web Application Exploit Generator with Allow-List Safety Controls

🎯 Project Overview

This project implements an AI-powered security testing tool that automatically discovers and exploits web application vulnerabilities while maintaining strict safety controls through an allow-list mechanism. The system leverages Large Language Models (LLMs) to generate intelligent exploit payloads and provides comprehensive vulnerability reports.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (React)                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │ TargetForm   │  │ StatusCard   │  │  ReportViewer        │ │
│  └──────────────┘  └──────────────┘  └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │ HTTP/REST API
┌─────────────────────────────────────────────────────────────────┐
│                      Backend (FastAPI)                           │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                    Scan Pipeline                            │ │
│  │  Phase 1: Allow-List Check → Phase 2: Crawling             │ │
│  │  Phase 3: Exploit Generation → Phase 4: Execution & Report │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐ │
│  │ Allow-List       │  │ Crawler Service  │  │ Context      │ │
│  │ Checker          │  │ (Playwright)     │  │ Detector     │ │
│  └──────────────────┘  └──────────────────┘  └──────────────┘ │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐ │
│  │ LLM Service      │  │ Execution        │  │ Reporting    │ │
│  │ (OpenAI GPT-4)   │  │ Service          │  │ Service      │ │
│  └──────────────────┘  └──────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                    Database (PostgreSQL)                         │
│  AllowListEntry │ ScanHistory │ GeneratedReport │ LLMInteraction│
└─────────────────────────────────────────────────────────────────┘

🔧 Technology Stack

Backend:

  • Python 3.9
  • FastAPI (REST API framework)
  • SQLAlchemy (ORM)
  • PostgreSQL (Database)
  • Playwright (Web automation)
  • OpenAI API (LLM integration)
  • Pydantic (Data validation)

Frontend:

  • React 18.2
  • JavaScript (ES6+)
  • CSS3
  • Fetch API

Infrastructure:

  • Docker & Docker Compose
  • Multi-container orchestration

📋 Prerequisites

Before you begin, ensure you have the following installed:

  1. Docker Desktop (includes Docker Compose)

  2. OpenAI API Key (for LLM functionality)

  3. Git (to clone the repository)

🚀 Quick Start Guide

Step 1: Clone the Repository

git clone https://github.com/AMR-M-ALSHAMEERI/LLM-Safe-Exploit-Generator.git
cd LLM-Safe-Exploit-Generator

Step 2: Configure Environment Variables

Backend Configuration:

# Copy the example environment file
cp backend\.env.example backend\.env

# Edit backend\.env and add your OpenAI API key
# Use notepad or any text editor:
notepad backend\.env

Update the following in backend\.env:

OPENAI_API_KEY=sk-your-actual-api-key-here
SECRET_KEY=your-random-secret-key-here

Frontend Configuration:

# Copy the example environment file
cp frontend\.env.example frontend\.env

# No changes needed unless you modify ports

Step 3: Build and Start the Application

# Build all Docker containers (first time only - may take 5-10 minutes)
docker-compose build

# Start all services
docker-compose up

Wait for the services to start:

  • Backend API: http://localhost:8000
  • Frontend UI: http://localhost:3000
  • Database: localhost:5432

You should see logs indicating:

backend_1   | INFO:     Uvicorn running on http://0.0.0.0:8000
frontend_1  | Compiled successfully!
db_1        | database system is ready to accept connections

Step 4: Access the Application

  1. Open your browser and navigate to: http://localhost:3000
  2. You should see the "LLM-Safe-Exploit-Generator" interface

Step 5: Add Targets to Allow-List (CRITICAL)

Before scanning any target, you MUST add it to the allow-list:

Option A: Using the API directly

# Add a test target to the allow-list
Invoke-RestMethod -Uri "http://localhost:8000/api/v1/admin/allow-list" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"domain": "testphp.vulnweb.com", "description": "Test vulnerability site", "added_by": "admin"}'

Option B: Using curl (if installed)

curl -X POST "http://localhost:8000/api/v1/admin/allow-list" `
  -H "Content-Type: application/json" `
  -d '{\"domain\": \"testphp.vulnweb.com\", \"description\": \"Test vulnerability site\", \"added_by\": \"admin\"}'

Option C: Using a REST client

  • Install Postman or similar tool
  • POST to http://localhost:8000/api/v1/admin/allow-list
  • Body: {"domain": "testphp.vulnweb.com", "description": "Test site", "added_by": "admin"}

Step 6: Run Your First Scan

  1. In the web UI at http://localhost:3000, enter a target URL:

    http://testphp.vulnweb.com

  2. Click "Start Scan"

  3. Monitor the progress (the UI will poll automatically)

  4. View the comprehensive vulnerability report when complete

🔍 Testing the Project

Test Case 1: Basic Scan Flow

  1. Add allow-list entry:

    Invoke-RestMethod -Uri "http://localhost:8000/api/v1/admin/allow-list" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"domain": "testphp.vulnweb.com", "description": "Test site", "added_by": "tester"}'

  2. Start a scan via UI:

    • Navigate to http://localhost:3000
    • Enter: http://testphp.vulnweb.com
    • Click "Start Scan"

  3. Expected Results:

    • Status changes: pending → in_progress → completed
    • Report shows discovered vulnerabilities with:
      • Severity level (Critical/High/Medium/Low)
      • Proof of Concept (PoC)
      • Mitigation recommendations
      • MITRE ATT&CK mapping

Test Case 2: Allow-List Safety Control

  1. Try to scan a non-allowed domain:

    • Enter: http://google.com
    • Click "Start Scan"

  2. Expected Result:

    • Error message: "Target not in allow-list"
    • Scan status: failed
    • No scan execution (safety mechanism works)

Test Case 3: API Health Check

# Check if backend is healthy
Invoke-RestMethod -Uri "http://localhost:8000/health"

# Expected output:
# status: healthy
# database: connected
# timestamp: <current time>

Test Case 4: View All Allow-List Entries

# List all allowed domains
Invoke-RestMethod -Uri "http://localhost:8000/api/v1/admin/allow-list"

📦 Manual Dependency Installation (Alternative Setup)

If you prefer to run services outside Docker:

Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
.\venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations (ensure PostgreSQL is running)
# Create database manually or use:
# CREATE DATABASE exploit_generator;

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

Frontend Setup

cd frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env

# Start development server
npm start

Database Setup (PostgreSQL)

# Install PostgreSQL (if not using Docker)
# Download from: https://www.postgresql.org/download/windows/

# Create database
psql -U postgres
CREATE DATABASE exploit_generator;
\q

# Update DATABASE_URL in backend/.env
# DATABASE_URL=postgresql://postgres:your_password@localhost:5432/exploit_generator

🛠️ Development Commands

# Stop all services
docker-compose down

# Stop and remove all data (including database)
docker-compose down -v

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f db

# Rebuild after code changes
docker-compose up --build

# Run backend tests (when implemented)
docker-compose exec backend pytest

# Access PostgreSQL database
docker-compose exec db psql -U postgres -d exploit_generator

# Execute commands in backend container
docker-compose exec backend bash

# Execute commands in frontend container
docker-compose exec frontend sh

📊 API Documentation

Once the backend is running, access the interactive API documentation:

🔐 Security Features

  1. Allow-List Control: Only pre-approved domains can be scanned
  2. Fail-Safe Design: Blocks execution if target is not in allow-list
  3. Audit Logging: All scans and LLM interactions are logged
  4. Sandboxed Execution: Playwright runs in isolated browser contexts
  5. Rate Limiting: Prevents resource exhaustion
  6. Input Validation: Pydantic schemas validate all inputs

📁 Project Structure

LLM-Safe-Exploit-Generator/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   └── endpoints/
│   │   │       ├── admin.py          # Allow-list CRUD
│   │   │       └── scan.py           # Scan orchestration
│   │   ├── modules/
│   │   │   ├── allow_list_checker.py # Safety control
│   │   │   ├── crawler_service.py    # Web crawling
│   │   │   ├── context_detector.py   # Vulnerability detection
│   │   │   ├── llm_service.py        # LLM integration
│   │   │   ├── execution_service.py  # Payload execution
│   │   │   └── reporting_service.py  # Report generation
│   │   ├── database.py               # DB connection
│   │   ├── models.py                 # SQLAlchemy models
│   │   ├── schemas.py                # Pydantic schemas
│   │       └── main.py                   # FastAPI app
│   ├── Dockerfile
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── public/
│   │   └── index.html
│   ├── src/
│   │   ├── components/
│   │   │   ├── TargetForm.js         # URL input form
│   │   │   ├── TargetForm.css
│   │   │   ├── ReportViewer.js       # Results display
│   │   │   └── ReportViewer.css
│   │   ├── services/
│   │   │   └── api.js                # API client
│   │   ├── App.js                    # Main component
│   │   ├── App.css
│   │   ├── index.js                  # Entry point
│   │   └── index.css
│   ├── Dockerfile
│   ├── package.json
│   └── .env.example
├── docker-compose.yml
├── .gitignore
├── LICENSE
└── README.md

🧪 Testing

Running Tests

To run the automated tests:

  1. Ensure Docker containers are running
  2. Execute the test script:
# For Linux/Mac
./scripts/test.sh

# For Windows
.\scripts\test.ps1

Test Results

  • Outputs are saved in tests/results/
  • JSON files contain detailed test reports

Notes

  • Ensure sufficient permissions are granted for test execution
  • Review tests/README.md for test structure and guidelines

📦 Deployment

Docker Deployment

For production deployment using Docker:

  1. Build the images: 
    docker-compose build --no-cache
  2. Start the containers: 
    docker-compose up -d
  3. Monitor logs: 
    docker-compose logs -f

Non-Docker Deployment

For manual deployment without Docker:

  1. Set up Python virtual environment
  2. Install dependencies: pip install -r backend/requirements.txt
  3. Configure environment variables in backend/.env
  4. Run database migrations: alembic upgrade head
  5. Start the FastAPI server: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

🐛 Troubleshooting

Issue: Docker containers won't start

Solution:

# Remove all containers and volumes
docker-compose down -v

# Rebuild from scratch
docker-compose build --no-cache

# Start again
docker-compose up

Issue: Backend shows "Database connection failed"

Solution:

# Check if PostgreSQL container is running
docker-compose ps

# View database logs
docker-compose logs db

# Restart database service
docker-compose restart db

Issue: Frontend can't connect to backend

Solution:

  1. Check frontend/.env has correct API URL: REACT_APP_API_BASE_URL=http://localhost:8000
  2. Ensure backend is running: docker-compose logs backend
  3. Check CORS settings in backend/.env

Issue: "OpenAI API key not found" error

Solution:

  1. Ensure you've created backend/.env from .env.example
  2. Add your OpenAI API key: OPENAI_API_KEY=sk-...
  3. Restart backend: docker-compose restart backend

Issue: Scan fails with "Target not in allow-list"

Solution: This is expected behavior! Add the target domain to the allow-list first:

Invoke-RestMethod -Uri "http://localhost:8000/api/v1/admin/allow-list" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"domain": "your-target-domain.com", "description": "Test", "added_by": "admin"}'

Issue: Playwright browser installation fails

Solution:

# Access backend container
docker-compose exec backend bash

# Manually install browsers
playwright install chromium

# Exit and restart
exit
docker-compose restart backend

📈 Supported Vulnerability Types

The system currently detects and generates exploits for:

  1. SQL Injection (SQLi)

    • Union-based
    • Boolean-based blind
    • Time-based blind

  2. Cross-Site Scripting (XSS)

    • Reflected XSS
    • DOM-based XSS
    • Stored XSS

  3. Command Injection

    • OS command injection
    • Code injection

  4. Path Traversal

    • Directory traversal
    • Local file inclusion (LFI)

  5. Server-Side Request Forgery (SSRF)

    • Internal network scanning
    • Cloud metadata access

🎓 Educational Use Only

⚠️ IMPORTANT DISCLAIMER:

This tool is designed for EDUCATIONAL PURPOSES ONLY and AUTHORIZED SECURITY TESTING.

  • ✅ Use on systems you own or have explicit written permission to test
  • ✅ Use in controlled lab environments
  • ✅ Use for security research and learning
  • ❌ DO NOT use on systems without authorization
  • ❌ DO NOT use for malicious purposes
  • ❌ DO NOT bypass the allow-list safety mechanism

Unauthorized access to computer systems is illegal and punishable by law.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

AMR M. ALSHAMEERI

🙏 Acknowledgments

  • OpenAI for GPT-4 API
  • FastAPI framework
  • React.js library
  • Playwright automation framework
  • OWASP for vulnerability classifications
  • MITRE ATT&CK framework

###📞 Support

For issues, questions, or contributions:

  1. Open an issue on GitHub
  2. Check existing documentation
  3. Review API documentation at /docs

Happy (Ethical) Hacking! 🛡️ LLM-Powered Automated Web Application Exploit Generator with Allow-List Safety Controls

About

LLM-Powered Automated Web Application Exploit Generator with Allow-List Safety Controls

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages