Understand Mend for GitHub.com

Overview

Before diving into each scan type of Mend for GitHub.com, it is important to understand the fundamentals of the integration.

This article provides general knowledge on the building blocks of Mend for GitHub.com as well as other GitHub.com settings and actions that apply to the integration.

Reference

Onboarding Pull Request

Once you have installed the Mend for GitHub.com app, you will see a GitHub Pull Request (PR) appear in your integrated repositories. This is also referred to as the Mend for GitHub.com “onboarding PR.”:

The “onboarding PR” will contain the .whitesource file, which handles the configuration of your Mend for GitHub.com scan. You can edit the .whitesource file before merging the onboarding PR to ensure that your first scan is configured appropriately for your repository:

This will then initiate the installation and start the first scan on your selected repositories. You can define settings (like selected branches) later on in the .whitesource file.

The .whitesource file

The .whitesource file is the Mend configuration file that is added to each repository that is enabled for a scan and provides configurable parameter(s) for the Mend scan. Each scan type (i.e. SCA, SAST, IaC) has its own set of parameters.

The .whitesource file is only added in the default branch of the repository. Any configuration change that is done to this file must be in the default branch of the repository.

Below is just one example of how you can set up a .whitesource file:

Note: A .whitesource file placed outside the default branch will be ignored.

CODE

{
  "scanSettings": {
    "configMode": "AUTO",
	"configExternalURL": "",
	"projectToken": "",
	"baseBranches": []
  },
  "checkRunSettings": {
    "displayMode": "diff",
    "vulnerableCheckRunConclusionLevel": "failure"
  },
  "issueSettings": {
    "minSeverityLevel": "LOW"
  }
}

Examples: Newly created .whitesource or repo-config.json files

The examples below are for Mend AppSec Platform organizations. An example for Legacy SCA organizations is available as a collapsible code snippet at the bottom of this section.

Below are examples of newly created .whitesource or repo-config.json files.
The PR creation will only include (in the initial configuration) the sections that are relevant to the organization’s entitlement (SCA/SAST/both).
The scans of a certain type will be enabled by default if the organization has this entitlement (e.g. enableScan set to ‘true’ for SAST if the organization has a SAST entitlement), to minimize manual work.

Mend Platform organization with SCA-only entitlement

CODE

{
  "scanSettings": {
    "configMode": "AUTO",
    "configExternalURL": "",
    "projectToken": "",
    "baseBranches": []
  },
  "checkRunSettings": {
    "vulnerableCheckRunConclusionLevel": "failure",
    "displayMode": "diff",
    "useMendCheckNames": true
  },
  "issueSettings": {
    "minSeverityLevel": "LOW",
    "issueType": "DEPENDENCY"
  },
  "remediateSettings": {
    "workflowRules": {
      "enabled": true
    }
  },
   "imageSettings":{
       "imageTracing":{
           "enableImageTracingPR": false,
           "addRepositoryCoordinate": false,
           "addDockerfilePath": false,
           "addMendIdentifier": false
       }
   }
}

Mend Platform organization with SAST-only entitlement

CODE

{
  "scanSettingsSAST": {
    "enableScan": true,
    "scanPullRequests": true,
    "incrementalScan": true,
    "baseBranches": [],
    "snippetSize": 10
  },
  "checkRunSettingsSAST": {
    "checkRunConclusionLevel": "failure",
    "severityThreshold": "high"
  },
  "issueSettingsSAST": { 
    "minSeverityLevel": "high", 
    "issueType": "repo" 
  },
  "checkRunSettings": {
    "useMendCheckNames": true
  },
   "imageSettings":{
       "imageTracing":{
           "enableImageTracingPR": false,
           "addRepositoryCoordinate": false,
           "addDockerfilePath": false,
           "addMendIdentifier": false
       }
   }
}

Mend Platform organization with SAST and SCA entitlements

CODE

{
  "scanSettings": {
    "configMode": "AUTO",
    "configExternalURL": "",
    "projectToken": "",
    "baseBranches": []
  },
  "scanSettingsSAST": {
    "enableScan": true,
    "scanPullRequests": true,
    "incrementalScan": true,
    "baseBranches": [],
    "snippetSize": 10
  },
  "checkRunSettings": {
    "vulnerableCheckRunConclusionLevel": "failure",
    "displayMode": "diff",
    "useMendCheckNames": true
  },
  "checkRunSettingsSAST": {
    "checkRunConclusionLevel": "failure",
    "severityThreshold": "high"
  },
  "issueSettings": {
    "minSeverityLevel": "LOW",
    "issueType": "DEPENDENCY"
  },
  "issueSettingsSAST": { 
    "minSeverityLevel": "high", 
    "issueType": "repo" 
  },
  "remediateSettings": {
    "workflowRules": {
      "enabled": true
    }
  },
   "imageSettings":{
       "imageTracing":{
           "enableImageTracingPR": false,
           "addRepositoryCoordinate": false,
           "addDockerfilePath": false,
           "addMendIdentifier": false
       }
   }
}

Example: A newly created .whitesource or repo-config.json file in a Legacy SCA organization:

CODE

{
  "scanSettings": {
    "configMode": "AUTO",
    "configExternalURL": "",
    "projectToken": "",
    "baseBranches": []
  },
  "scanSettingsSAST": {
    "enableScan": false,
    "scanPullRequests": false,
    "incrementalScan": true,
    "baseBranches": [],
    "snippetSize": 10
  },
  "checkRunSettings": {
    "vulnerableCheckRunConclusionLevel": "failure",
    "displayMode": "diff",
    "useMendCheckNames": true
  },
  "checkRunSettingsSAST": {
    "checkRunConclusionLevel": "failure",
    "severityThreshold": "high"
  },
  "issueSettings": {
    "minSeverityLevel": "LOW",
    "issueType": "DEPENDENCY"
  },
  "issueSettingsSAST": {
    "minSeverityLevel": "high",
    "issueType": "repo"
  },
  "remediateSettings": {
    "workflowRules": {
      "enabled": true
    }
  },
   "imageSettings":{
       "imageTracing":{
           "enableImageTracingPR": false,
           "addRepositoryCoordinate": false,
           "addDockerfilePath": false,
           "addMendIdentifier": false
       }
   }
}

Mend for GitHub.com - Initiate a merge policy

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: Mend for GitHub.com integration supports merge policies for PRs created either from a branch in the same repository or originating from a different repository.

Create a branch protection rule in GitHub.com using Mend checks

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:

Go to the repository Settings > Branches.
Click Add Rule.
Apply the rule to a specific branch or enter '*' to apply the rule to all branches.
Select the Require status checks to pass before merging the checkbox.
Select from the following values:
1. ‘Mend Security Check’ for SCA, open source management
2. ‘Mend Code Security Check’ for SAST, code weakness management
3. ‘Mend IaC’ for Infrastructure as Code scanning
4. ‘Mend License Check’ for SCA License Compliance

Note: If no Mend checks are visible, modify the '.whitesource' file and perform a commit. Wait for the scan to complete and then refresh the GitHub settings page to see Mend checkruns in the list.

Mend for GitHub.com Scan Types

For more information on specific scan scenarios (i.e. SCA, SAST, or IaC), visit the respective sections below: