--- description: Capture browser traffic via mitmproxy, generate OpenAPI 3.0 specs with mitmproxy2swagger, and replay/test with hargo. category: personal --- flowchart TD _HEADER_[""]:::headerStyle classDef headerStyle fill:none,stroke:none subgraph _MAIN_[" "] %% Phase 1: Setup & Install subgraph Setup["Phase 1: Setup"] INSTALL[Install Toolchain] --> CERT[Trust CA Certificate] CERT --> CHOOSE{Capture Mode?} end %% Phase 2: Traffic Capture subgraph Capture["Phase 2: Traffic Capture"] CHOOSE -->|Headless| MITMDUMP[mitmdump Headless Capture] CHOOSE -->|Interactive TUI| MITMPROXY[mitmproxy TUI] CHOOSE -->|Web UI| MITMWEB[mitmweb Browser UI] CHOOSE -->|Reverse Proxy| REVERSE[Reverse Proxy Mode] CHOOSE -->|Automated| PLAYWRIGHT[Playwright + mitmproxy] MITMDUMP --> BROWSE[Browse Target Site] MITMPROXY --> BROWSE MITMWEB --> BROWSE REVERSE --> BROWSE PLAYWRIGHT --> HAR_OUT BROWSE --> STOP[Stop Capture] STOP --> HAR_OUT[HAR File Output] end %% Phase 3: Spec Generation (Two-Pass) subgraph SpecGen["Phase 3: OpenAPI Spec Generation"] HAR_OUT --> PASS1[Pass 1: Discover Endpoints] PASS1 --> EDIT_SPEC[Edit spec.yaml] EDIT_SPEC --> PASS2[Pass 2: Generate with Examples] PASS2 --> SPEC_OUT[OpenAPI 3.0 Spec] end %% Phase 4: Analysis & Testing subgraph Analysis["Phase 4: Analysis and Testing"] HAR_OUT --> CURL[Export curl Commands] HAR_OUT --> REPLAY[Replay Requests] HAR_OUT --> LOADTEST[Load Test] HAR_OUT --> DUMP[Dump and Analyze HAR] SPEC_OUT --> VALIDATE[Validate Spec] end %% Phase 5: Iterative Discovery (optional loop) subgraph Iterate["Phase 5: Multi-Session Discovery"] SPEC_OUT --> MORE{More Flows?} MORE -->|Yes| NEW_SESSION[New Capture Session] NEW_SESSION --> MITMDUMP MORE -->|No| FINAL[Final API Spec] end %% Redaction sidecar REDACT[Redact Sensitive Data] -.-> MITMDUMP REDACT -.-> MITMPROXY click INSTALL "#" "**Install Toolchain**\nInstall all required tools:\n- `brew install mitmproxy` (includes mitmdump, mitmweb)\n- `pip install mitmproxy2swagger`\n- `brew install hargo` (or `go install github.com/mrichman/hargo@latest`)\n- `brew install webp` (optional, for cwebp)" click CERT "#" "**Trust CA Certificate**\nOne-time setup for HTTPS interception:\n\n`mitmdump &`\n`sleep 2`\n`kill %1`\n`sudo security add-trusted-cert -d -p ssl -p basic -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem`\n\nWithout this, HTTPS traffic cannot be decrypted." click CHOOSE "#" "**Choose Capture Mode**\nPick the right mode for your use case:\n- *Headless* (mitmdump): automation, scripting\n- *Interactive TUI* (mitmproxy): manual exploration\n- *Web UI* (mitmweb): visual traffic inspection\n- *Reverse Proxy*: when browser proxy config is not possible\n- *Automated* (Playwright): repeatable scripted captures" click MITMDUMP "#" "**mitmdump Headless Capture**\nCLI capture with filter expressions:\n\n`mitmdump -q --set hardump=capture.har '~d api.example.com'`\n\nCommon filters:\n- `~d domain` - match domain\n- `~t json` - content-type JSON\n- `!(~t image)` - exclude images\n- `~m POST` - HTTP method\n- `~c 500` - status code" click MITMPROXY "#" "**mitmproxy Interactive TUI**\nTerminal UI for exploring traffic in real time:\n\n`mitmproxy '~d api.example.com'`\n\nFeatures:\n- Live request/response inspection\n- Flow filtering and search\n- Export flows to HAR\n- Inline request editing" click MITMWEB "#" "**mitmweb Browser UI**\nWeb-based traffic inspector at http://localhost:8081:\n\n`mitmweb`\n\nThen configure Chrome to use the proxy:\n`open -a 'Google Chrome' --args --proxy-server='http://localhost:8080'`\n\nUse File > Save to export flows." click REVERSE "#" "**Reverse Proxy Mode**\nCapture without configuring the browser proxy.\nClients hit localhost, traffic is forwarded to the real server:\n\n`mitmdump --mode reverse:https://api.example.com -p 8080 --set hardump=capture.har`\n\nPoint your app at localhost:8080 instead of the real API." click PLAYWRIGHT "#" "**Playwright + mitmproxy**\nAutomated, repeatable capture using a Python script.\n\nStart mitmdump in a subprocess, launch Playwright Chromium through the proxy, script the browsing flow (login, navigate, exercise endpoints), then stop and generate the spec.\n\nSee `examples.md` Example 2 for the full script." click BROWSE "#" "**Browse Target Site**\nLaunch Chrome through the proxy:\n\n`open -a 'Google Chrome' --args --proxy-server='http://localhost:8080' 'https://example.com'`\n\nClick through every feature you want to capture:\n- Login and authentication flows\n- CRUD operations\n- Settings and admin pages\n- Edge cases and error states\n\nMore coverage = better spec." click STOP "#" "**Stop Capture**\nPress Ctrl+C to stop mitmdump/mitmproxy.\nFlows are flushed to the HAR file on exit." click HAR_OUT "#" "**HAR File Output**\nHTTP Archive format containing all captured requests and responses.\n\nIncludes:\n- Full request/response headers\n- Request/response bodies\n- Timing information\n- Status codes\n\nUsed as input for both spec generation and analysis." click PASS1 "#" "**Pass 1: Discover Endpoints**\nFirst pass discovers all API paths:\n\n`mitmproxy2swagger -i capture.har -o spec.yaml -p https://api.example.com`\n\nGenerates spec.yaml with all discovered paths prefixed with `ignore:` by default." click EDIT_SPEC "#" "**Edit spec.yaml**\nManual curation step:\n- Remove `ignore:` from real API paths\n- Keep `ignore:` on static assets, tracking, analytics\n- Parameterize IDs: `/users/123` becomes `/users/{user_id}`\n- Order: specific paths BEFORE generic `{id}` patterns\n- Add descriptions where helpful" click PASS2 "#" "**Pass 2: Generate with Examples**\nSecond pass enriches the spec with request/response examples:\n\n`mitmproxy2swagger -i capture.har -o spec.yaml -p https://api.example.com --examples`\n\nThe `--examples` flag adds real request/response bodies from the HAR as OpenAPI examples." click SPEC_OUT "#" "**OpenAPI 3.0 Spec**\nThe final `spec.yaml` is a valid OpenAPI 3.0 document.\n\nContains:\n- All discovered endpoints with methods\n- Request/response schemas\n- Real-world examples from captured traffic\n- Path parameters\n\nCan be imported into Swagger UI, Postman, or used for code generation." click CURL "#" "**Export curl Commands**\nConvert HAR entries to curl commands:\n\n`hargo fetch capture.har`\n\nFilter for specific endpoints:\n`hargo fetch capture.har | grep '/api/v1/users'`" click REPLAY "#" "**Replay Requests**\nReplay all captured requests against the server:\n\n`hargo run capture.har`\n\nUseful for regression testing or verifying the API still behaves the same way." click LOADTEST "#" "**Load Test**\nUse captured traffic patterns for load testing:\n\n`hargo load capture.har`\n\nReplays the traffic pattern at scale to stress-test the API." click DUMP "#" "**Dump and Analyze HAR**\nAnalyze captured traffic with hargo and jq:\n\n`hargo dump capture.har`\n\nUseful jq queries:\n- Find slow requests: `jq '.log.entries[] | select(.time > 1000)'`\n- Find errors: `jq '.log.entries[] | select(.response.status >= 400)'`\n- Extract unique endpoints" click VALIDATE "#" "**Validate Spec**\nVerify the generated spec is correct and complete.\nImport into Swagger UI or Postman.\nCompare endpoints against observed traffic.\nCheck for missing paths or incorrect schemas." click MORE "#" "**Decision: More Flows to Capture?**\nIf there are more features or user flows to cover, start a new capture session targeting the same spec file.\nEach session adds new endpoints to the existing spec." click NEW_SESSION "#" "**New Capture Session**\nCapture additional flows (e.g., admin features, checkout, settings):\n\n`mitmdump -q --set hardump=admin.har '~d api.example.com'`\n\nThen merge into the same spec:\n`mitmproxy2swagger -i admin.har -o spec.yaml -p https://api.example.com`\n\nThe tool appends new paths to the existing spec.yaml." click FINAL "#" "**Final API Spec**\nComplete OpenAPI 3.0 specification covering all discovered endpoints.\n\nReady for:\n- API documentation (Swagger UI)\n- Client code generation\n- Test suite creation\n- Integration into CI pipelines" click REDACT "#" "**Redact Sensitive Data**\nOptional: strip auth headers during capture using the redact addon.\n\n`mitmdump -s ~/.claude/skills/reverse-engineering-an-api/scripts/redact.py --set hardump=clean.har '~d api.example.com'`\n\nReplaces Authorization, Cookie, and other sensitive headers with [REDACTED].\nSafe to share or commit the resulting HAR." classDef setup fill:#d1ecf1,stroke:#7ec8d8 classDef capture fill:#e8daef,stroke:#b07cc6 classDef specgen fill:#fff3cd,stroke:#f0c040 classDef analysis fill:#ffeaa7,stroke:#e0c040 classDef iterate fill:#d4edda,stroke:#5cb85c classDef security fill:#f8d7da,stroke:#e06070 class INSTALL,CERT,CHOOSE setup class MITMDUMP,MITMPROXY,MITMWEB,REVERSE,PLAYWRIGHT,BROWSE,STOP,HAR_OUT capture class PASS1,EDIT_SPEC,PASS2,SPEC_OUT specgen class CURL,REPLAY,LOADTEST,DUMP,VALIDATE analysis class MORE,NEW_SESSION,FINAL iterate class REDACT security end style _MAIN_ fill:none,stroke:none,padding:0 _HEADER_ ~~~ _MAIN_