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/fetchPOSTSonarQube 서비스에서 최신 보고서를 가져오기

인증 및 권한 부여#

이 문서에 설명된 보고서 목록 및 다운로드 엔드포인트는 인증이 필요하지 않습니다.

POST /security/reports/fetch 엔드포인트는 API 토큰을 사용한 인증이 필요합니다 — 자세한 내용은 API 토큰을 참고하세요.

조직 ID#

대부분의 요청에 조직 식별자가 필요합니다. 조직 ID( UUID) 또는 별칭을 전달할 수 있습니다 — 자세한 내용은 식별자 및 별칭을 참고하세요.
조직 ID는 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를 찾을 수 있습니다.

엔드포인트

GET /security/report/list

쿼리 매개변수

  • 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는 무시됩니다.

요청 예시

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"

응답 예시

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

응답 필드

  • 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 형식으로 포함됩니다.

엔드포인트

GET /security/report/files

쿼리 매개변수

  • org (필수): 조직 ID 또는 별칭 (예: aspose 또는 groupdocs).
  • reports (필수): 포함할 보고서 ID. 여러 보고서를 포함하려면 매개변수를 반복합니다.

요청 예시

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

응답

  • 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 또는 별칭)와 version(프로젝트 버전)을 전달합니다. 이 경우 org 매개변수는 사용되지 않습니다.

project와 org가 모두 지정되면 org는 무시됩니다.

HTML 형식 보고서 가져오기#

단일 보고서를 HTML 페이지로 렌더링하거나 다운로드 가능한 HTML 파일로 반환합니다.

엔드포인트

GET /security/report/html

쿼리 매개변수

  • rt (필수): 보고서 유형.
  • rv (필수): 보고서 버전.
  • 보고서 선택 매개변수: 보고서 선택 참고.
  • download (선택): true 로 설정하면 HTML을 파일 다운로드(Content-Disposition: attachment) 형태로 반환합니다. 생략하거나 false이면 인라인으로 반환됩니다.

요청 예시

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

응답

  • Content-Type: text/html

PDF 형식 보고서 가져오기#

단일 보고서를 PDF 문서로 반환합니다.

엔드포인트

GET /security/report/pdf

쿼리 매개변수

  • rt (필수): 보고서 유형.
  • rv (필수): 보고서 버전.
  • 보고서 선택 매개변수: 보고서 선택 참고.

요청 예시

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

응답

  • Content-Type: application/pdf

ZIP 형식 보고서 가져오기#

HTML 및 PDF 버전을 모두 포함하는 ZIP 아카이브 형태로 단일 보고서를 반환합니다.

엔드포인트

GET /security/report/zip

쿼리 매개변수

  • rt (필수): 보고서 유형.
  • rv (필수): 보고서 버전.
  • 보고서 선택 매개변수: 보고서 선택 참고.

요청 예시

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

응답

  • Content-Type: application/zip

프로젝트 전체 보고서 다운로드#

지정된 프로젝트의 모든 보고서를 HTML 및 PDF 형식으로 포함하는 ZIP 아카이브를 다운로드합니다.

엔드포인트

GET /security/report/project-files

쿼리 매개변수

  • id (필수): 프로젝트 ID. 별칭은 지원되지 않으며 프로젝트 UUID를 전달해야 합니다.
  • rt (선택): 보고서 유형으로 필터링. 지원 값은 OWASP Top 10 및 CWE Top 25.
  • rv (선택): 보고서 버전(연도)으로 필터링.
  • version (선택): 프로젝트 버전으로 필터링.

필터를 지정하지 않으면 프로젝트의 모든 보고서가 포함됩니다. 필터 매개변수는 조합해서 사용할 수 있으며 독립적으로 적용됩니다.

요청 예시

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

응답

  • Content-Type: application/zip

프로젝트 그룹 전체 보고서 다운로드#

지정된 디렉터리(프로젝트 그룹) 내 모든 프로젝트의 보고서를 HTML 및 PDF 형식으로 포함하는 ZIP 아카이브를 다운로드합니다.

엔드포인트

GET /security/report/directory-files

쿼리 매개변수

  • id (필수): 디렉터리(프로젝트 그룹) ID. 별칭은 지원되지 않으며 디렉터리 UUID를 전달해야 합니다.
  • rt (선택): 보고서 유형으로 필터링. 지원 값은 OWASP Top 10 및 CWE Top 25.
  • rv (선택): 보고서 버전(연도)으로 필터링.
  • version (선택): 프로젝트 버전으로 필터링.

필터를 지정하지 않으면 디렉터리 내 모든 프로젝트의 보고서가 포함됩니다. 필터 매개변수는 조합해서 사용할 수 있으며 독립적으로 적용됩니다.

요청 예시

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

응답

  • Content-Type: application/zip

SonarQube에서 보고서 가져오기#

SonarQube 서비스에서 제품에 대한 최신 보안 보고서 데이터를 Procurize에 업로드합니다. 서비스는 SonarQube에서 최신 이슈 데이터를 가져와 OWASP Top 10 및 CWE Top 25 보고서의 최신 버전을 JSON 형태로 변환하고 응답에 포함합니다.

엔드포인트

POST /security/reports/fetch

인증

이 엔드포인트는 X-API-Key 헤더에 API 토큰을 전달해야 합니다. 토큰 생성 및 사용 방법은 API 토큰을 참고하세요.

쿼리 매개변수

SonarQube 소스는 다음 두 가지 방법 중 하나로 선택합니다:

  • 프로젝트 기반 — project(프로젝트 ID 또는 별칭) 를 전달합니다. (url 또는 key는 전달하지 않음) — 식별자 및 별칭 참고.
  • 서비스 기반 — url(SonarQube 서비스 URL) 과 key(SonarQube 프로젝트 키)를 함께 전달합니다. project는 전달하지 않음.

요청 예시

별칭으로 프로젝트 보고서를 가져오기:

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"

응답 예시

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

이 응답은 릴리즈 빌드 파이프라인에서 취약점이 발견된 경우 빌드를 중단할지 여부를 결정하는 데 유용합니다.

참고 사항

  • 보고서를 업로드하려면 해당 제품에 대한 개인 권한이 필요합니다. 권한이 없더라도 요청을 보내면 플랫폼이 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
한국어
日本語
中文
العربية
ქართული
עִברִית
हिंदी
فارسی