Configure Mend for GitHub Enterprise for SCA

configMode

String

Optional. Default Value: AUTO. 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 to be provided in the root folder of the current repository. The configuration file should be in the same format as the Unified Agent configuration file.

• EXTERNAL - External mode. This will look for a configuration file specified according to the configExternalURL parameter. The configuration file should be in the same format as the Unified Agent configuration file.

Note:

whitesource.config can be provided both in global config and in the repo itself. If it is provided in both places and there are parameters that are set on both levels - repo level will take precedence.

baseBranches

Array

Optional. Default Value: Your GitHub.com "default" branch. Adds the ability to specify one or more base branches for which scanning results will be sent to a new Mend project.

Example usage: 

"baseBranches": ["master", “integration"]

This will set both master and integration branches as base branches.

Notes:

• An Issue will only be created for the specified branch names.

• For each specified branch, a Mend project will be created in the Mend SCA application. The name of the project will contain a suffix "_branchname". For example, MyApp_dev. This suffix will not apply to the default branch.

• This value can be set on global and local level, the inheritance rules are as with the config file above.

cloneSubmodules

Boolean

Optional. Default Value: false. If set to true, git submodules that are used in the repository will be scanned as part of the repository where this parameter is enabled. If set to false all submodules that might be used in the repository will be ignored.

Note: Only enable this parameter if all of the submodules used in the repository are either public repositories or private repositories that are onboarded to Mend. Otherwise, the scan will fail.

configExternalURL

String

Required only if configMode is set to EXTERNAL. Default Value: N/A. 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'

Note: If you need to whitelist the IP address of the Mend server triggering the external configuration file, contact Mend support.

enableLicenseViolations

Boolean

Optional. Default Value: false. When set to true, a new Mend License Check will be generated for each valid push. You must have at least one policy of match type By License Group defined with a Reject action in the Mend SCA UI.

Notes:

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

• The policy name in the Mend SCA UI must start with a "[License]" prefix.
  For example, "[License] PolicyName".

javaVersion

String

Optional. Default Value: 17. Defines the version of Java used when scanning an integrated repository.

Available values: 8, 11, 17

Note:

• Starting from v23.8.2, Java 17 is the default version used for scans. Prior to v23.8.2, Java 11 was the default.

• For any projects that are using Gradle versions prior to v7.3, we recommend setting your Java version used by the integration to one of the lower supported versions, 8 or 11, via the javaVersion parameter.

projectToken

String

Optional. Default Value: N/A. Adds the ability to map a GitHub repository to an existing Mend project. The value used needs to be the Mend project token.

Note: Not supported in the repo-config.json file for Global Configuration.

releaseBranches

Array

Optional. Default Value: N/A. Upon receiving a valid push to branches matching the releaseBranches value(s), the repository integration will trigger a scan on these branches, creating a check run with the scan results. A project within the Mend UI will also be created for each unique release branch, based on the branch's name.

Example:

"releaseBranches": ["release", "release\\/.*"]

Notes:

• An automatic scan of newly created release branches will be performed.

• Regular expression (regex) patterns (Java-compatible) are supported.

• Release branches do not generate issues or remediation pull requests, as they do not serve as base branches for generating commit "diffs."

• If a branch is included in both baseBranches and releaseBranches, the baseBranches parameter and its functionalities take precedence.

repoNameSync

Boolean

Optional. Default Value: false. When set to true and a GitHub repository name was changed before the scan, products that reflect a new repo name and projects for each base branch will be renamed in the Mend UI.

skipScanningStage

Object

Optional. Default Value: none. Controls what stages of scanning process will be skiped for specific package manager.

The available parameters are:

• connectivity - Verifying authentication using the host rules info - private registry URL and credentials.

• config - Set environment variables and prepare global/local configuration files for the scan.

• preStep - Run package manager commands in order to have the dependencies and lock files ready for the scan.

The available parameter values are: maven, npm, nuget-csproj, nuget-packages, pip, yarn.

Usage example:

{
  "scanSettings": {
    "skipScanningStage": {
      "connectivity": ["maven", "npm"],
      "config": ["yarn"],
      "preStep": ["maven"]
    }
  }
}

exploitability

Boolean

Optional. Default Value: false. When set to true, if a vulnerability has data about exploitability it will be displayed under issues and security checks.

Additional information about exploitability is available in the designated Public Exploits page.

releaseProjectsRegex

String

Note: To enable this feature, you need to enable the “Release” event type for the GitHub Enterprise App:

Optional. Default Value: null. Specifies the regex rule that will create dedicated Mend projects for the releases when they are created.

When it contains a value, whenever an onboarded GitHub repository publishes a new release that satisfies the regex from the parameter, a scan will be automatically triggered for the associated commit, and a project will be created in the Mend Application.

This parameter works with the releaseProjectsSuffix parameter which specifies the <fixed suffix keyword> of the created Mend project that will contain the scan results for the release.

In order to prevent the proliferation of projects in the Mend Application, for each repo release, a single Mend project per repo will be used to keep only the latest release scanned. The project will be named as follows: GH_<repo name>_<fixed suffix keyword>

• The <fixed suffix keyword> would be a unique word that is configurable.

• If there is a project for a branch that has an equal name, that project will be used to reflect the scan results.

• Each time a new release is published for a given repo, the scan results will be pushed to the Mend project described above, effectively overwriting the scan results from the prior release.

• For each release that is scanned, the corresponding Mend project will be filled with two additional tags as follows:

  • 1) releaseTitle -> The title that was given to the release in GHE

  • 2) releaseTag -> The tag name that was associated with the release

