Global Repo Configuration

overrideConfigAllowList

Array

If 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 repo-config.json file can override the configuration locally.

• Empty array ("overrideConfigAllowList": []) - All repositories that inherit configuration from this repo-config.json file cannot override the configuration locally.

• Array with values ("overrideConfigAllowList": ["orgName1/repoName1", "orgName2/repoName2"]) - Only specified in the array repositories that inherit configuration from this .whitesource file can override the configuration locally.

No

overrideConfigAllowList

repoConfigMode

String

The configuration mode to be used on all integrated repositories. There are three options:

• createOnboardingPR - Create an onboarding PR/MR containing a .whitesource file with inherited configuration. The integrated repositories will inherit the configuration from the repo-config.json file located inside the whitesource-config repository. The .whitesource configuration file generated in each repository will contain a single parameter settingsInheritedFrom with a value pointing to the repo name and branch in which the repo-config.json file is located.

• pushwhitesourceFile - A .whitesource configuration file with inherited configuration will immediately be pushed to the default branch of all integrated repositories without creating any onboarding PRs/MRs. The .whitesource configuration file generated in each repository will contain a single parameter settingsInheritedFrom with a value pointing to the repo name and branch in which the repo-config.json file is located.

Note: If the pushwhitesourceFile parameter is set, please ensure there are no policies set on the default branch. For example, a default branch that only accepts changes to be made via a pull request. As this is a push update, such a policy will block onboarding.

• nowhitesourceFile - Integrated repositories will be scanned without creating a .whitesource file or onboarding PR/MR. The integrated repositories will inherit the configuration from the repo-config.json file located inside the whitesource-config repository.

Note: If the nowhitesourceFile parameter is set, the existing repositories that Mend has access to require a valid commit before scanning will continue. Newly created repositories that Mend has access to will automatically start the initial scan (versus waiting for the onboarding PR to be merged when createOnboardingPR is set).

Yes

createOnboardingPR

repoConfigFileName

String

It is possible to rename the .whitesource configuration file added to an integrated repository.

Notes:

• This is currently only supported for newly-integrated repositories. If a repository already includes a .whitesource file, the integration will continue using it.

• This parameter is ignored when the repoConfigMode is set to nowhitesourceFile.

No

.whitesource

branchProtectionRule

Automatically create a “Mend Security Check” branch protection rule for all branches configured by the “baseBranches” property. This will only occur for newly onboarded repositories.

Notes:

1. Only valid for the GitHub Enterprise integration.

2. This will require to add the “Repository administration” to the “Read & Write” permissions to the GitHub application.

{
  "branchProtectionRule": {
    "mode": "newInstallations"
  }
}

No

“none”

settingsInheritedFrom

Add an option for a regular account repo-config.json or global-config.json file to inherit settings from the whitesource-config account’s global-config.json file. For example, a global-config.json file in {someOrg}/whitesource-config could inherit settings from the whitesource-config/whitesource-config file.

If this parameter is enabled, after creating a whitesource-config file inside the repos of the given organization, it will be automatically populated with the settings from the whitesource-config/whitesource-config file.

Note:
You can override specific parameters that are relevant only in the specific repository by adding these after this parameter.

Examples:

Using only values defined in the global configuration:

"settingsInheritedFrom": "whitesource-config/whitesource-config@main"

Using values defined in the global configuration and overriding the scan settings parameters:

"settingsInheritedFrom": "whitesource-config/whitesource-config@main", 
 "issueSettings": {
    "minSeverityLevel": "MEDIUM"
  }

No

“none”

enableCustomProductMapping

Boolean

If set to true, each integrated repository that has a topic that starts with the mendmap- prefix will be connected to the Product in the Mend Application with the name that goes after prefix.

Notes:

• Only available for GitHub.com and GitHub Enterprise.

• Topic length limitation is 32 characters.

• Default prefix mendmap- can be changed in the GitHub Enterprise integration with use of the MEND_PRODUCT_MAPPING_PREFIX environment variable.

