配置 SonarQube 掃描

預設 SonarQube 實例

• 如果 sonarqube-config 設為 default，則依預設會使用 SonarQube 進行掃描。 此掃描以 Docker-in-Docker身分執行。

使用的實例只能在執行期間使用。 因此，您無法存取儀表板。

• 依預設，該管線使用 SonarQube 社群版本，該版本僅具有有限的 checks.Many 漏洞規則，且主機點問題未涵蓋在 Community Edition下。

• 若要驗證社群版本中是否已檢查漏洞，請參閱 Sonarqube 社群問題中的執行緒

要下載SonarQube,請參閱 SonarQube下載

dev 叢集上的 SonarQube 實例

如果 sonarqube-config 設為 cluster，則在開發叢集裡執行管線期間，管線會建立 SonarQube 實例。 您可以在靜態掃描階段順利 runs.You 可以透過埠轉遞在本端存取 SonarQube 儀表板。

現有 SonarQube 實例

將 sonarqube-config 設為 custom，以將您自己的 SonarQube 實例新增至現有管線，將工具整合新增至工具鏈，然後將 SonarQube 工具整合參數新增至管線。 如需相關資訊，請參閱 配置 SonarQube。

具有自簽證書的 Sonarqube 伺服器

如果 sonarqube-config 設定為 custom 以使用 現有的 sonarqube 伺服器，而且伺服器有自簽的憑證，那麼為了讓聲納掃瞄器成功連線到 sonarqube 伺服器，就需要將自簽的憑證 加入可信賴的 CA 憑證。

透過提供 PEM 格式的證書 ( base64 編碼的秘密值或 PEM 格式的純文字) 作為管道/觸發屬性 sonarqube-root-certificate 的值，設定會依據 SonarScanner for maven、SonarScanner for gradle sonar 或 SonarScanner invoked with Docker 的使用方式加入。

參數

若要執行 SonarQube 掃描，管線需要下列連續整合參數:

如需管線參數的相關資訊，請參閱 管線參數。

若您在管道中添加多個 SonarQube 工具整合，可透過變更管道參數 SonarQube 的值來切換不同整合工具。此參數屬於工具整合參數。

SonarQube 中安裝的外掛程式

DevSecOps Pipelines 預設使用SonarQube版本10.0。

若要進一步瞭解預先安裝的外掛程式清單，請參閱 外掛程式

SonarQube 報告的問題

DevSecOps Pipelines 會過濾掉SonarQube掃描期間報告的問題。 對於非 CODE_SMELL 或 BUG 類型的問題，管線會專門建立「相符性目的」。 管線也會跳過狀態為 CLOSED 的問題。

在應用程式預覽 PR 管道中啟用 Pull Request 分析

如果 PR 來自與目標套件庫相同的套件庫 (而非 fork)，則 App Preview PR pipeline 中會提供 PR 分析選項。 Sonarqube 實例也應支援 PR 分析。 cluster 和 dind 模式中使用的預設 sonarqube 實例不支援此功能，因為從 sonarqube 開發者版本開始，拉取請求分析已經可用。 環境變數 opt-in-sonar-pr-analysis 必須加入管道，且其值不能為空。

啟用 SonarQube 專案的品質閘門結果處理功能

SonarQube 中的品質閘門（Quality Gate ）是一組條件，用以判斷專案是否符合規定的規範品質標準。 要瞭解關於 Quality Gates 的更多資訊，請參閱 SonarQube 文件。

SonarQube issue 解析器支援處理 Quality Gate 結果，並在因此發生故障時建立問題。SonarQube 為了啟用 Quality Gates 結果的處理，請設定環境屬性 opt-in-sonar-quality-gates 為 1。

如果 opt-in-sonar-quality-gates 設定為 1，而您使用 自己的 SonarQube Instance 作為整合 ( sonarqube-config 設定為 custom)，為了取得品質閘門名稱，您可以產生 SonarQube User Token，並具有存取 SonarQube Web API 所需的權限，然後設定管道環境屬性 sonarqube-user-token，將 token 設定為 secret 值。 有關所需的令牌權限詳情，請參閱 SonarQube 令牌權限。

如果您使用管道建立的 SonarQube 範例或自訂 SonarQube 工具整合，請依照下列步驟瀏覽 SonarQube 面板：

1. 前往 URL 從 static-scan 任務中的管道日誌建立的 SonarQube dashboard。

   

2. 根據預設，Sonar way 品質閘門與任何未明確與特定品質閘門相關聯的專案相關聯。 也可以建立具有自訂公制條件的新品質閘門。

   • 若要在儀表板中尋找品質閘門清單，請按一下頂部導覽列中的品質閘門。

     

   • 若要建立新的品質閘門，請按一下上方導覽列中的品質閘門，然後按一下建立。 您可以為品質閘門新增名稱，並新增/刪除/更新條件指標。

   • 若要尋找與項目相關的品質門，請選擇該項目，然後按一下項目設定 > 品質門。

     

   • 若要將品質閘（非預設品質閘）關聯到特定項目，請選擇該項目，然後按一下項目設定 > 品質閘 > 始終使用特定品質閘 > 從下拉式選單中選擇所需的品質閘 > 儲存

     

