...

Introduction

The Mend for GitHub Enterprise is a GitHub Enterprise app, scanning your repositories, as part of your Mend account. It is an integrated product within GitHub Enterprise that shows a high-level security overview in the GitHub Enterprise repository, detects all open source components and displays all vulnerabilities for these components.

It provides you with information on vulnerable and outdated open source components and generates comprehensive up-to-date reports on the GitHub Enterprise Issues tab of the scanned repository. In addition, you will be able to view the scanned repositories in the Mend portal.

Mend for GitHub Enterprise is part of Mend Developer Integrations and includes automated fix Pull Requests as well as Automated Dependency Updates (as part of Mend Renovate) with Mend Remediate.

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

• The deployment includes two environments:

  • Build environment where the image is built.

  • Deployment environment where the image is deployed.

Build Environment

The Build Environment has the following requirements:

Hardware Requirements

• CPU: Dual Core, 2Ghz or higher (Intel or AMD)

• RAM: 16GB

• Storage: 16 GB

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-github-enterprise-19.4.2.tar.gz  or agent-4-github-enterprise-19.4.2.zip).

  • You can obtain these files from Mend Support. 

Target Environment

The relevant Mend Docker images are installed on the target environment. This environment requires the following:

Hardware Requirements

• CPU: Dual Core, 2Ghz or higher (Intel or AMD)

• RAM: 16GB

• Storage: 16 GB

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 GitHub Enterprise Server.

• Access to the Mend Application is required at times for operation of the Mend for GitHub Enterprise.

• 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-github-enterprise-<version>.tar.gz’) for Linux or 'zip' file Windows (‘agent-4-github-enterprise-<version>.zip’)

Installation and Configuration

In Windows, extract 'agent-4-github-enterprise-<version>.zip’ to an empty directory. In Linux, extract ‘agent-4-github-enterprise<version>.tar.gz’ to an empty directory.  
The extraction creates the following folders:

• wss-configuration: UI Configuration tool and related configuration file template

• wss-deployment: Deployment template (for example, deploying the integration using Helm charts)

• wss-ghe-app: Mend GitHub Enterprise server application

• wss-remediate: Mend Remediate worker

• wss-scanner: Mend GitHub Enterprise repository scanner

• build.sh/build.bat (Linux/Windows): The build script that will build the relevant Docker images.

Modifying the Scanner Dockerfile 

See here for more information on which package managers are part of the scanner image as well as how to add additional package managers.

Build and Tag the Docker Images

There are three different ways of building the Docker images.

1. Using an Executable Script File

The suggested way to build all the Docker images is by running the build.bat or build.sh executable script file (Windows/Linux).
Both files are located in the root of the extracted agent-4-github-enterprise-<version>.zip or agent-4-github-enterprise-<version>.tar.gz files.

Windows

1. Run build.bat file which is located in the main folder where you extracted the agent-4-github-enterprise zip file.

2. In order to ensure that the build succeeded, run docker images command and check if wss-ghe-app and wss-scanner and wss-remediate images were created.

Linux

1. Run the build.sh file, located in the main folder where you extracted the agent-4-github-enterprise tar.gz file.

2. In order to ensure that the build succeeded, run the docker images command and check if wss-ghe-app and wss-scanner and wss-remediate images were created.

2. Manually Build the Images

In case you want to run the steps of the build file manually, you can run the following commands directly:

IMPORTANT: If you have already run the build file, please skip these steps and continue to Target machine: Run the Images.

docker build -t wss-ghe-app:<version> wss-ghe-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-ghe-app:19.5.2 wss-ghe-app/docker
docker build -t wss-scanner:19.5.2 wss-scanner/docker
docker build -t wss-remediate:19.5.2 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-scanner:<version>
docker push <registry>/wss-scanner:<version>
docker push <registry>/wss-remediate:<version>

# For example:
docker push my-registry/wss-scanner:19.5.2
docker push my-registry/wss-scanner:19.5.2
docker push my-registry/wss-remediate:19.5.2

After executing the commands, you should be able to view the images in your registry.

Create a Mend GitHub App

1. Go to your GitHub enterprise instance, select Settings > Organization, and then select GitHub Apps from the Developer settings

2. Click the New GitHub app button.

3. Enter your GitHub Enterprise password.

4. The Register new GitHub App page is displayed. 

