mitm-cascade 🌊

中文 | English

Convert mitmproxy flows to Chrome-like waterfall charts for visualization.

Features:

• 📁 Support .mitm and HAR file input
• 🐍 Automatically capture HTTP requests from Python scripts
• 📊 Generate Chrome-style waterfall chart visualizations
• 🌐 Built-in web server for real-time visualization
• 🔍 Powerful filtering and sorting capabilities

Installation

From Source

# Clone the repository
git clone https://github.com/chokwinlee/mitm-cascade.git
cd mitm-cascade

# Using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e .

# Or using pip
pip install -e .

Install Development Dependencies

pip install -e ".[dev]"

Usage

Basic Usage

1. Convert from File

mitm-cascade input.mitm --format json --out cascade.json

2. Capture Python Script Requests (New Feature!)

# Run Python script and automatically capture HTTP requests
mitm-cascade python -m examples.test_requests --format json

# Or run script file directly
mitm-cascade python examples/test_requests.py --format json

# Start web server for visualization
mitm-cascade python examples/test_requests.py --serve

Options

Common Options:

• --format: Output format, json or perf-cascade (default: json)
• --out: Output file path (default: stdout)
• --filter-url <regex>: Filter entries by URL regex pattern
• --filter-method <GET|POST|...>: Filter entries by HTTP method
• --sort <start|duration>: Sort entries by field (default: start)
• --limit N: Limit number of entries to output
• --serve: Start web server for visualization (auto-opens browser)
• --serve-port <port>: Port for web visualization server (default: 18000)

Python Capture Mode Options:

• --proxy-port <port>: Port for mitmproxy to listen on (default: 8080)
• --timeout <seconds>: Timeout for script execution

Examples

File Mode

# Export to JSON
mitm-cascade sample.mitm --format json --out output.json

# Export to perf-cascade format
mitm-cascade sample.mitm --format perf-cascade --out cascade.json

# Filter specific URLs
mitm-cascade sample.mitm --filter-url ".*\.js$" --format json

# Show only GET requests
mitm-cascade sample.mitm --filter-method GET --format json

Python Script Capture Mode

# Capture script requests and export to JSON
mitm-cascade python examples/test_requests.py --format json --out output.json

# Run as module
mitm-cascade python -m examples.test_requests --format json

# Start web visualization (auto-opens browser)
mitm-cascade python examples/test_requests.py --serve

# Specify proxy port
mitm-cascade python examples/test_requests.py --proxy-port 8081 --format json

Project Structure

mitm_cascade/
├── cli.py                 # CLI entry point
├── capture.py             # Python script capture
├── server.py              # Web visualization server
├── reader/
│   ├── __init__.py
│   ├── mitm_reader.py    # mitm file parser
│   └── har_reader.py      # HAR file parser
├── model/
│   ├── __init__.py
│   └── cascade_entry.py  # Data model
├── exporter/
│   ├── __init__.py
│   ├── json_exporter.py  # JSON export
│   └── perf_cascade_exporter.py  # perf-cascade export
└── tests/
    ├── test_mitm_reader.py
    ├── test_har_reader.py
    ├── test_exporter.py
    └── fixtures/         # Test data

Development

Install Development Dependencies

pip install -e ".[dev]"

Run Tests

pytest

Code Formatting

black mitm_cascade tests

Type Checking

mypy mitm_cascade

Examples

The project includes example files in the examples/ directory:

# Use sample HAR file
mitm-cascade examples/sample.har --format json --out output.json

How It Works

1. Read Input: Auto-detect .mitm or .har file format
2. Parse Flows: Extract timing information for each HTTP request
3. Normalize Model: Convert to unified CascadeEntry data model
4. Export Format: Support JSON and perf-cascade compatible formats

Data Model

Each cascade entry contains:

• id: Unique identifier
• url: Request URL
• method: HTTP method
• startTime: Start time (milliseconds since epoch)
• duration: Total duration (milliseconds)
• timings: Detailed timing breakdown
  • blocked: Blocking time
  • dns: DNS lookup time
  • connect: TCP connection time
  • ssl: SSL/TLS handshake time
  • send: Request send time
  • wait: Wait time (TTFB - Time To First Byte)
  • receive: Response receive time

Limitations

• mitmproxy files may not contain all timing information; the tool will estimate when possible
• HAR files must conform to HAR 1.2 specification
• Some edge cases (e.g., missing responses) may not be fully handled

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

This project is licensed under the MIT License. See LICENSE file for details.

Related Projects

• mitmproxy - Interactive HTTP(S) proxy
• perf-cascade - Performance waterfall visualization

Acknowledgments

Thanks to all contributors and users for their support!

---

中文 | English