Bolt for GitHub Documentation

Table of Contents

Last Updated on 15/12/2018

Introduction

WhiteSource Bolt for GitHub is a GitHub app, scanning your repositories at no cost. The app can be installed from the following link – https://github.com/apps/whitesource-bolt-for-github.

It is an integrated product within GitHub that detects all open source components in your repository and alerts on vulnerabilities for these components.

WhiteSource Bolt for GitHub detects all open source components in your software, without ever scanning your code.
It provides you with issues on vulnerable and outdated open source components and generates comprehensive up-to-date reports on the GitHub ‘Issues’ tab of the scanned repository.

 

Prerequisites

‘Issues’ tab enabled for each repository: Do the following for each repository that requires a Bolt scan:
  1. Go to the relevant GitHub repository, and click on ‘Settings’.
     
  2. Verify that the ‘Issues’ checkbox is enabled.
  3. Check that the ‘Issues’ tab appears next to the ‘Code’ tab.

    You must also have administrator permissions to your GitHub account and to the relevant repositories (owner credentials) in order to install and use WhiteSource Bolt for GitHub.

    Bolt for GitHub does not scan archived GitHub repositories, since their ‘read only’ status blocks various actions that are required during the scan.

     

Installation Procedure

Installation is done via the following link. Click on the ‘Install’ button on the page that opens.

If you have more than one GitHub account then you should initially confirm your installation location by selecting the GitHub account(s) for which you would like to install the WhiteSource Bolt for GitHub app. Click on the ‘Configure’ link for the relevant account.

\

The following screen is displayed for the selected account or in cases that you have only one GitHub account:

Select one of the following options:

  • All Repositories (Default): An option to scan all the repositories of the account.
  • Only select repositories: Select specific repositories that you would like to scan.

The app does not scan archived GitHub repositories, since their ‘read only’ status blocks various actions that are required during the scan.

Read the permissions that must be provided for the WhiteSource Bolt for GitHub app to work, and then click on the ‘Install’ button.

 

Registration

After the installation, the following registration form appears:

Continue to the New User section.

New User

GitHub Email Address Marked as Private

The following procedure occurs when your GitHub account email address is set as private:

Fill in all the fields of the form and then click the ‘Submit’ button. The following message is then displayed:

An activation email message is then sent to the provided email address. Open the email message and click on the ‘Verify Account’ link.

You are then moved to the ‘Verification Complete’ screen.

Finally, the following ‘Thank You’ message is displayed:

At this stage, Bolt has started scanning your selected repositories. If a vulnerability is detected, then you will receive an email, and an issue will be created in your GitHub’s project ‘Issues’ tab. The scanning process may take a number of minutes.

GitHub Email Address Not Marked as Private

The following procedure occurs when your GitHub account email address is public. The email address field in the form should already include your email address. Fill in all the other fields of the form and then click the ‘Submit’ button. The following screen appears:

At this stage, Bolt has started scanning your selected repositories. If a vulnerability is detected, then you will receive an email, and an issue will be created in your GitHub’s project ‘Issues’ tab. The scanning process may take a number of minutes.

If the form page accidentally closes before you clicked on the ‘Submit’ button then you can use the link in the registration email message that was sent to you in order to complete the registration process. Use this link only in cases where the form screen has been closed before the ‘Submit’ button was clicked.

The ‘.whitesource’ File

A WhiteSource configuration file (‘.whitesource’) is added to each repository that is enabled for a scan. It currently mostly includes commented data, but in a future release of WhiteSource Bolt for GitHub it will provide configurable attributes for the WhiteSource scan.

Initiating a Scan

New users are entitled to scan each repository up to five times a day. Existing WhiteSource customers have the scan limitations that are set in their account agreement with WhiteSource.

