# API 文档与真实流量对不上，交给 mitmproxy 裁决

> 这款免费的 MIT 许可代理让在场所有人看到真实请求与响应，客户 IT 最先问的也是许可证。

原文: https://fdetimes.net/zh/tools/mitmproxy-debug-api-traffic/

客户的 API 文档写着，认证错误返回 401。你的应用却一直收到看似成功的响应，然后在往下三层的解析环节出错。会议毫无进展：客户坚称系统与描述一致，你这边坚称代码完全按文档实现。

只有一方是对的，证据就在线路上。与其争论规范，不如在中间放一个工具，让所有人一起看真实的请求和响应。mitmproxy 正是为此而生。

如果你在客户现场做集成工作，这种场景会反复出现。文档可能落后于系统；流量反映的永远是实际运行的系统。

## mitmproxy 到底是什么？

官方网站将 mitmproxy 描述为一款免费、开源的交互式 HTTPS 代理，由 Aldo Cortesi、Maximilian Hils 和 Thomas Kriechbaumer 开发，采用 MIT 许可证发布。许可证这一点值得记住：很多客户为办公电脑维护一份软件白名单，许可证是他们 IT 部门问的第一个问题。

开发者称它是一把用于调试、测试、隐私测量和渗透测试的“瑞士军刀”。GitHub 仓库明确写道，它同时面向渗透测试人员和软件开发者。

这套工具包含三个程序。`mitmproxy` 是交互式命令行界面，`mitmweb` 把主要功能放进基于浏览器的图形界面，`mitmdump` 则用于脚本和 addon。

在客户现场，第一次排查通常适合用 `mitmweb`，因为你可以共享屏幕，和客户的工程师逐个点开请求查看。需要把同一项检查重复几百次时，再换成 `mitmdump`。

## 它如何读取 HTTPS？

mitmproxy 文档解释了基本思路：对客户端，它扮演服务器；对服务器，它扮演客户端。为了在 TLS 下做到这一点，mitmproxy 内置了一个完整的证书颁发机构（CA），并即时生成伪证书。客户端设备必须信任这个 CA，连接才能成功。

这个技术细节背后有一条职业规则。在机器上安装陌生的 CA，尤其是客户基础设施里的机器，属于安全变更，而不是调试技巧。要取得书面许可，只在测试环境中操作，用完立即移除 CA。

还有一个后果：任何不信任 mitmproxy CA 的客户端都会拒绝连接。如果一开代理应用就报证书错误，先检查 CA 信任这一步，不要急着怪客户的系统。

## 在客户现场用哪种模式？

关键问题是你能否修改客户端的代理设置。官方文档推荐显式代理，即把客户端配置为经过 mitmproxy，因为这是最简单、最稳健的选项。客户端是你自己的代码时，几乎总能做到。

| 客户现场的情况 | 应使用的模式 |
|---|---|
| 客户端是你能配置的脚本或服务 | 显式代理（regular 模式） |
| 应用运行在同一台机器上，但没有代理设置 | 本地捕获：透明捕获，无需配置代理 |
| 你碰不了客户端，但能在服务前面放东西 | 反向代理：mitmproxy 像普通服务器一样工作 |

当客户系统回调你的服务时，例如通过 webhook，反向代理尤其有用。把 mitmproxy 放在你的端点前面，就能看到对方实际发来了什么。

## 示例：抓住一个返回 200 的“401”

回到开头的场景，把它当作一个假设情境。你以显式模式运行 mitmproxy，让客户端经过它，然后故意用错误的 token 发一个请求。在 `mitmweb` 中，你看到状态码 200，响应体里带着一个 error 字段，哪儿都没有 401。

这十分钟抵得上整场会议。你截取这对请求/响应，发给客户的工程师，讨论就从“谁错了”变成“这种情况怎么处理”。你的代码也应该检查错误响应体，而不是只看状态码。

下一步是把这个发现变成自动检查。根据文档，addon 是一个 Python 对象，每个事件对应一个方法，例如 `request` 或 `response`。下面的示例只打印响应体中包含“error”一词的成功响应：

```python
class FlagHiddenErrors:
    def response(self, flow):
        body = flow.response.get_text() or ""
        if flow.response.status_code == 200 and "error" in body:
            print("200 背后藏着错误：", flow.request.pretty_url)

addons = [FlagHiddenErrors()]
```

用 `mitmdump -s flag_errors.py` 运行。通过 `-s` 加载的脚本在文件修改后会自动重新加载，因此可以在流量持续进来时调整条件，无需重启。

**要点:** API 文档会过时，真实流量不会。

## 需要提前了解的局限

mitmproxy 只能看到经过它的流量。如果客户端配置不对，或不信任 CA，你会看到空白屏幕或 TLS 错误，很容易得出错误结论。阅读真实请求之前，务必先确认一个简单请求确实经过了代理。

它也是渗透测试人员的工具。未经许可把它放进客户系统中间，即使只是为了调试，也可能演变成安全事件。另外，抓到的流量可能包含 token 和真实客户数据，切勿原样粘贴到工单或聊天里。

## 先学什么，面试中怎么讲

合理的顺序是：先用 `mitmweb` 搭配显式代理，再学会安装并干净地移除 CA，然后用 `mitmdump` 运行一个小 addon。本地捕获和反向代理，等遇到需要的场景再学。

被问到某次集成与文档不符的经历时，按三步讲：症状、证据、修复。

可以把上面的场景当作模板：应用在解析环节出错；你把 mitmproxy 放在中间，发现认证错误返回 200 并附带错误响应体；你把这对请求/响应发给客户，修改代码读取错误响应体，并写了一个 addon 捕获所有类似情况。

这个故事向面试官展示的是双方僵持时你会怎么做，而不只是你知道某个工具的名字。在简历上，按同样的三步把它浓缩成一行成果描述。

知道工具的名字说服不了任何人。真正重要的是，当双方为规范争执不下时，你是那个能把证据带进会议室的人。

**本周动手试试:**

- 安装 mitmproxy，以显式代理模式让一个调用常用 API 的脚本经过它，然后打开 mitmweb，逐一查看每个请求和响应
- 写一个 addon，让 response 函数只打印状态码不是 2xx 的响应，用 mitmdump -s 运行，然后修改文件，观察脚本自动重新加载
- 针对一次做过的集成，写一份两栏笔记：“文档怎么说 / 真实流量显示什么”，作为面试时可以讲的故事

## 信源

- [mitmproxy - an interactive HTTPS proxy](https://mitmproxy.org/)

- [GitHub - mitmproxy/mitmproxy](https://github.com/mitmproxy/mitmproxy)

- [How mitmproxy works](https://docs.mitmproxy.org/stable/concepts/how-mitmproxy-works/)

- [Proxy Modes - mitmproxy docs](https://docs.mitmproxy.org/stable/concepts/modes/)

- [Addons overview - mitmproxy docs](https://docs.mitmproxy.org/stable/addons/overview/)
