기본 SonarQube 인스턴스

• sonarqube-config 가 default 로 설정되면 SonarQube 가 기본적으로 스캔에 사용됩니다. 이 스캔은 Docker-in -Docker로 실행됩니다.

사용된 인스턴스는 실행 중에만 사용 가능합니다. 따라서 대시보드에 접근할 수 없습니다.

• 기본적으로 파이프라인은 제한된 checks.Many 취약성 규칙만 있는 SonarQube 커뮤니티 에디션을 사용하며 호스트 스팟 문제는 Community Edition에서 다루지 않습니다.

• 커뮤니티 에디션에서 취약성이 확인되었는지 확인하려면 Sonarqube 커뮤니티 질문의 스레드 를 참조하십시오.

SonarQube, 다운로드하려면 SonarQube 다운로드를 참조하세요.

dev 클러스터의 SonarQube 인스턴스

sonarqube-config 가 cluster 로 설정되면 파이프라인이 dev 클러스터에서 파이프라인 실행 중에 SonarQube 인스턴스를 작성합니다. 정적 스캔 단계가 runs.You 포트 전달을 통해 로컬로 SonarQube 대시보드에 액세스할 수 있습니다.

기존 SonarQube 인스턴스

sonarqube-config 을 custom 으로 설정하여 기존 파이프라인에 SonarQube 인스턴스를 추가하고, 도구 통합을 도구 체인에 추가한 다음 SonarQube 도구 통합 매개변수를 파이프라인에 추가합니다. 자세한 정보는 SonarQube구성 을 참조하십시오.

자체 서명 인증서가 있는 소나퀘이브 서버

sonarqube-config 을 custom 으로 설정하여 기존 소나퀘이브 서버 를 사용하고 서버에 자체 서명된 인증서가 있는 경우, 소나 스캐너가 소나퀘이브 서버에 성공적으로 연결하려면 자체 서명된 인증서를 신뢰할 수 있는 CA 인증서에 추가해야 합니다.

인증서를 파이프라인/트리거 속성 sonarqube-root-certificate 의 값으로 PEM 형식( base64 인코딩된 비밀 값 또는 PEM 형식의 일반 텍스트)으로 제공하면, maven의 경우 SonarScanner, gradle sonar의 경우 SonarScanner 또는 Docker 으로 호출된 SonarScanner 의 사용법에 따라 구성이 추가됩니다.

매개변수

SonarQube 스캔을 실행하려면 파이프라인에 다음과 같은 지속적 통합 매개변수가 필요합니다.

파이프라인 매개변수에 관한 자세한 정보는 파이프라인 매개변수를 참조하십시오.

파이프라인에 여러 SonarQube 도구 통합을 추가하는 경우, 도구 통합 매개변수인 sonarqube 파이프라인 매개변수의 값을 변경하여 이러한 통합 간에 전환할 수 있습니다.

SonarQube 에 설치된 플러그인

DevSecOps 파이프라인은 기본적으로 SonarQube 버전 10.0 사용합니다.

사전 설치된 플러그인 목록에 대한 자세한 정보는 플러그인 을 참조하십시오.

SonarQube 에서 보고된 문제

DevSecOps 파이프라인은 SonarQube 스캔 중에 보고된 문제를 필터링합니다. 파이프라인은 CODE_SMELL 또는 BUG 유형이 아닌 문제에 대한 준수 인시던트를 독점적으로 작성합니다. 파이프라인은 상태가 CLOSED 인 문제점도 건너뜁니다.

앱 미리보기 PR 파이프라인에서 풀 리퀘스트 분석 활성화하기

PR이 대상 리포지토리와 동일한 리포지토리(포크가 아닌)에서 오는 경우 PR 분석 옵션은 App Preview PR pipeline 에서 제공됩니다. 소나퀘이브 인스턴스는 PR 분석도 지원해야 합니다. cluster 및 dind 모드에서 사용되는 기본 sonarqube 인스턴스는 이 기능을 지원하지 않습니다. 풀 리퀘스트 분석은 sonarqube 개발자 에디션부터 사용할 수 있기 때문입니다. 환경 변수 opt-in-sonar-pr-analysis 를 파이프라인에 추가해야 하며 해당 값이 비어 있지 않아야 합니다.

SonarQube 프로젝트에 대한 품질 게이트 결과 처리 활성화하기