No

False

ignoreSpecificVulnerabilities

Boolean

When set to true all vulnerabilities IDs listed in ignored-vulnerabilities.txt in the root of whitesource-config repository will be ignored during security scans (they will not be mentioned in the security checks and will not fail them, these vulnerabilities will not be mentioned in the issues).

Format of ignored-vulnerabilities.txt: list CVE, WS or MSC IDs separated by a new line. Example:

CVE-2017-1000048
WS-2014-0005
CVE-2014-6394

Notes:

• Existing mentions of the ignored vulnerabilities will be removed from the issues with the next valid push after this parameter is enabeled.

• These change affects only Repo Integration and doesn’t change the vulnerability alerts in the Mend Application.

No

False

overrideConfigAllowList

Array

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 repo-config.json file can override its settings locally in their .whitesource file.

• Empty array ("overrideConfigAllowList": []) - All repositories that inherit configuration from this repo-config.json file cannot override its settings in their .whitesource file.

• Array with values ("overrideConfigAllowList": ["orgName1/repoName1", "orgName2/repoName2"]) - Only the repositories specified in this list that inherit configuration from this repo-config.json file can override its settings locally in their .whitesource file.

Notes:

• This parameter has the same functionality as the one in repo-config.json.

• It was created to address behavior when there is a repo that is not included in the list of reports that can override the configuration locally, and it contains a .whitesource config with a wrong format. In this case, there will be a failed Configuration Change Check and further scans will be prevented. With this new implementation, such a case will not happen - the .whitesource file will always be ignored, and Configuration Change Check will not block the scans.

• If both this and the same parameter in repo-config.json are set up - only global-config.json parameter one will be used.

No

null

exactNames

Array

Provide a list of specific repositories to ignore from the integration. For example:

GitHub.com:

"ignoredRepos": {
  "exactNames": ["myorg/myrepo", "myorg/testrepo"]
}

Azure Repos:

"ignoredRepos": {
  "exactNames": ["Azure_Project_Name1/Repo_Name", "Azure_Project_Name2/Repo_Name"]
}

No

Empty

exactNames

Array

Provide a list of specific repositories that will be onboarded. For example:

"includedRepos": {
  "exactNames": ["user/myrepo", "user/testrepo"]
}

NOTES:

1. Not supported in Mend for GitHub.com

2. If parameter includedRepos is set to null then all repositories will be onboarded: "includedRepos": null.

3. This parameter shouldn’t be used together with ignoredRepos. Scenario of both parameters used in one configuration is unsupported and may lead to unexpected results.

4. When adding a new repository that was not previously included in the exactNames list, the creation of the repository's onboarding pull request will occur only after a valid push event happens in the repository (depending on the repoConfigMode). Given that the app was provided access to this repository in the SCM, otherwise the onboarding process will not take place.

5. In Mend for Bitbucket Cloud, the exactNames value is set to [] by default, which means that no repository will be onboarded until selected ones are listed in the array, or the parameter includedRepos is deleted from global-config.json to onboard all repositories of the integrated workspace.

6. This parameter will not override settings in SCMs where it is possible to control access to repositories for the installed integration. This means that if you excluded some repositories from access for Mend, they will not be scanned even if these repositories are mentioned in this parameter.

No

Empty

includedOwners->exactNames

Array

Define a whitelist of GitHub Organizations and/or GitHub repository owners that can integrate with the Mend integration.

For example:

"includedOwners": {
  "exactNames": ["MyOrg", "MyUserName"]
}

NOTES:

• You can use the exactNamesFile instead of exactNames to upload an included-owners.txt file containing a list of organization names. For more information on how to use this parameter, please check our article here: Global Repo Configuration - Account Management (includedOwners).

• This applies only to Mend for GitHub Enterprise and Mend for GitHub.com.

No

Empty

allowedUserAccounts->exactNames

Array