• Any subsequent release that will update GH_<repo name>_<fixed suffix keyword> project will override the releaseTitle and releaseTag Mend tags.

releaseProjectsSuffix

String

Optional. Default Value: RELEASE. This parameter defines the <fixed suffix keyword> appended to the Mend project name created as a result of a releaseProjectsRegex match.

This parameter is only effective when used in conjunction with releaseProjectsRegex

uaConfigMergeSetting

String

Optional. Default Value: OVERRIDE. Possible values: APPEND, OVERRIDE.
Controls whether the following global and local config settings are overridden or appended: includes, excludes, archiveIncludes, and archiveExcludes.

Note: All other UA settings are always overridden on a local level.

displayMode

String

Optional. Default Value: diff. How to display Mend security information for a scan performed on a non-base branch. The available parameter values are:

• diff - Only the diff of detected vulnerabilities between the current commit and its base branch commit will be displayed.

• baseline - A summary of all detected vulnerabilities in the full repository inventory will be displayed.

Note: diff is only supported when using the baseBranches configuration.

vulnerableCheckRunConclusionLevel

String

Optional. Default Value: failure. Defines the conclusion status for when a Mend Security Check is completed. The available parameter values are:

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

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

• none - The Mend Security Check will not be initiated, but a scan will occur and the project will be updated in the Mend User Interface.

Note: If using a global configuration, see also global-config.json General Parameters.

licenseCheckRunConclusionLevel

String

Optional. Default Value: failure. Defines the conclusion status for when a Mend License Check is completed. The available parameter values are:

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

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

Note:

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

• If using a global configuration, see also global-config.json General Parameters.

showWsInfo

Boolean

Optional. Default Value: false. 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 set to true:

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

useMendCheckNames

Boolean

Optional. Default Value: false. The available parameter values are:

• true - Names of all Checks (Security, License) will be named after Mend. For example: Mend Security Check.

• false - Names of all Checks (Security, License) will be named after WhiteSource. For example: WhiteSource Security Check.

Note: When a .whitesource file is created, the value of useMendCheckNames is true.

strictMode

String

Optional. Default Value: none. Controls the messaging and status of security and license checks in the case of partial scan results (i.e. Mend Scanner experienced issues pulling some of the project’s dependencies during the scan). The available parameter values are:

• none - When a scan concludes with partial results:

  • No message is shown in the check description.

  • The check status is not affected.

• warning - When a scan concludes with partial results:

  • A message alerting to the partial results is included in the check description. When possible, the message will also include detailed information and error logs on the cause of the partial results.

  • Partial result details include warning and error messages in the check run.

  • Check run does not fail based on warning or error messages.

  • A project tag "scanError" is not populated with package managers' names.

    • If there was a tag previously → it is removed with the next scan job

• failure - When a scan concludes with partial results:

  • A message alerting to the partial results is included in the check description. When possible, the message will also include detailed information and error logs on the cause of the partial results.

  • Partial result details include warning and error messages in the check run.

  • Check run fails only on error messages, not on warnings.

  • A project tag "scanError" includes only error-level package managers.

• failOnWarning - When a scan concludes with partial results:

  • Partial result details include warning and error messages in the check run.

  • Check run fails on both warning and error messages.

  • A project tag "scanError" lists package managers with warnings or errors.

Note: For strictMode to work, the vulnerableCheckRunConclusionLevel and licenseCheckRunConclusionLevel parameters must be set to failure or not used.

strictModeInfo

Boolean

Optional. Default Value: false. Controls the inclusion of INFO logs in the Scan Details report.

• When set to true, this allows info-level messages in all strict modes except none.

strictModeCustomMessage

String

Optional. Default Value: none. A string provided under this parameter will be included to the partial scan message when it occurs.

Usage example:

{
  "checkrunSettings": {
    "strictMode": "warning"
    "strictModeCustomMessage": "In order to debug this error you can go to <a href="https://site.com">documentation<a/>."
  }
}

Note:

• In order for this message to be shown the strictMode must be set to either warning or failure

• The message can contain HTML objects like <a> links.

checkRunSettings.failOnLicenseViolation

Boolean

Optional. Default Value: false. Determines whether a Mend Check Run in release branches should be marked as failed when a license violation is detected. The available parameter values are:

