配置 SonarQube 扫描

SonarQube 提供了源代码总体运行状况和质量的概述，并重点阐述了在新代码中发现的问题。代码分析器可检测到超过 20 种代码编写语言的棘手错误，例如空指针取消引用、逻辑错误和资源泄漏。

配置 SonarQube 以持续分析和测量源代码的质量：

在IBM Cloud控制台中，单击菜单图标图标 >平台自动化>工具链。在“工具链”页面，单击工具链打开其“概述”页面。或者，在应用程序“概述”页面的“持续交付”卡上，单击查看工具链。然后，单击概述。

a. 单击添加工具。

b. 在“工具集成”部分中，单击 SonarQube。
输入此 SonarQube 工具集成实例的名称。
输入在您单击工具链中 SonarQube 卡时想要打开的 SonarQube 实例的 URL。
可选：键入用于连接 SonarQube 服务器的用户名。

只有在使用密码连接 SonarQube 服务器时，才需要指定用户名。如果是使用认证令牌进行连接，请将此字段保留为空。
输入用于连接到 SonarQube 服务器的密码或认证令牌。
如果服务器不能位于公用因特网上，请选择高级。IBM Cloud 无法验证您提供的连接详细信息，并且将禁用需要对此服务器进行 API 访问的某些功能。交付管道仅通过使用对该服务器具有网络访问权的专用工作程序来工作。
单击创建集成。
在工具链的“概述”页面上的 第三方工具 卡上，单击 SonarQube 以查看您已连接到的 SonarQube 实例的仪表板。

将 SonarQube 添加到持续集成管道

缺省 SonarQube 实例

如果 sonarqube-config 设置为 default，那么缺省情况下将使用 SonarQube 进行扫描。此扫描以 Docker形式运行-Docker。

所使用的实例仅在运行期间可用。因此，您无法访问仪表板。

缺省情况下，管道使用仅具有有限 checks.Many 漏洞规则的 SonarQube 社区版本，并且 Community Edition未涵盖主机点问题。
要验证是否在社区版本中检查了漏洞，请参阅 Sonarqube 社区问题中的线程
向 CISO 注册的 SonarQube 社区 Edition 实例的缺省实现不是 ITSS 核准的 edition.SonarQube Enterprise Edition 是唯一的 ITSS 核准的版本。

要下载SonarQube, SonarQube下载

开发集群上的 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 调用 maven、使用 SonarScanner 调用 gradle sonar 或使用 SonarScanner 调用 Docker 的情况添加。

参数

要运行 SonarQube 扫描，管道需要以下连续集成参数:

Continuous integration pipeline parameters
名称	类型	描述	必需或可选
集群名称	文本	Docker 构建集群的名称。	必需
开发区域	文本	托管集群的 IBM Cloud 区域。	必需
选择性加入声纳	文本	用于启用 SonarQube 扫描的选项。	必需
sonarqube	工具集成	SonarQube 工具集成。	可选
sonarqube-config	文本	在隔离的 Docker-Docker 容器 (缺省配置) 或现有开发 Kubernetes 集群 (集群配置) 中运行 SonarQube 扫描。或者，您可以自带 SonarQube 实例并配置 SonarQube 工具集成 (定制配置)。选项: `default`，`cluster` 或 `custom`。默认为 `default`。有关更多信息，请参阅 (将 SonarQube 添加到持续集成管道)。	必需
选择性加入声纳热点	文本	Sonarqube 扫描以检测热点。	可选
选择声纳质量门	文本	允许 Sonarqube 扫描检测质量门故障。	可选
选择加入声纳-pr-分析	文本	允许 Sonarqube 扫描进行拉取请求分析（该选项只有在 PR 不是从分叉版本库贡献时才有效）。该参数仅对 `App-preview PR pipeline` 有效。	可选
sonarqube-user-token	私钥	如果 `sonarqube-config` 设置为 `custom`	可选
sonarqube-root-certificate	文本或密码	如果 `sonarqube-config` 设置为 `custom`，则以 PEM 格式文本或 base64 编码密文的形式传递自签名证书	可选

