# Sonarqube

SureCloud connects to SonarQube to retrieve project analysis results, security hotspots, vulnerability findings, and quality gate status. This allows SureCloud to verify that static application security testing (SAST) is being performed on your codebases, that identified security issues are tracked, and that code quality gates are enforced — providing continuous evidence for application security and secure development lifecycle controls.

## Authentication and setup

SonarQube authenticates API requests using a user token. SureCloud uses a token associated with a read-only SonarQube account.

{% tabs %}
{% tab title="SonarCloud (SaaS)" %}
{% stepper %}
{% step %}
**Generate a user token in SonarCloud**

Log in to [sonarcloud.io](https://sonarcloud.io/). Navigate to **My Account → Security** and click **Generate Token**. Name it `SureCloud CCM`, leave the type as **User Token**, and click **Generate**. Copy the token.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → SonarQube → Connect (SonarCloud)**. Enter your SonarCloud organisation key and the user token. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="SonarQube Server (self-managed)" %}
{% stepper %}
{% step %}
**Create a service account in SonarQube**

Log in to your SonarQube instance as an administrator. Navigate to **Administration → Security → Users** and create a new user (e.g. `surecloud-integration`). Assign it the **Browse** permission on all projects SureCloud needs to monitor (or the global **Browse All Projects** permission if appropriate).
{% endstep %}

{% step %}
**Generate a user token**

Log in as the new service account. Navigate to **My Account → Security** and click **Generate Tokens**. Name it `SureCloud CCM` and click **Generate**. Copy the token.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → SonarQube → Connect (Server)**. Enter your SonarQube server URL (e.g. `https://sonarqube.yourcompany.com`) and the user token. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the token securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days and update it in **SureCloud → Integrations → SonarQube → Edit Connection**.
{% endhint %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                                                                 | Use Case                                              |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `GET /api/projects/search`                                                               | Enumerate all projects analysed by SonarQube          |
| `GET /api/qualitygates/project_status?projectKey={key}`                                  | Retrieve quality gate pass/fail status per project    |
| `GET /api/issues/search?componentKeys={key}&types=VULNERABILITY`                         | Retrieve open vulnerability findings per project      |
| `GET /api/hotspots/search?projectKey={key}`                                              | Retrieve security hotspots requiring review           |
| `GET /api/measures/component?component={key}&metricKeys=security_rating,vulnerabilities` | Retrieve security metrics and rating per project      |
| `GET /api/project_analyses/search?project={key}`                                         | Retrieve analysis history to confirm regular scanning |

## Pagination

`GET /api/projects/search` and `GET /api/issues/search` use page-based pagination. SureCloud sets `p` (page number) and `ps` (page size) parameters and increments until the `total` count in the response is reached.

```json
GET /api/issues/search?componentKeys={key}&types=VULNERABILITY&ps=500&p=2
```

`GET /api/hotspots/search` uses the same pattern. `GET /api/qualitygates/project_status` returns a single object per project.

## Required permissions

SureCloud requires a SonarQube user token for an account with the following permissions:

| Permission                      | Purpose                                                   |
| ------------------------------- | --------------------------------------------------------- |
| Browse (per project)            | Read project analyses, issues, and quality gate status    |
| Execute Analysis (not required) | SureCloud reads results only — no analysis trigger needed |

For SonarCloud, a user token with access to the target organisation is sufficient.

## Polling frequency

| Data Type                                    | Interval       |
| -------------------------------------------- | -------------- |
| Project list and analysis status             | Every 24 hours |
| Vulnerability findings and security hotspots | Every 24 hours |
| Quality gate status                          | Every 24 hours |
| Security metrics                             | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The user token is invalid, has expired, or the account has been deactivated. Navigate to **SonarQube → My Account → Security** (or your SonarCloud account settings), regenerate the token, and update it in **SureCloud → Integrations → SonarQube → Edit Connection**.

</details>

<details>

<summary>Some projects are missing from SureCloud</summary>

The service account may not have Browse permission on all projects. In SonarQube Server, navigate to **Administration → Security → Global Permissions** to grant global Browse access, or add the account to each project individually under **Project Settings → Permissions**.

</details>

<details>

<summary>Quality gate status shows "ERROR" for all projects</summary>

A quality gate status of ERROR means the project's analysis failed the configured quality gate thresholds — this is expected behaviour and is valid evidence for SureCloud controls. It does not indicate a SureCloud integration problem. Review the quality gate conditions in SonarQube to understand which metrics are failing.

</details>

<details>

<summary>Self-managed SonarQube server is unreachable</summary>

Confirm the SonarQube server URL is accessible from the SureCloud collector network on port 443 (HTTPS) or port 9000 (default SonarQube HTTP). If the instance is on a private network, a firewall rule or reverse proxy may be required. Contact SureCloud Support for network connectivity guidance.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/sonarqube.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.