SonarQube 의 품질 게이트는 프로젝트가 필요한 코드 품질 표준을 충족하는지 여부를 결정하는 일련의 조건입니다. 품질 게이트에 대해 자세히 알아보려면 SonarQube 문서를 참조하세요.

SonarQube 이슈 파서는 SonarQube 품질 게이트 결과를 처리하고 이로 인해 장애가 발생하면 이슈를 생성하는 것을 지원합니다. 품질 게이트 결과 처리를 활성화하려면 환경 속성 opt-in-sonar-quality-gates 을 1 으로 설정합니다.

opt-in-sonar-quality-gates 이 1 으로 설정되어 있고 자체 SonarQube 인스턴스를 통합으로 사용하는 경우( sonarqube-config 이 custom 으로 설정되어 있음), 품질 게이트 이름을 가져오려면 SonarQube 웹 API에 액세스하는 데 필요한 권한으로 SonarQube 사용자 토큰을 생성하고 토큰을 비밀 값으로 파이프라인 환경 속성 sonarqube-user-token 을 설정할 수 있습니다. 필요한 토큰 권한에 대한 자세한 내용은 SonarQube 토큰 권한을 참조하세요.

파이프라인에서 만든 SonarQube 인스턴스 또는 사용자 지정 SonarQube 도구 통합을 사용하는 경우 다음 단계에 따라 SonarQube 대시보드를 탐색하세요:

1. static-scan 태스크의 파이프라인 로그에서 URL로 작성된 SonarQube 대시보드로 이동하십시오.

   

2. 기본적으로 Sonar way 품질 게이트는 특정 품질 게이트와 명시적으로 연결되지 않은 모든 프로젝트와 연결됩니다. 사용자 지정 메트릭 조건이 있는 새로운 품질 게이트도 만들 수 있습니다.

   • 대시보드에서 품질 관리 게이트 목록을 찾으려면 상단 탐색 모음에서 품질 관리 게이트를 클릭합니다.

     

   • 새 품질 게이트를 만들려면 상단 탐색 모음에서 품질 게이트를 클릭한 다음 만들기를 클릭합니다. 품질 게이트에 이름을 추가하고 조건 메트릭을 추가/삭제/업데이트할 수 있습니다.

   • 프로젝트와 연결된 품질 게이트를 찾으려면 프로젝트를 선택한 다음 프로젝트 설정 > 품질 게이트를 클릭합니다.

     

   • 특정 프로젝트에 (기본 품질 게이트가 아닌) 품질 게이트를 연결하려면 프로젝트를 선택한 다음 프로젝트 설정 > 품질 게이트 > 항상 특정 품질 게이트 사용 > 드롭다운에서 필요한 품질 게이트 선택 > 저장을 클릭합니다

     

