...
Table of Contents | ||
---|---|---|
|
...
Info |
---|
Note on private registries This integration does not support GitHub repositories requiring access to artifacts in private registries. Sourcing dependencies from authenticated repositories is also not supported in this integration. If you require support for any of the above, please use the WhiteSource for GitHub Enterprise integration. |
WhiteSource for GitHub.com is a GitHub app which is part of WhiteSource for Developers, that continuously scans your repositories and alerts on security vulnerabilities. It also includes continuous automated security remediation with WhiteSource Remediate, using fix Pull Requests. The app can be installed from here.
...
The Issues tab must be enabled for each repository. Do as follows for each repository requiring a scan:
Go to the relevant GitHub repository, and click Settings.
Verify that the Issues checkbox is enabled.
Check that the Issues tab appears next to the 'Code' tab.
You must have administrator permissions to your GitHub account and to the relevant repositories (owner credentials) in order to install the WhiteSource for GitHub.com app.
Python support: The default Python version supported is 2.7. If you have a python project with version 3 or above, you will need to perform the following procedure:
Add a .whitesource configuration file to your repository. Alternatively, you can apply this globally across your repositories by using the Global Repo Configuration.
Use the configMode parameter and set it to either LOCAL or EXTERNAL.
In the whitesource.config file, add the following parameter: python.path=python3.
NOTE: if you are using the pip package manager with python version 3, ensure you also add the following parameter: python.pipPath=pip3.
R support: The default CRAN Mirror URL used by the integration is https://cloud.r-project.org/. If you need to change the CRAN Mirror URL, do as follows:
Add a .whitesource configuration file to your repository. Alternatively, you can apply this globally across your repositories by using the Global Repo Configuration.
Use the configMode parameter and set it to either LOCAL or EXTERNAL.
In the whitesource.config file, add the following parameter: r.cranMirrorUrl=<INSERT_URL_HERE>.
Installation Procedure
Installation is done via the following link Click the Install button on the page that opens.
...
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
configMode | String | The configuration mode to be used for each scan. There are three options:
| No | AUTO |
configExternalURL | String | The URL of the external configuration file (you can choose any filename). The configuration file content should be in the same format as the Unified Agent configuration file. The following protocols are supported: 'ftp://', 'http://', 'https://'. For example: 'https://mydomain.com/whitesource-settings/wss-unified-agent.config' NOTES:
| No | Empty |
projectToken | String | Adds the ability to map a GitHub repository to an existing WhiteSource project. The parameter used needs to be the WhiteSource project token. NOTE: Not supported in the Global Configuration. | No | Empty |
baseBranches | Array | Adds the ability to specify one or more base branches for which scanning results will be sent to a new WhiteSource project. Example usage: ["master", “integration"] This will set both master and integration branches as base branches. Note the following:
| No | Empty In this case, the base branch only consists of the default branch. |
enableLicenseViolations | Boolean | When enabled, a new WhiteSource License Check will be generated for each valid push. NOTES:
| No | false |
enableIaC | Boolean | When enabled, a new WhiteSource IaC Check will be generated for each valid push. This will scan cloud infrastructure configurations to find misconfigurations before they are deployed, and alert on these via the creation of issues. NOTES:
| No | false |
...
Parameter | Type | Description | Required | Default | ||
---|---|---|---|---|---|---|
displayMode | String | How to display WhiteSource security information for a scan performed on a non-base branch:
| No | diff | ||
vulnerableCheckRunConclusionLevel | 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 '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 | ||
licenseCheckRunConclusionLevel | 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 License Check is completed. When the parameter is set to 'success', the conclusion status of a WhiteSource License 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 License Check found license policy violations. When the parameter is set to 'failure' (default), the conclusion status of a WhiteSource License Check will be 'Failure' in cases where WhiteSource License Check found license policy violations 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 | ||
showWsInfo | Boolean | Whether to show additional WhiteSource information such as the project token inside the WhiteSource Check Run (after the scan token). WhiteSource information is only displayed if the commit originated from a base branch. The following hidden JSON object will also be added inside the Check Run when this parameter is enabled:
NOTE: Additional WhiteSource data may be added inside the JSON object in the future. | No | false |
Issue Settings (issueSettings)
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 on a detected vulnerability. Available values for minSeverityLevel:
NOTE: The WhiteSource Security Check summary is also affected by this parameter. | No | LOW |
displayLicenseViolations | Boolean | Whether to generate an Issue for every detected license policy violation. NOTE: This parameter is relevant only if enableLicenseViolations (scanSettings) is set to true. | No | true (only if enableLicenseViolations (scanSettings) is set to true) |
Remediate Settings (remediateSettings)
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
enableRenovate | Boolean | When enabled, Remediate will raise automated Pull Requests for outdated dependencies in addition to Pull Requests remediating vulnerable dependencies. Remediate will then perform all the functionality and support all the configuration options available in WhiteSource Renovate. See Renovate configuration options for all configuration options. Refer here for parameter usage. | No | false |
transitiveRemediation | Boolean | Whether to enable transitive remediation for NPM repos. When npm v6 (npm v7 is not currently supported) is used with a package-lock.json file, and vulnerabilities are found within transitive dependencies in the file, then in most cases Remediate is able to successfully remediate the vulnerability. Sometimes it may not be possible to successfully remediate because a parent dependency does not yet have a new release that allows the necessary fixed-in version of the transitive dependency. | No | false |
Initiating a Scan
A WhiteSource 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 added/removed a source file(s) that has 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 an addition/modification of the package manager dependency file(s).
Refer to the list of supported dependency files to find out whether your dependency files are supported.
NOTE: a A push command may consist of multiple commits.
...
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:
CVE: A link to the related CVE page for the vulnerability. Displayed in a collapsible format (click the arrow to expand/collapse for more information regarding the vulnerability).
Severity: Overall score of the severity (High, Medium or Low).
CVSSScore
Vulnerable Library
Suggested Fix
Issue: A link to the WhiteSource issue that was generated for the vulnerability.
...
Success: No license policy violations were detected.
Failed: One or more license policy violations were detected during the WhiteSource scan.
Viewing WhiteSource IaC Checks
...
Success: No license policy violations were detected.
Failed: One or more license policy violations were detected during the WhiteSource scan.
Viewing Details in the WhiteSource UI
...
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.
NOTE: This integration supports merge policies for PRs created either from a branch in the same repository or originating from a different repository.
Adding a Branch Protection Rule
...