mitmproxy-skills

An AI Agent skill — mitmdump-windows — for driving mitmdump, the command-line member of the mitmproxy suite, on Windows from a shell. It's a cheatsheet + bundled reference docs for intercepting, capturing, inspecting, modifying, replaying, filtering, and analyzing HTTP/HTTPS/TCP/WebSocket/DNS traffic — and, heavily, for security analysis: standing up a MITM/HTTP(S) proxy, decrypting HTTPS by trusting the mitmproxy CA with certutil, saving/reading .mitm flow files, exporting HAR/curl, on-the-fly request/response tampering (map_local, map_remote, modify-headers/body), client/server replay, -s addon scripting, and recon across web / mobile / IoT / malware-C2 traffic.

mitmproxy-skills/
├── README.md                     ← you are here (setup / install)
├── LICENSE
└── mitmdump-windows/
    ├── SKILL.md                  ← the cheatsheet entry point (cert trust → modes → filters → recipes)
    └── reference/                ← verbatim upstream mitmproxy docs (authoritative fallback)
        ├── certificates.md       ← CA trust, custom certs, mTLS, cert pinning
        ├── filters.md            ← the full flow-filter operator language
        ├── modes.md              ← regular / local / reverse / upstream / socks5 / dns modes
        └── features.md           ← map_local/remote, modify_*, replay, sticky, streaming, blocklist

The skill assumes mitmdump is installed and on PATH — which is exactly what the winget install below gives you (mitmdump, mitmproxy, and mitmweb land on PATH under their plain names). HTTPS interception additionally needs mitmproxy's CA trusted on the client; the skill walks you through the one-line certutil setup. Install once with the guide below, then use the skill.

---

Get mitmproxy

mitmproxy ships mitmdump (CLI), mitmproxy (interactive TUI), and mitmweb (browser GUI) — all three from one package.

Recommended: winget

winget install --id mitmproxy.mitmproxy -e

This installs to C:\Program Files\mitmproxy\bin\ and adds it to PATH. Open a new shell afterwards so the updated PATH is picked up. (The Microsoft Store package and the official installer from https://mitmproxy.org/downloads/ work too; winget is the simplest for a scripted setup.)

Verify the install

# After install + a NEW shell:
mitmdump --version          # -> Mitmproxy: 12.x ... Platform: Windows

The first run of any mitmproxy tool generates the CA into %USERPROFILE%\.mitmproxy (mitmproxy-ca-cert.cer, .pem, .p12, …). To decrypt HTTPS you must trust that CA — the documented one-liner (covered in the skill) is:

# Current user, no admin needed:
certutil -user -addstore root "$env:USERPROFILE\.mitmproxy\mitmproxy-ca-cert.cer"

See mitmdump-windows/SKILL.md §1 for per-user vs machine-wide trust, verification, and cleanup.

---

Install this skill into your AI agent (global / user space)

Claude Code, Codex CLI, and GitHub Copilot all read the same SKILL.md Agent Skill format from a personal skills dir — installing is just dropping the mitmdump-windows/ folder into each:

Agent	Global skills dir (Windows)
Claude Code	%USERPROFILE%\.claude\skills\
OpenAI Codex CLI	%USERPROFILE%\.codex\skills\
GitHub Copilot	%USERPROFILE%\.copilot\skills\

$src = "C:\projects\mitmproxy-skills\mitmdump-windows"     # adjust to where you cloned it
foreach ($a in '.claude', '.codex', '.copilot') {          # keep only the agents you use
  $dst = "$env:USERPROFILE\$a\skills"
  New-Item -ItemType Directory -Force $dst | Out-Null
  Copy-Item -Recurse -Force $src $dst
}

Each agent auto-discovers the skill by its name/description and loads it when a task matches (in Claude Code, run /skills to confirm).

---

Use responsibly

mitmproxy is a man-in-the-middle tool. Only intercept, decrypt, or modify traffic on systems and networks you own or are explicitly authorized to test. Capturing third-party TLS without consent is illegal in most jurisdictions. When finished, remove the trusted CA and reset any system-proxy/SSLKEYLOGFILE changes (the skill's §13 covers cleanup).

Licensing

• This skill (the authored mitmdump-windows/SKILL.md content) is released under the MIT License.
• mitmdump-windows/reference/ contains documentation from the mitmproxy project, redistributed under mitmproxy's original MIT License. Those pages are © the mitmproxy contributors; see https://docs.mitmproxy.org/ for the canonical source.
• mitmproxy itself is developed by the mitmproxy contributors under the MIT License and is not included here — install it via winget as shown above.