5. Fill in the fields according to these guidelines:

   1. GitHub App name: “Mend App”. NOTE: The name cannot contain an underscore (“__”).

   2. Description: Mend for GitHub Enterprise

   3. Homepage URL: “https://www.whitesourcesoftware.com”

   4. User authorization callback URL: empty

   5. Setup URL (optional): empty

   6. Webhook URL: A valid URL pattern. This is a temporary value that is changed at a later stage of the installation process.

   7. Webhook secret: Generate and enter a secret value (string) and make sure you copy this value somewhere. You will need it for later. 

   8. Permissions:
             NOTE: Permission fields that are not specified below should be left as is ("No access")

      1. Repository administration: Read-only

      2. Checks: Read & write

      3. Repository contents: Read & write

      4. Deployments: Read-only

      5. Issues: Read & write

      6. Repository metadata: Read-only

      7. Pages: Read & write

      8. Pull requests: Read & write

      9. Repository webhooks: Read-only

      10. Repository projects: Read & write

      11. Security vulnerability alerts: Read-only

      12. Commit statuses: Read & write

      13. Organization members: Read-only

      14. Organization projects: Read & write

      15. Organization hooks: Read-only

   9. Subscribe to events: Select the following events:
      i. Check run
      ii. Check suite
      iii. Issues
      iv. Member
      v. Membership
      vi. Organization
      vii. Pull request
      viii. Push
      ix. Team
      x. Team add

   10. Where can this GitHub App be installed? It is recommended to select 'Any account', so that any GitHub Organization can install this App. Alternatively, you can limit it to your own organization.

6. Click the Create GitHub App button. 

7. (Optional) Edit the GitHub App and upload a logo for your App. 

Fill in fields in Mend 'Integrate' Page

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

1. Navigate to the Integrate page of the Mend application. Expand the Mend for GitHub Enterprise bar to view the following fields:
   

   1. GitHub URL: Your GitHub Enterprise instance Destination URL. For example: https://GitHubEnterprisedev.com.

   2. GitHub API URL: The GitHub URL value plus '/api/v3' - <GitHub URL>/api/v3

   3. GitHub application id: From the GitHub Enterprise server UI, go to Settings > Organization Settings > GitHub Apps. Click Edit next to the Github app you created previously. Scroll to the About section. Copy the GitHub ID value and paste it as the GitHub application id input field value.
      Leave this page open in Edit mode, as you will need it for the next field (Github webhook secret).

   4. Github webhook secret: Paste the webhook secret that you generated as part of the Install the GitHub Application step.

   5. GitHub application private key: In the Private key section, click Generate private key. Save the private_key.pem file that is generated. Open this file in any editor and copy its contents. Paste the contents in the GitHub application private key input field. NOTE: The key is encrypted and its value is not revealed to Mend.

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

3. Copy the generated Activation Key to the clipboard. You will need to use it in the next section.

Configuring Deployment Settings

Run the UI configuration tool from the wss-configuration Directory

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

1. Open the file 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 button 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 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.

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

...

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 Port

...

proxy.port

...

Integer

...

no

...

HTTP proxy port. Leave blank to disable. Default value: Empty

...

Proxy

...

Proxy User

...

proxy.user

...

String

...

no

...

Proxy Username (if applicable)

...

user

...

Proxy

...

Proxy Password

...

proxy.password

...

String

...

no

...

Proxy Password (if applicable)

...

abc123

...

Advanced

...

Controller URL

...

controller.url

...

String

...

no

...

The ability to modify the App container URL in case its default name (wss-ghe-app) was modified. Default value: http://wss-ghe-app:5678

...

http://wss-ghe-app:5678

...

Issues

...

Should Create Issues

...

bolt4scm.create.issues

...

Boolean

...

no

...

The ability to globally enable/disable Issues creation across all of your organization's repositories. Default value: true 
(NOTE: Supported from version 20.5.1.3 only)

...

Issues

...

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

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-ghe-app' app container:

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

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

Run the ‘wss-scanner’ scanner container:

docker run --name wss-scanner-ghe --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-ghe --restart=always --network my_bridge -p 9393:9393 -v c:/tmp/ghe/:/etc/usr/local/whitesource/conf/ wss-scanner:19.5.2

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/whitesource/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/ghe/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:19.5.2

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.

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-ghe-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

Provide GitHub App Webhook URL

At this stage you should replace the temporary webhook URL with the permanent webhook URL. 

1. Edit the App settings.

   1. Enter the webhook URL in the following format:
      http://<docker-wss-ghe-app-destinationURL>:5678/payload.

   2. Click on the 'Save Changes' button.

Select Accounts and Repositories

