Page Comparison

Versions Compared

Key

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

...

Details on Attributes of the Configuration File

Section	Label	Name	Type	Mandatory	Description	Sample Value
General	Activation Key	bolt.op.activation.key	String	yes	Your generated activation key in the WhiteSource application
Proxy	HTTP Proxy Host	proxy.host	Host Address	no	HTTP proxy host. Leave blank to disable. Default value: Empty
Proxy	HTTP Proxy Port	proxy.port	Integer	no	HTTP proxy port. Leave blank to disable. Default value: Empty
Proxy	Proxy User	proxy.user	String	no	Proxy Username (if applicable)	user
Proxy	Proxy Password	proxy.password	String	no	Proxy Password (if applicable)	abc123
Advanced	Controller URL	controller.url	String	no	The ability to modify the App container URL in case its default name (wss-ghe-app) was modified. Default value: http://wss-ghe-app:5678	http://wss-ghe-app:5678
Issues	Should Create Issues	bolt4scm.create.issues	Boolean	no	The ability to globally enable/disable Issues creation across all of your organization's repositories. Default value: true (NOTE: Supported from version 20.5.1.3 only)
Issues	Should Update Commit Status	bolt4scm.create.check.runs	Boolean	no	The ability to globally enable/disable commit statuses across all of your organization's repositories. Default value: true (NOTE: Supported from version 20.5.1.3 only)

Uploading WhiteSource Scan Results to the GitLab Security Dashboard (ForGitLab UltimateUsers Only)

...

A WhiteSource configuration file (.whitesource) is a JSON file added to each repository enabled for scanning. 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).

Code Block

{
  "scanSettings": {
    "configMode": "AUTO",
    "configExternalURL": "",
    "projectToken" : "",
    "baseBranches": []
  },
  "commitStatusSettings": {
    "displayMode": "diff",
    "vulnerableCommitStatus": "FAILED"
  },
  "issueSettings": {
    "minSeverityLevel": "LOW",
    "openConfidentialIssues": true
  }
}

Parameters

Global Settings

Parameter

Type

Description

Required

Default

settingsInheritedFrom

String

When the global configuration is enabled, this parameter will specify the location of the whitesource-config repository from which it will inherit its configuration. It must contain the GitLab user name, repository name and branch (optional) of the repo-config.json file location. The default branch is 'master', but can be modified according to the location of the repo-config.json file in the whitesource-config repo.

NOTE: You can override specific parameters that are relevant only in the specific repository by adding these after this parameter.

Examples:

Using only values defined in the global configuration:

Code Block
"settingsInheritedFrom": "whitesource-config@master"

Using values defined in the global configuration and overriding the scan settings parameters:

Code Block
"settingsInheritedFrom": "whitesource-config@master", "scanSettings": { "projectToken": "12345", "baseBranches": ["master","integration"] }

N/A

Scan Settings (scanSettings)

Parameter	Type	Description	Required	Default
configMode	String	The configuration mode to be used for each scan. There are three options: AUTO - Automatic mode. This will use the default WhiteSource configuration. LOCAL - Local mode. This will look for a local 'whitesource.config' file to be provided in the root folder of the current repository. The configuration file should be in the same format as the Unified Agent configuration file. NOTE: Not supported in the Global Configuration. EXTERNAL - External mode. This will look for a configuration file specified according to the configExternalURL parameter.	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' NOTE: This parameter is relevant only if configMode was set to EXTERNAL.	No	Empty
projectToken	String	Adds the ability to map a GitLab repository to a 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: An Issue will only be created for the specified branch names. Repositories which do not contain the baseBranches parameter will have issues generated for all branches. For each specified branch, a WhiteSource project will be created. The name of the project will contain a suffix "_branchname". For example, MyApp_dev. This suffix will not apply to the default branch. NOTE: This parameter is available only from version 20.7.1.	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: This parameter is available only from version 20.11.2. You must have it least one policy of match type By License Group defined with a Reject action in the WhiteSource UI. The policy name in the WhiteSource UI must start with a “[License] “ prefix. For example, "[License] PolicyName".	No	false

Commit Status Settings (commitStatusSettings)

Parameter

Type

Description

Required

Default

displayMode

String

How to display WhiteSource security information for a scan performed on a non-base branch:

When set to diff - Only the diff of detected vulnerabilities between the current commit and its base branch commit will be displayed. NOTE: This value is only supported when using the baseBranches configuration.
When set to baseline - A summary of all detected vulnerabilities in the full repository inventory will be displayed.

diff

vulnerableCommitStatus

String

Customizable commit status settings.

