mitm2openapi

Convert mitmproxy flow dumps and HAR files to OpenAPI 3.0 — fast, single binary, no Python.

A Rust rewrite of mitmproxy2swagger.

Why?

mitmproxy2swagger (the Python original by @alufers) works well, but requires Python, pip, and mitmproxy installed in the environment. For CI pipelines, slim Docker images, security audits, and one-off usage that's friction.

mitm2openapi ships as a single ~5 MB static binary — drop it into any environment, no runtime, no venv, no pip install. Same OpenAPI 3.0 output as the original, plus first-class HAR support and glob-based filters for fully unattended pipelines.

Credit to @alufers for the original tool that pioneered this workflow.

Features

• Fast — pure Rust, single-threaded, processes captures in milliseconds
• Single static binary — no Python, no venv, no pip, no runtime dependencies
• Two-format support — mitmproxy flow dumps (v19/v20/v21) and HAR 1.2
• Two-step workflow — discover finds endpoints, you curate, generate emits clean OpenAPI 3.0
• Glob filters — --exclude-patterns and --include-patterns for automated pipelines
• Error recovery — skips corrupt flows, continues processing
• Auto-detection — heuristic format detection from file content
• Battle-tested — integration tests against Swagger Petstore and OWASP crAPI with oasdiff verification
• Cross-platform — Linux, macOS, Windows pre-built binaries

Installation

From binary releases

Download a pre-built binary from GitHub Releases.

From source

cargo install --git https://github.com/Arkptz/mitm2openapi

Quick Start

# 1. Capture traffic with mitmproxy
mitmdump -w capture.flow

# 2. Discover API endpoints
mitm2openapi discover -i capture.flow -o templates.yaml -p "https://api.example.com"

# 3. Edit templates.yaml — remove 'ignore:' prefix from paths you want to include

# 4. Generate OpenAPI spec
mitm2openapi generate -i capture.flow -t templates.yaml -o openapi.yaml -p "https://api.example.com"

Skip the manual edit

If you know which paths you care about up front, use --exclude-patterns and --include-patterns to let discover do the curation:

mitm2openapi discover \
  -i capture.flow -o templates.yaml -p "https://api.example.com" \
  --exclude-patterns '/static/**,/images/**,*.css,*.js,*.svg' \
  --include-patterns '/api/**,/v2/**'

mitm2openapi generate \
  -i capture.flow -t templates.yaml -o openapi.yaml -p "https://api.example.com"

Paths matching --include-patterns are auto-activated (emitted without the ignore: prefix). Paths matching --exclude-patterns are dropped entirely. Everything else still gets ignore: for manual review.

discover

Scan captured traffic and produce a templates file listing all observed endpoints.

mitm2openapi discover [OPTIONS] -i <INPUT> -o <OUTPUT> -p <PREFIX>

generate

Generate an OpenAPI 3.0 spec from captured traffic using a curated templates file.

mitm2openapi generate [OPTIONS] -i <INPUT> -t <TEMPLATES> -o <OUTPUT> -p <PREFIX>

Resource Limits

To prevent denial-of-service when processing untrusted captures, mitm2openapi enforces several configurable limits:

In addition to the configurable limits above, the following per-field caps are applied unconditionally to prevent data corruption:

Identity fields (scheme, host, path, method, header names) require valid UTF-8. Flows with non-UTF-8 identity bytes are skipped to prevent data aliasing through replacement-character collisions. Control characters in paths are stripped automatically.

Increase --max-input-size if you work with captures larger than 2 GiB (e.g. --max-input-size 8GiB). The other limits rarely need tuning.

Both mitmproxy flow files and HAR files are processed incrementally — memory usage stays bounded regardless of input size.

Diagnostics

When the tnetstring parser encounters corruption in a mitmproxy flow file, it halts and emits a warn-level log with the byte offset, number of successfully parsed entries, and an error classification. No resync is attempted — binary payloads can contain bytes that mimic valid tnetstring length prefixes, so scanning forward would produce phantom flows.

Structured report (--report)

Pass --report <PATH> to either discover or generate to write a JSON processing summary. This is useful for CI pipelines that need structured data instead of log scraping.

{
  "report_version": 1,
  "tool_version": "0.2.3",
  "input": {
    "path": "capture.flow",
    "format": "Auto",
    "size_bytes": 102400
  },
  "result": {
    "flows_read": 150,
    "flows_emitted": 148,
    "paths_in_spec": 12
  },
  "events": {
    "parse_error": {
      "TNetString parse error at byte 98304: unexpected end of input": 1
    }
  }
}

Strict mode

Pass --strict to either discover or generate to treat any warning-level event as a hard failure. The process exits with code 2 if any resource cap fired, a flow was rejected, or a parse error was encountered.

This is designed for CI gates where silent degradation is unacceptable:

mitm2openapi discover -i capture.flow -o templates.yaml -p https://api.example.com --strict \
  || echo "FAIL: corrupt or over-limit flows detected"

Without --strict, the same conditions are logged at warn level and processing continues (exit code 0).

Supported Formats

Format is auto-detected from file content. Use --format to override.

Migration from Python mitmproxy2swagger

Key differences

• Two-step workflow: discover produces a templates file; you curate it; generate produces the final spec. This separates endpoint selection from spec generation.
• Templates file: Discovered endpoints are prefixed with ignore:. Remove the prefix to include an endpoint. This replaces editing the output spec directly.
• No Python dependency: Ships as a single static binary for Linux, macOS, and Windows.
• HAR support: Process HAR exports from browser DevTools or other HTTP tools.

Benchmarks

A GitHub Actions workflow runs hyperfine against the release binary on every push to main. Results are uploaded as build artifacts for manual inspection. No automated regression gate is enforced yet — the artifacts provide a historical record for eyeballing trends.

Contributing

Contributions welcome! See CONTRIBUTING.md for local testing setup (unit tests, Petstore golden test, crAPI integration, demo GIF pipeline).

License

MIT