API攻防 | 如何为测试目标制作定制 API 文档

当目标没有记录其API 的API文档时，测试时可能很难进行。因此对于安全研究人员和 Web 渗透测试人员来说，对目标进行定制API 文档是很有价值的。

在本文中，我将讨论如何在目标不存在API 文档的情况下自己制作 API 文档。我将演示如何自动化此过程，并向您展示如何在短短几分钟内直接在 Postman 中将定制API文档武器化。

为什么要关心 API 文档？

API 文档之所以重要有几个原因。首先，它让您了解 API 可以做什么以及如何使用它。其次，它提供了一种探索新 API 的好方法，而无需阅读源代码。

API 文档可以包含正确定义的结构，涵盖从端点功能到数据类型和实际对象模式的所有内容。技术内容可以包括有关允许的请求方法、请求需要哪些参数以及请求正文中可能需要的任何其他数据的详细信息。

最后，在某些情况下，API 文档可能包含可用于创建可与 API 通信的客户端的示例。事实上，一些 API 文档功能（例如 Swagger 规范中的功能）包含实现逻辑，允许您从文档直接向 API 发送请求。

稍后我们会讨论 Swagger 规范。但首先，我想解释一下什么是定制 API 文档。

什么是定制 API 文档？

定制 API 文档是由攻击者（而不是 API 发布者）创建的的 API 的文档。它用于通过从代理或浏览器中的网络选项卡直接保存的 HTTP 流量生成其规范文档来枚举和发现 API 的功能。

在某些情况下，它也可用于直接攻击 API。我们会解决这个问题的。现在，我们来谈谈定制 API 文档的一些好处。

定制 API 文档的好处

在理想情况下，我开发人员将使用 OpenAPI 规范提供完整的 API 文档（不用担心，我稍后会介绍它的内容），并包括支持与远程服务集成的代码所需的变量、对象和端点的描述。

但真实情况是，开发人员可能不会留下或暴露 OpenAPI 文档。

虽然从代码生成规范文档只需花费很少的精力，但我们需要自己控制并在探索服务器时执行制作 API 文档的工作。没关系。这种方法有很多好处。

您获得清晰的 API 操作说明

说实话。保持文档最新可能很困难。随着 API 的变化，开发人员很容易忘记编辑现有端点的详细信息；他们可能会忘记编写新文档或将其保存回源代码管理（如 GitHub）。

因此，通过生成您自己的定制 API 文档，您始终拥有基于 API 实际用途的最新文档。您可以捕获请求中的实际 URL 及其所有数据（通常采用 XML 或 JSON 格式）。因此您能够了解 API 的真正工作原理并记录任何差异。

跟踪目标的 API 生命周期

在现代 Web 应用程序中，敏捷开发使得很难跟上代码库的不断变化。但作为攻击者，了解目标应用程序中可用的端点以及它们在版本之间如何变化对您有利。Rogue API 文档为您提供了这种可见性，以便您可以随着服务的变化快速调整您的攻击向量。

在许多情况下，只需做一些额外的工作，您还可以构建自己的有关请求如何工作的说明。这使您能够支持“活的”定制文档，使您和您的团队能够专注于平台最需要测试的地方。

那么让我们来看看定制 API 文档是什么样子的。从讨论 Swagger 和 OpenAPI 规范开始。

Swagger 和 OpenAPI 规范

OpenAPI 规范[1]也称为 Swagger 规范，是一种文档格式，允许您描述 API 的功能。它提供了一种定义 API 公开的资源的方法，包括每个可用的方法（或端点）和参数。此外，它还可用于构建交互式文档和客户端库。

OpenAPI 规范是描述现代 API 的流行选择，并受到许多工具的支持。出于我们的目的，我们将使用开源工具Swagger Editor[2]在创建定制 API 文档后显示、搜索和编辑它。

Swagger 与 OpenAPI

