Help us learn about your current experience with the documentation. Take the survey.

API 安全测试分析器

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

对 Web API 进行动态应用安全测试（DAST），帮助发现其他 QA 流程可能遗漏的漏洞和潜在安全问题。将 API 安全测试与其他 GitLab Secure 安全扫描器以及您自己的测试流程结合使用。您可以在 CI/CD 工作流中运行 DAST API 测试，按需运行，或两者都使用。

不要对生产服务器运行 API 安全测试。它不仅可以执行 API 的任何功能，还可能触发 API 中的漏洞。这包括修改和删除数据等操作。仅对测试服务器运行 API 安全测试。

DAST API 已重新命名为 API Security Testing。作为此重新命名的一部分，模板名称和变量前缀也已更新。旧的模板和变量名称将继续工作，直到 2025 年 5 月的下一个主要版本 18.0。

入门指南

通过编辑您的 CI/CD 配置开始使用 API 安全测试。

先决条件：

要启用 API 安全测试，您必须根据环境的独特需求修改 GitLab CI/CD 配置 YAML。您可以使用以下方式指定要扫描的 API：

理解测试结果

要查看安全扫描的输出：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。
  2. 在左侧边栏，选择 Build > Pipelines。
  3. 选择管道。
  4. 选择 Security 标签页。
  5. 选择一个漏洞以查看其详细信息，包括：
    • Status：指示漏洞是否已分类或已解决。
    • Description：解释漏洞的原因、潜在影响和推荐的修复步骤。
    • Severity：根据影响分为六个级别。 了解有关严重性级别的更多信息。
    • Scanner：标识检测到漏洞的分析器。
    • Method：建立易受攻击的服务器交互类型。
    • URL：显示漏洞的位置。
    • Evidence：描述用于证明给定漏洞存在的测试用例
    • Identifiers：用于分类漏洞的引用列表，如 CWE 标识符。

您也可以下载安全扫描结果：

  • 在管道的 Security 标签页中，选择 Download results。

更多详细信息，请参阅管道安全报告。

发现在功能分支上生成。当它们合并到默认分支时，它们会成为漏洞。在评估您的安全态势时，这种区别很重要。

优化

为了充分利用 API 安全测试，请遵循以下建议：

  • 配置运行器使用始终拉取策略来运行最新版本的分析器。

  • 默认情况下，API 安全测试会下载管道中先前作业定义的所有工件。 如果您的 DAST 作业不依赖 environment_url.txt 来定义测试 URL 或先前作业创建的任何其他文件，则不应下载工件。为了避免下载工件，请扩展分析器 CI/CD 作业以指定无依赖项。例如，对于 API 安全测试分析器，将以下内容添加到您的 .gitlab-ci.yml 文件中：

    api_security:
  dependencies: []

要为您的特定应用程序或环境配置 API 安全测试，请参阅完整的配置选项列表。

部署

在 CI/CD 管道中运行时，API 安全测试扫描默认在 dast 阶段运行。为确保 API 安全测试扫描检查最新代码，请确保您的 CI/CD 管道在 dast 阶段之前的阶段将更改部署到测试环境。

如果您的管道配置为每次运行都部署到同一个 Web 服务器，则在另一个管道仍在运行时运行管道可能会导致竞争条件，其中一个管道会覆盖另一个管道的代码。在 API 安全测试扫描期间，应排除要扫描的 API。对 API 的唯一更改应来自 API 安全测试扫描器。在扫描期间对 API 进行的更改（例如，由用户、计划任务、数据库更改、代码更改、其他管道或其他扫描器进行的更改）可能导致不准确的结果。

API 安全测试扫描配置示例

以下项目演示了 API 安全测试扫描：

应用程序部署选项

API 安全测试需要一个已部署的应用程序可供扫描。

根据目标应用程序的复杂性，有几种部署和配置 API 安全测试模板的方法。

审查应用

审查应用是部署 DAST 目标应用程序最复杂的方法。为了协助此过程，GitLab 使用 Google Kubernetes Engine (GKE) 创建了审查应用部署。此示例可以在 Review Apps - GKE 项目中找到，以及在 README.md 中配置 DAST 审查应用的详细说明。

Docker 服务

如果您的应用程序使用 Docker 容器，您有另一个使用 DAST 部署和扫描的选项。在您的 Docker 构建作业完成并将映像添加到容器注册表后，您可以将映像用作服务。

通过在 .gitlab-ci.yml 中使用服务定义，您可以使用 DAST 分析器扫描服务。

在向作业添加 services 部分时，alias 用于定义可用于访问服务的主机名。在以下示例中，dast 作业定义中的 alias: yourapp 部分意味着已部署应用程序的 URL 使用 yourapp 作为主机名（https://yourapp/）。

stages:
  - build
  - dast

include:
  - template: API-Security.gitlab-ci.yml

# 将容器部署到 GitLab 容器注册表
deploy:
  services:
  - name: docker:dind
    alias: dind
  image: docker:20.10.16
  stage: build
  script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
    - docker pull $CI_REGISTRY_IMAGE:latest || true
    - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

api_security:
  services: # 使用服务将您的应用程序容器链接到 dast 作业
    - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
      alias: yourapp

variables:
  APISEC_TARGET_URL: https://yourapp

大多数应用程序依赖于多个服务，如数据库或缓存服务。默认情况下，在 services 字段中定义的服务无法相互通信。要允许服务之间的通信，请启用 FF_NETWORK_PER_BUILD 功能标志。

variables:
  FF_NETWORK_PER_BUILD: "true" # 启用每个构建的网络，以便所有服务可以在同一网络上通信

services: # 使用服务将容器链接到 dast 作业
  - name: mongo:latest
    alias: mongo
  - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    alias: yourapp

获取支持或请求改进

要获得特定问题的支持，请使用获取帮助渠道。

GitLab.com 上的 GitLab 问题跟踪器是有关 API Security 和 API 安全测试的错误和功能建议的正确位置。在打开有关 API 安全测试的新问题时，使用 ~"Category:API Security" 标签，以确保它被正确的人员快速审查。

在提交您自己的问题之前，搜索问题跟踪器以查找类似的条目，很有可能其他人遇到过相同的问题或功能建议。使用表情符号反应表示支持或加入讨论。

当遇到行为不符合预期的情况时，考虑提供上下文信息：

  • 如果使用 GitLab Self-Managed 实例，请提供 GitLab 版本。
  • .gitlab-ci.yml 作业定义。
  • 完整的作业控制台输出。
  • 可作为名为 gl-api-security-scanner.log 的作业工件使用的扫描器日志文件。

清理支持问题中附加的数据。删除敏感信息，包括：凭据、密码、令牌、密钥和密钥。

术语表

  • Assert：断言是检查用于触发漏洞的检测模块。许多断言具有配置。一个检查可以使用多个断言。例如，日志分析、响应分析和状态码是检查常用的断言。具有多个断言的检查允许它们被打开和关闭。
  • Check：执行特定类型的测试，或对特定类型的漏洞执行检查。例如，SQL 注入检查对 SQL 注入漏洞执行 DAST 测试。API 安全测试扫描器由多个检查组成。检查可以在配置文件中打开和关闭。
  • Profile：配置文件具有一个或多个测试配置文件，或子配置。您可能有一个用于功能分支的配置文件，另一个用于主分支的额外测试。