3. 새 스캔은 이 품질 게이트를 통해 평가되고 증거는 품질 게이트의 결과로 작성됩니다. 이슈는 품질 게이트 실패의 원인이 된 조건에 따라 생성됩니다.

   소나퀘이브 API의 응답인 품질 게이트 상태 결과 형식의 예: ${SONAR_HOST_URL}/api/qualitygates/project_status?projectKey=${SONAR_PROJECT_KEY}:

   {
      "projectStatus": {
         "status": "ERROR",
         "conditions": [
            {
            "status": "ERROR",
            "metricKey": "new_coverage",
            "comparator": "LT",
            "errorThreshold": "80",
            "actualValue": "0.0"
            },
            {
            "status": "OK",
            "metricKey": "new_duplicated_lines_density",
            "comparator": "GT",
            "errorThreshold": "3",
            "actualValue": "0.0"
            },
            {
            "status": "ERROR",
            "metricKey": "new_security_hotspots_reviewed",
            "comparator": "LT",
            "errorThreshold": "100",
            "actualValue": "0.0"
            },
            {
            "status": "ERROR",
            "metricKey": "new_violations",
            "comparator": "GT",
            "errorThreshold": "0",
            "actualValue": "14"
            }
         ],
         "ignoredConditions": false,
         "period": {
            "mode": "PREVIOUS_VERSION",
            "date": "2025-03-18T09:43:25+0000"
         },
         "caycStatus": "compliant",
         "additional": {
            "qualityGateName": "Sonar way",
            "projectKey": "hello-compliance-app-compliance-check",
            "dashboardUrl": "http://localhost:9001/dashboard?id=hello-compliance-app-compliance-check"
         }
      }
   }
   
   

   SonarQube API에 대한 자세한 내용은 소나퀘이브 WebAPI 문서를 참조하세요

   상태가 오류인 각 메트릭 키에 대해 이슈가 생성되어 실패한 모든 메트릭을 개별적으로 추적하고 해결할 수 있습니다.

   문제 예시:

   

   예 SonarQube 품질 게이트 오류로 인한 증거 실패:

   {
      "id": "abc",
      "evidence_type_id": "com.ibm.static_scan",
      "evidence_type_version": "1.0.0",
      "date": "2025-03-18T11:22:35.086Z",
      "origin": {
      },
      "details": {
         "result": "failure",
         "tool": "sonarqube",
         "failure_reason": "tool_detected_vulnerabilities"
      },
      "issues": [
         "https://github.com/<org-name>/compliance-issues-20250310111628285/issues/14",
         "https://github.com/<org-name>/compliance-issues-20250310111628285/issues/15"
      ],
      "findings": [
         {
            "id": "Metric: new_coverage",
            "due_date": "n/a",
            "severity": "high",
            "first_found": "2025-03-18",
            "url": "https://github.com/<org-name>/compliance-issues-repo/issues/14",
            "found_status": "existing",
            "has_exempt": false,
            "cvss": "n/a",
            "package": []
         },
         {
            "id": "Metric: new_security_hotspots_reviewed",
            "due_date": "n/a",
            "severity": "high",
            "first_found": "2025-03-18",
            "url": "https://github.com/<org-name>/compliance-issues-repo/issues/15",
            "found_status": "existing",
            "has_exempt": false,
            "cvss": "n/a",
            "package": []
         }
      ],
      "attachments": [
         {
            "hash": "d10a1e5d727b4f778a1d70c2ebaa2060251d56dd79",
            "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/attachments/d10a1e5d727b4f778a1d70c2e/content",
            "label": "app_issues"
         },
         {
            "hash": "d76d356cc4da1afc942a6259c1222a7b079607ea7e0d64",
            "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/attachments/d76d356cc4da1afc942a6259c1222a7b0/content",
            "label": "app_hotspots"
         },
         {
            "hash": "f0f84a2c2210a9c65c8430d577dafdd71bee6df5da",
            "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/attachments/f0f84a2c2210a9c65c8430d577dafdd71bee6e/content",
            "label": "app_quality_status_updated"
         }
      ],
      "assets": [
         {
            "hash": "1812f77dfc646c93320794810460acd3e53",
            "uri": "https://github.com/<org-name>/abcd/compliance-app-20250310111628285.git#7a06e70001a59032d1",
            "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/assets/1812f77dfc646c93320794810460acd3e/index.json"
         }
      ]
   }
   
   

CI 파이프라인에서 활성화된 경우 CC에서 opt-in-sonar-quality-gates 를 활성화해야 합니다. 그렇지 않으면 CC에서 발견한 품질 게이트 문제가 자동으로 닫힙니다. 현재 이 불일치에 관한 경고 메시지를 로그에 표시하고 있습니다.

SonarQube, 에 대해 자세히 알아보려면 SonarQube 문서를 참조하세요.

SonarQube 핫스팟 처리 활성화

SonarQube 핫스팟은 실제 위험을 초래하는지 여부를 판단하기 위해 수동 검토가 필요한 보안에 민감한 코드를 강조 표시합니다. 개발자가 오탐을 발생시키지 않고 잠재적인 취약점에 집중할 수 있도록 도와줍니다. 핫스팟 관리에 대해 자세히 알아보려면 SonarQube 문서를 참조하세요.

SonarQube 핫스팟 처리를 활성화하려면 환경 속성 opt-in-sonar-hotspots 을 1 로 설정합니다.

opt-in-sonar-hotspots 이 1 으로 설정되어 있고 자체 SonarQube 인스턴스를 통합으로 사용하는 경우( sonarqube-config 이 custom 로 설정되어 있는 경우), 웹 API를 사용하여 Sonarqube가 감지한 핫스팟을 가져오려면 SonarQube 웹 API에 액세스하는 데 필요한 권한으로 SonarQube 사용자 토큰을 생성하고 토큰을 비밀 값으로 파이프라인 환경 속성 sonarqube-user-token 을 설정할 수 있습니다. 필요한 토큰 권한에 대한 자세한 내용은 SonarQube 토큰 권한을 참조하세요.

