Mend for Bitbucket Data Center

Note: This integration is not hosted by Mend.io, it’s self-hosted. New major versions are traditionally released once a month.
For release notes, visit Mend for Bitbucket Data Center Release Notes.

Supported Bitbucket Products

• This documentation covers our 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.io 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

Note: Setting up global configuration is highly recommended for centralized mass deployments.

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).

• A Bitbucket version between 5.15.X and 9.X 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).

    • For users of Bitbucket Data Center Version 9.X:

      • Download the latest version with this link (supports Bitbucket Data Center V9.X).

    • For users of earlier Bitbucket Data Center Versions:

      • Note that Mend.io does not intend to release new versions supporting Bitbucket Data Center versions lower than 9.

      • Mend for Bitbucket Data Center 25.1.1.3 is the latest version supporting Bitbucket Data Center versions lower than 9.

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: 3.6.15, 2.7.18, 3.11.7, 3.12.3, 3.10.14, 3.7.17, 3.8.12, 3.9.18.
For this you will need to perform the following procedure:

1. Ensure the relevant Python version is uncommented in your scanner container’s Dockerfile.

2. Add or edit the .whitesource configuration file in your repository.

3. Use the configMode parameter and set it to either LOCAL or EXTERNAL.

4. Create a whitesource.config file and add the following:

   CODE

   python.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, or 3.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.

1. In the search field, enter mend and press Enter. The WhiteSource (Mend) App is displayed.

2. 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.

1. Click Upload app and select the JAR file located in the wss-bb-add-on folder.

2. 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

Note: This step contains mild deviations between the Mend AppSec Platform and the Legacy SCA Application. The Legacy SCA instructions are available at the bottom of this section.

1. 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”.

2. Log in to your Bitbucket Data Center with this Service user.

3. Login to the Mend Application.

4. 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 Webhook URL:  Enter the webhook URL in the following format: http://<docker-wss-bb-app-destinationURL>:5678/payload.

• Bitbucket Access Token:
  For Bitbucket Data Center 9.X: Enter your Bitbucket service user’s password.
  For Bitbucket Data Center versions before 9.X: 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).

• When clicking on ‘Submit’, 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 Data Center and Data Center SCA scans:

• build.gradle

• build.gradle.kts

• gradle.lockfile

• gradle.properties

• libs.gradle

• 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

• packages.lock.json

• 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. 

1. 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:
   
   

   

   
   
   

2. 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.

1. 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.
   
   

   

   
   
   

2. 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

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.

1. Go to the Bitbucket Data Center UI > Administration page > Mend Integration tab (Link:<your/bitbucket-server/url>:<port>/plugins/servlet/mend/configure).

2. Copy the activation key and paste it into the Activation key field, and then click Validate.

3. If you are integrating multiple repositories and want to apply global configurations, refer here before continuing in this procedure.

4. 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.

5. The project admin must do the following:

   1. Go to the project page of any integrated project (see above).

   2. Go to the Project settings page.

   3. In the navigation pane, under Security, click Project Permissions.

   4. Select the option to give the Service User Admin priveleges.

6. The project admin must also do the following:

   1. Stay on the Project settings page.

   2. In the navigation pane, under Workflow, click Mend Integration.

   3. 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.

