Overview

Before beginning the installation process, ensure that the guidelines described in Installation Prerequisites have been fulfilled.

NOTE: Follow all procedures in order as they are presented here.

Installing the GitLab Integration

Configure a System Hook

1. Go to your GitLab instance and click Admin Area > System Hooks.

2. Fill in the fields according to these guidelines:

   • URL: The Mend webhook handler URL. The URL should end with '/payload'. Enter the webhook URL in the following format: http://<docker-wss-gls-app-destinationURL>:5678/payload.

   • Secret Token: Secret token for payload validation

   • Trigger: All checkboxes except Tag push events must be marked

   • Enable SSL Verification: Yes

3. Click Add system hook. Your system hook will appear in the System Hooks section at the bottom of the screen.

Creating a New GitLab User and a Personal Access Token

1. Create a new and regular GitLab user and name it @whitesource. This user does not need to be an admin.
   NOTE: This user does not require a real email address. The Personal Access Token for the next step can be created by an admin impersonating the @whitesource user.

2. Create a Personal Access Token for your new @whitesource user. Go to the @whitesource Settings > Access Tokens, and fill in the fields according to these guidelines:

   • Name: The name of your token, e.g. "MendToken"

   • Expires at (optional): The expiration date for your token

   • Scopes: All checkboxes should be marked.

3. Click Create personal access token. Copy the generated Personal Access Token to the clipboard, to be used in the next section.

Creating an Activation Key

1. Open a separate browser tab or window and log in to Mend.

2. Navigate to the Integrate page of the Mend application. Expand the Mend for GitLab Server bar to view the following fields:

   • GitLab Server API URL: Your GitLab Server instance's API URL. For example: https://GitLabDevServer.com/api/v4

   • GitLab Webhook URL: The URL of the Mend webhook handler (the same URL as the system hook from Configure a System Hook).
     The webhook URL is used to create webhooks from GitLab projects the integration is installed for, to allow Mend Remediate to receive issue related events.
     NOTE: If this webhook URL is on a local server, make sure your GitLab server is configured to allow outbound requests to local servers in Admin Area > Settings > Network > Outbound Requests. Here you can allow outbound requests to your entire local network or simply whitelist the Mend webhook URL.

   • GitLab Webhook Secret: The webhook secret you entered when creating the system hook in Configure a System Hook.

   • GitLab Personal Access Token: The @whitesource user's personal access token created in the previous step.

3. Click Get Activation Key to generate your activation key. A new Service user is created for this integration inside the Mend Application with a WS prefix.  NOTE: Do not remove this Service user and ensure this user remains part of the Admin group. 

4. Copy the newly generated Activation Key (You will need it in the next procedure).

5. If you want Mend Remediate to only open automatic fix MRs in specific scenarios, clicking Manage Workflow Rules will allow you to configure custom rules for when Remediate opens MRs.

Running the UI Configuration Tool

The UI Configuration tool enables you to configure the deployment file according to your specific configuration requirements. 

1. Open index.html located inside the wss-configuration directory via a Chrome or Firefox Web browser. The Mend Configuration Editor page is displayed.

2. Load the template JSON configuration file by clicking Choose File and selecting the file located at wss-configuration/config/prop.json. The General tab appears in the Editor.

3. Click the General tab and enter the Activation Key which you copied in the previous section.

4. To manage the creation of GitLab Issues or Commit Statuses globally across all of your organization's repositories, click the Issues tab. (The parameters in this tab are displayed in the table below.)

5. To display the Proxy tab, click the Advanced Properties checkbox on the Home tab. Proxy fields that are not mandatory (e.g., user name and password) must be left blank. (The parameters in this tab are displayed in the table below.)

6. Click Export, and save the JSON file with the name prop.json. This file will be used in the next sections.

Details on Attributes of the Configuration File

Uploading Mend Scan Results to the GitLab Security Dashboard (For GitLab Ultimate Users Only)

In order to upload the Mend scan results to the GitLab security dashboard, add the following YAML to your .gitlab-ci.yml file:

1. whitesource-security-publisher:
     image: openjdk:8-jdk
     when: manual
     script: 
       - curl "{{WEBHOOK_URL}}/securityReport?repoId=$CI_PROJECT_ID&repoName=$CI_PROJECT_NAME&ownerName=$CI_PROJECT_NAMESPACE&branchName=$CI_COMMIT_REF_NAME&defaultBranchName=$CI_DEFAULT_BRANCH&commitId=$CI_COMMIT_SHA" -o gl-dependency-scanning-report-ws.json
     artifacts: 
       paths:
         - gl-dependency-scanning-report-ws.json
       reports:  
         dependency_scanning:
           - gl-dependency-scanning-report-ws.json
       expire_in: 30 days

2. Replace {{WEBHOOK_URL}} with the GitLab Webhook URL from Creating an Activation Key (remove the “payload” part from the URL).
   NOTE: The CI job’s name must be whitesource-security-publisher in order for Mend to recognize and trigger it.

