Mitmproxy Core: proxy runtime and flow inspection

# 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)