Table of Contents maxLevel 4
Introduction
WhiteSource Bolt for GitHub is a GitHub app, scanning your repositories at no cost. The app can be installed from the GitHub marketplace- https://github.com/marketplace/whitesource-bolt.
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 open source components and generates comprehensive up-to-date reports on the GitHub 'Issues' tab of the scanned repository.
For more information or questions on WhiteSource Bolt for GitHub, please reach out directly to boltgithub@whitesourcesoftware.com.
| Info | ||
|---|---|---|
| ||
GitHub repositories requiring access to artifacts in local registries are not supported. |
Prerequisites
'Issues' tab enabled for each repository: Do the following for each repository that requires a Bolt scan:
...
| Info |
|---|
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:
...
| Info |
|---|
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 'Authorize WhiteSource Bolt for GitHub by WhiteSource' button.
Registration
After the installation, the following registration form appears with your email address filled in:
Fill in all the required fields, select the required checkboxes, and then click the 'Submit' button.
...
This
...
You will be forwarded to the Bolt for GitHub 'Thanks for Installing' page. Click on the 'Go back to GitHub' button to return to your GitHub account page .
After selecting your repositories, an onboarding pull request is created. This pull request contains a WhiteSource configuration file (.whitesource) that can be customized before merging the pull request. Once the pull request is merged, a WhiteSource scan will be initiated.
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.
The '.whitesource' File
A WhiteSource configuration file ('.whitesource') is added to each repository that is enabled for a scan. It provides configurable parameters for the WhiteSource scan. The '.whitesource' file is only added in the default branch of the repository (unless modified, it is the master branch). Any configuration change that is done to this file must be in the default branch of the repository.
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"checkRunSettings": {
"vulnerableCheckRunConclusionLevel": "failure"
},
"issueSettings": {
"minSeverityLevel": "LOW"
}
} |
Parameters
vulnerableCheckRunConclusionLevel
...
The app utilizes the GitHub Checks API that provides checks in commits and pull requests on any repository branch. This parameter defines the conclusion status for when a WhiteSource Security Check is completed.
When the parameter is set to 'success', the conclusion status of a WhiteSource Security Check will always be 'Success', even if the check fails. This way, any repository member is able to merge a pull request, even if a WhiteSource Security Check found security vulnerabilities.
When the parameter is set to 'failure' (default), the conclusion status of a WhiteSource Security Check will be 'Failure' in cases where WhiteSource Security Check found security vulnerabilities or an error occurred during the scan. When this configuration is defined, and a branch protection rule has been added, a policy for approving a pull request is enforced. In this setting, only the administrator of the repository can approve the merging of a pull request that contains one or more checks with a 'Failure' status.
See also Initiating a Merge Policy.
...
minSeverityLevel
...
available
...
Available values for "minSeverityLevel" needs to be:
NONE - No GitHub Issues will be generated.
LOW - Any Low/Medium/High vulnerabilities found will generate a GitHub Issue.
MEDIUM - Any Medium/High vulnerabilities found will generate a GitHub Issue.
HIGH - Any High vulnerabilities found will generate a GitHub Issue.
...
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:
...
- 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;
| Info |
|---|
|
The Shared Repository Model
WhiteSource supports pull requests for the shared repository model (see also this GitHub article). In this case, topic branches are created in the same repository by maintainers to be later be in pull requests against the production branch (usually the master branch).
The administrator of the repository then decides whether to merge the pull requests. See also about-collaborative-development-models.
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.
| Info |
|---|
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.
| Info |
|---|
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:
...
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.
...
| Info |
|---|
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.
Initiating a Merge Policy
A merge policy utilizes the app's integration with GitHub Checks API. It enables the repository's administrator to approve the merging of a pull request with 'Failed' commit statuses to a target branch in the repository.
For more information on Checks API, see the related GitHub Checks API introduction page.
Prerequisite for the Merge Policy: Add a Branch Protection Rule
In order to enable a merge policy based on the conclusion of a WhiteSource Security Check, you must initially add the following GitHub rule for branch protection:
...
Checks API Indicators
Checks API indicators are displayed for each head commit on the 'Commits' section of the 'Code' tab. Clicking on a specific indicator opens a pop-up window that displays further details on the status:
Clicking on the 'Details' link in the pop up window displays the WhiteSource Security Check page for the selected head commit. The page includes the conclusion status of the head commit along with a Security Report:
The security report displays all the vulnerabilities that were found in descending order according to the severity and CVSS score. The following information is displayed for each vulnerability:
...
Types of Indicators
The following Checks API status indicators are available as a feedback on the head commits:
- Queued: Scan has not begun and is scheduled to begin.
- In progress: Scan is in progress.
- Completed: Scan completed with one of the following conclusions:
- Success: When the parameter 'vulnerable.check.run.conclusion.level' is set to 'success', the status of the head commit is always success A 'Success' status is displayed for the commit even when it fails.
- Failure: Default for all completed scans. When the parameter 'vulnerable.check.run.conclusion.level' is set to 'failure' (default), the status of a 'failed' head commit is 'failure', and a policy for approving merging pull requests that include failed head commits with the another branch in the repository is enforced. Note that a 'failed' status can be caused due to security vulnerabilities or due to an error that occurred during the scan.
Neutral: conclusion occurs when the repository has reached its daily limit of scans, and the next scan will be on the next day or when the push command was not valid.
Samples of All Checks API status Indicators
Queued
The following is a sample of a 'Queued' status, which indicates that the security check is about to start scanning the head commit's vulnerabilities.
In Progress
The following is a sample of an 'In-Progress' status, which indicates that the security check is currently scanning the head commit.
Completed with 'Success' Conclusion
The status can be displayed in two scenarios:
...
Completed with 'Failure' Conclusion
...
The following screenshot is a sample of the display in a pull request page when a 'failure' policy is enforced and one or more of its head commits have a 'failure' status. Only the administrator of the repository can approve the merging of a pull request with a 'failure' status:
Completed with 'Neutral' Conclusion
A neutral conclusion occurs in one of the following scenarios:
...
Uninstall
You can easily uninstall this app by doing the following:
...
at Mend’s new Knowledge Hub, here: Mend Bolt for GitHub