/api-mitmproxy

name: api-mitmproxy
description: >
  Interactive HTTPS proxy for API security testing with traffic interception, modification, and
  replay capabilities. Supports HTTP/1, HTTP/2, HTTP/3, WebSockets, and TLS-protected protocols.
  Includes Python scripting API for automation and multiple interfaces (console, web, CLI). Use when:
  (1) Intercepting and analyzing API traffic for security testing, (2) Modifying HTTP/HTTPS requests
  and responses to test API behavior, (3) Recording and replaying API traffic for testing, (4)
  Debugging mobile app or thick client API communications, (5) Automating API security tests with
  Python scripts, (6) Exporting traffic in HAR format for analysis.
version: 0.1.0
maintainer: SirAppSec
category: appsec
tags: [api-testing, proxy, https, intercepting-proxy, traffic-analysis, mitmproxy, har-export, websockets]
frameworks: [OWASP]
dependencies:
  python: ">=3.9"
  tools: [mitmproxy, mitmweb, mitmdump]
references:
  - https://mitmproxy.org/
  - https://docs.mitmproxy.org/

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:

   # 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

2. Configure target application to use proxy (HTTP: localhost:8080) 3. Install mitmproxy CA certificate on client device 4. Trigger API requests from the application 5. Intercept and inspect requests/responses in mitmproxy 6. Modify requests to test:

• Authentication bypass attempts
• Authorization flaws (IDOR, privilege escalation)
• Input validation (SQLi, XSS, command injection)
• Business logic vulnerabilities

7. 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:

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

2. Run automated tests or manual app interaction 3. Stop mitmdump (Ctrl+C) to save flows 4. 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

5. 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:

1. 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()]

2. Run mitmproxy with script:

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

3. Review automated findings and captured traffic 4. 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:

• Android: Frida script for SSL unpinning
• iOS: SSL Kill Switch or similar tools

3. Configure app traffic through mitmproxy 4. Alternatively, use reverse proxy mode:

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

5. Modify /etc/hosts to redirect API domain to mitmproxy 6. 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**