...
| Table of Contents | ||
|---|---|---|
|
...
Installing WhiteSource Bolt
Click the following link. The WhiteSource Bolt for GitHub page is displayed.
Click Install. Note that 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 the relevant account, and continue.
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.
Read the permissions that must be provided for the WhiteSource Bolt for GitHub app to work, and then click Install.
Registering WhiteSource Bolt
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.
| Info |
|---|
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. This feature is only available when your GitHub email address is not marked as Private. |
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.
...
vulnerableCheckRunConclusionLevel
Parameter | Type | Description | Required | Default |
|---|---|---|---|---|
vulnerable.check.run.conclusion.level | String | 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. | No | failure |
minSeverityLevel
Parameter | Type | Description | Required | Default |
|---|---|---|---|---|
minSeverityLevel | String | Enables users to decide whether to open a new GitHub Issue only if a certain Severity Level is available. Available values for "minSeverityLevel" needs to be:
| No | LOW |
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 added 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
...
| 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.
...
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 specific CVE in the CVE website.
CVSS 3 score: Basic CVSS 3 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.
...
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:
Go to the repository 'Settings ' → '> Branches'.
Click on the 'Add Rule' button.
Apply the rule to a specific branch or enter '*' to apply the rule to all branches:
Select the following checkboxes:
'Require status checks to pass before merging'.
'WhiteSource Security Check'. If you cannot view this setting, then modify the '.whitesource' file, and perform a commit. Wait for the scan to complete and then refresh the GitHub settings page until you can view this setting.
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:
...
Severity: Overall score of the severity (High, Medium or Low).
CVSS Score
CVE: A link to the related CVE page for the vulnerability.
GitHub Issue: A link to the WhiteSource issue that was generated for the vulnerability. For example, the following is an issue that was generated for the first vulnerability of the report on the above screenshot:
Types of Indicators
...
When the parameter 'vulnerable.check.run.conclusion.level' is set to 'success' or 'failure' (default), and a 'success' status is provided for the scan, since no vulnerabilities were found and no errors occurred during the scan for this head commit. In this case, the merging of a pull request that includes this commit to another branch in the repository is automatically approved.
When the parameter 'vulnerable.check.run.conclusion.level' is set to 'success'. In this configuration, even a 'failed' status for a head commit's scan is converted to 'success'. The following screenshot displays a 'success' indicator for a commit that includes high severity vulnerabilities, since the parameter 'vulnerable.check.run.conclusion.level' is set to 'success'. In this case, the merging of a pull request that includes this head commit to another branch in the repository is automatically approved.
The following screenshot displays a 'success' indicator for a commit that includes an error that occurred during the scan, since the parameter 'vulnerable.check.run.conclusion.level' is set to 'success'. In this case, the merging of a pull request that includes this head commit to another branch in the repository is automatically approved.
Completed with 'Failure' Conclusion
...
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.
The 'WhiteSource Bolt for GitHub' page opens. Scroll down in order to view the 'Uninstall WhiteSource Bolt for GitHub' button.
Click on the 'Uninstall' button. Uninstalling WhiteSource Bolt for GitHub removes it from all your repositories.
Optionally, go to 'Authorized GitHub apps' tab, and click the 'Revoke' button next to the 'Bolt for GitHub' app.