- name
- mitmproxy-core
- description
- Build and operate mitmproxy capabilities directly from official APIs (modes, addons, event hooks, filters, replay, certificates) without relying on MCP wrappers. Use when implementing or troubleshooting local mitmdump workflows, upstream chaining via 127.0.0.1:7891, flow query/inspect/replay/extract, or protocol hook customization.
# Mitmproxy Core
## Quick Start
Use this skill when the task needs mitmproxy-native capabilities, not MCP wrapper behavior.
Primary runtime baseline:
- listen: `0.0.0.0:8001`
- mode: `upstream:http://127.0.0.1:7891@8001`
- tool: `mitmdump`
- flow archive: `data/streams/flow-<timestamp>-<pid>.mitm` (default per-start file)
Runtime defaults are configurable by environment variables.
## Execute Workflow
```text
Task Progress:
- [ ] Step 1: Validate upstream and port state
- [ ] Step 2: Start runtime with core addon
- [ ] Step 3: Trigger deterministic traffic
- [ ] Step 4: Query/inspect indexed flows
- [ ] Step 5: Apply rules, replay, extract
- [ ] Step 6: Run validation matrix
```
## Commands
- Start proxy runtime:
- `bash .cursor/skills/mitmproxy-core/scripts/runtime/start.sh`
- Stop proxy runtime:
- `bash .cursor/skills/mitmproxy-core/scripts/runtime/stop.sh`
- Runtime status:
- `bash .cursor/skills/mitmproxy-core/scripts/runtime/status.sh`
- Health check:
- `bash .cursor/skills/mitmproxy-core/scripts/runtime/healthcheck.sh`
## Runtime Configuration
Runtime scripts read options from environment variables (default shown in parentheses):
- `MITM_CORE_LISTEN_HOST` (`0.0.0.0`)
- `MITM_CORE_LISTEN_PORT` (`8001`)
- `MITM_CORE_UPSTREAM_SCHEME` (`http`)
- `MITM_CORE_UPSTREAM_HOST` (`127.0.0.1`)
- `MITM_CORE_UPSTREAM_PORT` (`7891`)
- `MITM_CORE_MODE_SPEC` (auto-built as `upstream:${UPSTREAM_SCHEME}://${UPSTREAM_HOST}:${UPSTREAM_PORT}`)
- `MITM_CORE_TCP_PROBE_HOST` (`127.0.0.1`)
- `MITM_CORE_PROBE_TIMEOUT_SEC` (`2`)
- `MITM_CORE_CONFDIR` (`~/.mitmproxy`)
Flow archive controls:
- `MITM_CORE_SAVE_STREAM_FILE`:
- default: `.cursor/skills/mitmproxy-core/data/streams/flow-<YYYYmmdd-HHMMSS>-<pid>.mitm`
- no overwrite by default (new file per start)
- supports mitmproxy save syntax (`+` append, `strftime` path rotation)
- `MITM_CORE_SAVE_STREAM_FILTER`:
- optional filter expression for `save_stream_filter`
- empty by default (capture all flows)
## Flow Operations
仅处理 **离线 `.mitm` 文件**、且使用**自带脚本目录**的提取流程 → 见技能 **`mitmproxy-extract-data`**（不调用本目录 ops）。下列命令面向本技能运行时与本地/远程索引。
- Summary:
- `python .cursor/skills/mitmproxy-core/scripts/ops/query.py summary --limit 20 --source auto`
- file source: `python .cursor/skills/mitmproxy-core/scripts/ops/query.py summary --source file --flows-file .cursor/skills/mitmproxy-core/data/streams/<file>.mitm --limit 20`
- Search:
- `python .cursor/skills/mitmproxy-core/scripts/ops/query.py search --domain tiktokv.com --limit 20 --source auto`
- file source: `python .cursor/skills/mitmproxy-core/scripts/ops/query.py search --source file --flows-file .cursor/skills/mitmproxy-core/data/streams/<file>.mitm --domain tiktokv.com --limit 20`
- Full export:
- `python .cursor/skills/mitmproxy-core/scripts/ops/query.py export --source file --flows-file .cursor/skills/mitmproxy-core/data/streams/<file>.mitm --output logs/flows.full.json`
- stdout output: `python .cursor/skills/mitmproxy-core/scripts/ops/query.py export --source file --flows-file .cursor/skills/mitmproxy-core/data/streams/<file>.mitm`
- Inspect:
- `python .cursor/skills/mitmproxy-core/scripts/ops/inspect_flow.py --flow-id <id> --source auto`
- file source: `python .cursor/skills/mitmproxy-core/scripts/ops/inspect_flow.py --source file --flows-file .cursor/skills/mitmproxy-core/data/streams/<file>.mitm --flow-id <id>`
- API bridge config:
- `python .cursor/skills/mitmproxy-core/scripts/ops/api_bridge.py show`
- `python .cursor/skills/mitmproxy-core/scripts/ops/api_bridge.py set --enable --base-url http://<remote-host>:<port>`
- mitmweb token mode:
- `python .cursor/skills/mitmproxy-core/scripts/ops/api_bridge.py set --enable --base-url http://127.0.0.1:8081 --auth-type mitmweb_token --web-token <TOKEN> --summary-endpoint /flows --search-endpoint /flows --inspect-endpoint-template /flows`
- Rules:
- `python .cursor/skills/mitmproxy-core/scripts/ops/rules.py list`
- Replay:
- `python .cursor/skills/mitmproxy-core/scripts/ops/replay.py --flow-id <id>`
- Extract:
- `python .cursor/skills/mitmproxy-core/scripts/ops/extract.py --flow-id <id> --regex \"token=([A-Za-z0-9._-]+)\" --var token`
## Non-negotiable Constraints
- Do not claim upstream proxy is active unless runtime status shows `mode=upstream` and upstream probe passes.
- Treat listen port conflict as a hard startup failure until resolved.
- Prefer official `mode`, `upstream_auth`, `client_replay`, `server_replay`, and event hooks semantics.
- Keep scripting layer as orchestration; protocol behavior lives in addon hooks.
- Remote query mode (`api_bridge`) only covers query/inspect paths and requires remote endpoint contract configuration.
- `source=auto` keeps existing local/remote behavior and does not auto-switch to file source.
## References
- Official-to-local mapping: [reference.md](reference.md)
- Hook capability map: [events-capability-map.md](events-capability-map.md)
- Mode routing decisions: [modes-and-routing.md](modes-and-routing.md)
- Certificates and TLS: [certs-and-tls.md](certs-and-tls.md)
- Replay and extraction: [replay-and-extract.md](replay-and-extract.md)
- Contracts: [contracts.md](contracts.md)
- Validation: [validation.md](validation.md)
- Validation report: [validation-report.md](validation-report.md)
- Examples: [examples.md](examples.md)
Ver en GitHub