7. 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. "settingsInheritedFrom": "<Project Key>/<Repository Name>@<Branch>" 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 "settingsInheritedFrom": "WHIT/whitesource-config@master" Using values defined in the global configuration and overriding the scan settings parameters: CODE "settingsInheritedFrom": "WHIT/whitesource-config@master", "scanSettings": { "projectToken": "12345", "baseBranches": ["master","integration"] }	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: null ("overrideConfigAllowList": null) - All repositories that inherit configuration from this .whitesource file can override them locally. Empty array ("overrideConfigAllowList": []) - All repositories that inherit configuration from this .whitesource file cannot override them locally. Array with values ("overrideConfigAllowList": ["orgName1/repoName1", "orgName2/repoName2"]) - Only specified in the array repositories that inherit configuration from this .whitesource file can override them locally. 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: AUTO - Automatic mode. This will use the default Mend 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.   EXTERNAL - External mode. This will look for a configuration file specified according to the configExternalURL parameter.  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:  This parameter is relevant only if configMode was set to EXTERNAL. This value can be set on global and local level, the inheritance rules are as with the config file above.	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: An Issue will only be created for the specified branch names. For each specified branch, a Mend 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 Mend 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 Mend UI. The policy name in the Mend UI must start with a "[License] " prefix. For example, "[License] PolicyName".	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: When enabled, after every valid push, a branch (ws-iac-scan-results/{mend_scan_token}) is temporarily created and deleted after the scan has completed. When an IaC work item is closed it will not be detected in the future scans. IaC issues are meant to be opened for the default branch only and if they are opened for additional baseBranches then the branch name will not be shown.	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 javaVersion parameter.	No	For integration versions v23.8.2 and newer: 17 For integration versions older than v23.8.2: 11
cloneSubmodules	Boolean	If set to true git submodules that are used in the repository will be scanned as part of the repository where this parameter is enabled. If set to false all submodules that might be used in the repository will be ignored. 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 true and a Bitucket repository name was changed before the scan, projects for each base branch will be renamed in the Mend UI.	No	false
skipScanningStage	Object	Controls what stages of scanning process will be skiped for specific package manager. The available parameters are: connectivity - Verifying authentication using the host rules info - private registry URL and credentials. config - Set environment variables and prepare global/local configuration files for the scan. preStep - Run package manager commands in order to have the dependencies and lock files ready for the scan. The available parameter values are: maven, npm, nuget-csproj, nuget-packages, pip, yarn. Usage example: CODE { "scanSettings": { "skipScanningStage": { "connectivity": ["maven", "npm"], "config": ["yarn"], "preStep": ["maven"] } } }	No	none
exploitability	Boolean	When set to true, if a vulnerability has data about exploitability it will be displayed under issues and security checks. Additional information about exploitability is available in the designated Public Exploits page.	No	false
uaConfigMergeSetting	String	Possible values: APPEND, OVERRIDE. Controls whether the following global and local config settings are overridden or appended: includes, excludes, archiveIncludes, and archiveExcludes. Note: All other UA settings are always overridden on a local level.	No	OVERRIDE

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: 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.	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 false it will not be initiated. A scan will still occur and the project will be updated in the Mend User Interface.	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 false, the conclusion status of a WhiteSource IaC 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 IaC Check found IaC violations. When the parameter is set to true (default), the conclusion status of a WhiteSource IaC Check will be 'Failure' in cases where WhiteSource IaC Check found IaC 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. 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. If the commit exists in multiple branches, the Mend 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 Build Status when this parameter is enabled: CODE <!-- <INFO>{"projectToken":"8cd2d2a8651145c087609e0a43f783e95f7008cb908541498348fed529572e01"}</INFO> --> Note: Additional Mend data may be added inside the JSON object in the future.	No	false
useMendBuildNames	Boolean	If set to true names of all Checks (Security, License, IaC) will be named after Mend (e.g. “Mend Security Check”). If set to false all Checks will have word “WhiteSource” instead of “Mend”. Note: When .whitesource is created the value of useMendCheckNames is true.	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: none - When a scan concludes with partial results: No message is shown in the check description. The check status is not affected. warning - When a scan concludes with partial results: A message alerting to the partial results is included in the check description. When possible, the message will also include detailed information and error logs on the cause of the partial results. Partial result details include warning and error messages in the check run. Check run does not fail based on warning or error messages. A project tag "scanError" is not populated with package managers' names. If there was a tag previously → it is removed with the next scan job failure - When a scan concludes with partial results: A message alerting to the partial results is included in the check description. When possible, the message will also include detailed information and error logs on the cause of the partial results. Partial result details include warning and error messages in the check run. Check run fails only on error messages, not on warnings. A project tag "scanError" includes only error-level package managers. failOnWarning - When a scan concludes with partial results: Partial result details include warning and error messages in the check run. Check run fails on both warning and error messages. A project tag "scanError" lists package managers with warnings or errors. Note: For strictMode to work, the vulnerableCheckRunConclusionLevel and licenseCheckRunConclusionLevel parameters must be set to failure or not used.	No	none
strictModeInfo	Boolean	Controls the inclusion of INFO logs in the Scan Details report. When set to true, this allows info-level messages in all strict modes except none.	No	false

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: 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. CRITICAL - Any Critical vulnerabilities found will generate a GitHub Issue. Notes: This parameter specifies the scope of vulnerabilities for both Issues and Security Checks. If this parameter is used together with minVulnerabilityScore or maxVulnerabilityScore then it will be ignored.	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. Notes: This parameter specifies scope of vulnerabilities both for Issues and Security Checks. If this parameter is used together with minSeverityLevel then the latter will be ignored.	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: This parameter specifies scope of vulnerabilities both for Issues and Security Checks. If this parameter is used together with minSeverityLevel then the latter will be ignored.	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: true - If the IaC scan is enabled and IaC misconfigurations are detected, issues are created for these findings. false - If the IaC scan is enabled and IaC misconfigurations are detected, no issues are created for these findings. Note: This parameter is relevant only if the IaC scan is enabled by setting scanSettings.enableIaC to true.	No	When iacIssues is not included at all in the configuration (.whitesource/repo-config.json files), the default ofiacIssues is true. From v22.8.1, if you onboard a repository with new auto-generated .whitesource/repo-config.json files, iacIssues will be explicitly included and set to false by default.

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 "remediateSettings": { "workflowRules": { "enabled": true, "minVulnerabilitySeverity": "LOW" } } "remediateSettings": { "workflowRules": { "enabled": true, "minVulnerabilityScore": 1.5, "maxVulnerabilityScore": 10 } }	Yes	CODE "workflowRules": { "enabled": true }
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 true then Workflow Rules from the application are not being used.	Yes	true
workflowRules.minVulnerabilitySeverity	String	The minimal vulnerability severity level to automatically create remediation pull requests for. Allowed values - "LOW", "MEDIUM", "HIGH", and “CRITICAL". E.g. if set to "MEDIUM" then remediation pull requests of vulnerabilities with low severity will not be created - only for those with medium and high severity. 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. 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/. Requiered for Gradle 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. 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.	No	Empty
hostType	String	Type of private registry. Supported values: npm (for both NPM and Yarn projects), maven (for both Maven and Gradle projects), pypi (for Pip and Pipenv), go , nuget, ruby, sbt. Required if matchHost is used. Note: When using Renovate with a Ruby private registry, add a hostRules block with hostType=rubygems within the remediateSettings block.	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 matchHost parameter. Must be included inside the encrypted parameter: JSON "encrypted": { "password": "3f832f2983yf89hsd98ahadsjfasdfjaslf............" }	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 matchHost parameter. Must be included inside the encrypted parameter: JSON "encrypted": { "token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............" }	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). envVariablesMapping takes a value as an object with two literals: userName and password / token. For example, if you have: CODE [[source]] url = "https://${USER_PRIVATE_REPO}:{PASS_PRIVATE_REPO}:@pypi/PACKAGE_NAME/simple" verify_ssl = true name = "IndexName" or CODE { url 'https://private.jfrog.io/artifactory/dependencies' credentials { username System.getenv("USER_PRIVATE_REPO") ?: "${USER_PRIVATE_REPO}" password System.getenv("PASS_PRIVATE_REPO") ?: "${PASS_PRIVATE_REPO}" } } Then, set envVariablesMapping to: CODE "envVariablesMapping": {"userName": "USER_PRIVATE_REPO" ,"password":"PASS_PRIVATE_REPO"}	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 [packages] <package_name> = { version = "*", index = "IndexName" } Then set sourceName to CODE "sourceName": "IndexName"	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:

