SonarQube 报告 API#

本文介绍如何以编程方式访问存储在 Procurize 平台的 SonarQube 安全报告。内容涵盖用于列出报告以及以 HTML、PDF、ZIP 格式下载报告的 REST API。

概览#

SonarQube 报告子模块允许组织集中存储和管理由 SonarQube 生成的安全和代码质量报告。Procurize 平台通过公共 REST API 暴露这些数据，使您能够：

  • 列出组织、项目组或项目的报告元数据
  • 下载单个报告的 HTML、PDF 或 ZIP 格式
  • 将选定的报告下载为 ZIP 压缩包
  • 将项目或项目组的所有报告下载为 ZIP 压缩包
  • 直接从 SonarQube 服务获取最新的 OWASP Top 10 和 CWE Top 25 报告

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

接口端点#

接口方法目的
/security/report/listGET列出所选范围和版本的报告元数据。
/security/report/filesGET将选定的报告下载为 ZIP 压缩包。
/security/report/htmlGET获取单个报告的 HTML 版本。
/security/report/pdfGET获取单个报告的 PDF 版本。
/security/report/zipGET获取单个报告的 ZIP 压缩包。
/security/report/project-filesGET将项目的所有报告下载为 ZIP 压缩包。
/security/report/directory-filesGET将项目组（目录）的所有报告下载为 ZIP 压缩包。
/security/reports/fetchPOST从 SonarQube 服务获取最新报告。

身份验证与授权#

本文档中描述的报告列出和下载接口不需要身份验证。

POST /security/reports/fetch 接口需要使用 API 令牌进行身份验证——参见 API 令牌。

组织 ID#

大多数请求都需要组织标识符。您可以传递组织 ID（UUID）或其别名——参见 标识符和别名。可以在组织的 设置面板（https://dashboard.procurize.ai）中找到它。请注意，访问设置面板需要授权，且访问组织的设置面板需要在该组织中拥有至少管理员角色的用户。

复制 ID 按钮

标识符和别名#

范围参数接受实体 ID（UUID）或可读的别名。别名使请求更易阅读，并在不同环境中保持稳定。

参数接受示例别名
org组织 ID 或别名aspose, groupdocs
directory目录（项目组）ID 或别名aspose-imaging, groupdocs-annotation
project项目 ID 或别名aspose-imaging-net, groupdocs-annotation-java

例如，以下两个请求是等价的：

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

注意： 批量下载接口的 id 参数不支持别名。请向 GET /security/report/project-files 和 GET /security/report/directory-files 传递目录或项目的 UUID。

基础 URL#

所有 REST API 接口均位于以下基础 URL 下：

https://api.procurize.com

SonarQube 报告 REST API#

列出报告#

返回所选范围和版本可用的安全报告（不包含文件内容）。使用此接口可发现可传递给下载接口的报告 ID。

Endpoint

GET /security/report/list

Query Parameters

  • org（可选）：组织 ID 或别名（例如 aspose 或 groupdocs）。范围最大。
  • directory（可选）：目录（项目组）ID 或别名（例如 aspose-imaging 或 groupdocs-annotation）。范围较窄。
  • project（可选）：项目 ID 或别名（例如 aspose-imaging-net 或 groupdocs-annotation-java）。范围最窄。
  • version（可选）：精确的项目版本。
  • minver（可选）：最小项目版本。
  • maxver（可选）：最大项目版本。

至少需要提供 org、directory 或 project 中的一个。范围的优先级如下：如果指定了 project，仅搜索该项目；否则如果指定了 directory，搜索整个项目组；否则搜索整个组织（org）。当 org 与 project 或 directory 同时指定时，还会验证目标是否属于该组织。

version、minver、maxver 中至少需要一个。如果指定了 version，则忽略 minver 和 maxver。

Request Example

curl "https://api.procurize.com/security/report/list?org=aspose&version=1.0"

按项目组或项目别名进行范围限定：

curl "https://api.procurize.com/security/report/list?directory=aspose-imaging&minver=1.0&maxver=2.0"

curl "https://api.procurize.com/security/report/list?project=aspose-imaging-net&version=1.0"

Response Example

{
  "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"
    }
  ]
}

