mitmproxy API Security Testing Skill

mitmproxy API Security Testing

Overview

mitmproxy is an interactive, TLS-capable intercepting HTTP proxy for penetration testers and developers. It enables real-time inspection, modification, and replay of HTTP/HTTPS traffic including APIs, mobile apps, and thick clients. With support for HTTP/1, HTTP/2, HTTP/3, and WebSockets, mitmproxy provides comprehensive coverage for modern API security testing.

Interfaces

mitmproxy - Interactive console interface with keyboard navigation mitmweb - Web-based GUI for visual traffic inspection mitmdump - Command-line tool for automated traffic capture and scripting

Quick Start

Install and run mitmproxy:

# Install via pip
pip install mitmproxy

# Start interactive console proxy
mitmproxy

# Start web interface (default: http://127.0.0.1:8081)
mitmweb

# Start command-line proxy with output
mitmdump -w traffic.flow

Configure client to use proxy (default: localhost:8080)

Core Workflows

Workflow 1: Interactive API Traffic Inspection

For manual API security testing and analysis:

Start mitmproxy or mitmweb:

# Console interface
mitmproxy --mode regular --listen-host 0.0.0.0 --listen-port 8080

# Or web interface
mitmweb --mode regular --listen-host 0.0.0.0 --listen-port 8080

Configure target application to use proxy (HTTP: localhost:8080)
Install mitmproxy CA certificate on client device
Trigger API requests from the application
Intercept and inspect requests/responses in mitmproxy
Modify requests to test:
- Authentication bypass attempts
- Authorization flaws (IDOR, privilege escalation)
- Input validation (SQLi, XSS, command injection)
- Business logic vulnerabilities
Save flows for documentation and reporting

Workflow 2: Mobile App API Security Testing

Progress: [ ] 1. Install mitmproxy CA certificate on mobile device [ ] 2. Configure device WiFi to use mitmproxy as proxy [ ] 3. Start mitmweb for visual traffic inspection [ ] 4. Launch mobile app and exercise all features [ ] 5. Review API endpoints, authentication mechanisms, data flows [ ] 6. Test for common API vulnerabilities (OWASP API Top 10) [ ] 7. Export traffic as HAR for further analysis [ ] 8. Document findings with request/response examples

Work through each step systematically. Check off completed items.

Workflow 3: Automated API Traffic Recording

For capturing and analyzing API traffic at scale:

Start mitmdump with flow capture:

mitmdump -w api-traffic.flow --mode regular

Run automated tests or manual app interaction
Stop mitmdump (Ctrl+C) to save flows

Replay captured traffic:

# Replay to server
mitmdump -nc -r api-traffic.flow

# Replay with modifications via script
mitmdump -s replay-script.py -r api-traffic.flow

Export to HAR format for analysis:

# Using Python API
python3 -c "from mitmproxy.io import FlowReader; from mitmproxy.tools.dump import DumpMaster;
import sys; [print(flow.request.url) for flow in FlowReader(open('api-traffic.flow', 'rb')).stream()]"

Workflow 4: Python Scripting for API Testing

For automated security testing with custom logic:

Create Python addon script (api-test.py):

from mitmproxy import http

class APISecurityTester:
    def request(self, flow: http.HTTPFlow) -> None:
        # Modify requests on-the-fly
        if "api.example.com" in flow.request.pretty_url:
            # Test for authorization bypass
            flow.request.headers["X-User-ID"] = "1"

    def response(self, flow: http.HTTPFlow) -> None:
        # Analyze responses
        if flow.response.status_code == 200:
            if "admin" in flow.response.text:
                print(f"[!] Potential privilege escalation: {flow.request.url}")

addons = [APISecurityTester()]

Run mitmproxy with script:

mitmproxy -s api-test.py
# Or for automation
mitmdump -s api-test.py -w results.flow

Review automated findings and captured traffic
Export results for reporting

Workflow 5: SSL/TLS Certificate Pinning Bypass

For testing mobile apps with certificate pinning:

Install mitmproxy CA certificate on device
Use certificate unpinning tools or framework modifications:
- Android: Frida script for SSL unpinning
- iOS: SSL Kill Switch or similar tools
Configure app traffic through mitmproxy

