# Mitmproxy Quick Reference
## Three Ways to Use Mitmproxy with MCP
### 1. **Automatic Proxy for All Tools** (Easiest)
```bash
# Terminal 1: Start mitmproxy
mitmdump --listen-host 127.0.0.1 --listen-port 8080 -w flows.mitm
# Terminal 2: Enable proxy in MCP
export PROXY_ENABLED=true
export PROXY_URL=http://127.0.0.1:8080
# Run MCP - ALL compatible tools will use proxy automatically
./setup.sh start
# Now when you run nuclei, ffuf, httpx, etc., traffic goes through mitmproxy!
```
### 2. **MCP Traffic Interception Tool** (Most Powerful)
```python
# Step 1: Start intercept session
{
"tool": "start_traffic_intercept",
"program_id": "example-corp",
"listen_port": 8080,
"save_flows": true
}
# Returns session info and instructions
# Step 2: Configure browser to use proxy (127.0.0.1:8080)
# Browse the target application...
# Step 3: Analyze captured traffic
{
"tool": "analyze_traffic_flows",
"program_id": "example-corp",
"flow_file": "./data/proxy_sessions/example-corp/abc123/flows.mitm"
}
# Returns: endpoints, parameters, cookies, API keys
# Step 4: Extract API endpoints
{
"tool": "extract_api_endpoints",
"program_id": "example-corp",
"flow_file": "./data/proxy_sessions/example-corp/abc123/flows.mitm"
}
# Returns: In-scope and out-of-scope API endpoints
```
### 3. **Manual mitmproxy + MCP Analysis** (Most Flexible)
```bash
# Terminal 1: Start mitmproxy with custom script
mitmdump -w myflows.mitm --set flow_filter='~d api.example.com'
# Browse/test the application manually...
# Terminal 2: Use MCP to analyze
python -c "
from bugbounty_mcp.tools.proxy import ProxyTools
result = await proxy_tools.analyze_traffic_flows(
program_id='example-corp',
flow_file='myflows.mitm'
)
print(result)
"
```
## Common Commands
### Start Basic Proxy
```bash
mitmdump --listen-host 127.0.0.1 --listen-port 8080
```
### Save All Traffic
```bash
mitmdump -w flows.mitm
```
### Filter Traffic
```bash
# Only capture api.example.com
mitmdump -w flows.mitm --set flow_filter='~d api.example.com'
# Only capture /api/ paths
mitmdump -w flows.mitm --set flow_filter='~u /api/'
```
### Read Saved Flows
```bash
mitmdump -r flows.mitm
```
### With Custom Script
```bash
mitmdump -s myscript.py -w flows.mitm
```
## Tool Proxy Support
| Tool | Proxy Argument | Automatic |
|------|----------------|-----------|
| nuclei | `-proxy` | ✅ Yes |
| ffuf | `-x` | ✅ Yes |
| sqlmap | `--proxy` | ✅ Yes |
| httpx | `-http-proxy` | ✅ Yes |
| dalfox | `--proxy` | ✅ Yes |
| nmap | `--proxies` | ✅ Yes |
| subfinder | N/A | ⚠️ Env vars |
| amass | N/A | ⚠️ Env vars |
**Automatic**: When `PROXY_ENABLED=true`, MCP adds the correct proxy argument automatically.
## Environment Variables
```bash
# Enable proxy globally
export PROXY_ENABLED=true
export PROXY_URL=http://127.0.0.1:8080
# For tools that use environment variables
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
# SSL certificate (for HTTPS interception)
export REQUESTS_CA_BUNDLE=~/.mitmproxy/mitmproxy-ca-cert.pem
export SSL_CERT_FILE=~/.mitmproxy/mitmproxy-ca-cert.pem
```
## SSL Certificate Setup (HTTPS)
### Quick Setup
```bash
# 1. Start mitmproxy
mitmdump
# 2. Configure browser proxy to 127.0.0.1:8080
# 3. Visit http://mitm.it in browser
# 4. Download certificate for your platform
# 5. Install certificate in browser
```
### System-Wide (Linux)
```bash
cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt
sudo update-ca-certificates
```
### Python/Requests
```bash
export REQUESTS_CA_BUNDLE=~/.mitmproxy/mitmproxy-ca-cert.pem
```
## MCP Tool Examples
### Extract All Endpoints
```python
{
"tool": "extract_api_endpoints",
"program_id": "example-corp",
"flow_file": "flows.mitm"
}
# Returns:
{
"success": true,
"in_scope_endpoints": [
{
"method": "GET",
"url": "https://api.example.com/v1/users",
"parameters": ["page", "limit"],
"is_api": true
}
],
"out_scope_endpoints": [...]
}
```
### Find API Keys
```python
{
"tool": "analyze_traffic_flows",
"program_id": "example-corp",
"flow_file": "flows.mitm"
}
# Check result["api_keys_found"] for discovered tokens
```
### Filter Analysis
```python
{
"tool": "analyze_traffic_flows",
"program_id": "example-corp",
"flow_file": "flows.mitm",
"target_filter": "api.example.com"
}
# Only analyzes traffic to api.example.com
```
## Comparison
### vs Burp Suite
- ✅ **Free and open source**
- ✅ **Better for automation**
- ✅ **Lighter resource usage**
- ✅ **Python scripting**
- ❌ **No GUI (basic mitmweb)**
- ❌ **No active scanner**
### vs OWASP ZAP
- ✅ **Simpler CLI**
- ✅ **Better Python integration**
- ✅ **Faster startup**
- ❌ **No GUI (basic mitmweb)**
- ❌ **No active scanner**
### When to Use Each
**Use mitmproxy when:**
- Automating with MCP
- API endpoint discovery
- Parameter extraction
- Token/key identification
- CI/CD integration
- Lightweight traffic analysis
**Use Burp Suite when:**
- Manual testing
- Need active scanner
- Complex session handling
- Burp extensions required
- Full GUI needed
**Use ZAP when:**
- Automation + GUI needed
- CI/CD with active scanning
- Team familiar with ZAP
- Need Docker integration
## Tips & Tricks
### 1. Save Everything
```bash
mitmdump -w flows.mitm --set save_stream_file=/tmp/traffic.log
```
### 2. Multiple Sessions
```bash
# Use different ports for different targets
mitmdump -p 8080 -w app1.mitm &
mitmdump -p 8081 -w app2.mitm &
```
### 3. Filter by Method
```bash
mitmdump --set flow_filter='~m POST'
```
### 4. Transparent Proxy (Advanced)
```bash
# Requires iptables rules
mitmdump --mode transparent
```
### 5. Reverse Proxy
```bash
mitmdump --mode reverse:https://api.example.com
# Access via http://localhost:8080
```
## Troubleshooting
### Certificate Error
```bash
# Regenerate
rm -rf ~/.mitmproxy
mitmdump
```
### Port in Use
```bash
# Use different port
mitmdump -p 8081
```
### No Traffic Captured
1. ✅ Verify proxy settings
2. ✅ Check certificate (HTTPS)
3. ✅ Verify port is open
4. ✅ Check firewall
### Analysis Returns Empty
1. ✅ Verify file exists
2. ✅ Check file has content
3. ✅ Use absolute path
4. ✅ Verify format (.mitm)
## Best Practices
1. **Always filter to scope**
- Use MCP's automatic scope validation
- Or use `--set flow_filter=`
2. **Save flows**
- Always use `-w flows.mitm`
- Timestamp files for later reference
3. **Use target filters**
- When analyzing, filter to specific targets
- Reduces noise in results
4. **Combine with other tools**
- Use mitmproxy for discovery
- Use MCP tools for exploitation
- Use both together!
5. **Security**
- Don't expose proxy publicly
- Use 127.0.0.1 only
- Protect saved flow files (may contain secrets)
## More Info
- Full guide: `docs/MITMPROXY_GUIDE.md`
- Mitmproxy docs: https://docs.mitmproxy.org
- Examples: `examples/mitmproxy_workflows.py` (coming soon)