Response Fields

  • organizationId：报告所属的组织。
  • reports[].id：唯一的报告 ID。将此值传递给下载接口。
  • reports[].projectName：产品的显示名称。
  • reports[].projectVersion：产品的版本。
  • reports[].reportType：报告类型（OWASP Top 10 或 CWE Top 25）。
  • reports[].reportVersion：报告标准的版本（年份）。
  • reports[].date：报告生成的日期。
  • reports[].uploadDate：报告上传至 Procurize 的日期。
  • reports[].vulnerabilitiesCount：发现的漏洞数量。
  • reports[].securityRating：整体安全评级（A–E，其中 A 为最高）。

按 ID 下载报告#

下载包含所选报告的 ZIP 压缩包。每个报告均包含 HTML 和 PDF 两种格式。

Endpoint

GET /security/report/files

Query Parameters

  • org（必需）：组织 ID 或别名（例如 aspose 或 groupdocs）。
  • reports（必需）：要包含的报告 ID。若要包含多个报告，请重复该参数。

Request Example

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

Response

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

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

处理单个报告#

/security/report/html、/security/report/pdf 与 /security/report/zip 接口返回单个特定报告，且遵循相同的选择规则。

报告选择#

报告类型和版本始终是必需的：

  • rt（必需）：报告类型。支持的值为 OWASP Top 10 和 CWE Top 25。
  • rv（必需）：报告版本——标准版本的年份，例如 OWASP Top 10 为 2025，CWE Top 25 为 2024。

随后可通过以下两种方式之一确定具体报告：

  • 通过报告 ID — 传递 id（报告 ID）以及 project（项目 ID 或别名）或 org（组织 ID 或别名）之一。此模式下不要传递 version。
  • 通过项目版本 — 传递 project（项目 ID 或别名，例如 aspose-imaging-net 或 groupdocs-annotation-java）和 version（项目版本）。此模式下不使用 org 参数。

当 project 与 org 同时指定时，org 将被忽略。

获取报告的 HTML 版本#

渲染单个报告为 HTML 页面，或将其作为可下载的 HTML 文件返回。

Endpoint

GET /security/report/html

Query Parameters

  • rt（必需）：报告类型。
  • rv（必需）：报告版本。
  • 报告选择参数：参见 报告选择。
  • download（可选）：设为 true 时返回 HTML 文件下载（Content-Disposition: attachment）。省略或设为 false 时，报告内联返回。

Request Example

curl "https://api.procurize.com/security/report/html?rt=OWASP+Top+10&rv=2025&id=00000000-0000-0000-0000-000000000004&project=aspose-imaging-net"

若要下载 HTML 文件而不是内联渲染：

curl "https://api.procurize.com/security/report/html?rt=OWASP+Top+10&rv=2025&project=aspose-imaging-net&version=1.0&download=true" -o report.html

Response

  • Content-Type: text/html

获取报告的 PDF 版本#

返回单个报告的 PDF 文档。

Endpoint

GET /security/report/pdf

Query Parameters

  • rt（必需）：报告类型。
  • rv（必需）：报告版本。
  • 报告选择参数：参见 报告选择。

Request Example

curl "https://api.procurize.com/security/report/pdf?rt=CWE+Top+25&rv=2024&project=aspose-imaging-net&version=1.0" -o report.pdf

Response

  • Content-Type: application/pdf

获取报告的 ZIP 版本#

返回包含 HTML 与 PDF 两个版本的单个报告的 ZIP 压缩包。

Endpoint

GET /security/report/zip

Query Parameters

  • rt（必需）：报告类型。
  • rv（必需）：报告版本。
  • 报告选择参数：参见 报告选择。

Request Example

curl "https://api.procurize.com/security/report/zip?rt=CWE+Top+25&rv=2024&id=00000000-0000-0000-0000-000000000004&org=groupdocs" -o report.zip

Response

  • Content-Type: application/zip

下载项目的所有报告#

下载包含指定项目所有报告的 ZIP 压缩包，报告同时提供 HTML 与 PDF 两种格式。

Endpoint

GET /security/report/project-files

Query Parameters

  • id（必需）：项目 ID。不支持别名；请传递项目的 UUID。
  • rt（可选）：按报告类型过滤。支持的值为 OWASP Top 10 和 CWE Top 25。
  • rv（可选）：按报告版本（年份）过滤。
  • version（可选）：按项目版本过滤。