• 프로젝트에 대해 SonarQube 에서 탐지한 보안 핫스팟을 확인하려면 프로젝트를 선택한 다음 보안 핫스팟을 클릭합니다.

  

• 감지된 핫스팟을 검토하려면 핫스팟을 선택한 다음 검토를 클릭합니다. 검토 상태를 다음 중 하나로 설정할 수 있는 모달이 나타납니다: To Review, Acknowledged, Fixed 및 Safe.

  

opt-in-sonar-hotspots 플래그를 활성화하면 검토 상태가 SonarQube 으로 설정되지 않은 핫스팟이 감지될 때 이슈가 생성됩니다: Acknowledged, Fixed 및 Safe 에서 감지될 때 생성됩니다.

SonarQube API의 응답인 핫스팟 결과 형식의 예입니다:${SONAR_HOST_URL}/api/hotspots/search?projectKey=${SONAR_PROJECT_KEY}&p=$page&status=TO_REVIEW"

{
   "hotspots": [
      {
         "key": "AYLD_a1_Hqacjdg4wbDR",
         "component": "hello-compliance-app-compliance-check:index.js",
         "project": "hello-compliance-app-compliance-check",
         "securityCategory": "others",
         "vulnerabilityProbability": "LOW",
         "status": "TO_REVIEW",
         "line": 74,
         "message": "Make sure disabling content security policy frame-ancestors directive is safe here.",
         "author": "abc@1.com",
         "creationDate": "2022-04-01T06:29:13+0000",
         "updateDate": "2022-08-22T05:18:31+0000",
         "textRange": {
         "startLine": 74,
         "endLine": 84,
         "startOffset": 0,
         "endOffset": 1
         },
         "flows": [
         {
            "locations": [
               {
               "component": "hello-compliance-app-compliance-check:app.js",
               "textRange": {
                  "startLine": 76,
                  "endLine": 82,
                  "startOffset": 4,
                  "endOffset": 5
               }
               }
            ]
         }
         ],
         "rule": {
         "key": "javascript:S5732"
         }
      }
   ]
}

앞의 API 결과에서 To Review 상태 핫스팟이 발생하면 findings 섹션에 핫스팟 정보를 포함한 장애 증거가 수집됩니다.

예시 SonarQube 핫스팟 감지로 인해 증거에 실패했습니다:

{
  "id": "62fc60140b2a761a969c6ad4f64d93d9c0f8f2301b1",
  "evidence_type_id": "com.ibm.static_scan",
  "evidence_type_version": "1.0.0",
  "date": "2025-03-18T10:29:00.896Z",
  "origin": {
  },
  "details": {
    "result": "failure",
    "tool": "sonarqube",
    "failure_reason": "tool_detected_vulnerabilities"
  },
  "issues": [
    "https://github.com/<org-name>/compliance-issues-20250310111628285/issues/13"
  ],
  "findings": [
    {
      "id": "javascript:S4426",
      "due_date": "n/a",
      "severity": "high",
      "first_found": "2025-03-18",
      "url": "https://github.com/<org-name>/compliance-issues-20250310111628285/issues/12",
      "found_status": "new",
      "has_exempt": false,
      "cvss": "n/a",
      "package": []
    },
    {
      "id": "Hotspot: javascript:S2068",
      "due_date": "n/a",
      "severity": "high",
      "first_found": "2025-03-18",
      "url": "https://github.com/<org-name>/compliance-issues-20250310111628285/issues/13",
      "found_status": "new",
      "has_exempt": false,
      "cvss": "n/a",
      "package": []
    },
  ],
  "attachments": [
    {
      "hash": "e579a1ab8025d280d5870eb8d4464d6d6a41a22",
      "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/attachments/e579a1ab8025d280d5870eb8d4464d6d6a41a/content",
      "label": "app_issues"
    },
    {
      "hash": "6defa891c320ae2b80ae76d03e168edc2379",
      "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/attachments/6defa891c320ae2b80ae76d03e168edc2379748d9/content",
      "label": "app_hotspots"
    },
    {
      "hash": "060a60e2d693427cde6064f72743ebb9e1d6",
      "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/attachments/060a60e2d693427cde6064f72743ebb9e1d/content",
      "label": "app_quality_status_updated"
    }
  ],
  "assets": [
    {
      "hash": "d7391b3273e5e52852f293031d62b9",
      "uri": "https://github.com/<org-name>/compliance-app-20250310111628285.git#4eadaaf7454b8cb0edad927",
      "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/assets/d7391b3273e5e52852f293031d62b9bf0/index.json"
    }
  ]
}