最近，Swagger 和 OpenAPI 之间存在很多混淆。理解差异的最简单方法是：

•OpenAPI = 规范

•Swagger = 实现 OpenAPI 规范的工具

OpenAPI 是该规范的正式名称。它得到了微软、谷歌和 IBM 等行业巨头的支持。

Swagger：https://swagger.io/是用于生成 OpenAPI 文档的著名工具集。它目前由 Smartbear Software 所有。

您通常会发现 Swagger 和 OpenAPI 可以互换使用。我将向您展示一个名为mitmproxy2swagger：https://github.com/alufers/mitmproxy2swagger的工具，它可以做到这一点。

如何生成定制 API 文档

定制 API 文档的最佳方法是解析进出 Web 服务的实时流量。这可以通过代理来完成。Burp Suite 和 ZAP、mitmproxy等代理都行。

不过，我将向您展示一种不同的方式。您可以利用浏览器开发工具来收集所有这些流量，然后将其保存到文件中以供稍后处理。当您被迫在可能没有足够权限安装代理等其他工具的外部目标中收集流量时，这是一种很棒的方法。何时使用此功能的一个很好的例子是在渗透测试期间，您在内部公司网络的用户桌面上获得了立足点。您可以使用新用户桌面浏览器来控制和攻击内部 Web 应用程序，并将浏览器记录的 API 流量渗透回给您。然后你就可以离线创建你的定制 API 文档。

让我告诉你怎么做。

设置和准备

除了使用浏览器的开发工具之外，您还需要安装mitmproxy2swagger。可以直接从 GitHub 下载。也可以使用python pip来安装：

pip install mitmproxy2swagger

如果您使用的是 Windows，我建议您安装 Windows Subsystem for Linux (WSL) 并安装 Ubuntu 或 KALI。与尝试让 Python 在本机运行相比，这是一种更好的体验。我将在 Windows 11 上使用 WSL 来演示这一点。

安装完成后，我们就可以开始捕获一些流量了！

第 1 步：设置浏览器以捕获流量

您的浏览器的开发工具能够记录并捕获请求和响应。这显示在开发工具的“网络”选项卡中。

访问开发工具（Windows 11 Microsoft Edge），点击快捷键CTRL+SHIFT+I ，或者转到 Menu → More Tools → Developer Tools 。

Developer tools menu

我建议的一个技巧是在加载开发工具之前启动一个新选项卡。这样就可以在“网络”选项卡中获得一个干净的状态，没有任何流量。

进入开发工具后，请确保选择“保留日志”和“禁用缓存”。这将确保您记录页面加载期间的所有请求。最后，确保您已开启录制。如下图所示：

Developer Tools config

保持开发工具打开，然后返回选项卡。是时候收集一些流量了！

第二步：正常使用应用采集流量

接下来像普通用户一样使用该应用程序。尝试执行应用程序支持的每个特性和功能。从注册到注销，从密码重置到配置文件更新，运行尽可能多的应用程序逻辑。例如下载报告或更新头像。

如果您可以注册具有管理员权限的帐户，那就更好了。它将允许您探索应用程序的更多功能，并发掘更多潜在的 API 端点。

DevTools sample traffic

一旦了解了应用程序可以执行的所有操作，我们就可以开始将所有这些数据武器化。

第 3 步：生成 HTTP 存档 (HAR)

完成流量采集后，返回开发工具。将所有这些流量数据导出到 HTTP 存档文件中，称为 HAR 捕获。可以使用导出工具来执行此操作，该工具如图所示：

Export browser traffic to HAR capture file

这将创建一个扩展名为 .har 的文件。它基本上是开发工具记录的所有内容的 JSON 格式的结构化数据。

步骤 4：导入 HAR 文件以创建 OpenAPI 定义

接下来利用mitmproxy2swagger将 HAR 转换为粗略的 OpenAPI 定义文件。

它还不是一个真正的 API 文档，而是读取所有流量并构建一个我们可以编辑的 YAML 文件：