如果未指定过滤条件，则包含项目的所有报告。过滤参数可组合使用，且相互独立。

Request Example

curl "https://api.procurize.com/security/report/project-files?id=00000000-0000-0000-0000-000000000005" -o project-reports.zip

Response

  • Content-Type: application/zip

下载项目组的所有报告#

下载包含指定目录（项目组）中所有项目报告的 ZIP 压缩包，报告同时提供 HTML 与 PDF 两种格式。

Endpoint

GET /security/report/directory-files

Query Parameters

  • id（必需）：目录（项目组）ID。不支持别名；请传递目录的 UUID。
  • rt（可选）：按报告类型过滤。支持的值为 OWASP Top 10 和 CWE Top 25。
  • rv（可选）：按报告版本（年份）过滤。
  • version（可选）：按项目版本过滤。

如果未指定过滤条件，则包含目录中所有项目的报告。过滤参数可组合使用，且相互独立。

Request Example

curl "https://api.procurize.com/security/report/directory-files?id=00000000-0000-0000-0000-000000000006" -o directory-reports.zip

Response

  • Content-Type: application/zip

从 SonarQube 获取报告#

将来自 SonarQube 服务的最新安全报告数据上传至 Procurize。该服务从 SonarQube 获取最新的 issue 数据，转换为 OWASP Top 10 与 CWE Top 25 报告的 JSON 表示，并在响应中返回。

Endpoint

POST /security/reports/fetch

Authentication

此接口需要在 X-API-Key 头中传递 API 令牌。有关生成和使用令牌的详细信息，请参见 API 令牌。

Query Parameters

  • 通过项目 — 传递 project（项目 ID 或别名——参见 标识符和别名）。不要传递 url 或 key。
  • 通过 SonarQube 服务 — 同时传递 url（SonarQube 服务 URL）和 key（SonarQube 项目键）。不要传递 project。

Request Example

获取别名对应项目的报告：

curl -X POST "https://api.procurize.com/security/reports/fetch?project=aspose-imaging-net" \
  -H "X-API-Key: YOUR_API_TOKEN"

直接从 SonarQube 服务获取报告：

curl -X POST "https://api.procurize.com/security/reports/fetch?url=https://sonarqube.example.com&key=my-project-key" \
  -H "X-API-Key: YOUR_API_TOKEN"

Response Example

{
  "Owasp10_2025": {
    "TOTAL_SECURITY_RATING": "A",
    "TOTAL_COUNT": 0,
    ...
  },
  "Cwe25_2025": {
    "TOTAL_SECURITY_RATING": "A",
    "TOTAL_COUNT": 0,
    ...
  }
}

该响应可在发布构建流水线中使用，以决定在公共安全报告格式检测到漏洞时是否停止构建。

Notes

  • 上传报告需要对报告所属产品的个人权限。如果没有此权限，仍可发送请求：平台会返回 403 Forbidden 并自动通知平台管理员，管理员会审查请求并通知您决定。
  • 并非所有 SonarQube 服务都已在 Procurize 平台注册。若要注册新服务，请联系平台管理员；需要该服务的管理员令牌。

错误处理#

API 使用标准的 HTTP 状态码。

  • 200 OK：请求成功
  • 204 No Content：报告不存在
  • 400 Bad Request：参数无效或请求格式错误
  • 401 Unauthorized：缺少或无效的 API 令牌
  • 403 Forbidden：访问被拒绝（例如，缺少产品权限）
  • 500 Internal Server Error：服务器内部错误

错误响应包含机器可读的错误代码和人类可读的消息。

另请参阅：#

相关文档#

什么是安全报告？

安全报告仓库

如何配置安全报告

到顶部
选择语言
English
Български
Čeština
Dansk
Deutsch
Ελληνική
Eestlane
Español
Suomalainen
Français
Hrvatski
Magyar
Հայերեն
Indonesia
Italiano
Lietuvių
Melayu
Nederlands
Polski
Português
Română
Русский
Slovenský
Svenska
ไทย
Türk
Українська
Tiếng Việt
한국어
日本語
中文
العربية
ქართული
עִברִית
हिंदी
فارسی