1. Stop the wss-bb-app container.

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

3. 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:

1. Stop the workflow. Do not create a scan or the Mend Security build status.

2. Create a “Configuration Failed” build status.

3. 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

1. Get the latest Mend for Bitbucket Data Center version from Mend Support.

2. Upload the new Mend Bitbucket add-on by following the guidelines here. 

3. Build these three Docker images from the new version - see here.

   • wss-bb-app

   • wss-scanner

   • remediate-server

4. Stop currently-running Docker containers from the previous version:

   CODE

   docker stop <wss-bb-app> <wss-scanner> <remediate-server>

5. Remove the Docker containers from the previous version:

   CODE

   docker rm <wss-bb-app> <wss-scanner> <remediate-server>

6. 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.

7. Generate and save the new prop.json file by following the steps here and using the activation key value that was just copied. 

8. Run the containers - see here.

9. (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.

1. 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.

   1. 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.

   2. Run gpg --armor --export-secret-keys YOUR_NEW_KEY_ID > ws-private-key.asc to generate an armored (text-based) private key file

   3. Run gpg --armor --export YOUR_NEW_KEY_ID > ws-public-key.asc to generate an armored (text-based) public key file

2. 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.

   1. WS_HOST_RULES_PRIVATE_KEY - the value of the private key itself.

      1. Please note, that the private key should be formatted to work properly:

         1. Remove the beginning and end comments (as well as any extra lines).

         2. At the end of the key, remove the buffer text. It is usually 5 characters long and looks like the example below:

            

         3. Remove all of the new lines in the key so it is all in one line (i.e. delete all \n characters).

   2. WS_HOST_RULES_PRIVATE_KEY_FILE_PATH - path to the file containing the private key. This file should be mapped to the running containers.

3. Open wss-encryption/secret-encryption.html in your favorite editor.

4. 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`;

5. Generate a secret. There are the following fields on the encryption page:

   1. Organization\Group - required, your Bitbucket group to which tokens secret be scoped.

   2. Repository - optional, your Bitbucket repository to which secret should be scoped.

   3. Raw value - required, confidential values/secrets such as tokens or passwords.

   4. Encrypted value - the result of the encryption to be used in the integration.

6. After the secret is created, please add it to the hostRules parameter of the .whitesource file.

index-enterprise.html

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 the hostRules.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 or settings.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 the encrypted (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 key

• echo to echo a JSON object into jq

• jq to validate the JSON and then compact it

• gpg to encrypt the contents

• grep and tr 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:

1. 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.