Setting up the report of security alerts in GitHub

Starting in Developer Edition, SonarQube Server 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 Server 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 Server.

Initially, all issues marked Open on SonarQube Server 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 Server to GitHub

SonarQube Server 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 Server with GitHub. 

Synchronization process from GitHub to SonarQube Server 

The update in SonarQube Server 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 Server to inform it about the event. To do so, it retrieves the webhook URL and the webhook secret from the GitHub App for SonarQube Server.
3. SonarQube Server checks the received webhook secret against the secret stored in the GitHub Configuration for security import.
4. If the check is successful, SonarQube Server updates the status of the respective security issue. 

Setting up the report in SonarQube Server

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

Enabling the feature in the GitHub App for SonarQube Server

If not already done, edit your GitHub App for SonarQube Server 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 Server 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.