| Table of Contents | ||||
|---|---|---|---|---|
|
Overview
This page describes the installation process of Mend for Azure Repos.
Prerequisites
The following requirements must be accommodated before installing Mend for Azure Repos:
Access to a working Mend Application and a user with Admin privileges (either Organization or Product Admin).
“Developer Integrations” enabled in your Mend organization.
Access to Azure DevOps Repos and a user with Admin privileges.
Python support: The default Python version supported is 3.7.12. If you have a python project with a version that is not compatible with the default one, you can choose one of the following: 2.7.18, 3.6.15, 3.9.9.
For this you will need to perform the following procedure:Add a .whitesource configuration file to your repository. Alternatively, you can apply this globally across your repositories by using the Global Repo Configuration.
Use the configMode parameter and set it to either LOCAL or EXTERNAL.
In the whitesource.config file, add the following:
Code Block python.invokePipAsModule=true python.path=python3.9 python.installVirtualenv=trueNOTE: for
python.pathuse one of the following values:2.7,3.6,3.7,3.9.
Installing Mend for Azure Repos
For the application to work correctly Mend needs to receive a PAT (Personal Access Token) from a user who has full access to the repositories. We strongly recommend creating a dedicated bot-user solely dedicated to the integration with Mend for Azure Repos.
Create a whitesource-config project in the Azure DevOps organization you want to integrate. (Find more about this in Global Repo Configuration documentation)
Create and add a bot-user to your organization.
Open Organization Settings → Users in your Azure DevOps organization.
Click Add users.
Fill in an email for the bot-user, set Access level to Basic, provide access to the projects that you want to integrate and the whitesource-config project, set Azure DevOps Groups to Project Administrators.
Note:
When there is a new project created in the organization after this integration process, the bot-user must be manually added to that project. See more about this here.
It is crucial that the bot-user is set as a Project Administrator. Keep in mind, that the bot-user is provided with admin rights not to the organization, but to the projects inside the organization. So you add the bot-user only to the organizations you want to be integrated and provide him with admin rights only to the projects inside these organizations you want to be integrated.
Log in as the bot-user you just created and create a PAT.
Log in to the bot-user account.
Open User settings → Personal Access Tokens.
Create a new token. Give the token a name, and in the Organization dropdown select the All accessible organizations option.
Note: It is important to do so even if there is only one organization that is going to be updated. Control integration access to the different organizations by restricting access for the bot-use.
Set Expiration date. It is recommended to give the latest possible value, 1 year is the limit. Note that this PAT will expire at the end of that period and you will need to renew it. See here for more details.
Set Scopes to Full access.
Save the created token.
Note:
Even though the PAT scope is set as Full access it still will be limited by the access that the bot-user was provided with (i.e. specific organizations and projects). The Full access option is required because Azure Repos hasn’t provided a separate API control for providing check run statuses and comments in the commit, and Mend for Azure Repos requires this for displaying security checks.
By default, all repositories of the projects that bot-user has access to will be integrated. It is possible to specify in the global repo configuration which repositories shouldn’t be integrated.
Provide the PAT to the Mend application.
Log in to your Mend application as an Admin of the organization you want to integrate with these Azure Repos.
Open Integrate → Developer Integrations → Mend for Azure Repos and provide the PAT. After it is saved, projects that the bot-user has access to will be onboarded to the Mend for Azure Repo.
After the PAT is provided to the Mend application, two files (global-config.json and repo-config.json) will be created in whitesource-config/whitesource-config and all other projects will receive onboarding pull requests. The initial PR must be merged to the base branch first. This will then initiate the installation and start the first scan. You can then define further settings (like selected branches) in the .whitesource file.
Note: When a pull request in the repository is created by a bot-user it will be listed under the “Active”, and not in the default “Mine” tab
Note: Once each project is integrated, there will be Service hooks created for the bot-user to work correctly. The webhooks will be created for each of the following trigger actions: Code pushed, Pull request created, and Pull request updated.
...
Troubleshooting
Invalid PAT in the Mend application
...
You might see this error message in the Mend application when saving the PAT. It most likely indicates that the PAT’s organization was not set to the All accessible organizations option.
An onboarding or remediation pull request wasn’t created in the integrated repo
There can be several reasons for such behavior.
1. Make sure that the bot-user has access to the project
This is especially important to remember when a new project is created in the organization. By default, bot-user will not get access to the new projects and you have to do it manually in the Organization Settings → Users. Click on three dots on the bot-user and go to “Manage user”
...
There you can provide access to the new project. Keep in mind that the bot-user should get a “Project Administrators” access level. Also, after the bot-user gets access to the new project, sync must take place, as described here.
...
2. Make sure that projects are synchronized
When one of the following actions happens the integration should be synchronized:
Bot-user received access to a new organization
A new project was created in the organization
PAT updated
You can find more information about this here.
3. PAT might have expired
For information on how to deal with this, see the bot-user documentation.
4. Make sure that the pull request actually wasn’t created
Your pull request might have been actually created, but you didn’t look in the right place.
By default, when you open the Pull requests page in Azure Repos the “Mine” tab will be opened. This tab will show only those pull requests that were created by the logged-in user.
...
But if the integration relies on the bot-user’s PAT, all pull requests that Mend will create in the integrated repositories can be found in the “Active” tab.
...
The .whitesource File
A Mend configuration file (.whitesource) is added to each repository that is enabled for a scan. It provides configurable parameter(s) for the Mend scan. The .whitesource file is only added in the default branch of the repository (unless modified, it is the master branch). Any configuration change that is done to this file must be in the default branch of the repository.
We recommend using Global Repo Configuration to set config parameters for all repositories inside a given Organization. But any .whitesource file can also override parameters set in the global config or even have an isolated configuration (if settingsInheritedFrom global parameter is not set).
.whitesource file (with settings inherited from the Global Repo Configuration)
| Code Block | ||
|---|---|---|
| ||
{
"settingsInheritedFrom": "whitesource-config/whitesource-config@main"
} |
.whitesource file (with local configurations)
| Code Block | ||
|---|---|---|
| ||
{
"scanSettings": {
"configMode": "AUTO",
"configExternalURL": "",
"projectToken": "",
"baseBranches": []
},
"pullRequestStatusSettings": {
"displayMode": "diff",
"vulnerablePullRequestStatus": "failed"
},
"issueSettings": {
"minSeverityLevel": "LOW"
}
} |
Parameters
Global Settings
...
Parameter
...
Type
...
Description
...
Required
...
Default
...
settingsInheritedFrom
...
String
When the global configuration is enabled, this parameter will specify the location of the whitesource-config repository from which it will inherit its configuration. It must contain the Azure user name, repository name and branch (optional) of the repo-config.json file location. The default branch is 'master', but can be modified according to the location of the repo-config.json file in the whitesource-config repo.
NOTE: You can override specific parameters that are relevant only in the specific repository by adding these after this parameter. Parameters with type of array do not override the value from global configuration, but only add new values.
Examples:
Using only values defined in the global configuration:
| Code Block | ||
|---|---|---|
| ||
"settingsInheritedFrom": "whitesource-config/whitesource-config@master" |
...
| Code Block | ||
|---|---|---|
| ||
"settingsInheritedFrom": "whitesource-config/whitesource-config@master",
"scanSettings": {
"projectToken": "12345",
"baseBranches": ["master","integration"]
} |
...
No
...
N/A
...
overrideConfigAllowList
...
Array
...
When the global configuration is enabled, this parameter will regulate the ability of repositories that inherit their configuration from the whitesource-config repository to override the parameters locally. There are three options:
null (
"overrideConfigAllowList": null) - All repositories that inherit configuration from this .whitesource file can override them locally.Empty array (
"overrideConfigAllowList": []) - All repositories that inherit configuration from this .whitesource file cannot override them locally.Array with values (
"overrideConfigAllowList": ["orgName1/repoName1", "orgName2/repoName2"]) - Only specified in the array repositories that inherit configuration from this .whitesource file can override them locally.
NOTE: This parameter must be used in the repo-config.json file of the whitesource-config repository.
...
No
...
null
Scan Settings (scanSettings)
...
Parameter
...
Type
...
Description
...
Required
...
Default
...
configMode
...
String
...
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. NOTE: Not supported in the Global Configuration.
EXTERNAL - External mode. This will look for a configuration file specified according to the configExternalURL parameter.
...
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'
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.
...
No
...
Empty
...
projectToken
...
String
...
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.
...
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:
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 a suffix "_branchname". For example, MyApp_dev. This suffix will not apply to the default branch.
...
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:
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".
...
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 a Work item.
NOTES:
When enabled, after every valid push, a branch (ws-iac-scan-results/{whitesource_scan_token}) is temporarily created and deleted after the scan has completed.
...
No
...
false
Pull Request Status Settings (pullRequestStatusSettings)
...
Parameter
...
Type
...
Description
...
Required
...
Default
...
displayMode
...
String
...
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.
...
No
...
diff
...
vulnerablePullRequestStatus
...
String
...
Customizable commit status settings.
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. (default option)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
noneno remediation pull requests will be created.
...
No
...
failed
...
licensePullRequestStatus
...
String
...
Customizable commit status settings.
NOTE: The license check is dependent on the vulnerabilities check and will not be triggered if vulnerablePullRequestStatus is set to none.
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.
...
No
...
failed
...
showWsInfo
...
Boolean
...
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:
| Code Block |
|---|
<!-- <INFO>{"projectToken":"1cd2d2a8651145c087609e0a43f783e95f7008cb908541498348fed529572e01"}</INFO> --> |
NOTE: Additional Mend data may be added inside the JSON object in the future.
...
No
...
false
...
useMendStatusNames
...
Boolean
...
If set to true names of all Checks (Security, License, SAST, IaC) will be named after Mend (e.g. “Mend Security Check”). If set to false all Checks will have word “WhiteSource” instead of “Mend”.
Note: When .whitesource is created the value of useMendCheckNames is true.
...
No
...
false
Issue Settings (issueSettings)
...
Parameter
...
Type
...
Description
...
Required
...
Default
...
minSeverityLevel
...
String
...
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 vulnerabilities found will generate a Work item.
MEDIUM - Any Medium/High vulnerabilities found will generate a Work item.
HIGH - Any High vulnerabilities found will generate a Work item.
NOTE: The Mend Security Check summary is also affected by this parameter.
...
No
...
LOW
...
displayLicenseViolations
...
Boolean
...
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.
...
No
...
true
(only if enableLicenseViolations (scanSettings) is set to true)
...
customLabels
...
Array
...
Setting that will define labels that will be added to the issues created after the scan.
Usage example:
| Code Block |
|---|
{
"issueSettings": {
"customLabels": ["label1","label2"]
}
} |
Following labels are not available for the use:
security vulnerabilitylicense policy violationIaC violationconfiguration errormaintenance notice
...
No
...
Empty
...
issueType
...
String
...
Defines which type of the work items will be created in the repository: one for each vulnerability or one for each direct dependency.
...
No
...
VULNERABILITY
Remediate Settings (remediateSettings)
...
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
...
| Info |
|---|
This parameter would provide direct fix for transitive vulnerabilities in NPM projects. As transitive remediation for NPM is currently enabeled by default this parameter is no longer requiered. |
...
No
...
false
...
workflowRules
...
Object
This parameter is used to specify the rules that regulate when to open remediation pull requests.
Usage examples:
| Code Block |
|---|
"remediateSettings": {
"workflowRules": {
"enabled": true,
"minVulnerabilitySeverity": "LOW"
}
}
"remediateSettings": {
"workflowRules": {
"enabled": true,
"minVulnerabilityScore": 1.5,
"maxVulnerabilityScore": 10
}
} |
...
Yes
...
| Code Block |
|---|
"workflowRules": {
"enabled": true
} |
...
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 true then Workflow Rules from the application are not being used.
...
Yes
...
true
...
workflowRules.minVulnerabilitySeverity
...
String
...
The minimal vulnerability severity level to automatically create remediation pull requests for. Allowed values - "LOW", "MEDIUM", "HIGH".
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 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
Private Registry Settings (hostRules)
...
Parameter
...
Type
...
Description
...
Required
...
Default
...
matchHost
...
String
...
Defines where the credentials will be applied during the scan.
If you want to apply credentials only for a nested path within a host, then write matchHost as a base URL.
For example: https://registry.company.com/nested/path/.
If the same credentials apply to all paths on a host and not on any subdomains, configure matchHost with a protocol like https://registry.company.com.
Finally, to apply credentials to all hosts within the domain, use a matchHost value with no https:// prefix, e.g. company.com or registry.company.com, both of which would apply to a host like beta.registry.company.com.
...
No
...
Empty
...
hostType
...
String
...
Type of private registry. Supported values: npm (for both NPM and Yarn projects), maven, gradle, pypi, go , nuget, ruby.
Required if matchHost is used.
...
No
...
Empty
...
username
...
String
...
Used when credentials consist of username and password.
...
No
...
Empty
...
password
...
String
...
Used when credentials consist of username and password, should be encrypted on this page.
Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:
| Code Block | ||
|---|---|---|
| ||
"encrypted": {
"password": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
} |
...
No
...
Empty
...
token
...
String
...
Used when credentials consist of token, should be encrypted on this page.
Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:
| Code Block | ||
|---|---|---|
| ||
"encrypted": {
"token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
} |
...
No
...
Empty
Handling Private Registries and Authenticated Repositories
| Info |
|---|
Private registries hosted on any platform that can be accessed with credentials are supported (Nexus, Artifactory, JFrog, etc.) |
Supported languages and package managers:
NPM
Yarn
Maven
Gradle
PIP
Go
Nuget
Ruby
In order to scan dependencies from private registries and authenticated repositories, Mend must be provided with credentials, such as an NPM token. These credentials must be added as encrypted secrets to the .whitesource file, either per-repository or in the shared global config, if the secret scope is org-wide.
To create the encrypted secrets, please follow this link. Each secret you encrypt must be scoped to an Azure Repos organization or repository and its use will be restricted to those within the app. There are the following fields on the encryption page:
Organization\Group - required, your Azure organization to which tokens secret be scoped.
Repository - optional, your Azure repository to which secret should be scoped.
Raw value - required, confidential values/secrets such as tokens or passwords.
Encrypted value - the result of the encryption to be used in the integration.
After the secret is created, please add it to the hostRules parameter of the .whitesource file.
Example of hostRules:
| Code Block |
|---|
{
"hostRules": [
{
"matchHost": "registry.npmjs.org",
"hostType": "npm",
"encrypted": {
"token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
}
},
{
"matchHost": "https://custom.registry.company.com/maven/",
"hostType": "maven",
"username": "bot1",
"encrypted": {
"password": "p278djfdsi9832jnfdshufwji2r389fdskj........."
}
}
]
} |
...
is available at: https://docs.mend.io/bundle/integrations/page/installation_of_mend_for_azure_repos.html