Before beginning the installation process, ensure that the guidelines described in Installation Prerequisites have been fulfilled.
NOTE: Follow all procedures in order as they are presented here.
Go to your GitLab instance and click Admin Area > System Hooks.
Fill in the fields according to these guidelines:
URL: The WhiteSource webhook handler URL. The URL should end with '/payload'. Enter the webhook URL in the following format: http://<docker-wss-gls-app-destinationURL>:5678/payload.
Secret Token: Secret token for payload validation
Trigger: All checkboxes except Tag push events must be marked
Enable SSL Verification: Yes
Click Add system hook. Your system hook will appear in the System Hooks section at the bottom of the screen.
Create a new and regular GitLab user and name it @whitesource. This user does not need to be an admin.
NOTE: This user does not require a real email address. The Personal Access Token for the next step can be created by an admin impersonating the @whitesource user.
Create a Personal Access Token for your new @whitesource user. Go to the @whitesource Settings > Access Tokens, and fill in the fields according to these guidelines:
Name: The name of your token, e.g. "WhiteSourceToken"
Expires at (optional): The expiration date for your token
Scopes: All checkboxes should be marked.
Click Create personal access token. Copy the generated Personal Access Token to the clipboard, to be used in the next section.
Open a separate browser tab or window and log in to WhiteSource.
Navigate to the Integrate page of the WhiteSource application. Expand the WhiteSource for GitLab Server bar to view the following fields:
GitLab Server API URL: Your GitLab Server instance's API URL. For example: https://GitLabDevServer.com/api/v4
GitLab Webhook URL: The URL of the WhiteSource webhook handler (the same URL as the system hook from Configure a System Hook).
The webhook URL is used to create webhooks from GitLab projects the integration is installed for, to allow WhiteSource Remediate to receive issue related events.
NOTE: If this webhook URL is on a local server, make sure your GitLab server is configured to allow outbound requests to local servers in Admin Area > Settings > Network > Outbound Requests. Here you can allow outbound requests to your entire local network or simply whitelist the WhiteSource webhook URL.
GitLab Webhook Secret: The webhook secret you entered when creating the system hook in Configure a System Hook.
GitLab Personal Access Token: The @whitesource user's personal access token created in the previous step.
Click Get Activation Key to generate your activation key. A new Service user is created for this integration inside the WhiteSource Application with a WS prefix. NOTE: Do not remove this Service user and ensure this user remains part of the Admin group.
Copy the newly generated Activation Key (You will need it in the next procedure).
If you want WhiteSource Remediate to only open automatic fix MRs in specific scenarios, clicking Manage Workflow Rules will allow you to configure custom rules for when Remediate opens MRs.
The UI Configuration tool enables you to configure the deployment file according to your specific configuration requirements.
Open index.html located inside the wss-configuration directory via a Chrome or Firefox Web browser. The WhiteSource Configuration Editor page is displayed.
Load the template JSON configuration file by clicking Choose File and selecting the file located at wss-configuration/config/prop.json. The General tab appears in the Editor.
Click the General tab and enter the Activation Key which you copied in the previous section.
To manage the creation of GitLab Issues or Commit Statuses globally across all of your organization's repositories, click the Issues tab. (The parameters in this tab are displayed in the table below.)
To display the Proxy tab, click the Advanced Properties checkbox on the Home tab. Proxy fields that are not mandatory (e.g., user name and password) must be left blank. (The parameters in this tab are displayed in the table below.)
Click Export, and save the JSON file with the name prop.json. This file will be used in the next sections.
You can export the JSON file at any time, even if you did not finish editing it in order to save your configurations and to enable assigning the configuration of a specific section to the appropriate professional in your organization (e.g., data source section may be assigned to the DBA of your organization). |
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 | |
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) |
In order to upload the WhiteSource scan results to the GitLab security dashboard, add the following YAML to your .gitlab-ci.yml file:
whitesource-security-publisher: image: openjdk:8-jdk when: manual script: - curl "{{WEBHOOK_URL}}/securityReport?repoId=$CI_PROJECT_ID&repoName=$CI_PROJECT_NAME&ownerName=$CI_PROJECT_NAMESPACE&branchName=$CI_COMMIT_REF_NAME&defaultBranchName=$CI_DEFAULT_BRANCH&commitId=$CI_COMMIT_SHA" -o gl-dependency-scanning-report-ws.json artifacts: paths: - gl-dependency-scanning-report-ws.json reports: dependency_scanning: - gl-dependency-scanning-report-ws.json expire_in: 30 days |
Replace {{WEBHOOK_URL}}
with the GitLab Webhook URL from Creating an Activation Key (remove the “payload” part from the URL).
NOTE: The CI job’s name must be whitesource-security-publisher in order for WhiteSource to recognize and trigger it.
Create a network bridge (this will create a private network between the different containers since all containers need to run within the same network):
docker network create -d bridge my_bridge |
Run the wss-gls-app app container:
docker run --name wss-gls-app --network my_bridge -p 9494:9494 -p 5678:5678 -v <path/to/config/directory>:/etc/usr/local/whitesource/conf wss-gls-app:<version> # For example: docker run --name wss-gls-app --network my_bridge -p 9494:9494 -p 5678:5678 -v c:/tmp/gls/:/etc/usr/local/whitesource/conf/ wss-gls-app:19.9.1.1 |
Run the wss-scanner scanner container:
docker run --name wss-scanner-gls --restart=always --network my_bridge -p 9393:9393 -v <path/to/config/directory>:/etc/usr/local/whitesource/conf/ wss-scanner:<version> # For example: docker run --name wss-scanner-gls --restart=always --network my_bridge -p 9393:9393 -v c:/tmp/gls/:/etc/usr/local/whitesource/conf/ wss-scanner:19.9.1.1 |
Run the wss-remediate server container:
docker run --name remediate-server --restart=always --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v <path/to/config/directory>/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:<version> # For example: docker run --name remediate-server --restart=always --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v c:/tmp/gls/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:19.8.1 # NOTE: If port 8080 isn't available, you can use a different port by modifying the first port entry in the 'docker run' command. For example: # docker run --name remediate-server --network my_bridge -e LOG_LEVEL=debug -p 8082:8080 -v c:/tmp/gls/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:19.8.1 |
The wss-deployment folder consists of the following structure:
helm
configs
templates
config.yaml
wssScmIntegration.yaml
Chart.yaml
values.yaml
Copy the helm folder from wss-deployment to your target environment. Inside the helm/configs folder, add the configuration properties JSON file (prop.json) that you previously edited and exported using the Configuration Editor.
This file contains information about the chart.
NOTE: Do not edit this file.
This file represents the WhiteSource integration image names and versions.
wsscanner: image: {image} version: {version} wsscontroller: image: {image} version: {version} wssremediate: image: {image} version: {version} |
For each image declaration (wssscanner, wsscontroller, wssremediate), replace {image} and {version} with the actual built image name and version. NOTE: For wsscontroller, use the name and version of the wss-gls-app image.
An optional parameter, imagePullSecrets, can be added to this file in case Docker repository authentication is required.
In the helm folder, create a new folder named configs, and add to it the configuration properties JSON file (prop.json) that you previously edited and exported using the Configuration Editor.
This is a configuration file pointing to the configs/prop.json file.
NOTE: Do not edit this file.
This is a configuration file containing all the parameters for deploying the integration.
NOTE: In this file, there are 3 dashes ("- - - ") that separate the services Do not remove them.
In order for the webhook URL to be accessible publicly by the integration, a load balancer service must be added to the file. An example of such a service is provided below:
apiVersion: v1 kind: Service metadata: name: lb1 namespace: acme annotations: external-dns.alpha.kubernetes.io/hostname: helm.acme.io service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy: "ELBSecurityPolicy-TLS-1-2-2017-01" service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:us-east-7:834027593108:certificate/4720e07a-a231-4fd5-9c4a-12ab1450567d spec: type: LoadBalancer ports: - port: 443 name: https targetPort: 5678 selector: app: wss-controller |
If you are integrating multiple repositories and want to apply global configurations, refer here before continuing in this procedure.
Add the @whitesource user (the user you created during Creating a New GitLab User and a Personal Access Token) as a member with Maintainer permissions to the repositories you want WhiteSource to scan. This is how WhiteSource will determine which repositories will be scanned.
If you would like WhiteSource for GitLab to scan an entire GitLab group, add the @whitesource user to the group to enable WhiteSource for GitLab for all of the projects within that group.
NOTE: Adding the @whitesource user to a repository with any permissions less than Maintainer may create side-effects in the integration's functionality.
Unless specified otherwise via the global configuration, an onboarding merge request is created for each repository to which the @whitesource user was added. This request contains a WhiteSource configuration file (.whitesource) that can be customized before merging the request. Once merged, a WhiteSource scan will be initiated.
In order to disable scanning for a repository, remove the @whitesource user from the repository members.
See here for more information.
See here for more information.
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).
|
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:
Using values defined in the global configuration and overriding the scan settings parameters:
| No | N/A |
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' 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:
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:
| 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 | |
vulnerableCommitStatus | String | Customizable commit status settings.
| No | FAILED | |
licenseCommitStatus | String | Customizable commit status settings.
| No | 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. The following hidden JSON object will also be added inside the Commit Status when this parameter is enabled:
NOTE: Additional WhiteSource data may be added inside the JSON object in the future. | No | false |
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:
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 |
---|---|---|---|---|
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 |
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.