# Mitmproxy Integration Guide
## Overview
The Bug Bounty MCP Server now supports **mitmproxy/mitmdump** as a powerful alternative to Burp Suite or OWASP ZAP for traffic interception and analysis.
## Features
### 1. **Proxy Support for Existing Tools**
Route traffic from tools like nuclei, ffuf, httpx through mitmproxy for comprehensive analysis.
### 2. **Traffic Interception Tools**
Three new MCP tools for working with mitmproxy:
- `start_traffic_intercept` - Configure and start mitmdump
- `analyze_traffic_flows` - Analyze captured traffic
- `extract_api_endpoints` - Extract API endpoints from traffic
### 3. **Automatic Traffic Analysis**
Automatic extraction of:
- Unique hosts and endpoints
- HTTP parameters and cookies
- API keys and tokens
- Request/response patterns
## Quick Start
### Option 1: Route Existing Tools Through Proxy
```bash
# 1. Start mitmproxy in a terminal
mitmdump --listen-host 127.0.0.1 --listen-port 8080 -w flows.mitm
# 2. Configure MCP to use proxy
export PROXY_ENABLED=true
export PROXY_URL=http://127.0.0.1:8080
# 3. Run MCP tools - traffic will be routed through proxy
# Example: nuclei, ffuf, httpx will now use the proxy
```
### Option 2: Use MCP Traffic Interception Tools
```python
# 1. Start traffic intercept for a program
{
"program_id": "example-corp",
"listen_host": "127.0.0.1",
"listen_port": 8080,
"save_flows": True,
"mode": "regular"
}
# 2. Configure your browser/tools to use the proxy
# HTTP Proxy: 127.0.0.1:8080
# HTTPS Proxy: 127.0.0.1:8080
# 3. Browse the target application
# Traffic will be captured to flows.mitm
# 4. Analyze captured traffic
{
"program_id": "example-corp",
"flow_file": "./data/proxy_sessions/example-corp/abc123/flows.mitm"
}
# 5. Extract API endpoints
{
"program_id": "example-corp",
"flow_file": "./data/proxy_sessions/example-corp/abc123/flows.mitm"
}
```
## Environment Variables
Add to your `.env` file:
```bash
# Enable proxy for all compatible tools
PROXY_ENABLED=false # Set to true to enable
PROXY_URL=http://127.0.0.1:8080
# Other settings remain the same
REQUIRE_SCOPE_VALIDATION=true
LOG_LEVEL=INFO
```
## MCP Tool Reference
### start_traffic_intercept
Start mitmproxy/mitmdump for traffic interception.
**Parameters:**
- `program_id` (required): Program identifier
- `listen_host` (optional): Host to listen on (default: 127.0.0.1)
- `listen_port` (optional): Port to listen on (default: 8080)
- `mode` (optional): Proxy mode - regular, transparent, reverse, upstream, socks5
- `save_flows` (optional): Whether to save captured flows (default: true)
- `filter_pattern` (optional): Filter pattern for traffic
**Returns:**
```json
{
"success": true,
"session_id": "abc123",
"proxy_url": "http://127.0.0.1:8080",
"output_dir": "./data/proxy_sessions/example-corp/abc123",
"flow_file": "./data/proxy_sessions/example-corp/abc123/flows.mitm",
"instructions": {
"manual_start": "mitmdump --listen-host 127.0.0.1 --listen-port 8080 ...",
"configure_browser": "Set HTTP/HTTPS proxy to 127.0.0.1:8080",
"certificate": "Install mitmproxy CA cert from ~/.mitmproxy/...",
"stop": "Press Ctrl+C to stop the proxy"
}
}
```
### analyze_traffic_flows
Analyze captured traffic flows from mitmdump.
**Parameters:**
- `program_id` (required): Program identifier
- `flow_file` (required): Path to .mitm flow file
- `target_filter` (optional): Filter for specific targets
**Returns:**
```json
{
"success": true,
"flow_file": "./data/proxy_sessions/example-corp/abc123/flows.mitm",
"total_requests": 152,
"unique_hosts": ["app.example.com", "api.example.com"],
"endpoints_found": ["GET /api/users", "POST /api/login"],
"parameters_found": ["user_id", "token", "page"],
"cookies_found": ["session_id", "csrf_token"],
"api_keys_found": [
{
"header": "X-API-Key",
"value": "abc123...",
"url": "https://api.example.com/..."
}
]
}
```
### extract_api_endpoints
Extract API endpoints from captured traffic.
**Parameters:**
- `program_id` (required): Program identifier
- `flow_file` (required): Path to .mitm flow file
**Returns:**
```json
{
"success": true,
"total_endpoints": 45,
"in_scope_count": 38,
"out_scope_count": 7,
"in_scope_endpoints": [
{
"method": "GET",
"url": "https://api.example.com/v1/users",
"host": "api.example.com",
"path": "/v1/users",
"parameters": ["page", "limit"],
"is_api": true
}
]
}
```
## Proxy Modes
### Regular Mode (Default)
Standard HTTP/HTTPS proxy. Configure your browser or tool to use the proxy.
```python
{"mode": "regular"}
```
### Transparent Mode
Intercept traffic without client configuration (requires special network setup).
```python
{"mode": "transparent"}
```
### Reverse Proxy Mode
Act as a reverse proxy for a specific backend server.
```python
{"mode": "reverse:https://backend.example.com"}
```
### Upstream Proxy Mode
Chain with another proxy.
```python
{"mode": "upstream:http://corporate-proxy:8080"}
```
### SOCKS5 Mode
Provide a SOCKS5 proxy.
```python
{"mode": "socks5"}
```
## Tool-Specific Proxy Support
### Nuclei
```bash
# Automatically adds: -proxy http://127.0.0.1:8080
```
### FFUF
```bash
# Automatically adds: -x http://127.0.0.1:8080
```
### SQLMap
```bash
# Automatically adds: --proxy http://127.0.0.1:8080
```
### HTTPX
```bash
# Automatically adds: -http-proxy http://127.0.0.1:8080
```
### Dalfox
```bash
# Automatically adds: --proxy http://127.0.0.1:8080
```
## SSL/TLS Certificate Setup
For HTTPS interception, install the mitmproxy CA certificate:
### Browser Setup
1. Start mitmproxy: `mitmdump`
2. Configure browser proxy to 127.0.0.1:8080
3. Visit http://mitm.it
4. Download and install certificate for your browser
### System-Wide (Linux)
```bash
# Copy CA cert
cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt
# Update certificates
sudo update-ca-certificates
```
### Python/Requests
```bash
export REQUESTS_CA_BUNDLE=~/.mitmproxy/mitmproxy-ca-cert.pem
export SSL_CERT_FILE=~/.mitmproxy/mitmproxy-ca-cert.pem
```
## Use Cases
### 1. API Discovery
Manually browse application → Capture traffic → Extract endpoints
```python
# Start intercept
start_traffic_intercept(program_id="example-corp", listen_port=8080)
# Browse the application...
# Extract discovered APIs
extract_api_endpoints(
program_id="example-corp",
flow_file="./data/proxy_sessions/example-corp/abc123/flows.mitm"
)
```
### 2. Parameter Mining
Discover hidden parameters from real user interactions.
```python
# Analyze traffic
analyze_traffic_flows(
program_id="example-corp",
flow_file="flows.mitm"
)
# Returns all parameters found in requests
```
### 3. Token/Key Extraction
Automatically extract API keys and tokens from headers.
```python
# Analyze traffic
result = analyze_traffic_flows(...)
# Check result["api_keys_found"]
```
### 4. Traffic Analysis for Fuzzing
Capture real requests → Extract parameters → Use in fuzzing.
```python
# 1. Capture traffic
# 2. Analyze
analysis = analyze_traffic_flows(...)
# 3. Use discovered parameters for fuzzing
for param in analysis["parameters_found"]:
parameter_fuzzing(
program_id="example-corp",
url=f"https://api.example.com/endpoint?{param}=FUZZ"
)
```
## Comparison: mitmproxy vs Burp Suite vs ZAP
| Feature | mitmproxy | Burp Suite | ZAP |
|---------|-----------|------------|-----|
| **CLI/Automation** | ✅ Excellent | ⚠️ Limited (Pro) | ⚠️ Limited |
| **Python Scripting** | ✅ Native | ❌ Java | ⚠️ Python available |
| **Open Source** | ✅ Free | ❌ Paid (Pro) | ✅ Free |
| **Performance** | ✅ Lightweight | ⚠️ Resource heavy | ⚠️ Resource heavy |
| **MCP Integration** | ✅ Native | ❌ No | ❌ No |
| **Flow Analysis** | ✅ Excellent | ✅ Excellent | ✅ Good |
| **GUI** | ⚠️ Basic (mitmweb) | ✅ Full featured | ✅ Full featured |
| **Active Scanning** | ❌ Manual | ✅ Built-in | ✅ Built-in |
## Best Practices
### 1. Scope Filtering
Always filter traffic to in-scope targets only:
```python
extract_api_endpoints(
program_id="example-corp", # Automatically filters to scope
flow_file="flows.mitm"
)
```
### 2. Save Flows
Always save flows for later analysis:
```python
start_traffic_intercept(save_flows=True) # Default
```
### 3. Use Target Filters
When analyzing, filter to specific targets:
```python
analyze_traffic_flows(
program_id="example-corp",
flow_file="flows.mitm",
target_filter="api.example.com"
)
```
### 4. Combine with Other Tools
Use mitmproxy alongside other MCP tools:
```python
# 1. Discover with subdomain enum
subdomain_enum(...)
# 2. Capture traffic manually
start_traffic_intercept(...)
# 3. Extract endpoints
endpoints = extract_api_endpoints(...)
# 4. Fuzz discovered endpoints
for endpoint in endpoints["in_scope_endpoints"]:
path_fuzzing(base_url=endpoint["url"])
```
## Troubleshooting
### Certificate Errors
```bash
# Regenerate certificates
rm -rf ~/.mitmproxy
mitmdump # Will regenerate on first run
```
### Port Already in Use
```python
# Use different port
start_traffic_intercept(listen_port=8081)
```
### No Traffic Captured
1. Verify proxy is running
2. Check browser/client proxy settings
3. Verify certificate is installed (for HTTPS)
4. Check firewall settings
### Analysis Returns Empty
1. Verify flow file exists and has content
2. Check file path is absolute
3. Ensure mitmdump completed successfully
## Advanced: Custom Scripts
Create custom mitmproxy scripts for specialized analysis:
```python
# Save to custom_script.py
from mitmproxy import http
def request(flow: http.HTTPFlow) -> None:
# Custom analysis logic
if "api" in flow.request.path:
print(f"API Call: {flow.request.method} {flow.request.path}")
addons = [request]
```
Use with MCP:
```bash
mitmdump -s custom_script.py -w flows.mitm
```
## Conclusion
Mitmproxy provides a powerful, automation-friendly alternative to Burp Suite and ZAP, with native integration into the Bug Bounty MCP Server. Use it for:
- ✅ Automated traffic analysis
- ✅ API endpoint discovery
- ✅ Parameter extraction
- ✅ Token/key identification
- ✅ Integration with other MCP tools
For GUI-based manual testing, you can still use Burp Suite or ZAP alongside the MCP server, but mitmproxy is the recommended choice for automation workflows.
