Burptomator

Burptomator is an advanced automation tool for Burp Suite Professional that enables automated vulnerability scanning, scope management, and report generation.

Features

• Automated Burp Suite startup with project creation
• Spider + Active scanning workflow for comprehensive coverage
• Scope management - automatically add hosts to scan scope
• HTML report generation per host with detailed findings
• Concurrent scanning with configurable limits
• Text file host input for bulk scanning operations
• Headless operation for CI/CD integration

Prerequisites

• Java 21 (required for Burp Suite Professional)
• Python 3.8+ with pip
• Burp Suite Professional license and JAR file
• Burp REST API extension JAR file

Installation

1. Java 21 Setup

Ensure Java 21 is installed and available in your PATH:

java -version

Should output Java version 21.x.x

2. Clone and Setup

git clone <repository-url>
cd burptomator
pip install -r requirements.txt

3. Download Required JARs

1. Burp Suite Professional JAR: Download from PortSwigger and place as burpsuite_pro.jar
2. Burp REST API JAR: Download burp-rest-api-2.3.2.jar from VMware's Burp REST API

4. Configuration

1. Copy the environment template:

   cp .env.example .env

2. Edit .env and set your Burp API key:

   BURP_API_KEY=your_api_key_here
   

3. Create your hosts file:

   cp hosts_example.txt hosts.txt

   Edit hosts.txt and add your target hosts (one per line):

   https://example.com
   https://target1.com
   https://target2.com
   

Usage

Basic Scanning

Run a basic scan with default settings:

python main.py

Advanced Options

python main.py --help

Available options:

• --hosts-file: Specify custom hosts file (default: hosts.txt)
• --max-concurrent: Maximum concurrent scans (default: 10)
• --headless: Run Burp Suite in headless mode
• --output-dir: Custom output directory

Example Commands

# Scan with custom hosts file
python main.py --hosts-file my_targets.txt

# Limit concurrent scans and specify output directory
python main.py --max-concurrent 5 --output-dir ./my_scans

# Run in headless mode for CI/CD
python main.py --headless

Configuration

The project uses a hierarchical configuration system:

Environment Variables (.env)

BURP_API_KEY=your_api_key_here

Configuration Classes (config.py)

• BurpConfig: Burp Suite and API settings
• ProjectConfig: Output directories and project management
• ScanConfig: Scanning behavior and limits

Key Configuration Options

# Burp Suite Configuration
burp_jar_path = "./burpsuite_pro.jar"
burp_rest_api_jar_path = "./burp-rest-api-2.3.2.jar"
api_port = 8090  # REST API port
official_api_port = 1337  # Official Burp API port
headless = True

# Scanning Configuration
max_concurrent_scans = 10
hosts_file = "hosts.txt"
report_format = "HTML"

Output Structure

output/
└── scan_YYYYMMDD_HHMMSS/
    ├── project.burp          # Burp project file
    ├── reports/
    │   ├── host1_report.html
    │   ├── host2_report.html
    │   └── ...
    └── logs/
        └── scan.log

How It Works

1. Startup: Burptomator starts Burp Suite Professional with the REST API extension
2. Project Creation: Creates a new Burp project for the scan session
3. Scope Management: Automatically adds target hosts to the scan scope
4. Spider Phase: Performs content discovery on each target
5. Active Scan: Runs active vulnerability scans on discovered content
6. Report Generation: Generates detailed HTML reports per host
7. Cleanup: Safely terminates Burp processes and saves results

API Endpoints Used

Official Burp Suite API (Port 1337)

• Project management
• Scope configuration
• Scan orchestration
• Issue retrieval

VMware REST API (Port 8090)

• Report generation
• Additional scan controls
• Status monitoring

Troubleshooting

Common Issues

1. Java Version Mismatch

   Error: A JNI error has occurred

   Solution: Ensure Java 21 is installed and in PATH

2. API Connection Refused

   ConnectionError: Connection refused

   Solution: Check if Burp Suite started properly and API is enabled

3. Permission Denied

   PermissionError: [Errno 13] Permission denied

   Solution: Run with appropriate permissions or check file paths

4. Port Already in Use

   Address already in use: bind

   Solution: Change API ports in config.py or kill existing Burp processes

Debugging

Enable verbose logging by modifying the logging level in the code:

import logging
logging.basicConfig(level=logging.DEBUG)

Logs Location

Check scan logs in:

output/scan_YYYYMMDD_HHMMSS/logs/scan.log

Security Considerations

• Keep your Burp Suite Professional license secure
• Store API keys in environment variables, not in code
• Use HTTPS for target URLs when possible
• Review generated reports before sharing
• Ensure proper authorization before scanning targets

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

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

Disclaimer

This tool is intended for authorized security testing only. Users are responsible for ensuring they have proper authorization to scan target systems. Unauthorized scanning may be illegal in your jurisdiction.