Setting up the report of security alerts in GitHub

Starting in Developer Edition, SonarQube can provide feedback about security issues inside the GitHub interface itself as code scanning alerts under the Security tab. This feature is supported for bound projects only.

This page explains the feature and how to set it up. To view and manage the security issues reported in GitHub see Viewing and managing security issues in your DevOps platform.

Security alerts report overview

The report of security alerts in GitHub is part of the GitHub Advanced Security package and is currently free for public projects. It is available as a paid option for private projects and GitHub Enterprise. This option is entirely on the GitHub side. Sonar does not charge anything extra to enable the code scanning alerts feature.

Issue status synchronization

When users change the status of a security issue in the SonarQube interface, that status change is immediately reflected in the GitHub interface. Similarly, if users change an alert status in GitHub, that change is reflected in SonarQube.

Initially, all issues marked Open on SonarQube are marked Open on GitHub. Because the available statuses on the two systems are not exactly the same, the following logic is used to manage the transitions.

Issue report and synchronization from SonarQube to GitHub

SonarQube reports security issues to GitHub's Code scanning alerts by accessing GitHub through the GitHub App configured in Setting up a GitHub App to integrate SonarQube with GitHub. 

Synchronization process from GitHub to SonarQube 

The update in SonarQube of a security alert status change performed by a GitHub user is performed through a webhook mechanism as illustrated below. The procedure is as follows:

1. When a user changes a security alert status in GitHub, a webhook event is generated.
2. GitHub sends a webhook request to SonarQube to inform it about the event. To do so, it retrieves the webhook URL and the webhook secret from the SonarQube GitHub App.
3. SonarQube checks the received webhook secret against the secret stored in the GitHub Configuration for security import.
4. If the check is successful, SonarQube updates the status of the respective security issue. 

Setting up the report in SonarQube

The feature is only available to projects bound to their respective GitHub repository. It means that the integration of SonarQube with GitHub for repository import must have been set up.

Enabling the feature in the SonarQube GitHub App

If not already done, edit your SonarQube GitHub App to enable and set up the report of security alerts to GitHub:

1. In GitHub, go to Settings > Developer settings > GitHub Apps and select your GitHub App.
2. Go to the General > Webhook section and make sure to select the active checkbox.
3. Add the following Webhook URL:  https://<yourinstance>.sonarqube.com/api/alm_integrations/webhook_github. Replace <yourinstance>.sonarqube.com with your SonarQube instance.
4. Set a Webhook secret (see GitHub's webhook security recommendations).
5. Under Permissions & events > Repository permissions > Code scanning alerts, set the access level to Read and write. When you update this permission, GitHub sends an email to the GitHub organization's administrator, asking them to validate the changes on the installation of the GitHub App.
6. Under Permissions & events > Subscribe to events, select Code scanning alert.

Managing the user access to security alerts in GitHub

In GitHub, you can configure access to security alerts for a repository to enable and disable security and analysis features.