Prerequisites and Prep for Installation
Overview
This article provides details and instructions for prerequisites required on both the Mend Platform and within your GitHub Enterprise environment, hardware requirements for both your build and deployment environments, and optional configurations to support specific Python versions and to set up a dedicated SAST scanner.
Getting It Done
Prerequisites
The following requirements must be accommodated before installing the Mend server software.
Access to an active Mend Platform organization and be a user with organization administrator permissions.
The Issues tab must be enabled for each repository. Do as follows for each repository requiring a scan:
Go to the relevant GitHub repository, and click Settings.
Verify that the Issues checkbox is enabled.
Check that the Issues tab appears next to the Code tab.
You must have administrator permissions to your GitHub account and to the relevant repositories (owner credentials) in order to install the Mend for GitHub Enterprise app.
The deployment includes two environments:
A build environment where the images are built.
A deployment environment where the images are 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
The Build Environment has the following requirements:
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-github-enterprise-19.4.2.tar.gz or agent-4-github-enterprise-19.4.2.zip).
You can download the latest version with this link.
Target Environment
The relevant Mend Docker images are installed on the target environment. This environment requires the following:
Hardware Requirements
CPU: The CPU requirements vary based on the product(s) you plan to use:
Mend SCA: A minimum of Dual Core, 2GHz or higher (Intel or AMD).
Mend SAST (or combined with SCA): A minimum of 4 cores is required.
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 GitHub Enterprise Server.
Access to the Mend Application is required at times for the operation of Mend for GitHub Enterprise.
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>/healthCheckStatus
(e.g. https://saas.whitesourcesoftware.com/healthCheckStatus)
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-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.
Dedicated SAST Configuration
A dedicated SAST scanner container will allow the controller container to assign SAST and SCA scans to designated scanners. The following environment variable must be set in both the wss-ghe-app and the wss-scanner containers, WS_SAST_SCAN_PREFIX = SAST_. This environment variable can be set on the host machine during the docker run command, but it is best practice to set these within the Dockerfiles.
Modifying the Controller Dockerfile
The wss-ghe-app image Dockerfile is located in the wss-ghe-app\docker folder.
To set up a dedicated SAST scanner, the environment variable, WS_SAST_SCAN_PREFIX = SAST_, should be added after the base image is set, FROM ${BASE_IMAGE} as base.
# This default may be swapped for any compatible base image
ARG BASE_IMAGE=amd64/ubuntu:20.04@sha256:3246518d9735254519e1b2ff35f95686e4a5011c90c85344c1f38df7bae9dd37
# Containerbase is used for tool installation and user/directory setup
FROM ghcr.io/containerbase/base:9.19.3@sha256:6878fdecd861d6410dc02f400289fb874b7371fb7fbad2014868d2fd6089abf1 AS containerbase
FROM ${BASE_IMAGE} as base
# Set to enable support for a dedicated SAST Scanner Container
ENV WS_SAST_SCAN_PREFIX = SAST_
Modifying the Scanner Dockerfile
The wss-scanner image Dockerfile is located in the wss-scanner\docker\ folder.
Note: We recommend copying the wss-scanner directory and adding sast to the directory name, e.g. “wss-scanner-sast” before making any changes. This will allow you to keep the original image for SCA.
To set up a dedicated SAST scanner, the environment variable, WS_SAST_SCAN_PREFIX = SAST_, should be added after the base image is set, FROM ${BASE_IMAGE} as base.
# This default may be swapped for any compatible base image
ARG BASE_IMAGE=amd64/ubuntu:20.04@sha256:b795f8e0caaaacad9859a9a38fe1c78154f8301fdaf0872eaf1520d66d9c0b98
# This buildpack is used for tool installation and user/directory setup
FROM ghcr.io/containerbase/base:9.19.3@sha256:6878fdecd861d6410dc02f400289fb874b7371fb7fbad2014868d2fd6089abf1 AS containerbase
FROM ${BASE_IMAGE} as base
# Set to set up a dedicated SAST Scanner Container
ENV WS_SAST_SCAN_PREFIX = SAST_
Package Manager Configuration
Some package managers are installed by default and the others will need to be manually uncommented in the Dockerfile in order to use them.
We also offer the Dockerfilefull that is located in the wss-scanner\docker\ folder. When using the wss-scanner image’s Dockerfilefull, all of the supported package managers are uncommented and installed by default.
See here for more information on which package managers are part of the scanner image as well as how to add additional package managers.
Python Support
If you want to specify the Python version for your repository, you can choose one of the following versions included in your scanner Dockerfile: 2.7.18, 3.6.15, 3.7.12
, 3.8.12, 3.9.9
, or 3.11.
For this you will need to perform the following procedure:
Ensure the relevant Python version is uncommented in your scanner container’s Dockerfile.
Add or edit the .whitesource configuration file in your repository.
Use the
configMode
parameter and set it to eitherLOCAL
orEXTERNAL
.Create a whitesource.config file and add the following:
CODEpython.invokePipAsModule=true python.path=python3.9 python.installVirtualenv=true
Note:
For
python.path
, use one of the following values:2.7
,3.6
,3.7
,3.8
,3.9,
or3.11
.Alternatively, you can apply this globally across your repositories by using the Global Repo Configuration repo-config.json file.
Next Steps after fulfilling prerequisites and completing optional configurations
After you have fulfilled the prerequisites and completed any optional configuration changes, you are ready to Create the Mend for GitHub Enterprise App in your GitHub Enterprise environment.