api-mitmproxy

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:

1. Start mitmproxy or mitmweb:

```bash # 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 ```

1. Configure target application to use proxy (HTTP: localhost:8080)
2. Install mitmproxy CA certificate on client device
3. Trigger API requests from the application
4. Intercept and inspect requests/responses in mitmproxy
5. Modify requests to test:
6. Authentication bypass attempts
7. Authorization flaws (IDOR, privilege escalation)
8. Input validation (SQLi, XSS, command injection)
9. Business logic vulnerabilities
10. 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:

1. Start mitmdump with flow capture:

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

1. Run automated tests or manual app interaction
2. Stop mitmdump (Ctrl+C) to save flows
3. Replay captured traffic:

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

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

1. Export to HAR format for analysis:

``bash # 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:

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

```python 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()] ```

1. Run mitmproxy with script:

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

1. Review automated findings and captured traffic
2. Export results for reporting

Workflow 5: SSL/TLS Certificate Pinning Bypass

For testing mobile apps with certificate pinning:

1. Install mitmproxy CA certificate on device
2. Use certificate unpinning tools or framework modifications:
3. Android: Frida script for SSL unpinning
4. iOS: SSL Kill Switch or similar tools
5. Configure app traffic through mitmproxy
6. Alternatively, use reverse proxy mode:

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

1. Modify /etc/hosts to redirect API domain to mitmproxy
2. 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:

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

Android:

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

iOS:

1. Email certificate or host on web server
2. Install profile on device
3. Settings → General → About → Certificate Trust Settings
4. 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}")