SonarQube 报告 API 与 Webhook

本文档描述了如何以编程方式访问存储在 Procurize 平台中的 SonarQube 安全报告。内容涵盖列出和检索报告的 REST API、下载报告归档以及在摄取新报告时订阅 webhook 通知的方式。

概览

SonarQube 报告子模块允许组织集中存储和管理由 SonarQube 生成的安全和代码质量报告。Procurize 平台通过以下方式公开这些数据：

用于检索已存储报告元数据的 REST API
用于将报告制品下载为 ZIP 归档的端点
用于在新报告可用时进行近实时通知的 webhook

这些功能可与 CI/CD 流水线、GRC 系统、内部仪表盘以及第三方风险管理工具集成。

身份验证与授权

本文档中描述的所有 API 请求均不需要身份验证。

组织 ID

所有请求均需要组织 ID。可在组织的 设置面板（https://dashboard.procurize.ai）中找到。请注意，访问设置面板需要授权，且访问组织设置面板的用户角色至少需为该组织的管理员。

复制 ID 按钮

基础 URL

所有 REST API 端点均位于以下基础 URL 下：

https://api.procurize.com

SonarQube 报告 REST API

列出报告

检索平台中存储的 SonarQube 安全报告的分页列表。

端点

GET /security/report/list

查询参数

org（必需）：组织 ID。
version（可选）：产品的确切版本，使用语义化版本格式。
minver（可选）：产品的最低版本，使用语义化版本格式。
maxver（可选）：产品的最高版本，使用语义化版本格式。

请注意，version、minver 或 maxver 至少必须提供一个参数。

请求示例

curl "https://api.procurize.com/security/report/list?org=00000000-0000-0000-0000-000000000001&version=1.0"

响应示例

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

下载报告归档

下载包含完整 SonarQube 报告制品的 ZIP 归档。归档中包括 HTML 和 PDF 报告。

端点

GET /security/report/files

org（必需）：组织 ID。
reports（必需）：报告 ID 数组。

请求示例

curl "https://api.procurize.com/security/report/files?org=00000000-0000-0000-0000-000000000001&reports=00000000-0000-0000-0000-000000000002&reports=00000000-0000-0000-0000-000000000003"

响应

Content-Type: application/zip
响应体包含二进制 ZIP 文件

客户端应流式读取响应并将其保存到磁盘。

错误处理

API 使用标准的 HTTP 状态码。

200 OK：请求成功
204 No Content：报告不存在
400 Bad Request：参数无效或请求格式错误
500 Internal Server Error：服务器内部错误

错误响应包括机器可读的错误码和人类可读的错误信息。

Webhook

Procurize 的 webhook 允许外部系统在新 SonarQube 报告被摄取或更新时接收通知。

配置 webhook

可以在组织的 设置面板 → 安全报告 部分（https://dashboard.procurize.ai）添加或编辑 webhook。请注意，访问设置面板需要授权，且访问组织设置面板的用户角色至少需为该组织的管理员。

Webhook 编辑器

要检查 webhook，可以使用诸如 https://webhook-test.com 等流行的在线服务。

Webhook 负载

Webhook 事件以带有 JSON 负载的 HTTP POST 请求方式发送。

示例负载

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

Webhook 安全

为确保真实性，Webhook 请求会包含使用共享密钥生成的签名 Header。

签名采用 HMAC-SHA256 计算
客户端应在处理负载前验证签名

此机制可防止未经授权或伪造的 webhook 投递。

投递与重试

webhook 必须返回 2xx 响应才能视为投递成功
失败的投递会每小时自动重试
事件可能会被多次投递；消费者应实现幂等处理

典型用例

自动将 SonarQube 检测结果导入内部安全仪表盘
在质量门未通过时触发合规工作流
为审计和供应商风险评审归档安全报告
将第三方系统与最新代码安全状态同步