# Mitmproxy Integration - Implementation Summary
## Overview
Successfully implemented comprehensive mitmproxy integration into the Bug Bounty MCP Server as a powerful alternative to Burp Suite and OWASP ZAP.
**Date**: October 12, 2025
**Status**: ✅ Complete and Ready to Use
---
## 🎯 What Was Implemented
### 1. Proxy Support for Existing Tools ✅
**File**: `src/bugbounty_mcp/utils/executor.py`
Added proxy support to the ToolExecutor class:
- New `proxy_url` parameter in constructor
- New `use_proxy` parameter in execute method
- Automatic proxy argument injection for supported tools
- Environment variable support (HTTP_PROXY, HTTPS_PROXY)
**Supported Tools**:
- ✅ nuclei (adds `-proxy`)
- ✅ ffuf (adds `-x`)
- ✅ sqlmap (adds `--proxy`)
- ✅ httpx (adds `-http-proxy`)
- ✅ dalfox (adds `--proxy`)
- ✅ nmap (adds `--proxies`)
- ✅ All tools via environment variables
### 2. New Mitmproxy-Specific Tools ✅
**File**: `src/bugbounty_mcp/tools/proxy.py`
Created three new MCP tools:
#### `start_traffic_intercept`
- Starts mitmproxy/mitmdump for traffic capture
- Configurable proxy modes (regular, transparent, reverse, upstream, socks5)
- Automatic session management
- Flow file saving
- Custom logging script generation
#### `analyze_traffic_flows`
- Analyzes captured .mitm flow files
- Extracts unique hosts and endpoints
- Identifies HTTP parameters and cookies
- Discovers API keys and tokens in headers
- Provides detailed traffic statistics
#### `extract_api_endpoints`
- Extracts API endpoints from traffic
- Automatic scope validation (in-scope vs out-of-scope)
- Identifies API patterns (/api/, /v1/, .json, etc.)
- Lists HTTP methods, parameters, and paths
### 3. Configuration Support ✅
**File**: `src/bugbounty_mcp/config.py`
Added proxy configuration to ServerConfig:
- `proxy_url`: URL of proxy server
- `proxy_enabled`: Global toggle for proxy support
Environment variables:
- `PROXY_ENABLED`: Enable/disable proxy globally
- `PROXY_URL`: Proxy server URL (e.g., http://127.0.0.1:8080)
**File**: `.env.example`
Added proxy configuration examples and usage notes.
### 4. Server Integration ✅
**File**: `src/bugbounty_mcp/server.py`
- Imported ProxyTools
- Added three new tool definitions
- Added tool handlers for proxy tools
- Initialized ProxyTools in main()
- Configured ToolExecutor with proxy settings
### 5. Documentation ✅
Created comprehensive documentation:
**`docs/MITMPROXY_GUIDE.md`**:
- Full feature documentation
- Setup instructions
- Tool reference
- Use cases and workflows
- Comparison with Burp/ZAP
- Best practices
- Troubleshooting
**`docs/MITMPROXY_QUICKSTART.md`**:
- Quick reference guide
- Common commands
- Tool examples
- Environment variables
- Tips and tricks
**`README.md`**:
- Added "Traffic Analysis" section
- Listed three new tools
---
## 🚀 How to Use
### Option 1: Global Proxy for All Tools
```bash
# Terminal 1: Start mitmproxy
mitmdump --listen-host 127.0.0.1 --listen-port 8080 -w flows.mitm
# Terminal 2: Enable in .env
echo "PROXY_ENABLED=true" >> .env
echo "PROXY_URL=http://127.0.0.1:8080" >> .env
# Start MCP - all tools now use proxy!
./setup.sh start
```
### Option 2: MCP Traffic Tools
```python
# 1. Start traffic intercept
await start_traffic_intercept(
program_id="example-corp",
listen_port=8080,
save_flows=True
)
# 2. Browse application with proxy configured
# 3. Analyze captured traffic
await analyze_traffic_flows(
program_id="example-corp",
flow_file="./data/proxy_sessions/example-corp/abc123/flows.mitm"
)
# 4. Extract API endpoints
await extract_api_endpoints(
program_id="example-corp",
flow_file="./data/proxy_sessions/example-corp/abc123/flows.mitm"
)
```
### Option 3: Manual + MCP Analysis
```bash
# Capture traffic manually
mitmdump -w myflows.mitm --set flow_filter='~d api.example.com'
# Analyze with MCP
await analyze_traffic_flows(
program_id="example-corp",
flow_file="myflows.mitm"
)
```
---
## 📁 Files Modified/Created
### Modified Files
1. `src/bugbounty_mcp/utils/executor.py` - Added proxy support
2. `src/bugbounty_mcp/config.py` - Added proxy configuration
3. `src/bugbounty_mcp/server.py` - Integrated proxy tools
4. `.env.example` - Added proxy environment variables
5. `README.md` - Added traffic analysis section
### New Files
1. `src/bugbounty_mcp/tools/proxy.py` - Proxy tools implementation
2. `docs/MITMPROXY_GUIDE.md` - Comprehensive guide
3. `docs/MITMPROXY_QUICKSTART.md` - Quick reference
4. `docs/MITMPROXY_IMPLEMENTATION.md` - This file
---
## ✨ Key Features
### Automatic Proxy Injection
- Tools automatically get correct proxy arguments
- No manual configuration needed per tool
- Environment variable fallback
### Scope-Aware Analysis
- All extracted endpoints validated against program scope
- Automatic separation of in-scope vs out-of-scope
- Prevents testing unauthorized targets
### Traffic Intelligence
- Automatic parameter extraction
- Cookie discovery
- API key identification
- Endpoint pattern recognition
### Session Management
- Automatic session directories
- Timestamped flow files
- Organized output structure
### Flexible Modes
- Regular proxy (default)
- Transparent proxy
- Reverse proxy
- Upstream proxy chaining
- SOCKS5 proxy
---
## 🔧 Technical Details
### Proxy Argument Mapping
```python
proxy_args_map = {
'nuclei': ['-proxy', proxy_url],
'ffuf': ['-x', proxy_url],
'sqlmap': ['--proxy', proxy_url],
'httpx': ['-http-proxy', proxy_url],
'dalfox': ['--proxy', proxy_url],
'nmap': ['--proxies', proxy_url],
}
```
### Environment Variables
```python
if use_proxy and self.proxy_url:
env['HTTP_PROXY'] = self.proxy_url
env['HTTPS_PROXY'] = self.proxy_url
```
### Session Structure
```
./data/proxy_sessions/
└── example-corp/
└── abc123/
├── flows.mitm
├── traffic.log
└── logger.py
```
### Analysis Output Format
```json
{
"success": true,
"total_requests": 152,
"unique_hosts": ["api.example.com", "app.example.com"],
"endpoints": ["GET /api/users", "POST /api/login"],
"parameters": ["user_id", "token", "page"],
"cookies": ["session_id", "csrf_token"],
"api_keys": [
{
"header": "X-API-Key",
"value": "abc123...",
"url": "https://api.example.com/..."
}
]
}
```
---
## 🆚 Comparison
| Feature | mitmproxy | Burp Suite | ZAP |
|---------|-----------|------------|-----|
| **MCP Integration** | ✅ Native | ❌ No | ❌ No |
| **Automation** | ✅ Excellent | ⚠️ Limited | ⚠️ Limited |
| **Open Source** | ✅ Free | ❌ Paid (Pro) | ✅ Free |
| **Python Scripting** | ✅ Native | ❌ Java | ⚠️ Available |
| **CLI** | ✅ Full | ⚠️ Basic | ⚠️ Basic |
| **Resource Usage** | ✅ Light | ❌ Heavy | ❌ Heavy |
| **GUI** | ⚠️ Basic | ✅ Full | ✅ Full |
| **Active Scanner** | ❌ No | ✅ Yes | ✅ Yes |
---
## 🎓 Use Cases
### 1. API Endpoint Discovery
```python
# Manually browse app → Capture traffic → Extract endpoints
start_traffic_intercept() → browse() → extract_api_endpoints()
```
### 2. Parameter Mining
```python
# Discover hidden parameters from real interactions
analyze_traffic_flows() → Check parameters_found
```
### 3. Token Extraction
```python
# Automatically find API keys and tokens
analyze_traffic_flows() → Check api_keys_found
```
### 4. Fuzzing Preparation
```python
# Capture requests → Extract parameters → Fuzz
extract_api_endpoints() → parameter_fuzzing()
```
### 5. Comprehensive Testing
```python
# Route all MCP tools through mitmproxy
PROXY_ENABLED=true → Run any tool → Analyze captured traffic
```
---
## ⚠️ Important Notes
### Security
1. **Never expose proxy publicly** - Use 127.0.0.1 only
2. **Protect flow files** - May contain sensitive data
3. **Scope validation** - Always enabled by default
4. **Certificate security** - Keep mitmproxy CA cert secure
### Performance
1. **Proxy adds latency** - ~10-50ms per request
2. **Flow files grow large** - Monitor disk space
3. **Analysis is async** - Won't block other operations
### HTTPS
1. **Certificate required** - Install mitmproxy CA cert
2. **Browser warnings** - Expected for self-signed cert
3. **Certificate pinning** - May break some apps
---
## 🧪 Testing
### Quick Test
```bash
# Terminal 1
mitmdump -p 8080
# Terminal 2
export PROXY_ENABLED=true
export PROXY_URL=http://127.0.0.1:8080
curl -x http://127.0.0.1:8080 https://httpbin.org/get
# Should see traffic in Terminal 1
```
### MCP Tool Test
```python
# Start intercept
result = await start_traffic_intercept(
program_id="example-program",
listen_port=8080
)
# Verify
assert result["success"] == True
assert result["proxy_url"] == "http://127.0.0.1:8080"
```
---
## 📚 Further Reading
- **Mitmproxy Docs**: https://docs.mitmproxy.org
- **MCP Server Guide**: `README.md`
- **Tool Reference**: `TOOLS.md`
- **Examples**: `examples/usage_examples.py`
---
## 🎉 Summary
**Mitmproxy is now fully integrated** into the Bug Bounty MCP Server:
✅ **Option 1**: Global proxy for all tools (easiest)
✅ **Option 2**: Dedicated MCP traffic tools (most powerful)
✅ **Option 3**: Manual capture + MCP analysis (most flexible)
All three approaches are production-ready and can be used immediately!
**Next Steps**:
1. Install mitmproxy: `pip install mitmproxy`
2. Read quick start: `docs/MITMPROXY_QUICKSTART.md`
3. Try it out with your first program!
Happy hunting! 🎯