FAILED - If the WhiteSource scan detects vulnerabilities in a repository, the commit status will show a "failure" indicating that vulnerabilities were detected.
If no vulnerabilities were detected, the commit status shows a "success" indicator. (default option)
SUCCESS - The commit status will show a success indicator at the end of the scan regardless of whether the scan detected vulnerabilities in the repository.
NONE - The commit status will not be updated by WhiteSource under any circumstances, not even to a "running" indicator while the scan is in progress.

FAILED

licenseCommitStatus

String

Customizable commit status settings.

FAILED - If the WhiteSource scan detects license policy violations in a repository, the commit status will show a "failure" indicating that license policy violations were detected.
If no license policy violations were detected, the commit status shows a "success" indicator. (default option)
SUCCESS - The commit status will show a success indicator at the end of the scan regardless of whether the scan detected license policy violations in the repository.
NONE - The commit status will not be updated by WhiteSource under any circumstances, not even to a "running" indicator while the scan is in progress.

FAILED

showWsInfo

Boolean

Whether to show additional WhiteSource information such as the project token inside the WhiteSource Commit Status (after the scan token).

WhiteSource information is only displayed if the commit originated from a base branch.
If the commit exists in multiple branches, the WhiteSource information displayed will only represent the origin base branch (i.e. where the baseBranches parameter was defined).

The following hidden JSON object will also be added inside the Commit Status when this parameter is enabled:

Code Block
<!-- <INFO>{"projectToken":"1cd2d2a8651145c087609e0a43f783e95f7008cb908541498348fed529572e01"}</INFO> -->

NOTE: Additional WhiteSource data may be added inside the JSON object in the future.

false

Issue Settings (issueSettings)

Parameter	Type	Description	Required	Default
minSeverityLevel	String	Enables users to decide whether to open a new Issue only if a certain severity level is available on a detected vulnerability. Available values for minSeverityLevel: NONE - No Issues will be generated. LOW - Any Low/Medium/High vulnerabilities found will generate an Issue. MEDIUM - Any Medium/High vulnerabilities found will generate an Issue. HIGH - Any High vulnerabilities found will generate an Issue. NOTE: The WhiteSource Security Check summary is also affected by this parameter.	No	LOW
openConfidentialIssues	Boolean	Whether the GitLab issues opened by WhiteSource will be confidential issues.	No	false
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)

Parameter

Type

Description

Required

Default

minSeverityLevel

String

Enables users to decide whether to open a new Issue only if a certain severity level is available on a detected vulnerability.

Available values for minSeverityLevel:

NONE - No Issues will be generated.
LOW - Any Low/Medium/High vulnerabilities found will generate an Issue.
MEDIUM - Any Medium/High vulnerabilities found will generate an Issue.
HIGH - Any High vulnerabilities found will generate an Issue.

NOTE: The WhiteSource Security Check summary is also affected by this parameter.

LOW

openConfidentialIssues

Boolean

Whether the GitLab issues opened by WhiteSource will be confidential issues.

false

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.

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 Merge Requests for outdated dependencies in addition to Merge 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

Parameter

Type

Description

Required

Default

enableRenovate

Boolean

When enabled, Remediate will raise automated Merge Requests for outdated dependencies in addition to Merge 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.

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.

false

Providing a Global Configuration File

NOTE: Supported from version 20.5.1.3 only.

You can provide a custom .whitesource configuration file as part of the wss-gls-app container, in order to apply it globally to all of your organization's repositories. Doing so will apply the file to all onboarding pull requests for newly-selected repos. Repos which were already selected and activated before this change will not be affected by this global configuration. Only newly onboarded repos will be affected.

To apply this global change, do as follows:

Stop the wss-gls-app container.
In the "wss-gls-app/conf" folder, add your custom “.whitesource” file (where the prop.json file is located).
Start the wss-gls-app container.

Configuration Error Issues

Will alert the user on configuration errors that affects their scan by creating a configuration error issue and commit status. In case of such an error the following will occur:

Stop the workflow. Do not create a scan or the WhiteSource Security commit status.
Create a “Configuration Failed” commit status.
For each config file that failed parsing - create a new type of issue, titled Action Required: Fix WhiteSource Configuration File - {fileName}. If the error originated from the repo-config.json or global-config.json files, then the issue will be created in the whitesource-config repo.

Handled errors:

...

Error parsing the configuration files (.whitesource/repo-config.json/global-config.json json)

...

Private Registry Settings (hostRules)

Parameter

Type

Description

Required

Default

matchHost

String

Defines where the credentials will be applied during the scan.

If you want to apply credentials only for a nested path within a host, then write matchHost as a base URL.
For example: https://registry.company.com/nested/path/.