有关管道参数的更多信息，请参阅管道参数。

如果将多个 SonarQube 工具集成添加到管道，那么可以通过更改作为工具集成参数的 SonarQube 管道参数的值来在这些集成之间进行切换。

安装在 SonarQube 中的插件

DevSecOpsPipelines 默认使用SonarQube 10.0版本。

要了解有关预安装插件列表的更多信息，请参阅插件

从 SonarQube 报告的问题

DevSecOpsPipelines 可过滤SonarQube扫描期间报告的问题。管道专门针对类型不是 CODE_SMELL 或 BUG 的问题创建合规性说明。管道还会跳过状态为 CLOSED 的问题。

在应用程序预览公关管道中启用拉动请求分析

如果 PR 来自与目标版本库相同的版本库（而非分叉），则 App Preview PR pipeline 中会提供 PR 分析选项。 Sonarqube 实例还应支持 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 用户令牌，该令牌必须具有访问 SonarQube Web API 的权限，并将管道环境属性 sonarqube-user-token 设置为令牌的秘密值。有关所需令牌权限的详细信息，请参阅 SonarQube 令牌权限。

如果您使用管道创建的 SonarQube 实例或自定义 SonarQube 工具集成，请按照以下步骤浏览 SonarQube 面板：

转到 URL 在 static-scan 任务中创建的 SonarQube 仪表板。

仪表板 SonarQube仪表板
默认情况下，Sonar way 质量门与任何未明确与特定质量门关联的项目相关联。还可以创建具有自定义度量条件的新质量门。
- 要在仪表板中查找质量控制门列表，请单击顶部导航栏中的质量控制门。
  
  SonarQube
- 要创建新的质量门，请单击顶部导航栏中的质量门，然后单击创建。您可以为质量门添加名称，并添加/删除/更新条件指标。
- 要查找与项目相关的质量门，请选择项目，然后单击项目设置 > 质量门。
  
  SonarQube
- 要将质量门（默认质量门除外）与特定项目关联，请选择项目，然后单击项目设置 > 质量门 > 始终使用特定质量门 > 从下拉菜单中选择所需的质量门 > 保存
  
  caption-side=bottom"

此质量门将对新扫描进行评估，而质量门的结果将创建证据。根据导致质量门失败的条件创建问题。

作为 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 issue Sonarqube 针对一个失败指标的问题 — caption-side=bottom"

示例 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.ibm.com/abcd/compliance-issues-20250310111628285/issues/14",
      "https://github.ibm.com/abcd/compliance-issues-20250310111628285/issues/15"
   ],
   "findings": [
      {
         "id": "Metric: new_coverage",
         "due_date": "n/a",
         "severity": "high",
         "first_found": "2025-03-18",
         "url": "https://github.ibm.com/abcd/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.ibm.com/abcd/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.ibm.com/abcd/compliance-app-20250310111628285.git#7a06e70001a59032d1",
         "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/assets/1812f77dfc646c93320794810460acd3e/index.json"
      }
   ]
}

如果 CI 管道已启用 opt-in-sonar-quality-gates，请确保在 CC 中启用。否则，CC 发现的质量门问题将被自动销毁。目前，我们在日志中出现了有关这种不一致的警告信息。

要了解有关“SonarQube,的更多信息，请参阅”SonarQube文档。

启用 SonarQube 热点处理

SonarQube 热点会突出显示安全敏感代码，这些代码需要人工审核，以确定是否会带来真正的风险。它有助于开发人员关注潜在漏洞，而不会产生误报。要了解有关管理热点的更多信息，请参阅 SonarQube 文档。

为启用 SonarQube 热点处理功能，请将环境属性 opt-in-sonar-hotspots 设置为 1。

如果 opt-in-sonar-hotspots 设置为 1，并且您使用自己的 SonarQube 实例作为集成（ sonarqube-config 设置为 custom ），为了使用 Web API 获取 Sonarqube 检测到的热点，您可以生成一个 SonarQube 用户令牌，该令牌具有访问 SonarQube Web API 所需的权限，并设置管道环境属性 sonarqube-user-token，将令牌作为秘密值。有关所需令牌权限的详细信息，请参阅 SonarQube 令牌权限。

