API Báo cáo SonarQube#

Bài viết này mô tả cách truy cập các báo cáo bảo mật SonarQube một cách lập trình, được lưu trữ trên nền tảng Procurize. Nó bao gồm API REST để liệt kê báo cáo và tải chúng dưới dạng HTML, PDF và ZIP.

Tổng quan#

Mô-đun phụ Báo cáo SonarQube cho phép các tổ chức lưu trữ và quản lý tập trung các báo cáo bảo mật và chất lượng mã nguồn được tạo bởi SonarQube. Nền tảng Procurize cung cấp dữ liệu này qua một API REST công cộng, cho phép bạn:

  • Liệt kê siêu dữ liệu báo cáo cho một tổ chức, một nhóm dự án, hoặc một dự án
  • Tải một báo cáo duy nhất dưới dạng HTML, PDF hoặc ZIP
  • Tải các báo cáo đã chọn dưới dạng tệp ZIP
  • Tải tất cả báo cáo của một dự án hoặc một nhóm dự án dưới dạng tệp ZIP
  • Lấy các báo cáo OWASP Top 10 và CWE Top 25 mới nhất trực tiếp từ dịch vụ SonarQube

Các khả năng này cho phép tích hợp với các pipeline CI/CD, hệ thống GRC, bảng điều khiển nội bộ và công cụ quản lý rủi ro của bên thứ ba.

Các điểm cuối#

EndpointMethodPurpose
/security/report/listGETLiệt kê siêu dữ liệu báo cáo cho phạm vi và phiên bản đã chọn.
/security/report/filesGETTải các báo cáo đã chọn dưới dạng tệp ZIP.
/security/report/htmlGETLấy một báo cáo duy nhất dưới dạng HTML.
/security/report/pdfGETLấy một báo cáo duy nhất dưới dạng PDF.
/security/report/zipGETLấy một báo cáo duy nhất dưới dạng tệp ZIP.
/security/report/project-filesGETTải tất cả báo cáo của một dự án dưới dạng tệp ZIP.
/security/report/directory-filesGETTải tất cả báo cáo của một nhóm dự án (thư mục) dưới dạng tệp ZIP.
/security/reports/fetchPOSTLấy các báo cáo mới nhất từ dịch vụ SonarQube.

Xác thực và ủy quyền#

Các điểm cuối liệt kê và tải báo cáo được mô tả trong bài viết này không yêu cầu xác thực.

Điểm cuối POST /security/reports/fetch yêu cầu xác thực bằng token API — xem API Tokens.

ID Tổ chức#

Một định danh tổ chức là bắt buộc cho hầu hết các yêu cầu được mô tả ở đây. Bạn có thể truyền ID tổ chức (UUID) hoặc bí danh của nó — xem Identifiers and Aliases.

Bạn có thể tìm thấy nó trong bảng điều khiển cài đặt của Tổ chức tại https://dashboard.procurize.ai.

Lưu ý rằng việc truy cập bảng điều khiển cài đặt yêu cầu ủy quyền, và truy cập bảng điều khiển cài đặt của tổ chức yêu cầu vai trò người dùng ít nhất là Quản trị viên trong tổ chức đó.

Nút sao chép ID

Định danh và Bí danh#

Các tham số phạm vi chấp nhận ID thực thể (UUID) hoặc bí danh dễ đọc. Bí danh giúp các yêu cầu dễ đọc hơn và ổn định qua các môi trường.

ParameterAcceptsExample aliases
orgID tổ chức hoặc bí danhaspose, groupdocs
directoryID thư mục (nhóm dự án) hoặc bí danhaspose-imaging, groupdocs-annotation
projectID dự án hoặc bí danhaspose-imaging-net, groupdocs-annotation-java

Ví dụ, hai yêu cầu sau là tương đương:

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"

Lưu ý: Bí danh không được hỗ trợ cho tham số id của các điểm cuối tải xuống hàng loạt. Truyền UUID thư mục hoặc dự án vào GET /security/report/project-files và GET /security/report/directory-files.

URL Cơ sở#

Tất cả các điểm cuối REST API được phục vụ dưới URL cơ sở sau:

https://api.procurize.com

API REST Báo cáo SonarQube#

Liệt kê Báo cáo#

Trả về các báo cáo bảo mật có sẵn cho phạm vi và phiên bản đã chọn, không kèm nội dung tệp. Sử dụng điểm cuối này để khám phá các ID báo cáo có thể truyền vào các điểm cuối tải xuống.

Endpoint

GET /security/report/list

Query Parameters

  • org (tùy chọn): ID tổ chức hoặc bí danh (ví dụ, aspose hoặc groupdocs). Phạm vi rộng nhất.
  • directory (tùy chọn): ID thư mục (nhóm dự án) hoặc bí danh (ví dụ, aspose-imaging hoặc groupdocs-annotation). Phạm vi hẹp hơn.
  • project (tùy chọn): ID dự án hoặc bí danh (ví dụ, aspose-imaging-net hoặc groupdocs-annotation-java). Phạm vi hẹp nhất.
  • version (tùy chọn): Phiên bản dự án chính xác.
  • minver (tùy chọn): Phiên bản dự án tối thiểu.
  • maxver (tùy chọn): Phiên bản dự án tối đa.

