Mend for Bitbucket Server and Data Center
Supported Bitbucket Products
This documentation covers our Bitbucket Server and Bitbucket Data Center repository integration.
Following Atlassian’s discontinuation of Server products on February 15, 2024, Mend for Bitbucket Server will no longer be supported after version 24.1.2. You can continue using the same Mend integration you’re currently using with Bitbucket Server for your Data Center deployment.
For more information on our Bitbucket Cloud repository integration, read more here: Mend for Bitbucket Cloud.
Introduction
Mend for Bitbucket Data Center is a Bitbucket Data Center app, scanning your repositories, as part of your Mend account.
It is an integrated product within Bitbucket Data Center that shows a high-level security overview in the Bitbucket repository, detects all open source components and displays all vulnerabilities for these components.
It generates comprehensive up-to-date reports on the Bitbucket Data Center ‘Mend integration’ tab of the scanned repository. In addition, you will be able to view the scanned repositories in the Mend portal.
Mend for Bitbucket Data Center is part of Mend Developer Integrations and includes continuous automated dependency updates with Mend Remediate, using fix Pull Requests.
Prerequisites
The following requirements must be accommodated before installing the Mend server software.
Access to a working Mend Application and a user with Admin privileges (either Organization or Product Admin).
Bitbucket version 5.15 or above is installed.
Admin privileges on the Bitbucket instance
Bitbucket online editor needs to be enabled to allow the creation of the configuration file (either the .whitesource or the .mend file, depending on which agent version you are using).
File: bitbucket.properties
Setting: feature.file.editor=true
The deployment includes two environments:
Build environment where the image is built.
Deployment environment where the image is deployed.
The build environment can be the same one as the deployment environment on which the relevant Mend Docker images will be deployed.
For both build and target environments arm64 is not supported.
Build Environment
This build environment can be the same one as the deployment environment on which the Mend Docker image is deployed. It requires the following:
Hardware Requirements
CPU: Dual-Core, 2Ghz or higher (Intel or AMD)
RAM: 16GB
Storage: 100GB minimum; depending on maximum repository size and complexity
Environment Requirements
An internet connection for the entire duration of the build procedure.
When using a Container Orchestration Platform (i.e Kubernetes, ECS, Rancher etc.), please make sure you have logs collection in place: ELK, Splunk or similar. If you are not using an Orchestration platform for the containers, the logs will be collected in designated folders.
A user with admin privileges: If the operating system is Windows, then you must have administrative privileges. If the operating system is Linux, then you must have root privileges.
Docker server version 18 and above. You can verify the Docker version by entering the following:
docker –version
Software and files delivered by mend:
Mend Docker distribution artifacts that are delivered as a tar.gz or zip file (For example, agent-4-bitbucket-19.2.1.tar.gz or agent-4-bitbucket-19.2.1.zip).
You can download the latest version with this link.
Target Environment
The image is installed on the target environment. This environment requires the following:
Hardware Requirements
CPU: Dual Core, 2Ghz or higher (Intel or AMD)
RAM: 16GB
Storage: 100GB minimum; depending on maximum repository size and complexity
Environment Requirements
A user with admin privileges: If the operating system is Windows, then you must have administrative privileges. If the operating system is Linux, then you must have root privileges.
Docker server version 18 and above. You can verify the Docker version by entering the following:
docker –version
Port 5678 must be open at all times. This port will be used to receive webhooks from the Bitbucket add-on.
Access to the Mend Application is required at times for the operation of the Mend for Bitbucket Data Center.
The access to the app can be checked by issuing an HTTP GET request using a web browser or a utility (e.g., cURL, wget):
https://<your-base-url>/healthCheck
(e.g., https://saas.whitesourcesoftware.com/healthCheck)
It is recommended to verify that the returned status is 200 (OK).
This is only a validation URL. Access must be open for all paths and endpoints under the app’s subdomain.
If a proxy server is available, then the following proxy settings need to be obtained:
URL
Port number
Username and password (for authenticated access)
A valid SSL certificate and KeyStore containing the certificate.
User Steps on Build Machine
Prepare for Installation
Download the ‘tar.gz’ file (‘agent-4-bitbucket-<version>.tar.gz’) for Linux or 'zip' file Windows (‘agent-4-bitbucket-<version>.zip’)
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:
‘wss-bb-add-on’: Includes the jar of the add-on that will be uploaded to your Bitbucket Data Center.
‘wss-bb-app’: Mend Bitbucket Data Center application. This application is responsible for communication between Mend application and Mend Bitbucket add-on. (located in the path 'wss-bb-app/docker/Dockerfile')
‘wss-config’: UI Configuration tool and related configuration file template.
'wss-deployment': Deployment template (for example, deploying the integration using Helm charts)
'wss-remediate': Mend Remediate worker
‘wss-scanner’: Mend BitBucket repository-scanner. wss-scanner is responsible for scanning Bitbucket repositories. (located in the path 'wss-scanner/docker/Dockerfile')
‘build.sh’/'build.bat’ (Linux/Windows): The build script
Modifying the Scanner Dockerfile
The wss-scanner image Dockerfile is located in the wss-scanner\docker\ folder. Some package managers are installed by default and the others will need to be manually uncommented in the Dockerfile in order to use them.
We also offer the Dockerfilefull that is located in the wss-scanner\docker\ folder. When using the wss-scanner image’s Dockerfilefull, all of the supported package managers are uncommented and installed by default.
See here for more information on which package managers are part of the scanner image as well as how to add additional package managers.
Python Support
If you want to specify the Python version for your repository, you can choose one of the following versions included in your scanner Dockerfile: 2.7.18, 3.6.15, 3.7.12
, 3.8.12, 3.9.9
, or 3.11.
For this you will need to perform the following procedure:
Ensure the relevant Python version is uncommented in your scanner container’s Dockerfile.
Add or edit the .whitesource configuration file in your repository.
Use the
configMode
parameter and set it to eitherLOCAL
orEXTERNAL
.Create a whitesource.config file and add the following:
CODEpython.invokePipAsModule=true python.path=python3.9 python.installVirtualenv=true
Note:
For
python.path
, use one of the following values:2.7
,3.6
,3.7
,3.8
,3.9,
or3.11
.Alternatively, you can apply this globally across your repositories by using the Global Repo Configuration repo-config.json file.
Installing the Mend App in Bitbucket Data Center
There are two ways to install the Mend App in Bitbucket Data Center - by installing the app via the Atlassian marketplace for Bitbucket, or by uploading the JAR file directly from the extracted Mend for Bitbucket folder. For Bitbucket Data Center only the second option is available at the moment.
Installing via the Atlassian Marketplace
Navigate to the Administration page (<your/bitbucket-server/url>:<port>/admin) and then click Find new apps under the ADD-ONS menu.
In the search field, enter mend and press Enter. The WhiteSource (Mend) App is displayed.
Click Install.
Uploading the Mend App JAR file
Navigate to the Administration page (<your/bitbucket-server/url>:<port>/admin) and then click Manage apps under the ADD-ONS menu.
Click Upload app and select the JAR file located in the wss-bb-add-on folder.
Click Upload.
NOTE: Since Bitbucket 8.18.0 the option to upload apps via the UI/API is disabled.
To enable app installation with these two methods, in the bitbucket.properties
file, set the property upm.plugin.upload.enabled=true
See Bitbucket documentation for more information
Creating a Bitbucket Mend user and generating a Mend Activation Key
Navigate to the Users page under the ACCOUNTS menu (<your/bitbucket-server/url>:<port>/admin/users) and create a new user for Mend in your Bitbucket Data Center with a permission level “Bitbucket User”.
Log in to your Bitbucket Data Center with this Service user.
Login to the Mend Application.
Generate ‘activationKey’ in the Application by navigating to the 'Integrate' page. Expand the 'Mend for Bitbucket Data Center' bar to view the following fields:
The displayed fields are the following:
Bitbucket Data Center URL: Your Bitbucket Data Center URL. For example: https://bitbucketdev.com.
Bitbucket Username: Your Bitbucket Service user’s username. Notice: it must be a username, please do not insert an email.
Bitbucket Personal Access Token: Your Bitbucket Service user’s personal access token with maximum privileges for this user. See also an explanation about retrieving a personal access token in Bitbucket documentation. (Link in Bitbucket Data Center: <your/bitbucket-server/url>:<port>/plugins/servlet/access-tokens/users/<service-user-created-above>/manage).
Bitbucket Webhook URL: Enter the webhook URL in the following format: http://<docker-wss-bb-app-destinationURL>:5678/payload.
When clicking on ‘Get Activation Key’, your activation key will be generated. A new Service user will also be created for this integration inside the Mend Application with a WS prefix. NOTE: Do not remove this Service user.
Supported Dependency Files
The following dependency files are supported for Mend for Bitbucket Server and Data Center SCA scans:
build.gradle
build.gradle.kts
gradle.lockfile
gradle.properties
settings.gradle
cargo.toml
dependencies.scala
pom.xml
setup.py
requirements.txt
Gemfile.lock
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
bower.json
go.mod
Gopkg.lock
Godeps.lock
vendor.conf
gogradle.lock
glide.lock
composer.json
build.sbt
packages.config
packrat.lock
paket.dependencies
Pipfile
pipfile.lock
Podfile
pyproject.toml
libs.versions.toml
poetry.lock
pubspec.yaml
setup.cfg
environment.yml
Any metafile with one of the following extensions:
asp
aspx
config
csproj
do
htm
html
jsp
shtml
tf
xhtml
Cargo.lock
Running the UI configuration tool from the ‘wss-configuration’ Directory
This editor enables you to configure the deployment file according to your specific configuration requirements.
Use the editor by opening the file index.html in 'wss-configuration' directory via a Chrome or Firefox Web browser. The ‘Mend Configuration Editor’ page is then displayed:
Load the template JSON configuration file by clicking the Choose File button and selecting the file located at config/prop.json. The editor page then changes its display to the following:
On the left pane of the editor the different sections of the configuration are displayed. The main pane of the editor enables you to add/edit values to relevant parameters for the selected section. Note that many of the parameters already include default values.
Please copy the Activation key that was generated in Mend 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.
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 Mend 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 |
Proxy | Enable Proxy For All Traffic | proxy.for.all | Boolean | no | If set to NOTES:
| |
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 | |
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) |
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).
In case of replacing the prop.json file with a new one, it is not enough to restart the controller and scanner pods. It is required to delete the old pods and run new ones.
See also the ‘Configuring Deployment Settings’ section in this document.
Optional step: If you want to pull the images from another machine and run them as a container, push them to your Docker registry.
Building and Tagging the Docker Images
There are three different ways of building the Docker images.
A total of 3 images will be built: wss-bb-app, wss-scanner, and wss-remediate.
1. Using an Executable Script File (Recommended)
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.
docker build -t wss-bb-app:<version> wss-bb-app/docker
docker build -t wss-scanner:<version> wss-scanner/docker
docker build -t wss-remediate:<version> wss-remediate/docker
# For example:
docker build -t wss-bb-app:19.9.1.1 wss-bb-app/docker
docker build -t wss-scanner:19.9.1.1 wss-scanner/docker
docker build -t wss-remediate:19.8.1 wss-remediate/docker
NOTE: From version 21.5.1, the Remediate Dockerfile supports both Ubuntu 18.04 and Ubuntu 20.04-compatible images. The base image can be changed using the BASE_IMAGE build argument. e.g.
docker build --build-arg BASE_IMAGE=ubuntu:18.04 -t wss-remediate:21.5.1 wss-remediate/docker
3. Using a Docker Registry
If you are using a private Docker Registry, run the following commands to push the images into your registry:
docker push <registry>/wss-bb-app:<version>
docker push <registry>/wss-scanner:<version>
docker push <registry>/wss-remediate:<version>
# For example:
docker push my-registry/wss-bb-app:19.9.1.1
docker push my-registry/wss-scanner:19.9.1.1
docker push my-registry/wss-remediate:19.8.1
After executing the commands, you should be able to view the images in your registry.
Target Machine: Run the Containers
Deploying Using Docker
On the target environment, create a directory (e.g., ‘<path/to/config/dir>’) and add to it the configuration properties JSON file (prop.json) that you previously edited and exported using the Configuration Editor.
Then, you will need to create a network bridge and run the following Docker containers by using Docker or Kubernetes.
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-remediate’ server container:
docker run --name remediate-server --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v <path/to/config/directory>/prop.json:/etc/usr/local/mend/conf/prop.json -v /tmp:/tmp wss-remediate:<version>
# For example:
docker run --name remediate-server --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v c:/tmp/bb/prop.json:/etc/usr/local/mend/conf/prop.json -v /tmp:/tmp wss-remediate:19.5.1
Changing Remediate Server Port
If port 8080 is not available, you can use a different port by modifying only the first port 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/bb/prop.json:/etc/usr/local/mend/conf/prop.json -v /tmp:/tmp wss-remediate:19.5.1
Run the 'wss-bb-app' app container:
docker run --name wss-bb-app --network my_bridge -p 9494:9494 -p 5678:5678 -v <path/to/config/directory>:/etc/usr/local/mend/conf wss-bb-app:<version>
# For example:
docker run --name wss-bb-app --network my_bridge -p 9494:9494 -p 5678:5678 -v c:/tmp/bb/:/etc/usr/local/mend/conf/ wss-bb-app:19.5.1.1
Run the ‘wss-scanner’ scanner container:
docker run --name wss-scanner-bb --restart=always --network my_bridge -p 9393:9393 -v <path/to/config/directory>:/etc/usr/local/mend/conf/ wss-scanner:<version>
# For example:
docker run --name wss-scanner-bb --restart=always --network my_bridge -p 9393:9393 -v c:/tmp/bb/:/etc/usr/local/mend/conf/ wss-scanner:19.5.1.1
Deploying Using Helm Charts
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.
Chart.yaml
This file contains information about the chart.
Values.yaml
This file represents the Mend 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-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.
templates/config.yaml
This is a configuration file pointing to the configs/prop.json file.
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
Activating the Mend Integration
If the wss-bb-app webhook URL changes, then you will need to re-validate the activation key by performing step 2 again.
Go to the Bitbucket Data Center UI > Administration page > Mend Integration tab (Link:<your/bitbucket-server/url>:<port>/plugins/servlet/mend/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 mend.
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 Security, click Project Permissions.
Select the option to give the Service User Admin priveleges.
The project admin must also do the following:
Stay on the Project settings page.
In the navigation pane, under Workflow, click Mend Integration.
Select one of the following options:
All repositories: Integrate all the (current and future) repositories inside the Bitbucket instance.
Selected repositories only: Select specific repositories that you would like to integrate with mend.
NOTE: Only a user with Admin or Write permissions on a selected repository will be able to access the Mend 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 mend configuration file (.whitesource) that can be customized before merging the pull request. The initial PR must be merged to the base branch first. This will then initiate the installation and start the first scan. You can then define further settings (like selected branches) in the .whitesource file.
Bitbucket Integration 1.0 - Setting Up a Repository
This video demonstrates the repository onboarding process after the integration is set up.
Remediation
Mend Remediate provides continuous automated dependency updates, saving time and reducing your security risks. To read more and configure automated Pull Requests, see Mend Remediate
Initiating a Scan
A Mend scan is initiated via a valid Bitbucket 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 mend.
Refer to the Mend 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 push command may consist of multiple commits.
Inventory post-scan
Mend continuously researches new vulnerabilities and updates its vulnerability database with these findings. In order for these newly-discovered vulnerabilities to be reflected in projects as soon as possible, Mend initiates a post-scan process for all integrated projects every 6 hours and additionally at 01:00 UTC. Mend will create or update issues and pull requests for vulnerabilities that were added to the database during this period of time.
This is an automated procedure, and no action from the user is required.
Viewing Details of the Scan
Results can be viewed in the following places:
The Mend Integration tab within the project
The Mend Security/License Check within the Bitbucket repo Commits tab.
The Mend UI.
Via email notifications.
Viewing Details of an Issue
See here for more information.
Viewing Mend Security Checks
In the Commits tab you can view the status and results of each scan. Click a specific build icon in order to view the Builds page.
Types of Indicators
The following build status indicators are available as feedback on the head commits:
In progress: The Mend scan is in progress.
Success: The Mend scan completed successfully and no vulnerabilities were detected.
Failed: The Mend 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.
Samples of Status Check Indicators
In Progress
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, Mend 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 ‘Mend 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 (Critical, High, Medium or Low).
CVSS Score
Vulnerable Library
Suggested Fix
Issue - A link to the relevant issue generated by Mend (when available)
Scan failed: Due to system error or not a valid Bitbucket ‘push’ command.
Security Check with Partial Scan results
In case when during the scanning of the repository Mend encountered exceptions thrown by the package managers, the scan may conclude with partial results. You can use the strictMode parameter to control the messaging and status of the checks. By default, there is no messaging included in the check description, and the check status is not affected, even if the scan results in partial findings.
Viewing Mend License Checks
In the Commits tab you can view the status and results of each scan. Click a specific build icon in order to view the Builds page.
Types of Indicators
The following build status indicators are available as feedback on the head commits:
Success: No license policy violations were detected.
Failed: One or more license policy violations were detected during the Mend scan.
Viewing Details in the Mend UI
Mend projects will have the same name as the corresponding Bitbucket repository, with a "BB_" prefix, unless otherwise specified in the .whitesource file using a project token.
The name of the Mend product will be the same as that of the Bitbucket project preceded by a "BB_" prefix if the Bitbucket repository is under a Project. Otherwise, the name will be your Bitbucket username preceded by "BB_".
Accessing Scan Statistics via API
See here for more information.
Health Check APIs
See here for more information.
The .whitesource File
A whitesource configuration file (.whitesource) is a JSON file added to each repository that is enabled for a scan. It provides configurable parameters for the scan.
The .whitesource file is only added in the default branch of the repository (unless modified, it is the master branch).
.whitesource file
{
"scanSettings": {
"configMode": "AUTO",
"configExternalURL": "",
"projectToken": "",
"baseBranches": []
},
"buildSettings": {
"displayMode": "diff",
"failBuilds": true
},
"issueSettings": {
"minSeverityLevel": "LOW"
}
}
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 Bitbucket project key, repository name and branch (optional) of the repo-config.json file location. 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:
JS
Using values defined in the global configuration and overriding the scan settings parameters:
JS
| No | N/A |
overrideConfigAllowList | Array | When the global configuration is enabled, this parameter will regulate the ability of repositories that inherit their configuration from the whitesource-config repository to override the parameters locally. There are three options:
NOTE: This parameter must be used in the repo-config.json file of the whitesource-config repository. | No | null |
Scan Settings (scanSettings)
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
configMode | String | The configuration mode to be used for each scan. There are three options:
Note: whitesource.config can be provided both in global config and in the repo itself. If it is provided in both places and there are parameters that are set on both levels - repo level will take precedence. | 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 Bitbucket repository to a Mend project. The parameter used needs to be the Mend 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 Mend 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 Mend License Check will be generated for each valid push. Notes:
| No | false |
enableIaC | Boolean | When enabled, a new Mend 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 a Work item. Notes:
| No | false |
javaVersion | String | Defines version of Java in the Scanner. Available values: 8, 11, 17. Note: For any projects that are using Gradle versions prior to v7.3, we recommend setting your Java version used by the integration to one of the lower supported versions, 8 or 11, via the | No |
|
cloneSubmodules | Boolean | If set to Note: Only enable this parameter if all of the submodules used in the repository are either public repositories or private repositories that are onboarded to Mend. Otherwise the scan will fail. | No | false |
repoNameSync | Boolean | When set to | No | false |
skipScanningStage | Object | Controls what stages of scanning process will be skiped for specific package manager. The available parameters are:
The available parameter values are: Usage example:
CODE
| No | none |
exploitability | Boolean | When set to Additional information about exploitability is available in the designated Public Exploits page. | No | false |
Build Settings (buildSettings)
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
displayMode | String | How to display Mend security information for a scan performed on a non-base branch:
| No | diff |
createBuildStatus | Boolean | The app can provide checks in commits and pull requests on any repository branch. This parameter defines whether Mend Security Check is going to run. If set to | No | true |
failBuilds | Boolean | The app provides checks in commits and pull requests on any repository branch. This parameter defines the conclusion status for when a Mend Security Check is completed. When the parameter is set to false, the conclusion status of a Mend 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 Mend Security Check found security vulnerabilities. When the parameter is set to true (default), the conclusion status of a Mend Security Check will be 'Failure' in cases where Mend 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 Mend License Check is completed. When the parameter is set to false, the conclusion status of a Mend 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 Mend License Check found license policy violations. When the parameter is set to true (default), the conclusion status of a Mend License Check will be 'Failure' in cases where Mend 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 |
failIacBuilds | Boolean | The app provides checks in commits and pull requests on any repository branch. This parameter defines the conclusion status for when a WhiteSource IaC Check is completed. When the parameter is set to When the parameter is set to NOTE: When an IaC issue is closed it will not be detected in the future scans. | No | true |
showWsInfo | Boolean | Whether to show additional Mend information such as the project token inside the Mend Build Status (after the scan token). Mend 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:
CODE
NOTE: Additional Mend data may be added inside the JSON object in the future. | No | false |
useMendBuildNames | Boolean | If set to Note: When .whitesource is created the value of useMendCheckNames is | No | false |
strictMode | String | Controls the messaging and status of security and license checks in the case of partial scan results (i.e. Mend Scanner experienced issues pulling some of the project’s dependencies during the scan). The available parameter values are:
Note: For strictMode to work, the vulnerableCheckRunConclusionLevel and licenseCheckRunConclusionLevel parameters must be set to | No |
|
strictModeInfo | Boolean | Controls the inclusion of INFO logs in the Scan Details report.
| No |
|
Issue Settings (issueSettings)
NOTE: Starting with the release of version 22.12.1 (January 2nd, 2022), to take advantage of the Critical label for vulnerabilities for existing Issues created by our repo integration, a new scan must be triggered on the repository. If a scan has not been triggered after upgrading to this version, the repo will continue to only show the previous three labels (High, Medium, Low) for existing Issues. For more information on the Critical setting, please visit our documentation here.
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:
| No | LOW |
minVulnerabilityScore | string | Enables users to define issue creation based on a specified minimum vulnerability CVSS score. Allowed values - floats with one decimal from 0 to 10. For more information on CVSS 3 Scores, click here. NOTE:
| No | 0 |
maxVulnerabilityScore | string | Enables users to define issue creation based on a specified maximum vulnerability CVSS score. Allowed values - floats with one decimal from 0 to 10. For more information on CVSS 3 Scores, click here. Notes:
| No | 10 |
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) |
iacIssues | Boolean | Whether to generate issues for IaC findings. The available values are:
Note: This parameter is relevant only if the IaC scan is enabled by setting scanSettings.enableIaC to | No |
|
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 Mend Renovate. See Renovate https://docs.renovatebot.com/configuration-options for all configuration options. | No | false |
workflowRules | Object | This parameter is used to specify the rules that regulate when to open remediation pull requests. Usage examples:
CODE
| Yes |
CODE
|
workflowRules.enabled | Boolean | Enables Workflow Rules being set from a .whitesource file. Note: workflow rules can also be set in the Mend application in the Admin → Integration Workflow Rules. But if this parameter is set to | Yes | true |
workflowRules.minVulnerabilitySeverity | String | The minimal vulnerability severity level to automatically create remediation pull requests for. Allowed values - E.g. if set to Note: if this parameter is used together with minVulnerabilityScore and maxVulnerabilityScore than only minVulnerabilitySeverity will have affect. | No | LOW |
workflowRules.minVulnerabilityScore | Float | The minimal vulnerability CVSS 3 score to automatically create remediation pull requests for. Allowed values - floats with one decimal from 0 to 10. For more information on CVSS 3 Scores, click here. Note: if this parameter is used together with minVulnerabilitySeverity it will not have any effect. | No | Empty |
workflowRules.maxVulnerabilityScore | Float | The maximal vulnerability CVSS 3 score to automatically create remediation pull requests for. Allowed values - floats with one decimal from 0 to 10. For more information on CVSS 3 Scores, click here. Note: if this parameter is used together with minVulnerabilitySeverity it will not have any effect. | No | Empty |
Private Registry Settings (hostRules)
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
matchHost | String | Defines where the credentials will be applied during the scan. More details.
| No | Empty |
hostType | String | Type of private registry. Supported values: Required if Note: When using Renovate with a Ruby private registry, add a | No | Empty |
userName | String | Used when credentials require username. | No | Empty |
encrypted.password | String | Used when credentials require password. For more information on setting up hostRules encryption, please visit the Handling Private Registries and Authenticated Repositories section. Encrypted secret that will be applied as a credential to the host set in the
JSON
| No | Empty |
encrypted.token | String | Used when credentials require token. For more information on setting up hostRules encryption, please visit the Handling Private Registries and Authenticated Repositories section. Encrypted secret that will be applied as a credential to the host set in the
JSON
| No | Empty |
envVariablesMapping | Object | Use this parameter if you used environmental variables in the settings of your package manager to include username and password/token (e.g. for a specified package index).
CODE
or
CODE
Then, set
CODE
| No | Empty |
sourceName | String | This parameter is relevant only for Pipenv private registries. Use this parameter if you don’t have a specified a package index, in this case Mend will create one for you based on other parameters of hostRules. The value of sourceName should be a the index name used for your private packages. For example, if you have packages with such index
CODE
Then set sourceName to
CODE
| No | Empty |
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.
Configuration Error Issues
Alert the user on configuration errors that affect their scan, by creating a configuration error issue and build status. In case of such an error, do as follows:
Stop the workflow. Do not create a scan or the Mend Security build status.
Create a “Configuration Failed” build status.
For each config file that failed parsing, create a new type of issue, entitled Action Required: Fix Mend 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
Upgrading to the Latest Docker Images
Get the latest Mend for Bitbucket Data Center version from Mend Support.
Upload the new Mend 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:
CODEdocker stop <wss-bb-app> <wss-scanner> <remediate-server>
Remove the Docker containers from the previous version:
CODEdocker 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.
Triggering a New Scan in Bitbucket
A scan is initiated via a valid 'push' command. A 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 an extension supported by Mend and/or one of the commits in the 'push' command included a removal of file(s) that have an extension supported by mend. Refer to the Mend 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 as specified here.
Each time a valid 'push' command is made for a repository, Mend initiates a scan.
NOTE: The 'push' command may include multiple commits.
Handling Private Registries and Authenticated Repositories
Private registries hosted on any platform that can be accessed with credentials are supported (Nexus, GitHub, Artifactory, Azure Artifacts, GitLab, NPM)
Supported languages and package managers:
NPM
Yarn
Maven
Gradle
Pip
Pipenv
Go
Nuget
Ruby
SBT
In order to scan dependencies from private registries and authenticated repositories, Mend 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 Bitbucket group or repository and use of it will be restricted to those within the app.
Use GPG to generate a PGP Key. Use the command
gpg --full-generate-key
and follow the prompts to generate a key. 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. Name and email are not important.Copy the key ID from the output or run
gpg --list-secret-keys
if you forgot to take a copy. This is your public key.Run
gpg --armor --export-secret-keys YOUR_NEW_KEY_ID > ws-private-key.asc
to generate an armored (text-based) private key fileRun
gpg --armor --export YOUR_NEW_KEY_ID > ws-public-key.asc
to generate an armored (text-based) public key file
Provide the private key to the Controller, Remediate, and Scanner with environmental variable (learn more about environmental variables in the Advanced Technical Information documentation). There are two options for how to do it, but only one option should be used.
WS_HOST_RULES_PRIVATE_KEY
- the value of the private key itself.Please note, that the private key should be formatted to work properly:
Remove the beginning and end comments (as well as any extra lines).
At the end of the key, there will be a buffer that looks like
==<some_text>
. This needs to be removed.Remove all of the new lines in the key so it is all in one line (i.e. delete all
\n
characters).
WS_HOST_RULES_PRIVATE_KEY_FILE_PATH
- path to the file containing the private key. This file should be mapped to the running containers.
Open wss-encryption/secret-encryption.html in your favorite editor.
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`;
Generate a secret. There are the following fields on the encryption page:
Organization\Group - required, your Bitbucket group to which tokens secret be scoped.
Repository - optional, your Bitbucket repository to which secret should be scoped.
Raw value - required, confidential values/secrets such as tokens or passwords.
Encrypted value - the result of the encryption to be used in the integration.
After the secret is created, please add it to the hostRules parameter of the .whitesource file.
Example of hostRules:
{
"hostRules": [
{
"matchHost": "registry.npmjs.org",
"hostType": "npm",
"userName": "bot1",
"encrypted": {
"token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
}
},
{
"matchHost": "https://custom.registry.company.com/maven/",
"hostType": "maven",
"userName": "bot1",
"encrypted": {
"password": "p278djfdsi9832jnfdshufwji2r389fdskj........."
}
}
]
}
Additional notes
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.
We use asymmetric public-key cryptography of the PGP methodology. Organization/Group, Repository, Raw Value - all information you provide on the encryption page is secured with this approach.
Notes for NPM private registries:
To connect to private registries the https://docs.npmjs.com/cli/v8/configuring-npm/npmrc file of the scanned project is used. It is either edited (
hostRules
from the config are applied) or created for scanning purposes.If .npmrc is missing and only one host is used in the project it should be connected to the official http://npmjs.com . Otherwise, only private dependencies will be scanned and all public dependencies of this registry will be omitted.
If several hosts are used in the project it is required that .npmrc file exists in the project and contains information about these hosts.
Notes for Yarn private registries:
For Yarn 1 projects, to connect to private registries the .npmrc file of the scanned project is used. For Yarn 2/3 .yarnrc is used. It is either edited (
hostRules
from the config are applied) or created for scanning purposes.If .yarnrc is missing (or
npmRegistryServer
in it is not set) and only one host is used in the project - it will be set to thehostRules.matchHost
from the config. In the same case, if several hosts are used,npmRegistryServer
will be set to https://registry.yarnpkg.com.
Notes for Maven private registries:
To connect to private registries the settings.xml file of the scanned project is used. It is either edited (
hostRules
from the config are applied) or created for scanning purposes.
Notes for Gradle private registries:
To connect to private registries the build.gradle or settings.gradle file of the scanned project is used. For both of these files, we also support the kotlin (.kts) format.
The buildscript or pluginManagement blocks need to be at the beginning of the
build.gradle
orsettings.gradle
respectively.matchHost
should contain the full path to the private registries, not just the domain.
Notes for Nuget private registries:
To connect to private registries the NuGet.Config file of the scanned project is used. It is either edited (
hostRules
from the config are applied) or created for scanning purposes.
Notes for Pip private registries:
Certain special characters are not valid in the credential part of a URL. If the user or password part of the login credentials contains any of these special characters then they must be percent-encoded.
Notes for Pipenv private registries:
Use either envVariablesMapping or sourceName when setting host rules.
Notes for Go private registries:
To connect to private registries the .netrc file of the scanned project is used. It is either edited (
hostRules
from the config are applied) or created for scanning purposes.Only HTTPS is available for
matchHost
, HTTP is not supported.If the private registry is hosted on GitHub, only
token
can be used in theencrypted
(i.e.,password
is not supported).
Automate Secret Encryption for Private Registries
You can encrypt secrets from the CLI, using the curl
, echo
, jq
, gpg
, grep
and tr
CLI programs.
Here is an example:
curl https://app.renovatebot.com/renovate.pgp --output renovate.pgp
echo -n '{"o":"your-organization", "r":"your-repository (optional)", "v":"your-secret-value"}' | jq . -c | gpg --encrypt -a --recipient-file renovate.pgp | grep -v '^----' | tr -d '\n'
The above script uses:
curl
to download the Mend Renovate hosted app's public keyecho
to echo a JSON object intojq
jq
to validate the JSON and then compact itgpg
to encrypt the contentsgrep
andtr
to extract the encrypted payload which we will use
The jq
step is optional, you can leave it out if you wish. Its primary value is validating that the string you echo to gpg
is valid JSON and compact.
Note: Encrypted secrets must have at least an org/group scope, and optionally a repository scope. This means that Renovate will check if a secret's scope matches the current repository before applying it, and warn/discard if there is a mismatch.
Encrypted secrets usually have a single organization. But you may encrypt a secret with more than one organization, for example, org1,org2
. This way the secret can be used in both the org1
and org2
organizations.
For more information on how to use secrets for private packages, refer to the Private package support documentation.
Uninstalling
You can easily uninstall this add-on by doing the following:
Go to the 'Administration’ page of your Bitbucket Data Center interface, and click on ‘Manage apps’ of the Add Ons section.
Select the Mend Integration app, and click on the ‘Uninstall’ button.