• false - In this mode, the presence of license violations will not block the overall progress of the scan, and the checkrun should pass in any case.

• true - In case a release branch is scanned, the checkrun should fail if a license violation has been found.

checkRunSettings.showWsInfo

Boolean

Optional. Default Value: false. Whether to show additional Mend information such as the project token inside the Mend Check Run in release branches (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 set to true:

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

checkRunSettings.strictMode

String

Optional. Default Value: none. Controls the messaging and status of security and license checks in release branches in the case of partial scan results (i.e. Mend Scanner experienced issues pulling some of the project’s dependencies during the scan). The available parameter values are:

• none - When a scan concludes with partial results:

  • No message is shown in the check description.

  • The check status is not affected.

• warning - When a scan concludes with partial results:

  • A message alerting to the partial results is included in the check description. When possible, the message will also include detailed information and error logs on the cause of the partial results.

  • The check status is not affected.

• failure - When a scan concludes with partial results:

  • A message alerting to the partial results is included in the check description. When possible, the message will also include detailed information and error logs on the cause of the partial results.

  • The check status is affected and is set to "Failed".

Note: For strictMode to work, the vulnerableCheckRunConclusionLevel and licenseCheckRunConclusionLevel parameters must be set to failure or not used.

minSeverityLevel

String

Optional. Default Value: LOW. Define GitHub Issue creation on a certain severity level for a detected vulnerability. The available parameter values are:

• NONE - No GitHub Issues will be created.

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

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

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

• CRITICAL- Any Critical vulnerabilities found will create GitHub Issue.

Note:

• minSeverityLevel specifies the scope of vulnerabilities for both Issues and Security Checks.

• If minSeverityLevel is used together with minVulnerabilityScore or maxVulnerabilityScore, then the minSeverityLevel value will be ignored.

minVulnerabilityScore

String

Optional. Default Value: 0. Define GitHub Issue creation based on a specified minimum vulnerability CVSS score. The available parameter values are floats with one decimal from 0 to 10. For more information on CVSS 3 Scores, click here.

Note:

• minVulnerabilityScore specifies scope of vulnerabilities both for Issues and Security Checks.

• If minVulnerabilityScore is used together with minSeverityLevel, then the minSeverityLevel value will be ignored.

maxVulnerabilityScore

String

Optional. Default Value: 10. Define GitHub Issue creation based on a specified maximum vulnerability CVSS score. The available parameter values are floats with one decimal from 0 to 10. For more information on CVSS 3 Scores, click here.

Note:

• maxVulnerabilityScore specifies scope of vulnerabilities both for Issues and Security Checks.

• If maxVulnerabilityScore is used together with minSeverityLevel, then the minSeverityLevel value will be ignored.

displayLicenseViolations

Boolean

Optional. Default Value: true. Create GitHub Issues on every detected license policy violation.

Note: displayLicenseViolations is relevant only if enableLicenseViolations (scanSettings) is set to true.

issueType

String

Optional. Default Value: VULNERABILITY. Define the type of GitHub Issues that will be created in the repository. The available parameter values are:

• VULNERABILITY - Create a GitHub Issue for each vulnerability.

• DEPENDENCY - Create a GitHub Issue for each direct dependency.

customLabels

Array

Optional. Default Value: N/A. Define labels that will be added to the GitHub Issues created after the scan.

Usage example:

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

Following labels are not available for the use:

• Mend: dependency security vulnerability

• Mend: license policy violation

• Mend: IaC violation

• Mend: configuration error

• Mend: code security findings

assignees

Array

Optional. Default Value: N/A. Define users that will be assigned to the GitHub 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.

enableRenovate

Boolean

Optional. Default Value false. The available parameter values are:

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

• false - Renovate functionality will not be enabled.

workflowRules

Object

Required. Default Value:

    "workflowRules": {       
      "enabled": true    
    }

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

Usage example:

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

workflowRules.enabled

Boolean

Required. Default Value: true. When set to true, enables Workflow Rules being set from a .whitesource file.

Note: Workflow rules can also be set in the Mend SCA application in the Admin → Integration Workflow Rules. But if this parameter is set to true, then Workflow Rules from the Mend SCA application are not being used.

workflowRules.minVulnerabilitySeverity

String

Optional. Default Value: LOW. The minimal vulnerability severity level to automatically create remediation pull requests for. Allowed values - "LOW", "MEDIUM", "HIGH".

For example, if you set to "MEDIUM" then remediation pull requests of vulnerabilities with low severity will not be created - only for those with medium and high severity.

If CVSSv3 is enabled in the global-config.json file, the value "CRITICAL" can also be used.

Note: If this parameter is used together with minVulnerabilityScore and maxVulnerabilityScore, then only minVulnerabilitySeverity will have affect.

workflowRules.minVulnerabilityScore

Float

Optional. Default Value: 0. 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.

workflowRules.maxVulnerabilityScore

Float

Optional. Default Value: 10. 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.