Ít nhất một trong các tham số phạm vi org, directory, hoặc project là bắt buộc. Các phạm vi được ưu tiên như sau: nếu project được chỉ định, chỉ dự án đó được tìm kiếm; nếu không, nếu directory được chỉ định, toàn bộ nhóm dự án được tìm kiếm; nếu không, toàn bộ tổ chức (org) được tìm kiếm. Khi org được chỉ định cùng với project hoặc directory, mục tiêu sẽ được kiểm tra thêm để chắc chắn thuộc về tổ chức đó.

Ít nhất một trong version, minver, hoặc maxver là bắt buộc. Nếu version được chỉ định, minver và maxver sẽ bị bỏ qua.

Request Example

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

Scoping to a project group or a project by alias:

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: ID tổ chức mà các báo cáo thuộc về.
  • reports[].id: ID báo cáo duy nhất. Truyền giá trị này vào các điểm cuối tải xuống.
  • reports[].projectName: Tên hiển thị của sản phẩm.
  • reports[].projectVersion: Phiên bản của sản phẩm.
  • reports[].reportType: Loại báo cáo (OWASP Top 10 hoặc CWE Top 25).
  • reports[].reportVersion: Phiên bản (năm) của tiêu chuẩn báo cáo.
  • reports[].date: Ngày báo cáo được tạo.
  • reports[].uploadDate: Ngày báo cáo được tải lên Procurize.
  • reports[].vulnerabilitiesCount: Số lượng lỗ hổng được tìm thấy.
  • reports[].securityRating: Xếp hạng bảo mật tổng thể (A–E, trong đó A là tốt nhất).

Tải Báo cáo theo ID#

Tải một tệp ZIP chứa các báo cáo đã chọn. Mỗi báo cáo được bao gồm cả định dạng HTML và PDF.

Endpoint

GET /security/report/files

Query Parameters

  • org (bắt buộc): ID tổ chức hoặc bí danh (ví dụ, aspose hoặc groupdocs).
  • reports (bắt buộc): Các ID báo cáo cần bao gồm. Lặp lại tham số để bao gồm nhiều báo cáo.

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
  • Thân phản hồi chứa tệp ZIP nhị phân.

Các client nên stream phản hồi và lưu nó vào đĩa.

Làm việc với một Báo cáo Đơn lẻ#

Các điểm cuối /security/report/html, /security/report/pdf, và /security/report/zip trả về một báo cáo cụ thể và chia sẻ cùng quy tắc lựa chọn.

Lựa chọn Báo cáo#

Loại báo cáo và phiên bản luôn luôn bắt buộc:

  • rt (bắt buộc): Loại báo cáo. Các giá trị hỗ trợ là OWASP Top 10 và CWE Top 25.
  • rv (bắt buộc): Phiên bản báo cáo — năm của phiên bản tiêu chuẩn, ví dụ 2025 cho OWASP Top 10 hoặc 2024 cho CWE Top 25.

Báo cáo cụ thể sau đó được chọn theo một trong hai cách:

  • Theo ID báo cáo — truyền id (ID báo cáo) cùng với project (ID hoặc bí danh dự án) hoặc org (ID hoặc bí danh tổ chức). Không truyền version trong chế độ này.
  • Theo phiên bản dự án — truyền project (ID hoặc bí danh dự án, ví dụ aspose-imaging-net hoặc groupdocs-annotation-java) và version (phiên bản dự án). Tham số org không được sử dụng trong chế độ này.

Khi cả project và org đều được chỉ định, org sẽ bị bỏ qua.

Lấy Báo cáo dưới dạng HTML#

Renders a single report as an HTML page, or returns it as a downloadable HTML file.

Endpoint

GET /security/report/html

Query Parameters

  • rt (bắt buộc): Loại báo cáo.
  • rv (bắt buộc): Phiên bản báo cáo.
  • Các tham số lựa chọn báo cáo: xem Lựa chọn Báo cáo.
  • download (tùy chọn): Đặt thành true để trả về HTML dưới dạng tải xuống tệp (Content-Disposition: attachment). Khi bỏ qua hoặc false, báo cáo được trả về inline.

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"

Để tải tệp HTML thay vì hiển thị inline:

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

Lấy Báo cáo dưới dạng PDF#

Returns a single report as a PDF document.

Endpoint

GET /security/report/pdf

Query Parameters

  • rt (bắt buộc): Loại báo cáo.
  • rv (bắt buộc): Phiên bản báo cáo.
  • Các tham số lựa chọn báo cáo: xem Lựa chọn Báo cáo.

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