CI 파이프라인에서 활성화된 경우 CC에서 opt-in-sonar-hotspots 를 활성화해야 합니다. 그렇지 않으면 CC가 발견한 핫스팟 문제가 자동으로 닫힙니다. 현재 이 불일치에 관한 경고 메시지를 로그에 표시하고 있습니다.

SonarQube 토큰에 대한 권한

기존 SonarQube 인스턴스를 사용하고 테스트 레코드를 Devops Insights에 성공적으로 게시하고 프로젝트의 품질 게이트 이름을 가져오려면 필요한 권한이 있는 사용자 토큰을 생성하고 환경 속성 sonarqube-user-token 에 비밀 값으로 설정하여 필요한 Sonarqube 엔포인트에 액세스할 수 있는 권한을 제공해야 합니다.

사용자 토큰을 생성하려면 SonarQube 대시보드 열기 > 프로필 사진 클릭 > 내 계정 선택 > 보안 선택 > 유형 드롭다운에서 사용자 토큰 선택 > 생성을 클릭합니다

1. Devops 인사이트 플러그인은 Sonarqube 서버에 다음과 같은 API 호출을 수행합니다:

   • GET api/qualitygates/project_status

     다음 권한 중 하나가 필요합니다:

     • '시스템 관리'
     • 지정된 프로젝트에 대한 '관리자' 권한
     • 지정된 프로젝트에서 '찾아보기'
     • 지정된 프로젝트의 '분석 실행'

   • GET api/measures/component

     지정된 프로젝트에 '찾아보기' 권한이 필요합니다. 컴포넌트.

   • GET api/이슈/검색

     지정된 프로젝트에 대한 '찾아보기' 권한이 필요합니다.

   • GET api/ce/task

     다음 권한 중 하나가 필요합니다:

     • 글로벌 또는 프로젝트 수준에서 '관리'
     • 글로벌 또는 프로젝트 수준에서 '분석 실행'

2. 품질 게이트 이름을 가져오기 위해 다음 SonarQube 엔드포인트가 사용됩니다:

   • GET api/qualitygates/get_by_project

     다음 권한 중 하나가 필요합니다:

     • '시스템 관리'
     • 지정된 프로젝트에 대한 '관리자' 권한
     • 지정된 프로젝트에서 '찾아보기'

3. SonarQube 감지된 핫스팟을 가져오기 위해 다음 SonarQube 엔드포인트가 사용됩니다:

   • GET api/핫스팟/검색

     지정된 프로젝트에 대한 '찾아보기' 권한이 필요합니다.

SonarQube 웹 API에 액세스할 수 있는 권한에 대한 자세한 내용은 SonarQube 웹 API 문서를 참조하세요

고유의 구성 파일 사용

고유의 SonarQube 인스턴스를 사용하지 않고 기본 구성을 수정할 수 있습니다. 구성 파일을 만들려는 리포지토리에 sonar-project.properties 파일을 만듭니다. 스크립트가 저장소에서 기존 configuration sonar-project.properties 파일을 발견하면 기본 파일 대신 해당 파일을 사용합니다. 구성 파일에서 사용 가능한 분석 매개변수에 대한 자세한 내용은 여기에서 분석 매개변수를 참조하세요.

sonarqube-project.properties 파일에 sonar.branch.name 가 추가되면 sonar-branch-name 환경 속성이 기본값으로 설정되고, 그렇지 않으면 load_repo <app-name> branch 에서 제공되는 브랜치 이름이 고려됩니다. 자세한 내용은 브랜치 분석 문서를 참조하세요.

올바른 로그인 인증 정보 및 호스트 URL을 구성 파일에 추가해야 합니다.

다른 정적 스캔 구현 사용

고유의 정적 스캔 구현을 사용하도록 .pipeline-config.yaml 파일을 수정하여 static-scan 스테이지에 고유의 사용자 정의 스크립트를 추가할 수 있습니다.