{"id":49176070,"url":"https://github.com/arkptz/mitm2openapi","last_synced_at":"2026-04-27T02:00:37.309Z","repository":{"id":352662541,"uuid":"1216182687","full_name":"Arkptz/mitm2openapi","owner":"Arkptz","description":"Convert mitmproxy flow dumps and HAR files to OpenAPI 3.0 — fast Rust alternative to mitmproxy2swagger with HAR support","archived":false,"fork":false,"pushed_at":"2026-04-24T23:10:30.000Z","size":85907,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T00:02:44.431Z","etag":null,"topics":["api","api-documentation","cli","har","mitmproxy","mitmproxy2swagger","openapi","openapi-generator","reverse-engineering","rust","rust-cli","swagger"],"latest_commit_sha":null,"homepage":"https://arkptz.github.io/mitm2openapi/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Arkptz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T16:46:11.000Z","updated_at":"2026-04-24T23:20:19.000Z","dependencies_parsed_at":"2026-04-25T00:01:04.321Z","dependency_job_id":null,"html_url":"https://github.com/Arkptz/mitm2openapi","commit_stats":null,"previous_names":["arkptz/mitm2openapi"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/Arkptz/mitm2openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arkptz%2Fmitm2openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arkptz%2Fmitm2openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arkptz%2Fmitm2openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arkptz%2Fmitm2openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Arkptz","download_url":"https://codeload.github.com/Arkptz/mitm2openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arkptz%2Fmitm2openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32282187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-documentation","cli","har","mitmproxy","mitmproxy2swagger","openapi","openapi-generator","reverse-engineering","rust","rust-cli","swagger"],"created_at":"2026-04-22T22:05:32.067Z","updated_at":"2026-04-26T01:00:49.859Z","avatar_url":"https://github.com/Arkptz.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# mitm2openapi\n\n**Convert mitmproxy flow dumps and HAR files to OpenAPI 3.0 — fast, single binary, no Python.**\n\nA Rust rewrite of [mitmproxy2swagger](https://github.com/alufers/mitmproxy2swagger).\n\n[![CI](https://github.com/Arkptz/mitm2openapi/actions/workflows/ci.yml/badge.svg)](https://github.com/Arkptz/mitm2openapi/actions/workflows/ci.yml)\n[![Nightly Integration](https://github.com/Arkptz/mitm2openapi/actions/workflows/integration-level2.yml/badge.svg)](https://github.com/Arkptz/mitm2openapi/actions/workflows/integration-level2.yml)\n[![Crates.io](https://img.shields.io/crates/v/mitm2openapi.svg)](https://crates.io/crates/mitm2openapi)\n[![Downloads](https://img.shields.io/crates/d/mitm2openapi.svg)](https://crates.io/crates/mitm2openapi)\n[![docs.rs](https://img.shields.io/docsrs/mitm2openapi)](https://docs.rs/mitm2openapi)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n\u003cimg src=\"docs/demo.gif\" alt=\"Demo: capture → discover → generate → browse Swagger UI\" width=\"720\"\u003e\n\n\u003c/div\u003e\n\n## Why?\n\n[mitmproxy2swagger](https://github.com/alufers/mitmproxy2swagger) (the Python original by [@alufers](https://github.com/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.\n\n`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.\n\nCredit to [@alufers](https://github.com/alufers) for the original tool that pioneered this workflow.\n\n## Features\n\n- **Fast** — pure Rust, single-threaded, processes captures in milliseconds\n- **Single static binary** — no Python, no venv, no pip, no runtime dependencies\n- **Two-format support** — mitmproxy flow dumps (v19/v20/v21) and HAR 1.2\n- **Two-step workflow** — `discover` finds endpoints, you curate, `generate` emits clean OpenAPI 3.0\n- **Glob filters** — `--exclude-patterns` and `--include-patterns` for automated pipelines\n- **Error recovery** — skips corrupt flows, continues processing\n- **Auto-detection** — heuristic format detection from file content\n- **Battle-tested** — integration tests against Swagger Petstore and OWASP crAPI with `oasdiff` verification\n- **Cross-platform** — Linux, macOS, Windows pre-built binaries\n\n## Installation\n\n### From binary releases\n\nDownload a pre-built binary from [GitHub Releases](https://github.com/Arkptz/mitm2openapi/releases).\n\n### From source\n\n```bash\ncargo install --git https://github.com/Arkptz/mitm2openapi\n```\n\n## Quick Start\n\n```bash\n# 1. Capture traffic with mitmproxy\nmitmdump -w capture.flow\n\n# 2. Discover API endpoints\nmitm2openapi discover -i capture.flow -o templates.yaml -p \"https://api.example.com\"\n\n# 3. Edit templates.yaml — remove 'ignore:' prefix from paths you want to include\n\n# 4. Generate OpenAPI spec\nmitm2openapi generate -i capture.flow -t templates.yaml -o openapi.yaml -p \"https://api.example.com\"\n```\n\n### Skip the manual edit\n\nIf you know which paths you care about up front, use `--exclude-patterns`\nand `--include-patterns` to let `discover` do the curation:\n\n```bash\nmitm2openapi discover \\\n  -i capture.flow -o templates.yaml -p \"https://api.example.com\" \\\n  --exclude-patterns '/static/**,/images/**,*.css,*.js,*.svg' \\\n  --include-patterns '/api/**,/v2/**'\n\nmitm2openapi generate \\\n  -i capture.flow -t templates.yaml -o openapi.yaml -p \"https://api.example.com\"\n```\n\nPaths matching `--include-patterns` are auto-activated (emitted without\nthe `ignore:` prefix). Paths matching `--exclude-patterns` are dropped\nentirely. Everything else still gets `ignore:` for manual review.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCLI Reference\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n### `discover`\n\nScan captured traffic and produce a templates file listing all observed endpoints.\n\n```\nmitm2openapi discover [OPTIONS] -i \u003cINPUT\u003e -o \u003cOUTPUT\u003e -p \u003cPREFIX\u003e\n```\n\n| Option | Description |\n|--------|-------------|\n| `-i, --input \u003cPATH\u003e` | Input file (flow dump or HAR) |\n| `-o, --output \u003cPATH\u003e` | Output YAML templates file |\n| `-p, --prefix \u003cURL\u003e` | API prefix URL to filter requests |\n| `--format \u003cFORMAT\u003e` | Input format: `auto`, `har`, `mitmproxy` (default: `auto`) |\n| `--exclude-patterns \u003cGLOBS\u003e` | Comma-separated globs; matching paths are dropped entirely. `*` = single segment, `**` = any subtree. E.g. `/static/**,*.css` |\n| `--include-patterns \u003cGLOBS\u003e` | Comma-separated globs; matching paths are emitted without `ignore:` (auto-activated for `generate`) |\n| `--max-input-size \u003cBYTES\u003e` | Maximum input file size (default: `2GiB`). Accepts suffixes: `KiB`, `MiB`, `GiB` |\n| `--allow-symlinks` | Allow symlinked input files (default: rejected for safety) |\n| `--strict` | Treat warnings as errors; exit code 2 if any cap fires, flow is rejected, or parse error occurs |\n| `--report \u003cPATH\u003e` | Write a structured JSON processing report to the given path |\n\n### `generate`\n\nGenerate an OpenAPI 3.0 spec from captured traffic using a curated templates file.\n\n```\nmitm2openapi generate [OPTIONS] -i \u003cINPUT\u003e -t \u003cTEMPLATES\u003e -o \u003cOUTPUT\u003e -p \u003cPREFIX\u003e\n```\n\n| Option | Description |\n|--------|-------------|\n| `-i, --input \u003cPATH\u003e` | Input file (flow dump or HAR) |\n| `-t, --templates \u003cPATH\u003e` | Templates YAML file (from `discover`) |\n| `-o, --output \u003cPATH\u003e` | Output OpenAPI YAML file |\n| `-p, --prefix \u003cURL\u003e` | API prefix URL |\n| `--format \u003cFORMAT\u003e` | Input format: `auto`, `har`, `mitmproxy` (default: `auto`) |\n| `--openapi-title \u003cTITLE\u003e` | Custom title for the spec |\n| `--openapi-version \u003cVER\u003e` | Custom spec version (default: `1.0.0`) |\n| `--exclude-headers \u003cLIST\u003e` | Comma-separated headers to exclude |\n| `--exclude-cookies \u003cLIST\u003e` | Comma-separated cookies to exclude |\n| `--include-headers` | Include headers in the spec |\n| `--ignore-images` | Ignore image content types |\n| `--suppress-params` | Suppress parameter suggestions |\n| `--tags-overrides \u003cJSON\u003e` | JSON string for tag overrides |\n| `--max-input-size \u003cBYTES\u003e` | Maximum input file size (default: `2GiB`). Accepts suffixes: `KiB`, `MiB`, `GiB` |\n| `--max-payload-size \u003cBYTES\u003e` | Maximum tnetstring payload size (default: `256MiB`) |\n| `--max-depth \u003cN\u003e` | Maximum tnetstring nesting depth (default: `256`) |\n| `--max-body-size \u003cBYTES\u003e` | Maximum request/response body size (default: `64MiB`) |\n| `--allow-symlinks` | Allow symlinked input files (default: rejected for safety) |\n| `--strict` | Treat warnings as errors; exit code 2 if any cap fires, flow is rejected, or parse error occurs |\n| `--report \u003cPATH\u003e` | Write a structured JSON processing report to the given path |\n\n\u003c/details\u003e\n\n## Resource Limits\n\nTo prevent denial-of-service when processing untrusted captures, `mitm2openapi`\nenforces several configurable limits:\n\n| Flag | Default | Purpose |\n|------|---------|---------|\n| `--max-input-size` | 2 GiB | Reject files larger than this before reading |\n| `--max-payload-size` | 256 MiB | Cap on individual tnetstring payload allocation |\n| `--max-depth` | 256 | Recursion depth limit for nested tnetstring structures |\n| `--max-body-size` | 64 MiB | Maximum request/response body considered during schema inference |\n| `--allow-symlinks` | off | By default, symlinked inputs are rejected to prevent path-traversal on shared CI runners |\n\nIn addition to the configurable limits above, the following per-field caps are\napplied unconditionally to prevent data corruption:\n\n| Field | Cap | Behaviour |\n|-------|-----|-----------|\n| Header name | 8 KiB | Dropped (other headers still processed) |\n| Header value | 64 KiB | Truncated to cap |\n| Form fields per request | 1 000 | Excess fields ignored |\n| URL scheme | `http` / `https` only | Non-HTTP flows silently skipped |\n| Port number | 1–65 535 | Out-of-range port drops the request |\n| HTTP status code | 100–599 | Invalid codes treated as no response |\n\nIdentity fields (scheme, host, path, method, header names) require valid UTF-8.\nFlows with non-UTF-8 identity bytes are skipped to prevent data aliasing through\nreplacement-character collisions. Control characters in paths are stripped\nautomatically.\n\nIncrease `--max-input-size` if you work with captures larger than 2 GiB (e.g.\n`--max-input-size 8GiB`). The other limits rarely need tuning.\n\nBoth mitmproxy flow files and HAR files are processed incrementally — memory usage\nstays bounded regardless of input size.\n\n## Diagnostics\n\nWhen the tnetstring parser encounters corruption in a mitmproxy flow file, it\nhalts and emits a warn-level log with the byte offset, number of successfully\nparsed entries, and an error classification. No resync is attempted — binary\npayloads can contain bytes that mimic valid tnetstring length prefixes, so\nscanning forward would produce phantom flows.\n\n### Structured report (`--report`)\n\nPass `--report \u003cPATH\u003e` to either `discover` or `generate` to write a JSON\nprocessing summary. This is useful for CI pipelines that need structured data\ninstead of log scraping.\n\n```json\n{\n  \"report_version\": 1,\n  \"tool_version\": \"0.2.3\",\n  \"input\": {\n    \"path\": \"capture.flow\",\n    \"format\": \"Auto\",\n    \"size_bytes\": 102400\n  },\n  \"result\": {\n    \"flows_read\": 150,\n    \"flows_emitted\": 148,\n    \"paths_in_spec\": 12\n  },\n  \"events\": {\n    \"parse_error\": {\n      \"TNetString parse error at byte 98304: unexpected end of input\": 1\n    }\n  }\n}\n```\n\n### Strict mode\n\nPass `--strict` to either `discover` or `generate` to treat any warning-level\nevent as a hard failure. The process exits with code 2 if any resource cap\nfired, a flow was rejected, or a parse error was encountered.\n\nThis is designed for CI gates where silent degradation is unacceptable:\n\n```bash\nmitm2openapi discover -i capture.flow -o templates.yaml -p https://api.example.com --strict \\\n  || echo \"FAIL: corrupt or over-limit flows detected\"\n```\n\nWithout `--strict`, the same conditions are logged at warn level and processing\ncontinues (exit code 0).\n\n## Supported Formats\n\n| Format | Versions | Extension |\n|--------|----------|-----------|\n| mitmproxy flow dumps | v19, v20, v21 | `.flow` |\n| HAR (HTTP Archive) | 1.2 (incrementally parsed) | `.har` |\n\nFormat is auto-detected from file content. Use `--format` to override.\n\n## Migration from Python mitmproxy2swagger\n\n| Python (`mitmproxy2swagger`) | Rust (`mitm2openapi`) |\n|-----|-----|\n| `pip install mitmproxy2swagger` | Single binary, no runtime |\n| `mitmproxy2swagger -i \u003cfile\u003e -o \u003cspec\u003e -p \u003cprefix\u003e` | Two-step: `discover` then `generate` |\n| Edits spec file in-place | Separate templates file for curation |\n| Requires Python 3.x + mitmproxy | Standalone binary |\n| Supports mitmproxy only | Supports mitmproxy flow dumps + HAR |\n\n### Key differences\n\n- **Two-step workflow**: `discover` produces a templates file; you curate it; `generate` produces the final spec. This separates endpoint selection from spec generation.\n- **Templates file**: Discovered endpoints are prefixed with `ignore:`. Remove the prefix to include an endpoint. This replaces editing the output spec directly.\n- **No Python dependency**: Ships as a single static binary for Linux, macOS, and Windows.\n- **HAR support**: Process HAR exports from browser DevTools or other HTTP tools.\n\n## Benchmarks\n\nA [GitHub Actions workflow](.github/workflows/bench.yml) runs `hyperfine`\nagainst the release binary on every push to `main`. Results are uploaded as\nbuild artifacts for manual inspection. No automated regression gate is enforced\nyet — the artifacts provide a historical record for eyeballing trends.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for local testing setup (unit tests, Petstore golden test, crAPI integration, demo GIF pipeline).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkptz%2Fmitm2openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farkptz%2Fmitm2openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkptz%2Fmitm2openapi/lists"}