1. Copy and navigate to the "public link" of the created app and click the Configure button.

2. Select Accounts to scan.

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

4. Select repositories to scan in each selected account. Select one of the following options:

   1. All Repositories (Default): An option to scan all the repositories of the account.

   2. Selected repositories only: Select specific repositories that you would like to scan.

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

The .whitesource File

A Mend configuration file (.whitesource) is a JSON file added to each repository that is enabled for a scan. 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).

.whitesource file

{
  "scanSettings": {
    "configMode": "AUTO",
	"configExternalURL": "" 
    "projectToken": "",
	"baseBranches": []
  },
  "checkRunSettings": {
    "displayMode": "diff",
    "vulnerableCheckRunConclusionLevel": "failure"
  },
  "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 GitHub user name, repository name and branch (optional) of the repo-config.json file location. The default branch is 'master', but can be modified according to the location of the repo-config.json file in the whitesource-config repo. 

NOTE: You can override specific parameters that are relevant only in the specific repository by adding these after this parameter. Parameters with type of array do not override the value from global configuration, but only add new values.

Examples:

Using only values defined in the global configuration:

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

Using values defined in the global configuration and overriding the scan settings parameters:

"settingsInheritedFrom": "whitesource-config/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 in the scanned branch of the current repository. The configuration file should be in the same format as the Unified Agent configuration file. NOTE: Not supported in the Global Configuration.

• EXTERNAL - External mode. This will look for a configuration file specified according to the configExternalURL parameter. 

...

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://'.

...

No

...

Empty

...

projectToken

...

String

Adds the ability to map a GitHub repository to a Mend project. The parameter used needs to be the Mend project token.

...

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:

• The license check is dependent on the vulnerabilities check and will not be triggered if vulnerableCheckRunConclusionLevel is set to none.

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

NOTES:

• When enabled, after every valid push, a branch (ws-iac-scan-results/{whitesource_scan_token}) is temporarily created and deleted after the scan has completed.

...

No

...

false

Check Run Settings (checkRunSettings)

...

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

...

vulnerableCheckRunConclusionLevel

...

String

The app utilizes the GitHub Checks API that 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 success, 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 failure (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, and a branch protection rule has been added, 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. 

When the parameter is set to none Mend Security Check will not be initiated at all.

See also Initiating a Merge Policy.

...

No

...

failure

...

licenseCheckRunConclusionLevel

...

String

...

The app utilizes the GitHub Checks API that 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. 

NOTE: The license check is dependent on the vulnerabilities check and will not be triggered if vulnerableCheckRunConclusionLevel is set to none.

When the parameter is set to 'success', 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 'failure' (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, and a branch protection rule has been added, 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.

See also Initiating a Merge Policy.

...

No

...

failure

...

iacCheckRunConclusionLevel

...

String

...

Customizable commit status settings:

• failure - If the Mend scan detects IaC misconfigurations in a repository, the commit status will show a "failure" indicating that misconfigurations were detected.
  If no misconfigurations were detected, the commit status shows a "success" indicator.

• success - The commit status will show a success indicator at the end of the scan regardless of whether the scan detected misconfigurations in the repository.

...

No

...

failure

...

showWsInfo

...

Boolean

...

Whether to show additional Mend information such as the project token inside the Mend Check Run (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 Check Run when this parameter is enabled:

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

NOTE: Additional Mend data may be added inside the JSON object in the future.

...

No

...

false

...

useMendCheckNames

...

Boolean

...

If set to true names of all Checks (Security, License, SAST, 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

Issue Settings (issueSettings)

...

Parameter 

...

Type

...

Description

...

Required 

...

Default

...

minSeverityLevel

...

String

...

Enables users to decide whether to open a new GitHub Issue only if a certain severity level is available on a detected vulnerability.

Available values for minSeverityLevel:

• NONE - No GitHub Issues will be generated.

• LOW - Any Low/Medium/High vulnerabilities found will generate a GitHub Issue.

• MEDIUM - Any Medium/High vulnerabilities found will generate a GitHub Issue.

• HIGH - Any High vulnerabilities found will generate a GitHub Issue.

NOTE: The Mend Security Check summary is also affected by this parameter.

...

No

...

LOW

...

displayLicenseViolations

...

Boolean

...

Whether to generate an Issue for every detected license policy violation.

NOTE: This parameter is relevant only if enableLicenseViolations (scanSettings) is set to true.

...

No

...

true

(only if 
enableLicenseViolations 
(scanSettings) is set to true)

...

issueType

...

string

...

Defines the type of issues that will be created in the repository; VULNERABILITY (one for each vulnerability) or DEPENDENCY (one for each direct dependency).

...

No

...

DEPENDENCY

...

customLabels

...

Array

...

Setting that will define labels that will be added to the issues created after the scan.

Usage example:

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

Following labels are not available for the use:

• security vulnerability

• license policy violation

• IaC violation

• configuration error

• maintenance notice

...

No

...

Empty

...

assignees

...

Array

...

Setting that will define users that will be assigned to the issues created after the scan.

Usage example:

{
  "issueSettings": {
    "assignees": ["user1", "user2"]
  }
}

Note: Only users that are Collaborators with access to the repository and push permission can be added

...

No

...

Empty

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 configuration options for all configuration options.

Refer here for parameter usage.

...

No

...

false

...

transitiveRemediation

...

Boolean

...

...

No

...

false

...

workflowRules

...

Object

This parameter is used to specify the rules that regulate when to open remediation pull requests.

Usage examples:

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

...

Yes

...

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

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

...

0

...

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

...

10

Private Registry Settings (hostRules)

...

Parameter 

...

Type

...

Description

...

Required 

...

Default

...

matchHost

...

String

...

Defines where the credentials will be applied during the scan.

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

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.

Finally, 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, gradle, pypi, go , nuget, ruby.

Required if matchHost is used.

...

No

...

Empty

...

username

...

String

...

Used when credentials consist of username and password.

...

No

...

Empty

...

password

...

String

...

Used when credentials consist of username and password, should be encrypted by this instruction.

Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:

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

...

No

...

Empty

...

token

...

String

...

Used when credentials consist of username and password, should be encrypted by this instruction.

Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:

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

...

No

...

Empty

Providing a Global .whitesource Configuration File

NOTE: Supported from version 20.5.1.3 only

You can provide a custom .whitesource configuration file as part of the wss-ghe-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-ghe-app container.

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

3. Start the wss-ghe-app container.

Configuration Error Issues

Alert the user on configuration errors that affects their scan by creating a configuration error issue and check run. In case of such an error the following will occur:

1. Stop the workflow. Do not create a scan or the Mend Security check run.

2. Create a “Configuration Failed” check run.

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

Initiating a Scan

A Mend scan is initiated via a valid GitHub 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.

• You can manually trigger a scan for several repositories at once. Refer the Global Repo Configuration document.

Inventory post-scan

WhiteSource continuously researches new vulnerabilities and updates its vulnerability database with these findings. In order that these newly-discovered vulnerabilities be reflected in projects a soon as possible, Mend initiates a post-scan process for all integrated projects at 01:00 UTC and opens new issues for vulnerabilities that were added to the database in the previous 24 hours.

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 Issues tab within the GitHub project.

• The Mend Security/License/IaC Check within the GitHub project's Commits tab.

• The Mend UI.

• Via email notifications.

Viewing the Issues Tab

If you are performing Pull Requests or push commands via the Web browser, refresh your Web browser in order to view the issues that were generated by Mend. NOTE: It may take a number of minutes for the issues to be scanned and displayed after a valid push command is initiated.

The Issues tab displays all the issues that the Mend Integration detected with the red security vulnerability label. This proprietary label indicates a security vulnerability was detected by Mend. 

As part of your workflow, you have the option to add a relevant label(s) to specific issues, and close issues that were resolved.

Issues that were manually closed will not be re-opened during future Mend scans unless their label and/or name have been manually changed or changed via the GitHub API.

Viewing Details of an Issue

See here for more information.

Viewing Mend Security Checks

Status Check indicators are displayed for each head commit on the Commits sub-tab of the Code tab. Clicking a specific indicator opens a pop-up window that displays further details on the status:

Clicking the Details link in the popup window displays the Mend Security Check page for the selected head commit. The page includes the conclusion status of the head commit along with a Security Report.

The security report displays all the vulnerabilities that were found in descending order according to the severity and CVSS score. The following information is displayed for each vulnerability:

...

CVE: A link to the related CVE page for the vulnerability. Displayed in a collapsible format (click the arrow to expand/collapse for more information regarding the vulnerability).

...

Severity: Overall score of the severity (High, Medium or Low).

...

Vulnerable Library

...

Suggested Fix 

...

Issue - A link to the relevant issue generated by Mend (when available)

Types of Indicators

The following Checks API status indicators are available as a feedback on the head commits:

• Queued: Scan has not begun and is scheduled to begin.

  • In progress: Scan is in progress.

  • Completed: Scan completed with one of the following conclusions:

    • Success: When the parameter 'vulnerable.check.run.conclusion.level' is set to 'success', the status of the head commit is always success  A 'Success' status is displayed for the commit even when it fails.

    • Failure: Default for all completed scans. When the parameter 'vulnerable.check.run.conclusion.level' is set to 'failure' (default), the status of a 'failed' head commit is 'failure', and a policy for approving merging pull requests that include failed head commits with the another branch in the repository is enforced. Note that a 'failed' status can be caused due to security vulnerabilities or due to an error that occurred during the scan.

    • Neutral: Conclusion occurs when the push command was not valid.

Samples of Check Status Indicators 

Queued

The following is a sample of a 'Queued' status, which indicates that the security check is about to start scanning the head commit's vulnerabilities.

...

In Progress

The following is a sample of an 'In-Progress' status, which indicates that the security check is currently scanning the head commit.

...

Completed with Success Conclusion

This status can be displayed in two scenarios:

...

Completed with Failure Conclusion

...

The following screenshot is a sample of the display in a pull request page when a 'failure' policy is enforced and one or more of its head commits have a 'failure' status. Only the administrator of the repository can approve the merging of a pull request with a 'failure' status:

...

Completed with Neutral Conclusion

A neutral conclusion occurs in the following scenario:

...

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

Supported Configuration Files

Terraform, CloudFormation, Kubernetes, ARM Templates, Serverless, and Helm

Viewing Mend IaC Checks

In the Code > commits page you can view the status and results of each scan. Click a specific check icon in order to view the Mend check.

Types of Indicators

The following commit 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

• In the Mend UI, Mend projects will have the same name as the corresponding GitHub repository, with a "GH_" 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 GitHub organization preceded by a "GH_" prefix if the GitHub repository is under a GitHub organization. Otherwise, the name will be your GitHub username preceded by "GH_".

Email Notifications

After a Mend scan is performed, a separate email message is sent for each generated Issue, with information on the vulnerability or license policy violation that was detected.

NOTE: The information in the email message is identical to the displayed information on the Issues tab.

Accessing Scan Statistics via API

See here for more information.

Health Check APIs

See here for more information.

Initiating a Merge Policy

Overview

A merge policy utilizes the app's integration with GitHub Checks API. It enables the repository's administrator to approve the merging of a pull request with 'Failed' commit statuses to a target branch in the repository. 
For more information on Checks API, see the related GitHub Checks API introduction page.

NOTE: This integration supports merge policies for PRs created either from a branch in the same repository or originating from a different repository.

Adding a Branch Protection Rule 

In order to enable a merge policy based on the conclusion of a Mend Security Check, you must initially add the following GitHub rule for branch protection:

1. Go to the repository 'Settings' → 'Branches'.

2. Click on the 'Add Rule' button.

3. Apply the rule to a specific branch or enter '*' to apply the rule to all branches:

4. Select the following checkboxes:

   1. 'Require status checks to pass before merging'.

   2. If you cannot view this setting, then modify the '.whitesource' file, and perform a commit. Wait for the scan to complete and then refresh the GitHub settings page until you can view this setting.

Upgrading to the Latest Docker Images

1. Get the latest Mend for GitHub Enterprise version from Mend Support.

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

   • wss-ghe-app

   • wss-scanner

   • remediate-server

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

   Code Block
   docker stop <wss-ghe-app> <wss-scanner> <remediate-server>

4. Remove the Docker containers from the previous version:

   Code Block
   docker rm <wss-ghe-app> <wss-scanner> <remediate-server>

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

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

7. Run the containers - see here.

8. (Optional) If the new wss-ghe-app container has a different URL than the previous container, then follow the guidelines here to update the GitHub App webhook URL.

NOTE: From version 20.4.2. the remediate-db image and container are not required anymore. If you are upgrading from a previous version, you can stop the container and remove the image as part of step 3.

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 GitHub organization 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 GitHub organization to which tokens secret be scoped.

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

Uninstalling

You can easily uninstall this app by doing the following:

...

Go to the 'Applications' section of your GitHub's account settings, and click on the 'Configure' button next to the 'Mend App' application.

...

The 'Mend Bolt for GitHub' page opens. Scroll down in order to view the 'Uninstall Mend App' button. 

...

Click on the 'Uninstall' button. Uninstalling Mend App removes it from all your repositories.

...

This page is available at https://docs.mend.io/bundle/integrations/page/mend_for_github_enterprise.html