Provide a way to limit the integration to organization accounts and block all or specific user accounts. If the exactNames property is empty, all user accounts will be blocked. If the object is missing, no limitation will be enforced on account type.

When a blocked account is trying to install the integration, it will be automatically uninstalled.

NOTE: Only valid for the GitHub Enterprise integration.

{
  "allowedUserAccounts": {
    "exactNames": ["userName1", "userName2"]
  }
}

No

Null

workItemType

String

This parameter specifies the type of work item to be created for all Mend work items. Set this parameter to a string equal to the name of a work item type in your project.

NOTES:

• Using a non-existent work item type will prevent the creation or update of work items for vulnerabilities, licensing, or IaC.

• If the specified work item type has any required fields, they must be specified with the customFields parameter in order for work items to be created or updated

• If there are problems in the configuration and Mend fails to create/update work items properly there will be created a configuration error work item with a message about this.

• The “Description" field for work items is required. If this “Description" field is missing from the work item type, the integration result details (CVE details) will not be provided in the work item.

No

Depends on the process type:

• Basic - Issue

• Agile - Issue

• CMMI - Issue

• Scrum - Impediment

customFields

Object

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:

“azureReposSettings”:{
  “workItemType”: “Custom Work Item”,
  “customFields”: {
    “Priority”: 2,
    “Assigned To” : “john.doe@mail.com”,
    "Team" : "Blue",
    “Mend Detected Vulnerabilities” : "mend.description"
  }
}

NOTES:

• This parameter can also be set per repository within the .whitesource file. Read more here: Mend for Azure Repos - Issue Settings (issueSettings).

  • If configurations exists 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 in order 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".

No

None

migrationMode.changeType

String

Type of change to perform as part of the migration.

There are three possible values:

• inheritance - The migrating repositories will inherit from the global configuration

• deletion - The .whitesource file (if found) will be removed from the migrating repositories. Note the following:

  • This should only be used when repoConfigMode in the global-config.json file has the value nowhitesourceFile. Otherwise, no migration will be performed.

  • In Mend for Bitbucket Server, the deletion option is not available. You will need to manually delete the .whitesource file for each migrated repository.

• fixInheritance - The migration will update existing inheritedFrom parameter values in repo-level .whitesource configuration files, to the correct whitesource-config repository.

  • This parameter can be used in case the Global Configuration repository was moved or renamed since the initial integration.

No

inheritance

migrationMode.openPR
(Mend for GitHub Enterprise, Mend for GitHub.com, and Mend for Bitbucket Server/Data Center)

migrationMode.openMR
(Mend for GitLab)

Boolean

Whether an onboarding PR/MR should be created for the migrating repositories.

NOTE: When set to false, every migrating repository that currently contains a .whitesource file will trigger an automatic scan after these are migrated. This may affect overall performance of the integration depending on how many migrating repositories you have.

No

true

migrationMode.triggerScan

Boolean

Control whether the migration should trigger a scan after completion.

NOTE: This parameter is relevant only when using migrationMode.changeType=inheritance.

No

true

includeRepos

Array

Provide a list of specific full repository names (organization/repo_name) on which the migration should run. Organization is a GitHub term and each source control manager has an equivalent term that should be used in place of organization.

Azure DevOps(project), Bitbucket(workspace), GitLab(group), GitHub(organization)

Example:

"includeRepos": ["whitesource/unified-agent-distribution", "whitesource/jenkins-whitesource-plugin"]

NOTES:

• You cannot use includeRepos together with excludeRepos as part of a migration.

• The includeRepos parameter is added to the root level of migration.json, as shown in the “complete migration.json file” example below.

No

Empty

excludeRepos

Array

Provide a list of specific full repository names (owner/repo_name) on which the migration should not run.

Example:

"excludeRepos": ["whitesource/unified-agent-distribution"]

NOTES:

• You cannot use excludeRepos together with includeRepos as part of a migration.

• The excludeRepos parameter is added to the root level of migration.json, as shown in the “complete migration.json file” example below.

No

Empty