Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

After the installation, the following registration WhiteSource Bolt for GitHub Registration form appears with your email address filled in:

...

  1. Fill in all the required fields, select the required checkboxes, and then click Submit.

...

  1. NOTE: 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

...

  1. Submit

...

  1. button was clicked. This feature is only available when your GitHub email address is not marked as Private.

  2. You will be forwarded to the Bolt for GitHub Thanks for Installing page. Click 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. 

...

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:

  • 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.

No

LOW

Initiating a Scan

Info

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 WhiteSource scan is initiated via a valid GitHub 'GitHub push' command command. A valid 'push' command meets 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 push command added/removed a source file that has 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 .
    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; 

Info
  • The modification of existing source file(s) is not considered a valid GitHub 'push' command. It will not initiate a scan.

  • The GitHub 'push' commands may include multiple commits.

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.

...

  •  push command includes an addition/modification of the package manager dependency files.
    Refer to the list of supported dependency files to find out whether your dependency files are supported.

Info

A push command may consist of 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. 

...

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 multiple relevant label labels to specific issues, and close issues that were resolved.

...

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.

    Image Removed


    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:

    Image Removed


    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.

Info

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

...

    • 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.

Info

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

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. Do as follows:

  1. Go to the repository Settings > Branches. Click The Branches screen is displayed.

  2. In the Branch protection rules area, click Add Rule.

    Image Removed

  3. Apply the rule to a specific branch or enter '*' to apply the rule to all branches:

  4. Select the following checkboxes:

    • 'Require status checks to pass before merging'.

    • 'WhiteSource Security Check'.  If -  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.

      Image Removed

Checks API Indicators

Checks API indicators are displayed for each head commit on the 'Commits' section of the 'Code' tab.

To view WhiteSource information, click any of the following:

  • 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:

...