Info | ||
---|---|---|
| ||
This is a controlled WhiteSource integration release. For more information, please contact support@whitesourcesoftware.com. |
...
- Port 5678 must be open at all times. This port will be used to receive webhooks from the Bitbucket add-on.
- Access to the WhiteSource Application is required at times for the operation of the WhiteSource for Bitbucket Server.
...
Installation and Configuration
In Windows, extract ‘agent-4-bitbucket-<version>.zip’ to an empty folder. In Linux, extract ‘agent-4-bitbucket-<version>.tar.gz’ to an empty folder.
The extraction creates the following items:
...
Please copy the Activation key that was generated in WhiteSource application and paste it to 'Activation Key' property in the editor.
- In order to configure the proxy settings, select the 'advanced properties' checkbox. Proxy fields that are not mandatory (e.g., user name and password) should be left blank.
- After you have finished editing, export the filled in configuration file by clicking the ‘Export’ button and saving the JSON file with the name prop.json in a different location. This file will be used when running the application.
...
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 Host | 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-bb-app) was modified. Default value: http://wss-bb-app:5678 | http://wss-bb-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 Create Build Status | bolt4scm.create.check.runs | Boolean | no | The ability to globally enable/disable build statuses across all of your organization's repositories. Default value: true (NOTE: Supported from version 20.5.1.3 only) |
Info |
---|
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., datasource section may be assigned to the DBA of your organization). |
...
Building and Tagging the Docker Images
There are three different ways of building the Docker images.
Info |
---|
A total of 3 images will be built: wss-bb-app, wss-scanner, and wss-remediate. |
...
Run the build.bat or build.sh executable script file (Windows/Linux).
Both files are located in the root of the extracted agent-4-bitbucket-<version>.zip or agent-4-bitbucket-<version>.tar.gz files.
For Windows:
Run build.bat file which is located in the main folder where you extracted the agent-4-bitbucket zip file.
In order to ensure that the build succeeded, run the command docker images and check if wss-bb-app and wss-scanner and wss-remediate images were created.
For Linux:
Run build.sh file which is located in the main folder where you extracted the agent-4-bitbucket tar.gz file.
In order to ensure that the build succeeded, run the command docker images and check if wss-bb-app and wss-scanner and wss-remediate images were created.
2. Manually Build the Images
To run the steps of the build file manually, run the following commands directly:
NOTE: If you have already run the build file, skip these steps and continue to Target machine: Running the Containers step.
...
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.
...
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-bb-app image.
An optional parameter, imagePullSecrets, can be added to this file in case Docker repository authentication is required.
configs/prop.json
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.
...
NOTE: Do not edit this file.
templates/wssScmIntegration.yaml
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
...
- Go to the Bitbucket server UI > Administration page > WhiteSource Integration tab (Link:<your/bitbucket-server/url>:<port>/plugins/servlet/whitesource/configure).
- Copy the activation key and paste it into the Activation key field, and then click Validate.
- If you are integrating multiple repositories and want to apply global configurations, refer here before continuing in this procedure.
- Select one of the following options:
- All projects: (default) Integrate all the (current and future) projects inside the Bitbucket instance.
- Selected projects only: Select specific projects that you would like to integrate with WhiteSource.
- The project admin must do the following:
- Go to the project page of any integrated project (see above).
- Go to the Project settings page.
- In the navigation pane, under Workflow, click WhiteSource Integration.
- Select one of the following options:
- All repositories: (default) Integrate all the (current and future) repositories inside the Bitbucket instance.
- Selected repositories only: Select specific repositories that you would like to integrate with WhiteSource.
NOTE: Only a user with Admin or Write permissions on a selected repository will be able to access the WhiteSource Integration tab inside the repository page.
- Click Save. Unless specified otherwise via the global configuration, an onboarding pull request is created for the selected repositories. This 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.
...
Results can be viewed in the following places:
- The Issues WhiteSource Integration tab within the GitHub project
- The WhiteSource Security/License Check within the Bitbucket repo Commits tab.
- The WhiteSource UI.
- Via email notifications.
Viewing Details of an Issue
See here for more information.
...
- In progress: The WhiteSource scan is in progress.
- Success: The WhiteSource scan completed successfully and no vulnerabilities were detected.
- Failed: The WhiteSource scan did not complete successfully, this is the default for all completed scans. NOTE: a failed status may be shown due to security vulnerabilities, or due to an error that occurred during the scan.
...
The following is a sample of a In Progress status, which indicates that the security check is currently scanning the head commit.
Success
When no vulnerabilities are found and no errors occurred during the scan, WhiteSource will display the following status check, and a security report indicating that no vulnerabilities were detected:
Failed
- Security vulnerabilities found: One or more vulnerabilities have been found as displayed in these sample screenshots:
Click on the ‘WhiteSource Security Check’ link to view the security report on all vulnerabilities that were found for the specific commit’s scan. It includes the following columns:
- 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).
- CVSS Score
- Vulnerable Library
- Suggested Fix
- Issue - A link to the relevant issue generated by WhiteSource (when available)
- Scan failed: Due to system error or not a valid Bitbucket ‘push’ command.
Viewing WhiteSource License 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
...
Accessing Scan Statistics via API
See here for more information.
Health Check APIs
See here for more information.
...
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' | No | Empty |
projectToken | String | Adds the ability to map a Bitbucket 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 | ||
failBuilds | Boolean | The app 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 false, 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 true (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, 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. | No | true | ||
failLicenseBuilds | Boolean | The app 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 false, 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 true (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, 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. | No | true | ||
showWsInfo | Boolean | Whether to show additional WhiteSource information such as the project token inside the WhiteSource Build 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 Build Status when this parameter is enabled:
| No | 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:
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 |
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-bb-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-bb-app container.
- In the "wss-bb-app/conf" folder, add your custom “.whitesource” file (where the prop.json file is located).
- Start the wss-bb-app container.
Upgrading to the Latest Docker Images
- Get the latest WhiteSource for Bitbucket Server version from WhiteSource Support.
- Upload the new WhiteSource Bitbucket add-on by following the guidelines here.
- Build these three Docker images from the new version - see here.
- wss-bb-app
- wss-scanner
- remediate-server
Stop currently-running Docker containers from the previous version:
Code Block docker stop <wss-bb-app> <wss-scanner> <remediate-server>
Remove the Docker containers from the previous version:
Code Block docker rm <wss-bb-app> <wss-scanner> <remediate-server>
- Fetch the activation key from the existing prop.json file (the propertyValue associated to the property "bolt.op.activation.key") and copy it to the clipboard.
- Generate and save the new prop.json file by following the steps here and using the activation key value that was just copied.
- Run the containers - see here.
- (Optional) If the new wss-bb-app container has a different URL than the previous container, then follow the guidelines here to update the Bitbucket webhook URL.
Uninstalling
You can easily uninstall this add-on by doing the following:
...