Running the Containers

Deploying Using Docker

Create a network bridge (this will create a private network between the different containers since all containers need to run within the same network):

docker network create -d bridge my_bridge

Run the wss-gls-app app container:

docker run --name wss-gls-app --network my_bridge -p 9494:9494 -p 5678:5678 -v <path/to/config/directory>:/etc/usr/local/whitesource/conf wss-gls-app:<version>

# For example:
docker run --name wss-gls-app --network my_bridge -p 9494:9494 -p 5678:5678 -v c:/tmp/gls/:/etc/usr/local/whitesource/conf/ wss-gls-app:19.9.1.1

Run the wss-scanner scanner container:

docker run --name wss-scanner-gls --restart=always --network my_bridge -p 9393:9393 -v <path/to/config/directory>:/etc/usr/local/whitesource/conf/ wss-scanner:<version>

# For example:
docker run --name wss-scanner-gls --restart=always --network my_bridge -p 9393:9393 -v c:/tmp/gls/:/etc/usr/local/whitesource/conf/ wss-scanner:19.9.1.1

Run the wss-remediate server container:

docker run --name remediate-server --restart=always --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v <path/to/config/directory>/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:<version>

# For example:
docker run --name remediate-server --restart=always --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v c:/tmp/gls/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:19.8.1


# NOTE: If port 8080 isn't available, you can use a different port by modifying the first port entry in the 'docker run' command. For example:
# docker run --name remediate-server --network my_bridge -e LOG_LEVEL=debug -p 8082:8080 -v c:/tmp/gls/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:19.8.1

Deploying Using Helm Charts

The wss-deployment folder consists of the following structure:

• helm

  • configs

  • templates

    • config.yaml

    • wssScmIntegration.yaml

  • Chart.yaml

  • values.yaml

Chart.yaml

This file contains information about the chart.

NOTE: Do not edit this file.

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-gls-app image.

An optional parameter, imagePullSecrets, can be added to this file in case Docker repository authentication is required.

configs/prop.json

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.

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

Selecting Repositories to Scan

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

2. Add the @whitesource user (the user you created during Creating a New GitLab User and a Personal Access Token) as a member with Maintainer permissions to the repositories you want Mend to scan. This is how Mend will determine which repositories will be scanned.

   If you would like Mend for GitLab to scan an entire GitLab group, add the @whitesource user to the group to enable Mend for GitLab for all of the projects within that group.
   NOTE: Adding the @whitesource user to a repository with any permissions less than Maintainer may create side-effects in the integration's functionality.

3. Unless specified otherwise via the global configuration, an onboarding merge request is created for each repository to which the @whitesource user was added. This request contains a Mend configuration file (.whitesource) that can be customized before merging the 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.

4. In order to disable scanning for a repository, remove the @whitesource user from the repository members.

Accessing Scan Statistics via API

See here for more information.

Health Check APIs

See here for more information.

The .whitesource File

A Mend configuration file (.whitesource) is a JSON file added to each repository enabled for scanning. It provides configurable parameters for the Mend scan. The .whitesource file is only added in the default branch of the repository (unless modified, it is the master branch).

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

Parameters

Global Settings

"settingsInheritedFrom": "whitesource-config/whitesource-config@master"

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

Scan Settings (scanSettings)

Commit Status Settings (commitStatusSettings)

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

Issue Settings (issueSettings)

{
  "issueSettings": {
    "customLabels": ["label1","label2"]
  }
}

Remediate Settings (remediateSettings)

   "remediateSettings": {
    "workflowRules": {
      "enabled": true,
      "minVulnerabilitySeverity": "LOW"
    }
  }
   "remediateSettings": {
    "workflowRules": {
      "enabled": true,
        "minVulnerabilityScore": 1.5,
        "maxVulnerabilityScore": 10
    }
  }

    "workflowRules": {       
      "enabled": true    
    }

Private Registry Settings (hostRules)

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

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

Providing a Global Configuration File

NOTE: Supported from version 20.5.1.3 only.

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

To apply this global change, do as follows:

1. Stop the wss-gls-app container.

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

3. Start the wss-gls-app container.

Configuration Error Issues

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

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

2. Create a “Configuration Failed” commit status.

3. For each config file that failed parsing - create a new type of issue, titled 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

Handling Private Registries and Authenticated Repositories

Supported languages and package managers:

• NPM

• Yarn

• Maven

• Gradle

• PIP

• Go

• Nuget

• Ruby

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

   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 index-enterprise.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 Gitlab group to which tokens secret be scoped.

   2. Repository - optional, your Gitlab 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.

Example of hostRules:

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

NOTE:

• Copy the entire output of the key generator including comments to paste into the string.

  i.e. include "-----BEGIN PGP PUBLIC KEY BLOCK-----..."

• The string uses javascript backticks and not quotes. This is to allow a multi-line string so that you do not have to replace any line breaks with new-line characters. Be aware of any auto indenting by your editor that may introduce spaces to the public key and cause encryption to fail.

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