Alternatively, use reverse proxy mode:

mitmproxy --mode reverse:https://api.example.com --listen-host 0.0.0.0 --listen-port 443

Modify /etc/hosts to redirect API domain to mitmproxy
Intercept and analyze traffic normally

Operating Modes

mitmproxy supports multiple deployment modes:

Regular Proxy Mode (default):

mitmproxy --mode regular --listen-port 8080

Client configures proxy settings explicitly.

Transparent Proxy Mode (invisible to client):

mitmproxy --mode transparent --listen-port 8080

Requires iptables/pf rules to redirect traffic.

Reverse Proxy Mode (sits in front of server):

mitmproxy --mode reverse:https://api.example.com --listen-port 443

mitmproxy acts as the server endpoint.

Upstream Proxy Mode (chain proxies):

mitmproxy --mode upstream:http://corporate-proxy:8080

Routes traffic through another proxy.

Certificate Installation

Install mitmproxy CA certificate for HTTPS interception:

Browser/Desktop:

Start mitmproxy and configure proxy settings
Visit http://mitm.it
Download certificate for your platform
Install in system/browser certificate store

Android:

Push certificate to device: adb push ~/.mitmproxy/mitmproxy-ca-cert.cer /sdcard/
Settings → Security → Install from SD card
Select mitmproxy certificate

iOS:

Email certificate or host on web server
Install profile on device
Settings → General → About → Certificate Trust Settings
Enable trust for mitmproxy certificate

Common Patterns

Pattern 1: API Authentication Testing

Test authentication mechanisms and token handling:

# auth-test.py
from mitmproxy import http

class AuthTester:
    def __init__(self):
        self.tokens = []

    def request(self, flow: http.HTTPFlow):
        # Capture auth tokens
        if "authorization" in flow.request.headers:
            token = flow.request.headers["authorization"]
            if token not in self.tokens:
                self.tokens.append(token)
                print(f"[+] Captured token: {token[:20]}...")

        # Test for missing authentication
        if "api.example.com" in flow.request.url:
            flow.request.headers.pop("authorization", None)
            print(f"[*] Testing unauthenticated: {flow.request.path}")

addons = [AuthTester()]

Pattern 2: API Parameter Fuzzing

Fuzz API parameters for injection vulnerabilities:

# fuzz-params.py
from mitmproxy import http

class ParamFuzzer:
    def request(self, flow: http.HTTPFlow):
        if flow.request.method == "POST" and "api.example.com" in flow.request.url:
            # Clone and modify request
            original_body = flow.request.text
            payloads = ["' OR '1'='1", "<script>alert(1)</script>", "../../../etc/passwd"]

            for payload in payloads:
                # Modify parameters and test
                # (Implementation depends on content-type)
                print(f"[*] Testing payload: {payload}")

addons = [ParamFuzzer()]

Pattern 3: GraphQL API Testing

Inspect and test GraphQL APIs:

# graphql-test.py
from mitmproxy import http
import json

class GraphQLTester:
    def request(self, flow: http.HTTPFlow):
        if "/graphql" in flow.request.path:
            try:
                data = json.loads(flow.request.text)
                query = data.get("query", "")
                print(f"[+] GraphQL Query:\n{query}")

                # Test for introspection
                if "__schema" not in query:
                    introspection = {"query": "{__schema{types{name}}}"}
                    print(f"[*] Testing introspection")
            except:
                pass

addons = [GraphQLTester()]

Pattern 4: HAR Export for Analysis

Export traffic as HTTP Archive for analysis:

# Export flows to HAR format
mitmdump -s export-har.py -r captured-traffic.flow

# export-har.py
from mitmproxy import http, ctx
import json

class HARExporter:
    def done(self):
        har_entries = []
        # Build HAR structure
        # (Simplified - use mitmproxy's built-in HAR addon)
        ctx.log.info(f"Exported {len(har_entries)} entries")

addons = [HARExporter()]

Or use built-in addon:

mitmdump --set hardump=./traffic.har

Security Considerations