Lấy Báo cáo dưới dạng ZIP#

Returns a single report as a ZIP archive that contains both the HTML and PDF versions.

Endpoint

GET /security/report/zip

Query Parameters

  • rt (bắt buộc): Loại báo cáo.
  • rv (bắt buộc): Phiên bản báo cáo.
  • Các tham số lựa chọn báo cáo: xem Lựa chọn Báo cáo.

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

Tải Tất cả Báo cáo của một Dự án#

Downloads a ZIP archive containing all reports of the specified project, in both HTML and PDF formats.

Endpoint

GET /security/report/project-files

Query Parameters

  • id (bắt buộc): ID dự án. Bí danh không được hỗ trợ; truyền UUID dự án.
  • rt (tùy chọn): Lọc theo loại báo cáo. Các giá trị hỗ trợ là OWASP Top 10 và CWE Top 25.
  • rv (tùy chọn): Lọc theo phiên bản báo cáo (năm).
  • version (tùy chọn): Lọc theo phiên bản dự án.

Nếu không có bộ lọc nào được chỉ định, tất cả báo cáo của dự án sẽ được bao gồm. Các tham số lọc có thể kết hợp và được áp dụng độc lập.

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

Tải Tất cả Báo cáo của một Nhóm Dự án#

Downloads a ZIP archive containing reports of all projects in the specified directory (project group), in both HTML and PDF formats.

Endpoint

GET /security/report/directory-files

Query Parameters

  • id (bắt buộc): ID thư mục (nhóm dự án). Bí danh không được hỗ trợ; truyền UUID thư mục.
  • rt (tùy chọn): Lọc theo loại báo cáo. Các giá trị hỗ trợ là OWASP Top 10 và CWE Top 25.
  • rv (tùy chọn): Lọc theo phiên bản báo cáo (năm).
  • version (tùy chọn): Lọc theo phiên bản dự án.

Nếu không có bộ lọc nào được chỉ định, báo cáo của tất cả dự án trong thư mục sẽ được bao gồm. Các tham số lọc có thể kết hợp và được áp dụng độc lập.

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

Lấy Báo cáo từ SonarQube#

Uploads the latest security report data for a product from a SonarQube service to Procurize. The service retrieves the latest issue data from SonarQube, converts it into JSON representations of the latest versions of the OWASP Top 10 and CWE Top 25 reports, and returns them in the response.

Endpoint

POST /security/reports/fetch

Authentication

Điểm cuối này yêu cầu token API, được truyền trong header X-API-Key. Để biết chi tiết về tạo và sử dụng token, xem API Tokens.

Query Parameters

Nguồn SonarQube được chọn theo một trong hai cách:

  • Theo dự án — truyền project (ID hoặc bí danh dự án — xem Identifiers and Aliases). Không truyền url hoặc key.
  • Theo dịch vụ SonarQube — truyền url (URL dịch vụ SonarQube) và key (khóa dự án SonarQube) cùng nhau. Không truyền project.

Request Example

Lấy báo cáo cho một dự án theo bí danh của nó:

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

Lấy báo cáo trực tiếp từ dịch vụ 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,
    ...
  }
}

Phản hồi này hữu ích trong các pipeline xây dựng phát hành để quyết định có dừng build hay không khi phát hiện lỗ hổng trong các định dạng báo cáo bảo mật công cộng.

Notes

  • Việc tải lên báo cáo yêu cầu quyền cá nhân cho sản phẩm mà báo cáo thuộc về. Nếu bạn không có quyền này, vẫn gửi yêu cầu: nền tảng sẽ trả về 403 Forbidden và tự động thông báo cho quản trị viên nền tảng, những người sẽ xem xét yêu cầu và thông báo quyết định cho bạn.
  • Không phải mọi dịch vụ SonarQube đều được đăng ký trên nền tảng Procurize. Để đăng ký dịch vụ mới, liên hệ với quản trị viên nền tảng; cần một token quản trị cho dịch vụ đó.

Xử lý Lỗi#

API sử dụng các mã trạng thái HTTP chuẩn.

  • 200 OK: Yêu cầu thành công
  • 204 No Content: Báo cáo không tồn tại
  • 400 Bad Request: Tham số không hợp lệ hoặc yêu cầu sai định dạng
  • 401 Unauthorized: Thiếu hoặc token API không hợp lệ
  • 403 Forbidden: Truy cập bị từ chối (ví dụ, thiếu quyền cho sản phẩm)
  • 500 Internal Server Error: Lỗi máy chủ không mong muốn

Phản hồi lỗi bao gồm mã lỗi máy có thể đọc được và thông báo dành cho người dùng.

Xem thêm:#

Bài viết liên quan#

What are Security Reports?

Security reports repository

How to Configure Security Reports

đến đầu
Chọn ngôn ngữ
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
한국어
日本語
中文
العربية
ქართული
עִברִית
हिंदी
فارسی