If the same credentials apply to all paths on a host and not on any subdomains, configure matchHost with a protocol like https://registry.company.com.

Finally, to apply credentials to all hosts within the domain, use a matchHost value with no https:// prefix, e.g. company.com or registry.company.com, both of which would apply to a host like beta.registry.company.com.

Empty

hostType

String

Type of private registry. Supported values: npm.

Empty

username

String

Used when credentials consist of username and password.

Empty

password

String

Used when credentials consist of username and password, should be encrypted by this instruction.

Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:

Code Block
"encrypted": { "password": "3f832f2983yf89hsd98ahadsjfasdfjaslf............" }

Empty

token

String

Used when credentials consist of username and password, should be encrypted by this instruction.

Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:

Code Block
"encrypted": { "token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............" }

Empty

Providing a Global Configuration File

NOTE: Supported from version 20.5.1.3 only.

To apply this global change, do as follows:

Stop the wss-gls-app container.
In the "wss-gls-app/conf" folder, add your custom “.whitesource” file (where the prop.json file is located).
Start the wss-gls-app container.

Configuration Error Issues

Will alert the user on configuration errors that affects their scan by creating a configuration error issue and commit status. In case of such an error the following will occur:

Stop the workflow. Do not create a scan or the WhiteSource Security commit status.
Create a “Configuration Failed” commit status.
For each config file that failed parsing - create a new type of issue, titled Action Required: Fix WhiteSource Configuration File - {fileName}. If the error originated from the repo-config.json or global-config.json files, then the issue will be created in the whitesource-config repo.

Handled errors:

Error parsing the configuration files (.whitesource/repo-config.json/global-config.json json)
Missing repository and/or branch in the inheritance configuration

Handling Private Registries and Authenticated Repositories

Info
Only NPM private registries are currently supported.

In order to scan dependencies from private registries and authenticated repositories, WhiteSource must be provided with credentials, such as an NPM token. These credentials must be added as encrypted secrets to the .whitesource file, either per-repository or in the shared global config, if the secret scope is org-wide.

Сreate the encrypted secrets. Each secret you encrypt must be scoped to a GitLab org or repo and use of it will be restricted to those within the app.
1. Generate a PGP Key using one of several methods. We recommend using an online generator such as attogtech.com/pgp-key-generator. Please note that at this time we do not support using a passphrase for decryption, so it is best to generate the keys without a passphrase.
2. Open index-enterprise.html in your favorite editor.
3. Find and replace the text "COPY_YOUR_PUBLIC_PGP_KEY_HERE" with your newly generated public key and save the file.
  const publicKeyString = `COPY_YOUR_PUBLIC_PGP_KEY_HERE`;
After the secret is created, please add it to the hostRules parameter of the .whitesource file.

View file

name	index-enterprise.html

Example of hostRules:

Code Block
{ "hostRules": [ { "matchHost": "registry.npmjs.org", "hostType": "npm", "encrypted": { "token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............" } }, { "matchHost": "https://custom.registry.company.com/maven/", "hostType": "maven", "username": "bot1", "encrypted": { "password": "p278djfdsi9832jnfdshufwji2r389fdskj........." } } ] }

Code Block

{
  "hostRules": [
    {
      "matchHost": "registry.npmjs.org",
      "hostType": "npm",
      "encrypted": {
        "token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
      }
    },
    {
      "matchHost": "https://custom.registry.company.com/maven/",
      "hostType": "maven",
      "username": "bot1",
      "encrypted": {
        "password": "p278djfdsi9832jnfdshufwji2r389fdskj........."
      }
    }
  ]
}

NOTE:

Copy the entire output of the key generator including comments to paste into the string.
i.e. include "-----BEGIN PGP PUBLIC KEY BLOCK-----..."
The string uses javascript backticks and not quotes. This is to allow a multi-line string so that you do not have to replace any line breaks with new-line characters. Be aware of any auto indenting by your editor that may introduce spaces to the public key and cause encryption to fail.

Manage space

Manage content

Integrations

App links

Versions Compared

Old Version 47

New Version 48

Key

Details on Attributes of the Configuration File

Uploading WhiteSource Scan Results to the GitLab Security Dashboard (ForGitLab UltimateUsers Only)

Parameters

Global Settings

Scan Settings (scanSettings)

Commit Status Settings (commitStatusSettings)

Issue Settings (issueSettings)

Remediate Settings (remediateSettings)

Providing a Global Configuration File

Configuration Error Issues

Private Registry Settings (hostRules)

Providing a Global Configuration File

Configuration Error Issues

Handling Private Registries and Authenticated Repositories