REST API 静态安全测试操作会在仓库中查找遵循 OpenAPI 规范（OAS，原名 Swagger）的 REST API 契约，并对其运行全面的安全检查。支持 OAS v2 和 v3.0.x，同时支持 JSON 和 YAML 格式。
你可以在以下场景中使用此操作：
该操作由 42Crunch API Security Audit 提供支持。Security Audit 对 API 定义执行静态分析，包含 300 多项针对最佳实践以及与身份验证、授权和数据约束相关的潜在漏洞的检查。
默认情况下，此操作将：
.json 和 .yaml 文件。这样，你就可以定位仓库中任何新增或修改的 API 契约。
你可以通过指定要包含或排除的仓库特定部分或文件名掩码，来微调操作在 API 发现中的行为。你甚至可以完全禁用自动发现，只列出要检查的特定 API 文件，并将它们映射到你在 42Crunch API 安全平台上的现有 API。所有设置都在配置文件 42c-conf.yaml 中完成。高级示例请参见此处。
所有发现的 API 都会上传到 42Crunch 平台中的一个 API 集合。默认情况下，操作使用环境变量 GITHUB_REPOSITORY 和 GITHUB_REF 来命名 API 集合来源的仓库和分支/标签/PR 名称。你可以使用 default-collection-name 操作参数覆盖该名称。在后续运行中，集合中的 API 会与仓库中的变更保持同步。
将此操作添加到 GitHub 的 CI/CD 工作流中，使其在包含安全问题的 API 定义上失败。
Security Audit 会为每个 API 契约提供一个 0 到 100 的审计分数，反映你的 API 的安全面。你可以使用 GitHub Action 的 min-score 参数来设置操作失败的审计分数阈值（如果未指定其他值，默认值为 75）。这有助于尽早发现质量较差的 API 定义，并在设计阶段就解决问题。
更高级的失败条件可以在配置文件 42c-conf.yaml 中设置，例如按类别（安全或数据验证）划分的审计分数、问题的严重级别，甚至通过问题 ID 指定特定问题。高级示例请参见此处。
此外，该插件还会强制执行平台级别定义的安全质量门禁（默认或基于标签的）。安全质量门禁用于强制执行企业内定义的应用安全要求。
每次操作运行时，它都会为你的每个 OpenAPI 文件附带一个详细的、按优先级排列的可操作报告链接：
点击链接可在 42Crunch 平台阅读详细报告：
你也可以直接在 GitHub 的 安全 选项卡下的 代码扫描警报 中跟踪 42Crunch 审计发现的问题。
要启用此功能，只需在 GitHub 工作流的操作参数中加入 upload-to-code-scanning:true。
点击任意警报即可查看其在代码中的准确位置，并获取漏洞详情及建议的修复步骤。
此操作使用 42Crunch API Security Audit 服务。在使用操作之前，你需要拥有 42Crunch 平台上的账户。如果你不是 42Crunch 客户，可以从以下页面申请免费账户：https://42crunch.com/get-started/。
然后，按照文档中描述的步骤创建 API 令牌，供操作向 42Crunch 平台进行身份验证，并将其保存为 GitHub 中的 secret。
api-token必需 GitHub 操作用于向 42Crunch 平台进行身份验证的 API 令牌。不要将 API 令牌直接写入工作流文件！而应在仓库设置中创建 GitHub secret，并按下面的示例引用它。
min-scoreOpenAPI 文件必须达到的最低审计分数，否则操作将失败。默认值为 75。
upload-to-code-scanning将审计结果上传到 GitHub 代码扫描。默认值为 false。注意，工作流必须具备特定权限，此步骤才能成功。
...
jobs:
run_42c_audit:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
...
ignore-failures如果设置为 true，即使已满足你所设置的失败条件（如 min-score 或 SQG 条件），也会强制成功完成执行。默认值为 false。
如果你希望在检测 SQG 失败场景时不强制执行（即在开始破坏构建之前给开发团队一段宽限期），此参数会很有用。
ignore-network-errors如果设置为 true，即使发生网络错误（例如无法连接到 42Crunch 平台等），也会强制成功完成执行。默认值为 false。
skip-local-checks如果设置为 true，将禁用 42c-conf.yaml 文件中设置的所有失败条件（如最低分数），仅当 SQG 中定义的条件未满足时才使执行失败。默认值为 false。
platform-url你访问 42Crunch 平台的 URL。默认值为 https://us.42crunch.cloud。
如果你是企业客户，请输入用于访问生产平台的 URL。
root-directory包含 42c-conf.yaml 配置文件的根目录。如果未指定，则使用插件的当前工作目录，通常对应于检出仓库的根目录。
default-collection-name为发现的 API 创建集合时使用的默认集合名称。如果未提供名称，则会根据仓库和分支/PR 信息生成默认名称。
log-level日志详细级别，取值为：FATAL、ERROR、WARN、INFO、DEBUG。默认值为 INFO。
share-everyone自动将 CI/CD 任务创建的 API 集合共享给组织中 42Crunch 平台上的所有成员。接受的值为：OFF、READ_ONLY、READ_WRITE。默认值为 OFF。请注意，操作运行所使用的身份（API 令牌的所有者）必须具有 Share with Everyone 权限，否则任务将因 403 错误而失败。
json-report将 JSON 格式的审计执行报告写入指定文件。执行报告 详细列出了创建、更新和删除的 API 列表。如果你想在后续流水线步骤中自动消费审计执行结果，这会很有用。默认情况下不写入报告。
api-tagsCI/CD 任务可以自动为新创建的 API 分配标签。标签按以下格式指定：category1:name1 category2:name2。此标志是可选的。
sarif-report将审计原始 JSON 格式转换为 SARIF，并将结果保存到指定文件中。默认情况下不写入报告。
audit-timeout设置审计报告的最大超时时间（秒）。如果在此时间内结果未就绪，任务将失败。默认值：600
在 42Crunch 平台上创建一个 API 令牌，并将其值复制到名为 API_TOKEN 的仓库 secret中。
在现有工作流中新增一个典型步骤，如下所示：
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
一个典型的工作流，用于检查仓库内容、对项目中发现的每个 OpenAPI 文件运行 Security Audit，并将执行文件保存为工件，如下所示：
name: "42crunch-audit-workflow"
# follow standard Code Scanning triggers
on:
push:
branches: [ "main" ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ "main" ]
schedule:
- cron: '19 9 * * 6'
env:
PLATFORM_URL: https://us.42crunch.cloud
jobs:
run_42c_audit:
environment: QA
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
platform-url: ${{ env.PLATFORM_URL}}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
# Upload results to Github code scanning
upload-to-code-scanning: false
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
- name: save-audit-report
if: always()
uses: actions/upload-artifact@v3
with:
name: auditaction-report-${{ github.run_id }}
path: audit-action-report-${{ github.run_id }}.json
if-no-files-found: error
此操作由 42Crunch Ecosystems 团队维护。如果你遇到问题，或有此处未解答的疑问，可以在 support.42crunch.com 创建支持工单。
报告问题时，请包含：