3. 此品質閘道會評估新的掃描，而品質閘道的結果會建立證明。 根據導致品質閘門失敗的條件來建立問題。

   品質閘門狀態結果格式範例，即 Sonarqube 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，請參閱 Sonarqube WebAPI 文件

   每個狀態為 ERROR 的度量衡關鍵都會建立一個問題，確保每個失敗的度量衡都會被個別追蹤和處理。

   範例問題：

   

   範例 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 pipeline 已啟用 opt-in-sonar-quality-gates，請確保在 CC 中啟用。 否則，CC 發現的品質門問題將自動銷毀。 目前，我們在日誌中出現了與此不一致相關的警告訊息。

要了解有關SonarQube,請參閱 SonarQube文件。

啟用 SonarQube 熱點處理

SonarQube 熱點會強調需要手動檢閱以確定是否會構成真正風險的安全敏感程式碼。 它可幫助開發人員專注於潛在的弱點，而不會產生誤判。 若要瞭解有關管理 Hotspots 的詳細資訊，請參閱 SonarQube 文件。

為了啟用 SonarQube 熱點的處理，請將環境屬性 opt-in-sonar-hotspots 設為 1。

如果 opt-in-sonar-hotspots 設定為 1，而您使用 自己的 SonarQube Instance 作為整合 ( sonarqube-config 設定為 custom)，為了使用 Web API 取得 Sonarqube 偵測到的熱點，您可以產生 SonarQube User Token，具有存取 SonarQube Web API 所需的權限，並設定管道環境屬性 sonarqube-user-token，將 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 因偵測到 Hotspot 而導致證據失敗：

{
  "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 pipeline 已啟用 opt-in-sonar-hotspots，請確保在 CC 中啟用。 否則，CC 發現的熱點問題將自動銷毀。 目前，我們在日誌中出現了與此不一致相關的警告訊息。

SonarQube 令牌的權限

在使用現有 SonarQube 範例的情況下，若要成功將 testrecord 發佈到 Devops Insights 並取得專案的 Quality Gate 名稱，我們需要建立具有所需權限的 User token，並將其設定為 env 屬性 sonarqube-user-token 中的 secret 值，以便提供存取所需的 Sonarqube enpoints 的權限。

若要建立使用者權限，請開啟 SonarQube Dashboard > 點選您的個人資料圖片 > 選擇「我的帳戶」> 選擇「安全性」> 從「類型」下拉選單中選擇「使用者權限」> 點選「產生」

1. Devops Insights 外掛程式會對 Sonarqube 伺服器進行下列 API 呼叫：

   • GET api/qualitygates/project_status

     需要下列其中一個權限：

     • 管理系統
     • 指定專案的「管理員」權限
     • 在指定的專案上「瀏覽
     • 在指定專案上「執行分析

   • GET api/措施/元件

     需要指定專案的「瀏覽」權限。

   • GET api/issues/search

     需要指定專案的「瀏覽」權限。

   • GET api/ce/task

     需要下列其中一個權限：

     • 在全球或專案層級「管理
     • 在全局或專案層級「執行分析

2. 要取得品質閘門名稱，會使用下列 SonarQube Endpoint：

   • GET api/qualitygates/get_by_project

     需要下列其中一個權限：

     • 管理系統
     • 指定專案的「管理員」權限
     • 在指定的專案上「瀏覽

3. 要取得 SonarQube 偵測到的熱點，會使用下列 SonarQube Endpoint：

   • GET api/熱點/搜尋

     需要指定專案的「瀏覽」權限。

有關 SonarQube Web API 存取權限的詳細資訊，請參閱 SonarQube Web API 文件

使用您自己的配置檔

您可以在不使用自己的 SonarQube 實例的情況下修改預設配置。 在您要在其中建立配置檔的儲存庫中建立 sonar-project.properties 檔案。 如果我們的 Script 偵測到儲存庫中的現有 configuration sonar-project.properties 檔案，則會使用該檔案而非預設檔案。 如需配置檔中可能分析參數的相關資訊，請參閱這裡的 分析參數。

如果 sonar.branch.name 已加入 sonarqube-project.properties 檔案，則會設定 sonar-branch-name 環境屬性為預設值，否則會考慮 load_repo <app-name> branch 中可用的分支名稱。 如需詳細資訊，請參閱 Branch Analysis 文件。

請確保您在設定檔中加入正確的登入憑證，並將主機位址設定為 URL。

使用另一個靜態掃描實作

您可以修改 .pipeline-config.yaml 檔，將您自己的自訂 Script 新增至 static-scan 階段，以使用您自己的靜態掃描實作。