Sensitive Data Handling: Captured traffic may contain credentials, tokens, PII. Encrypt and secure stored flows. Never commit flow files to version control
Access Control: Restrict access to mitmproxy instance. Use authentication for mitmweb (--web-user/--web-password flags)
Audit Logging: Log all intercepted traffic and modifications for security auditing and compliance
Compliance: Ensure proper authorization before intercepting production traffic. Comply with GDPR, PCI-DSS for sensitive data
Safe Defaults: Use isolated testing environments. Avoid intercepting production traffic without explicit authorization

Integration Points

Penetration Testing Workflow

Reconnaissance: Identify API endpoints via mitmproxy
Authentication testing: Capture and analyze auth tokens
Authorization testing: Modify user IDs, roles, permissions
Input validation: Inject payloads to test for vulnerabilities
Business logic: Test workflows for logical flaws
Export findings as HAR for reporting

CI/CD Integration

Run automated API security tests:

# Run mitmdump with test script in CI
mitmdump -s api-security-tests.py --anticache -w test-results.flow &
PROXY_PID=$!

# Run API tests through proxy
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080
pytest tests/api_tests.py

# Stop proxy and analyze results
kill $PROXY_PID
python3 analyze-results.py test-results.flow

Mobile App Security Testing

Standard workflow for iOS/Android apps:

Configure device to use mitmproxy
Install CA certificate
Bypass SSL pinning if needed
Exercise app functionality
Analyze API security (OWASP Mobile Top 10)
Document API vulnerabilities

Advanced Features

Traffic Filtering

Filter displayed traffic by expression:

# Show only API calls
mitmproxy --view-filter '~d api.example.com'

# Show only POST requests
mitmproxy --view-filter '~m POST'

# Show responses with specific status
mitmproxy --view-filter '~c 401'

# Combine filters
mitmproxy --view-filter '~d api.example.com & ~m POST'

Request/Response Modification

Modify traffic using built-in mappers:

# Replace request headers
mitmproxy --modify-headers '/~u example/Authorization/Bearer fake-token'

# Replace response body
mitmproxy --modify-body '/~s & ~b "error"/success'

WebSocket Interception

Intercept and modify WebSocket traffic:

# websocket-test.py
from mitmproxy import websocket

class WebSocketTester:
    def websocket_message(self, flow):
        message = flow.messages[-1]
        print(f"[+] WebSocket: {message.content[:100]}")

        # Modify messages
        if message.from_client:
            message.content = message.content.replace(b"user", b"admin")

addons = [WebSocketTester()]

Troubleshooting

Issue: SSL Certificate Errors

Solution: Ensure mitmproxy CA certificate is properly installed and trusted:

# Verify certificate location
ls ~/.mitmproxy/

# Regenerate certificates if needed
rm -rf ~/.mitmproxy/
mitmproxy  # Regenerates on startup

Issue: Mobile App Not Sending Traffic Through Proxy

Solution:

Verify WiFi proxy configuration
Check firewall rules aren't blocking proxy port
Ensure mitmproxy is listening on correct interface (0.0.0.0)
Test with browser first to verify proxy works

Issue: Certificate Pinning Blocking Interception

Solution: Use SSL unpinning tools:

# Android with Frida
frida -U -l universal-android-ssl-pinning-bypass.js -f com.example.app

# Or modify app to disable pinning (development builds)

Issue: Cannot Intercept HTTP/2 or HTTP/3

Solution: mitmproxy supports HTTP/2 by default. For HTTP/3:

# Enable HTTP/3 support (experimental)
mitmproxy --set http3=true

OWASP API Security Top 10 Testing

Use mitmproxy to test for OWASP API Security Top 10 vulnerabilities:

API1: Broken Object Level Authorization - Modify object IDs in requests
API2: Broken Authentication - Test token validation, session management
API3: Broken Object Property Level Authorization - Test for mass assignment
API4: Unrestricted Resource Consumption - Test rate limiting, pagination
API5: Broken Function Level Authorization - Modify roles, escalate privileges
API6: Unrestricted Access to Sensitive Business Flows - Test business logic
API7: Server Side Request Forgery - Inject URLs in parameters
API8: Security Misconfiguration - Check headers, CORS, error messages
API9: Improper Inventory Management - Enumerate undocumented endpoints
API10: Unsafe Consumption of APIs - Test third-party API integrations

Agent Skills: mitmproxy API Security Testing

Install this agent skill to your local

Skill Files