SonarQube 보고서 API 및 웹후크

이 문서는 Procurize 플랫폼에 저장된 SonarQube 보안 보고서에 프로그래밍 방식으로 접근하는 방법을 설명합니다. 보고서 목록 조회 및 가져오기, 보고서 아카이브 다운로드, 새로운 보고서가 들어올 때 웹후크 알림을 구독하는 방법을 다룹니다.

개요

SonarQube 보고서 서브모듈은 조직이 SonarQube에서 생성된 보안 및 코드 품질 보고서를 중앙에서 저장하고 관리할 수 있게 해줍니다. Procurize 플랫폼은 이를 다음을 통해 제공됩니다:

저장된 보고서에 대한 메타데이터를 검색하는 REST API
ZIP 아카이브 형태로 보고서 아티팩트를 다운로드하는 엔드포인트
새 보고서가 사용 가능해질 때 거의 실시간 알림을 제공하는 웹후크

이 기능들은 CI/CD 파이프라인, GRC 시스템, 내부 대시보드, 서드파티 위험 관리 도구와의 통합을 가능하게 합니다.

인증 및 권한 부여

이 문서에 설명된 모든 API 요청은 인증이 필요하지 않습니다.

조직 ID

모든 요청에 조직 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 (옵션): Semantic Versioning 형식의 정확한 제품 버전.
minver (옵션): Semantic Versioning 형식의 최소 제품 버전.
maxver (옵션): Semantic Versioning 형식의 최대 제품 버전.

요청에는 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: 예상치 못한 서버 오류

오류 응답에는 기계가 읽을 수 있는 오류 코드와 사람이 읽을 수 있는 메시지가 포함됩니다.

웹후크

Procurize 웹후크를 사용하면 외부 시스템이 새로운 SonarQube 보고서가 들어오거나 업데이트될 때 알림을 받을 수 있습니다.

웹후크 구성

웹후크는 조직의 설정 패널, 보안 보고서 섹션에서 추가하거나 편집할 수 있습니다(https://dashboard.procurize.ai).
설정 패널에 접근하려면 권한이 필요하며, 조직의 설정 패널에 접근하려면 해당 조직에서 최소 관리자 역할이 필요합니다.

웹후크 편집기

웹후크를 확인하려면 https://webhook-test.com 과 같은 온라인 서비스를 사용할 수 있습니다.

웹후크 페이로드

웹후크 이벤트는 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"
    }
  ]
}

웹후크 보안

인증을 보장하기 위해 웹후크 요청에는 공유 비밀을 사용해 생성된 시그니처 헤더가 포함됩니다.

시그니처는 HMAC-SHA256을 사용해 계산됩니다
클라이언트는 페이로드를 처리하기 전에 시그니처를 검증해야 합니다

이를 통해 무단 또는 위조된 웹후크 전달을 방지합니다.

전달 및 재시도

웹후크는 2xx 응답을 성공적인 전달로 간주합니다
실패한 전달은 매시간 자동 재시도됩니다.
이벤트가 여러 번 전달될 수 있으므로, 소비자는 멱등 처리 구현이 필요합니다

일반적인 사용 사례

SonarQube 발견 사항을 자동으로 내부 보안 대시보드에 수집
품질 게이트 실패 시 컴플라이언스 워크플로 트리거
감사 및 공급업체 위험 검토를 위해 보안 보고서를 아카이브
타사 시스템을 최신 코드 보안 상태와 동기화 유지