...
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:
...
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.
Info |
---|
A total of three images will be built: wss-ghe-app, wss-scanner, and wss-remediate. |
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
Run build.bat file which is located in the main folder where you extracted the agent-4-github-enterprise zip file.
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
Run the build.sh file, located in the main folder where you extracted the agent-4-github-enterprise tar.gz file.
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.
...
After executing the commands, you should be able to view the images in your registry.
Create a Mend GitHub App
Go to your GitHub enterprise instance, select Settings > Organization, and then select GitHub Apps from the Developer settings
Click the New GitHub app button.
Enter your GitHub Enterprise password.
The Register new GitHub App page is displayed.
Fill in the fields according to these guidelines:
GitHub App name: “Mend App”. NOTE: The name cannot contain an underscore (“__”).
Description: Mend for GitHub Enterprise
Homepage URL: “https://www.whitesourcesoftware.com”
User authorization callback URL: empty
Setup URL (optional): empty
Webhook URL: A valid URL pattern. This is a temporary value that is changed at a later stage of the installation process.
Webhook secret: Generate and enter a secret value (string) and make sure you copy this value somewhere. You will need it for later.
Permissions:
NOTE: Permission fields that are not specified below should be left as is ("No access")Repository administration: Read-only
Checks: Read & write
Repository contents: Read & write
Deployments: Read-only
Issues: Read & write
Repository metadata: Read-only
Pages: Read & write
Pull requests: Read & write
Repository webhooks: Read-only
Repository projects: Read & write
Security vulnerability alerts: Read-only
Commit statuses: Read & write
Organization members: Read-only
Organization projects: Read & write
Organization hooks: Read-only
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 addWhere 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.
Click the Create GitHub App button.
(Optional) Edit the GitHub App and upload a logo for your App.
...
Navigate to the Integrate page of the Mend application. Expand the Mend for GitHub Enterprise bar to view the following fields:
GitHub URL: Your GitHub Enterprise instance Destination URL. For example: https://GitHubEnterprisedev.com.
GitHub API URL: The GitHub URL value plus '/api/v3' - <GitHub URL>/api/v3
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).Github webhook secret: Paste the webhook secret that you generated as part of the Install the GitHub Application step.
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.
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.Copy the generated Activation Key to the clipboard. You will need to use it in the next section.
...
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.
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.
Click the General tab and enter the Activation Key which you copied in the previous section.
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.
Click Export, and save the JSON file with the name prop.json. This file will be used in the next sections.
...
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 | |
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 |
Target Machine: Run the Containers
...
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.
...
Code Block |
---|
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.
...
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:
Code Block |
---|
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 |
...
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
configMode | String | The configuration mode to be used for each scan. There are three options:
| 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' | 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. NOTE: Not supported in the Global Configuration. | No | Empty |
baseBranches | Array | Adds the ability to specify one or more base branches for which scanning results will be sent to a new Mend project. Example usage: ["master", “integration"] This will set both master and integration branches as base branches. Note the following:
NOTE: This parameter is available only from version 20.7.1. | No | Empty In this case, the base branch only consists of the default branch. |
enableLicenseViolations | Boolean | When enabled, a new Mend License Check will be generated for each valid push. NOTES:
| No | false |
enableIaC | Boolean | When enabled, a new Mend IaC Check will be generated for each valid push. This will scan cloud infrastructure configurations to find misconfigurations before they are deployed, and alert on these via the creation of issues. NOTES:
| No | false |
...
Parameter | Type | Description | Required | Default | ||
---|---|---|---|---|---|---|
displayMode | String | How to display Mend security information for a scan performed on a non-base branch:
| 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 When the parameter is set to When the parameter is set to 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:
| 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. The following hidden JSON object will also be added inside the Check Run when this parameter is enabled:
NOTE: Additional Mend data may be added inside the JSON object in the future. | No | false | ||
useMendCheckNames | Boolean | If set to Note: When .whitesource is created the value of useMendCheckNames is | 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:
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 | ||
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:
Following labels are not available for the use:
| No | Empty | ||
assignees | Array | Setting that will define users that will be assigned to the issues created after the scan. Usage example:
Note: Only users that are Collaborators with access to the repository and push permission can be added | No | Empty |
...
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:
| Yes |
| ||||
workflowRules.enabled | Boolean | Enables Workflow Rules being set from a .whitesource file. Note: workflow rules can also be set in the Mend application in the Admin → Integration Workflow Rules. But if this parameter is set to | Yes | true | ||||
workflowRules.minVulnerabilitySeverity | String | The minimal vulnerability severity level to automatically create remediation pull requests for. Allowed values - E.g. if set to Note: if this parameter is used together with minVulnerabilityScore and maxVulnerabilityScore than only minVulnerabilitySeverity will have affect. | No | LOW | ||||
workflowRules.minVulnerabilityScore | Float | The minimal vulnerability CVSS 3 score to automatically create remediation pull requests for. Allowed values - floats with one decimal from 0 to 10. For more information on CVSS 3 Scores, click here. Note: if this parameter is used together with minVulnerabilitySeverity it will not have any effect. | No | 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 |
...
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:
Stop the wss-ghe-app container.
In the wss-ghe-app/conf folder, add your custom .whitesource file (where the prop.json file is located).
Start the wss-ghe-app container.
...
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.
...
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).
CVSSScore
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:
...
Success: No license policy violations were detected.
Failed: One or more license policy violations were detected during the Mend scan.
Supported Configuration Files
...
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
...
Get the latest Mend for GitHub Enterprise version from Mend Support.
Build these three Docker images from the new version - see here.
wss-ghe-app
wss-scanner
remediate-server
Stop currently-running Docker containers from the previous version:
Code Block docker stop <wss-ghe-app> <wss-scanner> <remediate-server>
Remove the Docker containers from the previous version:
Code Block docker rm <wss-ghe-app> <wss-scanner> <remediate-server>
Fetch the activation key from the existing prop.json file (the propertyValue associated to the property "bolt.op.activation.key") and copy it to the clipboard.
Generate and save the new prop.json file by following the steps here and using the activation key value that was just copied.
Run the containers - see here.
(Optional) If the new wss-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.
...