mitmproxy2swagger -i crapi.apisec.ai.har -o crapi.yaml -p http://crapi.apisec.ai -e -f har

mitmproxy2swagger first pass

命令参数详解：

•-i .har ：源输入 HAR 文件。

•-o .yaml ：要生成的输出 YAML 文件。这将是您将要编辑的内容。

•-p http://target.domain[3] ：这是API前缀。通常这将类似于 target.domain 或 target.domain/v1 等。

•-e ：这告诉工具您还希望在文档中提供示例数据。您在这里要小心，因为它将使用您提供的实际数据。如果您不想在文档中包含该数据，则可以忽略此选项。

•-f har ：这告诉工具输入文件是 HAR 捕获，而不是典型的 mitmproxy流文件。

第一遍完成后，我们可以看看生成了什么。

步骤 5：编辑定义文件以描述 API 端点

在编辑器中打开 YAML 定义文件并查看。请注意，x-path-templates 下有大量以“-ignore:/”开头的行。这是设计使然。

浏览该文件并删除任何看似 API 调用的请求上的“ignore:”。如果想要忽略图像、图标、HTML、Javascript 等内容的话可以不用删。

完成后，保存文件：

Out from first pass of mitmproxy2swagger

现在准备生成定制 API 文档。

第 6 步：根据定义生成 OpenAPI 文档

现在运行相同的命令行来对定义文件执行第二遍：

mitmproxy2swagger -i crapi.apisec.ai.har -o crapi.yaml -p http://crapi.apisec.ai -e -f har

再次打开 YAML 文件。看看它改变了多少。

注意结构。它包括端点、使用的方法、对象的参数和属性，如果包含 -e 选项，甚至还包括完整的示例。

这就是遵循 OpenAPI 规范的 API 文档！但它与规格的符合程度如何？让我们来看看吧。

步骤 7：在 Swagger 编辑器中测试 OpenAPI 文档

前往https://editor.swagger.io[4] 。复制并粘贴 YAML 文件中的内容，或点击File → Import File 。Swagger 编辑器将加载 API 文档，并尝试解析它。根据路径执行的彻底程度，您可能会或可能不会看到一些错误。

没关系。如果需要的话，我们可以稍后在编辑器中修复它们。但现在，看看您如何看待基于收集的所有流量的完整描述的 API：

展开其中一个端点，看看它的定义如何：

您甚至可以单击“Try it Out”按钮并直接从 API 文档执行 Web 服务请求。

此时我们已经有了一个完全可用的定制 API 文档，涵盖了我们路径执行期间看到的所有端点。

如何在 Postman 中使用定制 API 文档

只需将文档作为新集合导入到 Postman 中即可。如下步骤所示。

在 Postman 中配置新工作区

启动postman。单击Workspaces → Create Workspace ，并将其命名名称。

导入 OpenAPI 定义文件

在工作区的左上角，您所命名的名称旁边有一个“导入”按钮。单击该按钮。出现提示时，使用资源管理器查找您创建的 YAML 文件。然后点击导入按钮。

如下图所示：

 

现在已经将集合导入 Postman 并可以开始发出请求！接下去就是burp结合postman进行测试

测试目标API

现在转到 Burp，并将您的请求发送到 Burp Repeater 或 Intruder。

您的定制 API 文档现已武器化，您可以开始漏洞挖掘了！

结论

经过努力，您现在应该拥有自己根据目标定制的API 文档。这允许您一起使用 Postman 和 BurpSuite 来更精确地测试目标 API。请记住，关键是探索应用程序的每个特性和功能，记录所需的所有流量，以便绘制完整的API文档。希望这有帮助。祝你好运！

免费获取网络安全优质学习资料与干货教程

申明：本账号所分享内容仅用于网络安全技术讨论，切勿用于违法途径，所有渗透都需获取授权，违者后果自行承担，与本号及作者无关，请谨记守法。