要查看 SonarQube 检测到的项目安全热点，请选择项目，然后单击安全热点。

SonarQube
要查看检测到的热点，请选择热点，然后单击“查看”。此时将出现一个模态窗口，允许您将“审核状态”设置为以下状态之一：To Review, Acknowledged, Fixed 和 Safe。

SonarQube

启用 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"
         }
      }
   ]
}

如果在上述应用程序接口的结果中遇到 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.ibm.com/abcd/compliance-issues-20250310111628285/issues/13"
  ],
  "findings": [
    {
      "id": "javascript:S4426",
      "due_date": "n/a",
      "severity": "high",
      "first_found": "2025-03-18",
      "url": "https://github.ibm.com/abcd/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.ibm.com/abcd/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.ibm.com/abcd/compliance-app-20250310111628285.git#4eadaaf7454b8cb0edad927",
      "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/assets/d7391b3273e5e52852f293031d62b9bf0/index.json"
    }
  ]
}

如果 CI 管道已启用 opt-in-sonar-hotspots，请确保在 CC 中启用。否则，CC 发现的热点问题将被自动删除。目前，我们在日志中出现了有关这种不一致的警告信息。

SonarQube 令牌的权限

在使用现有 SonarQube 实例的情况下，为了成功将 testrecord 发布到 Devops Insights 并获取项目的质量门名称，我们需要创建一个具有所需权限的用户令牌，并将其设置为 env 属性 sonarqube-user-token 中的秘密值，以便提供访问所需的 Sonarqube enpoints 的权限。

要创建用户令牌，请打开 SonarQube 控制面板 > 点击右上角的个人资料图片 > 选择我的账户 > 选择安全 > 从类型下拉菜单中选择用户令牌 > 点击生成

Devops Insights 插件对 Sonarqube 服务器进行以下 API 调用，如下所示：
- GET api/qualitygates/project_status
  
  需要以下权限之一：
  - 管理系统
  - 指定项目的“管理者”权限
  - 浏览 "指定项目
  - 在指定项目上 "执行分析
- GET api/measures/component
  
  需要指定项目的“浏览”权限。
- GET api/issues/search
  
  需要指定项目的“浏览”权限。
- GET api/ce/task
  
  需要以下权限之一：
  - 在全球或项目层面进行 "管理
  - 在全球或项目层面 "执行分析
要获取质量门的名称，需要点击下面的 SonarQube 端点：
- GET api/qualitygates/get_by_project
  
  需要以下权限之一：
  - 管理系统
  - 指定项目的“管理者”权限
  - 浏览 "指定项目
要获取 SonarQube 检测到的热点，需要点击下面的 SonarQube 端点：
- GET api/hotspots/search
  
  需要指定项目的“浏览”权限。

有关访问 SonarQube Web API 的权限的更多信息，请参阅 SonarQube Web API 文档

使用您自己的配置文件

您可以在不使用自己的 SonarQube 实例的情况下修改缺省配置。在要在其中创建配置文件的存储库中创建 sonar-project.properties 文件。如果我们的脚本在存储库中检测到现有 configuration sonar-project.properties 文件，那么它将使用该文件而不是缺省文件。有关配置文件中可能的分析参数的更多信息，请参阅此处的分析参数。

如果在 sonarqube-project.properties 文件中添加了 sonar.branch.name，则会将其设置为 sonar-branch-name env 属性的默认值，否则会考虑 load_repo <app-name> branch 中可用的分支名称。更多信息，请参阅分支分析文档。

请确保您添加了正确的登录凭据，并将主机 URL 添加到配置文件中。

使用另一静态扫描实现

您可以修改 .pipeline-config.yaml 文件以将自己的定制脚本添加到 static-scan 阶段，从而使用自己的静态扫描实现。

了解有关 SonarQube 的更多信息

要了解有关 SonarQube, 的更多信息，请参阅将 SonarQube 分析集成到工具链中。