Configure Mend for Azure Repos for SCA

configMode

String

Optional. Default Value: AUTO. The configuration mode is 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.  NOTE: Not supported in the Global Configuration.

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

Note:

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

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’

Notes: 

• This parameter is relevant only if configMode was set to EXTERNAL.

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

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

projectToken

String

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

Note: Not supported in the Global Configuration.

baseBranches

Array

Optional. Default Value: Your Azure DevOps Repos "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: ["master", “integration"]

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

Notes:

• A Work item 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 the suffix "_branchname". For example, MyApp_dev. This suffix will not apply to the default branch.

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.

enableLicenseViolations

Boolean

Optional. Default Value: false. When set to true, 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 vulnerablePullRequestStatus is set to none.

• You must have at 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".

javaVersion

String

Optional. Default Value: 17. Defines version of Java in the Scanner.

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.

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.

repoNameSync

Boolean

Optional. Default Value: false. When set to true and an Azure repository name is changed before the scan, projects for each base branch will be renamed in the Mend UI.

skipScanningStage

Object

Optional. Default Value: none. Controls what stages of the scanning process will be skipped for specific package managers.

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.

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:

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

vulnerablePullRequestStatus

String

Optional. Default Value: failed. Customizable commit status settings for when a Mend Security Check is completed.

• failed - If the Mend scan detects vulnerabilities in a repository, the commit status will show a "failure" indicating that vulnerabilities were detected.
  If no vulnerabilities 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 vulnerabilities in the repository.

• none - The commit status will not be updated by Mend under any circumstances, not even to a "running" indicator while the scan is in progress. Note, that if this parameter is set to none no remediation pull requests will be created.

Notes:

• Only pull request status is affected by this parameter.

• Commit status will behave independently, e.g., fail even if the vulnerablePullRequestStatus parameter is set to “success”.

licensePullRequestStatus

String

Optional. Default Value: failed. Customizable commit status settings for when a Mend License Check is completed.

• failed - If the Mend scan detects license policy violations in a repository, the commit status will show a "failure" indicating that license policy violations were detected.
  If no license policy violations were detected, the commit status shows a "success" indicator. (default option)

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

Notes:

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

• Only pull request status is affected by this parameter.

• Commit status will behave independently, e.g., fail even if the licensePullRequestStatus parameter is set to “success”.

showWsInfo

Boolean

Optional. Default Value: false. Whether to show additional Mend information such as the project token inside the Mend Commit Status (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 Commit Status when this parameter is enabled:

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

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

useMendStatusNames

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 .whitesource is created the value of useMendStatusNames 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.

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.

minSeverityLevel

String

Optional. Default Value: LOW. Enables users to decide whether to open a new Work item only if a certain severity level is available on a detected vulnerability.

Available values for minSeverityLevel:

• NONE - No Work items will be generated.

• LOW - Any Low/Medium/High/Critical vulnerability found will generate a Work item.

• MEDIUM - Any Medium/High/Critical vulnerability found will generate a Work item.

• HIGH - Any High/Critical vulnerability found will generate a Work item.

• CRITICAL - Any Critical vulnerability found will generate a Work item.

Notes:

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

• If this parameter is used together with minVulnerabilityScore or maxVulnerabilityScore then it will be ignored.

minVulnerabilityScore

String

Optional. Default Value: 0. Enables users to define issue creation based on a specified minimum vulnerability CVSS score. Allowed values - floats with one decimal from 0 to 10.

For more information on CVSS 3 Scores, click here.

Notes:

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

• If this parameter is used together with minSeverityLevel then the latter will be ignored.

maxVulnerabilityScore

String

Optional. Default Value: 10. Enables users to define issue creation based on a specified maximum vulnerability CVSS score. Allowed values - floats with one decimal from 0 to 10.

For more information on CVSS 3 Scores, click here.

Notes:

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

• If this parameter is used together with minSeverityLevel then the latter will be ignored.

displayLicenseViolations

Boolean

Optional. Default Value: true. Whether to generate a Work item for every detected license policy violation.

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

customLabels

Array

Optional. Default Value: N/A. Define labels that will be added to the Azure DevOps Repos issues created after the scan.

Usage example:

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

The following labels are not available for use:

• Mend: dependency security vulnerability

• Mend: license policy violation

• Mend: IaC violation

• Mend: configuration error

• Mend: code security findings

customFields

Object

Optional. Default Value: null. This parameter specifies custom fields to be added to all Mend work items.

If a field with a matching name exists in the work item template and the value is a compatible data type, it will be added to the work item.

Example of use:

“issueSettings”:{
  “customFields”: {
    “Priority”: 2,
    “Assigned To” : “john.doe@mail.com”,
    "Team" : "Blue",
    “Mend Detected Vulnerabilities” : "mend.description",
    "Area Path": "test-2\\Area1\\SubArea1"
  }
}

Note:

• To learn more about Area Path, visit our View the results of the Mend for Azure Repos SCA scan documentation.

• If configurations exist both at the global and local repository levels, the local repository configuration (.whitesource file) takes precedence.

• This parameter must include all required fields for the specified workItemType to create or update work items for vulnerabilities, licensing, or IaC.

• The customFields parameter can be used to specify a custom Work Item field where the vulnerability description ("mend.description") will be populated in instead of the default "Description" Azure Work Item field. When creating this custom field, the Type must be Text (multiple lines). In the example above, the custom field for this is "Mend Detected Vulnerabilities".

issueType

String

Optional. Default Value: VULNERABILITY. Defines which type of the work items will be created in the repository. The available parameter values are:

• VULNERABILITY - Create a Work Item for each vulnerability

• DEPENDENCY - Create a Work Item for each direct dependency

enableRenovate

Boolean

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

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 examples:

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

workflowRules.enabled

Boolean

Required. Default Value: true. 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.

workflowRules.minVulnerabilitySeverity

String

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

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 or maxVulnerabilityScore, only minVulnerabilitySeverity will take effect.

workflowRules.minVulnerabilityScore

Float

Optional. Default Value: 0. The minimal vulnerability CVSS 3 score to automatically create remediation pull requests. 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. 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.