alufers/mitmproxy2swagger

# mitmproxy2swagger [](https://badge.fury.io/py/mitmproxy2swagger) [](https://archlinux.org/packages/extra/any/mitmproxy2swagger/) 一个用于自动将 [mitmproxy](https://mitmproxy.org/) 捕获数据转换为 [OpenAPI 3.0](https://swagger.io/specification/) 规范的工具。这意味着您只需运行应用程序并捕获流量，即可自动对 REST API 进行逆向工程。 **🆕 新功能！** 增加了对从浏览器 DevTools 导出的 HAR 文件进行处理的支持。详情请参阅 [使用方法 - HAR](#har)。 ## 安装 首先，您需要安装 python3 和 pip3。 ``` $ pip install mitmproxy2swagger # ... 或 ... $ pip3 install mitmproxy2swagger # ... 或 ... $ git clone git@github.com:alufers/mitmproxy2swagger.git $ cd mitmproxy2swagger $ docker build -t mitmproxy2swagger . ``` 然后克隆该仓库，并按照下面的示例运行 `mitmproxy2swagger`。 ## 使用方法 ### Mitmproxy 要通过检查 HTTP 流量来创建规范，您需要： 1. 使用 mitmproxy 工具捕获流量。我个人推荐使用 mitmweb，这是 mitmproxy 内置的 Web 界面。 $ mitmweb Web server listening at http://127.0.0.1:8081/ Proxy server listening at http://*:9999 ... **重要提示** 要配置您的客户端使用 mitm proxy 暴露的代理，请查阅 [mitmproxy 文档](https://docs.mitmproxy.org/stable/) 以获取更多信息。 2. 将流量保存为 flow 文件。 在 mitmweb 中，您可以通过“File”菜单并选择“Save”来执行此操作：  3. 运行 mitmproxy2swagger 的第一遍处理： $ mitmproxy2swagger -i -o -p # ... 或者 ... $ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i -o -p 请注意，您可以使用现有的 schema，在这种情况下，现有的 schema 将通过新数据进行扩展。您也可以使用不同的 flow 捕获多次运行它，捕获的数据将被安全地合并。 `` 是您希望逆向工程的 API 的 base url。您需要通过观察 mitmproxy 中的请求来获取它。 例如，如果一个应用程序发出了如下请求： https://api.example.com/v1/login https://api.example.com/v1/users/2 https://api.example.com/v1/users/2/profile 那么可能的 prefix 是 `https://api.example.com/v1`。 4. 运行第一遍处理应该在 schema 文件中创建了如下部分： x-path-templates: # 移除 ignore: 前缀以生成带有其 URL 的 endpoint # 靠近顶部的行优先级更高，匹配是贪婪的 - ignore:/addresses - ignore:/basket - ignore:/basket/add - ignore:/basket/checkouts - ignore:/basket/coupons/attach/{id} - ignore:/basket/coupons/attach/104754 您应该使用文本编辑器编辑 schema 文件，并从您希望生成的路径中移除 `ignore:` 前缀。您还可以调整路径中出现的参数。 5. 运行 mitmproxy2swagger 的第二遍处理： $ mitmproxy2swagger -i -o -p [--examples] # ... 或者 ... $ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i -o -p [--examples] 第二次运行该命令（使用相同的 schema 文件）。它将拾取编辑过的行并生成 endpoint 描述。 请注意，mitmproxy2swagger 不会覆盖现有的 endpoint 描述，如果您想覆盖它们，可以在运行第二遍处理之前将其删除。 传递 `--examples` 将向请求和响应添加示例数据。使用此选项时请务必小心，因为它可能会将敏感数据（tokens、密码、个人信息等）添加到 schema 中。 传递 `--headers` 将向请求和响应添加 headers 数据。使用此选项时请务必小心，因为它可能会将敏感数据（tokens、密码、个人信息等）添加到 schema 中。 ### HAR 1. 从浏览器 DevTools 捕获并导出流量。 在浏览器 DevTools 中，转到 Network 选项卡并点击“Export HAR”按钮。  2. 继续按照处理 mitmproxy dump 的相同方式进行操作。`mitmproxy2swagger` 将自动检测 HAR 文件并对其进行处理。 ## 示例输出 请参阅 [示例](./example_outputs/)。您将在那里找到生成的 schema 以及一个包含生成文档的 html 文件（通过 [redoc-cli](https://www.npmjs.com/package/redoc-cli)）。 请在此处查看生成的 html 文件：[here](https://raw.githack.com/alufers/mitmproxy2swagger/master/example_outputs/lisek-static.html)。 ## 开发与贡献 本项目使用了： - [poetry](https://python-poetry.org/) 用于依赖管理 - [pre-commit](https://pre-commit.com/) 用于代码格式化和 linting - [pytest](https://docs.pytest.org/en/stable/) 用于单元测试 要安装依赖项： ``` poetry install ``` 运行 linter： ``` pre-commit run --all-files ``` 安装 pre-commit hooks： ``` pre-commit install ``` 运行测试： ``` poetry run pytest ``` 运行测试并查看覆盖率： ``` poetry run pytest --cov=mitmproxy2swagger ``` ## 许可证 MIT

标签：API 文档生成, DevTools, HAR, HTTP 代理, mitmproxy, OpenAPI, Python, REST API, Swagger, 中间人攻击, 云资产清单, 后端开发, 接口分析, 无后门, 流量捕获, 网络安全, 网络拓扑, 网络调试, 自动化, 请求拦截, 逆向工具, 逆向工程, 隐私保护