A scan is initiated via a valid GitHub ‘push’ command . A valid ‘push’ command meets at least one of the following requirements:

  • One of the commits in the ‘push’ command include file(s) that have an extension supported by WhiteSource and/or one of the commits in the push command included a removal of file(s) that have an extension supported by WhiteSource. Refer to the WhiteSource Languages page in order to find out whether or not a specific language and its extensions are supported.
  • One of the commits in the push command includes a modification in the package manager configuration file(s). This includes any of the following files:
    • build.gradle
    • pom.xml
    • setup.py
    • requirements.txt
    • Gemfile.lock
    • package.json
    • bower.json
    • Gopkg.lock
    • Godeps.lock
    • vendor.conf
    • gogradle.lock
    • glide.lock
    • composer.json
    • build.sbt
    • paket.dependencies
    • Any metafile with one of the following extensions:
      • config
      • csproj
      • htm
      • html
      • shtml
      • xhtml
      • jsp
      • asp
      • do
      • aspx

Each time a valid GitHub ‘push’ command is made for a repository, WhiteSource initiates a scan;

  • The modification of existing source file(s) is not considered a valid GitHub ‘push’ command. It will not initiate a scan.
  • The GitHub ‘push’ command may include multiple commits.

Viewing Details of the Scan

Results are viewed on the ‘Issues’ tab of the repository on GitHub and via email notifications.

 

Viewing the Issues Tab

If you are making ‘push’ commands via the Web browser then click the ‘Refresh’ button of the Web browser in order to view the issues that were found.

It may take a number of minutes for the issues to be scanned and displayed after a valid ‘push’ command is initiated.

The ‘Issues’ tab displays all the issues that WhiteSource Bolt for GitHub detected with the red ‘security vulnerability’ label. This proprietary label indicates a security vulnerability was detected by WhiteSource.

As part of your workflow, you have the option to add relevant label(s) to specific issues, and close issues that were resolved.

All manually closed issues are not resent or reopened as open issues during the next scan unless their label and/or name has been manually changed or changed via an API.

Viewing Details of an Issue

Clicking on a specific issue displays its details:

Click on an item’s list bullet () to view more information on it.

The display changes according to the type of library:

  • Component based library (e.g., ‘*.tgz’, ‘*.jar’ ): The vulnerable library appears first after the heading that indicates the name of the issue.

  • It includes the following information:
    • Vulnerable library: Includes the path of the library. If the path is of a transitive dependency library then only the path information of the root library is relevant to you.

    • Commit link: Includes the path to the GitHub commit link where the vulnerability was found.
    • Vulnerability details: Description of vulnerability, published date, and link to the specific CVE in the CVE website.
    • CVSS 3 score: Basic CVSS3 score matrix. If this score is not available then the CVSS 2 score matrix is displayed.
    • Suggested fix for the vulnerability: A detailed suggestion that includes type, origin, release date, and fix resolution. Note that a fix may not always be available.
  • Source file based component: The vulnerable library appears as the first item in the list:

  • It includes the following information:
    • Vulnerable library: Includes a comment that indicates the possibility of a false origin recognition, and a list of all the source files of this library.
    • Vulnerability Details: Description of vulnerability, published date, and link to the CVE in the CVE website.
    • CVSS 3 score: Basic CVSS3 score matrix. If this score is not available then the CVSS 2 score matrix is displayed.
    • Suggested fix for the vulnerability: A detailed suggestion that includes type, origin, release date, and fix resolution. Note that a fix may not always be available.
    • Commit link: Includes the path to the GitHub commit link where the vulnerability was found.

WhiteSource supports displaying multiple libraries for the same CVE when such a case occurs.

As part of your workflow, you have the option to use various GitHub tasks for a specific issue such as the tasks in the ‘Assignees’, ‘Labels’, ‘Projects’, ‘Milestone’, and ‘Notification’ sections. You can also add and edit comments for a specific issue.

 

Email Notifications

After the scan is made, a separate email message is sent on each issue as shown in this sample screenshot of a typical email message on a vulnerability that was found:

The information in the email message is identical to the displayed information on the ‘Issues’ tab.

 

Uninstall

You can easily uninstall this app by doing the following:

  1. Go to the ‘Applications’ section of your GitHub’s account settings, and click on the ‘Configure’ button next to the ‘WhiteSource Bolt for GitHub’ app.
  2. The ‘WhiteSource Bolt for GitHub’ page opens. Scroll down in order to view the ‘Uninstall WhiteSource Bolt for GitHub’ button.
  3. Click on the ‘Uninstall’ button. Uninstalling WhiteSource Bolt for GitHub removes it from all your repositories