REST API extension for Burp Suite Professional providing programmatic access to proxy traffic, active scanner, scope management, and collaborative testing workflows. Designed for security teams implementing scripted testing workflows and custom tooling integrations.
- Why Use Belch?
- Installation & Setup
- Quick Start Examples
- API Documentation
- Use Cases
- Requirements
- Building from Source
- Support
API Coverage
- Proxy traffic management: search, filter, export HTTP requests/responses
- Scanner operations: trigger scans, retrieve vulnerability findings
- Scope configuration: programmatic include/exclude URL management
- Burp Collaborator integration for out-of-band testing
- Session tracking and traffic organization
Integration Options
- REST API with OpenAPI 3.0 specification
- WebSocket endpoints for real-time traffic streaming
- HAR and CSV export formats
- cURL command generation for request replay
Operational Features
- SQLite-based traffic storage with full-text search
- Request/response body handling up to 50MB
- Concurrent scan management and task tracking
- Session-based traffic filtering and organization
# Clone the repository
git clone https://github.com/campbellcharlie/belch.git
cd belch
# Build the extension
mvn clean package
# The JAR file will be in target/belch-1.0.0.jar- Open Burp Suite Professional (must be running for the API to work)
- Go to Extensions → Installed → Add
- Select Java extension type
- Choose the
belch-1.0.0.jarfile - Click Next and Close
The API runs on port 7850 when Burp Suite Professional is active with the extension loaded.
Endpoints:
- API Base:
http://localhost:7850 - Documentation:
http://localhost:7850/docs - OpenAPI Specification:
http://localhost:7850/openapi - Health Check:
http://localhost:7850/health - WebSocket Stream:
ws://localhost:7850/ws/stream
Health Check
curl http://localhost:7850/healthProxy Traffic Search
curl "http://localhost:7850/proxy/search?host=example.com&method=POST&limit=10"Export Traffic Data
curl "http://localhost:7850/proxy/search/download?format=csv&session_tag=test_session"Submit URL for Scanning
curl -X POST http://localhost:7850/scanner/scan-url-list \
-H "Content-Type: application/json" \
-d '{"urls": ["https://example.com/api"]}'Retrieve Scan Results
curl http://localhost:7850/scanner/issuesconst ws = new WebSocket('ws://localhost:7850/ws/stream');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Traffic event:', data.event_type, data.data.url);
};- Interactive API Docs:
http://localhost:7850/docs- Complete endpoint reference with testing interface - OpenAPI Spec:
http://localhost:7850/openapi- Machine-readable specification for tooling integration - Postman Collection:
http://localhost:7850/postman- Import directly into Postman for testing
import requests
import sys
def security_scan_workflow():
# Verify API availability
health = requests.get('http://localhost:7850/health')
if health.status_code != 200:
print("Belch API not available")
sys.exit(1)
# Submit URLs for scanning
scan_request = {
"urls": ["https://api.example.com"],
"session_tag": "security_assessment_2024"
}
response = requests.post('http://localhost:7850/scanner/scan-url-list',
json=scan_request)
# Retrieve scan results
issues = requests.get('http://localhost:7850/scanner/issues').json()
# Process findings
high_severity = [i for i in issues['issues'] if i['severity'] == 'HIGH']
if high_severity:
print(f"Found {len(high_severity)} high severity issues")
for issue in high_severity:
print(f"- {issue['name']} at {issue['base_url']}")#!/bin/bash
# Export traffic data for analysis
SESSION_TAG="pentest_$(date +%Y%m%d)"
# Set session for current testing
curl -X POST http://localhost:7850/session/tag \
-H "Content-Type: application/json" \
-d "{\"session_tag\": \"$SESSION_TAG\"}"
# Perform testing activities...
# Export results
curl "http://localhost:7850/proxy/search/download?format=csv&session_tag=$SESSION_TAG" \
-o "traffic_analysis_$SESSION_TAG.csv"Runtime Dependencies
- Burp Suite Professional 2023.1 or later
- Java 11+ (typically bundled with Burp Suite)
- Minimum 2GB available RAM for traffic storage
- Port 7850 available (configurable via application.properties)
Build Dependencies
- Maven 3.6+
- Java Development Kit 11+
git clone https://github.com/campbellcharlie/belch.git
cd belch
mvn clean packageThe compiled extension will be located at target/belch-1.0.0.jar.
- WebSocket connections limited to 50 concurrent clients
- Request/response body storage capped at 50MB per request
- SQLite database performance may degrade with >1M stored requests
- Scanner integration depends on Burp Suite Professional license limitations
- API rate limiting: 1000 requests per minute per client
Extension fails to load
- Verify Java 11+ compatibility with your Burp Suite installation
- Check Burp Suite extension error logs for specific failure details
API connection refused
- Confirm Burp Suite Professional is running with extension loaded
- Verify port 7850 is available and not blocked by firewall
- Check
http://localhost:7850/healthfor service status
High memory usage
- Large traffic history increases memory requirements
- Consider periodic database cleanup for long-running sessions
- Monitor SQLite database size in user data directory
Belch requires Burp Suite Professional and must be used in compliance with PortSwigger's license terms.
MIT License - see LICENSE file for details.
Burp Suite is a trademark of PortSwigger Ltd.
This project is an independent, third-party extension and is not affiliated with, endorsed by, or sponsored by PortSwigger Ltd.
This extension makes no claims of being secure and is intended for use only in controlled, local environments.
It must not be exposed to the public internet or used in a manner that violates PortSwigger's license terms.
Special thanks to Phil Thomas for the fantastic name "Belch" - it perfectly captures the essence of this Burp extension!
- Documentation:
http://localhost:7850/docs - Issues: GitHub Issues