Package: mend-azure-wi-sync
Integrate Mend SCA with Azure Work ItemsA self-hosted tool that creates and updates Azure Work Items based on Mend SCA Issue Tracking policies.The tool is deployed within an Azure Pipeline triggered on fixed intervals by a cron schedule.It utilizes Mend'sIssue Tracking APIto identify the Mend SCA projects that weremodifiedsince the last execution, obtain the list ofpolicy matched issuesfor each of them and create or update the corresponding Work Item.Table of ContentsSupported Operating SystemsPrerequisitesPlanning Your WorkItems SetupAzure DevOps SetupMend SCA SetupAzure Pipeline VariablesCustom Field MappingExamplesExecutionSupported Operating SystemsLinux:CentOS, Debian, UbuntuWindows:10, 2012, 2016PrerequisitesPython 3.9+Azure DevOps Services or Server instanceAzure DevOps service user Personal Access Token (PAT) withRead & writepermissions for both "Work Items" and the "Project and Team" scopes on any organization where you want to run the integration.Azure DevOps service user added to a group with the following permissions in the project:Create tag definition,Manage project propertiesandView permissions for this nodeThe user needs to be added to the team for each area path you wish to create work items for.Mend SCAIssue Tracking policiesMend SCA service user with associated with arole assignmentof eitherOrganization AdministratororOrganization AuditorPlanning your Work Items SetupThe Mend Work Items integration has the flexibility for creating work items with granularity. Before setting up the integration, make sure you have a clear understanding of which projects and/or products should have work items created. The below list specifies where you should place themend-azure-wi-sync.ymlfile in step 2 below for proper implementationIf only a single repository should have work items created, then add the example pipeline file to the specific repository where you want workitems created. In this type of implementation, you want to make sure thatMEND_PROJECTTOKENis set appropriatelyIf a full project, or more than one repository inside of a project need Work Items created, then create a new repository where the pipeline file will live. In this type of implementation, you can use a combination ofMEND_PRODUCTTOKENandMEND_EXCLUDETOKENto exclude certain projects inside of a productIf your full Mend organization needs work-items created, then it is recommended to create a separate repository for the pipeline. In this type of implementation, leaving bothMEND_PRODUCTTOKENandMEND_PROJECTTOKENempty, and usingMEND_EXCLUDETOKENto exclude projects where needed is advisedSeeAzure Pipeline Variablesfor details.Azure DevOps SetupCreate aPersonal Access Token (PAT)withRead & writepermissions for theWork Itemsscope andProject and TeamscopeCreate a new Azure pipeline from the example fileexamples/mend-azure-wi-sync.ymlMake sure the user you created the PAT for has the following permissions in each repository where workitems are needed:Create tag definition,Manage project propertiesandView permissions for this nodeSet up the appropriate environment variables/secrets for the pipeline. The minimum requirements for these variables are:MEND_URL,MEND_USERKEY,MEND_APIKEY,MEND_AZUREPAT, andMEND_RESET. We recommend also settingMEND_PRODUCTTOKEN,MEND_PROJECTTOKEN, and/orMEND_EXCLUDETOKENas detailed above. TheMEND_RESETvariable should be configured to allow users to override its valueFor your first scan, the integration requiresMEND_RESETto be true for initial workitem creation. For all other scans, this variable can be set to falseMend SCA SetupSet up a policy withIssueaction for each use case you wish a Work Item to be created for.The naming convention should include, other than a self explanatory description of what the policy does, a square-bracketed prefix, either[License]or[Security].NOTE: Refer to the Mend SCA documentation for detailed instructions on how tocreate new policies.For best practices concerning desigining your policy scheme, refer toBest Practices for Mend SCA PoliciesAzure Pipeline VariablesThe following variables can be placed into the pipeline where the integration is run, to configure its behavior:VariableTypeRequiredDefaultDescriptionMEND_URLstringYesN/AMend server URLMEND_USERKEYsecretYesN/AYour Mend User KeyMEND_APIKEYsecretYesN/AMend Organization API KeyMEND_AZUREPATsecretYesN/AAzure DevOpsPersonal Access TokenMEND_AZUREURIstringYesN/AAzure DevOps organization URI (e.g.https://dev.azure.com/MyOrganization).Accepts thesystem variable$(System.CollectionUri)MEND_AZUREPROJECTstringYesN/AAzure Team Project name.Accepts thesystem variable$(System.TeamProject)MEND_PRODUCTTOKENstringNoEmpty String(Include all products)Comma-separated list of Mend Product Tokens that should be monitored for changes.MEND_PROJECTTOKENstringNoEmpty String(Include all projects)Comma-separated list of Mend Project Tokens that should be monitored for changes.MEND_EXCLUDETOKENstringNoEmpty String(No exclusions)Comma-separated list of Mend Project Tokens that should not be monitored.MEND_AZUREAREAstringNo$MEND_AZUREPROJECTArea Pathto group created Work Items under.For example:TeamProject\Area1\SubArea2orArea1\SubArea2. Use double-backslashes when specifying sub-areas.MEND_AZURETYPEstringNoTaskWork Item type for creating new Work Items.Must be one of thebuilt-inorcustomtypes that are available for the project'sprocess. (Basic, Agile, Scrum, etc.) associated with the specified Team Project in theMEND_AZUREPROJECTvariable.MEND_RESETbooleanNofalseWhether to force Work Item creation for a Mend Projects' full history (rather than just the diff since the last run). Creates work items for the diff when set tofalse.MEND_CUSTOMFIELDSstringNo*Empty String(No custom fields)Used for mapping additional information from Mend's Issue Policy objects into custom fields of the specified Work Item type ($MEND_AZURETYPE).SeeCustom Work Item Typesbelow for syntax guidelines.This variable is required when using custom Work Item types.MEND_REPONAMEstringNo*<Name of Repository>Do not changeThe field contains Repo Name which can be used as value for any Custom field according Custom Fields syntax. SeeCustom Work Item Typesbelow for syntax guidelines ($MEND_REPONAME).MEND_DEPENDENCYbooleanNo*TrueSpecify whether to create work items based on the dependency (value: True) or based on the CVE (value: False). Typically creates more work items if set tofalse.MEND_DESCRIPTIONstringNo*"ReproSteps"Used to tell the Integrations which field should contain the description. Use "ReproSteps" for bugs, "Description" for issues, or a custom name for a custom field.MEND_CALCULATEPRIORITYbooleanNo*FalsePriority will be calculated according to Mend’s severity (CSS3) value if the value is equal to True. If not, it will be set to 2 (default priority).MEND_PROXYstringNoEmpty StringThe Proxy URL. The right format is <proxy_ip>:<proxy_port>. In case of a proxy requires Basic Authentication the format should be like this <proxy_username>:<proxy_password>@<proxy_ip>:<proxy_port>.If http:// or https:// prefix is not provided, the prefix http:// will be used by default.MEND_ALERTbooleanNo*TrueWhether to include ignored vulnerabilities. Set to false for exclude ignored vulnerabilities.NOTE:azure-wi-syncwould accept all environment variables with eitherMEND_orWS_prefix.ExecutionThe recommended way to implement this integration, is by having the pipeline run on a cron schedule. We recommend that the cron schedule run on a daily basis, or by your desired frequency. This is demonstrated in theexample pipeline file.schedules:-cron:"0*/1***"displayName:Mend SCA Sync Schedulerbranches:include:-mainalways:trueWhen the configured pipeline is executed, the integration fetches all the Issue policy matches that were created since the last execution.Custom Field MappingWhen specifying acustom Work Item typewith$MEND_AZURETYPE, the integration will utilize theAzure APIto automatically obtain its definition.The"issues": []objects returned by thefetchProjectPolicyIssuesAPI response will be used to populate the corresponding Work Item fields. However, you can choose to use theMEND_CUSTOMFIELDSvariable to populate additional information into any custom fields of that Work Item, if its type has any of those.Setting the Custom Fields VariableTheMEND_CUSTOMFIELDSvariable accepts a string that is a semi-colon separated list of key-value pairs in the format ofFieldName::StaticValueorFieldName::MEND:MappedValue. More than one mapped value can be placed into a custom field by concatenating them with "&" like:CustomField:MEND:MappedValue&MEND:MappedValueThe field name directly corresponds to the "name" property data returned in the API "WorkItemTypeFieldInstance", whereas the mapped value directly corresponds to the API Response for Mend's "fetchProjectPolicyIssues". Please refer to the response example in the API documentation for an example of what you can parse, or you can run the API itself to get real data.NOTE: If the definition of the specified Work Item type ($MEND_AZURETYPE) includes any fields that are set up as mandatory ("alwaysRequired": true), you must also useMEND_CUSTOMFIELDSto map values to those fields.GuidelinesThe value ofMEND_CUSTOMFIELDSshould be a quoted string (single or double quotes)The string should contain all the desiredKey::Valuemapping pairs, separated by semicolons (;)TheKeyof each pair should be the name of the Work Item field (thenameproperty, AKA "friendly name". SeeWorkItemTypeFieldInstancefor details)The value can contain a dot-separated JSON path of the desired property from thefetchProjectPolicyIssuesresponse, prefixed by the namespaceMEND:(case sensitive)The process iterates through the objects under the"issues": []array of thefetchProjectPolicyIssuesresponse, so anyMEND:values must be from under that object. Values cannot include JSON paths for other properties from outside"issues": []The value can also contain custom text, either dynamic (using pipeline variables) or staticThe value can combine multiple parts, bothMEND:proeprties and/or free text. Parts should be delimited by an ampersand (&)If you plan to use theMEND_REPONAMEorMEND_DESCRIPTIONvariables then you can add this to a custom field with$MEND_REPONAMEor$MEND_DESCRIPTIONSyntaxenv:...MEND_AZURETYPE:'SCAIssue'MEND_CUSTOMFIELDS:'Field1::MEND:path.to.property1;Field2::MEND:property2&FreeText&MEND:property3;Field4::$MEND_REPONAME'ExamplesAll the following examples assume a custom Work Item type namedSCA Issue, which was configured to inherit fields from theBugWork Item of theAgileprocess flow.Example 1Populating the Work Item's custom fieldsIssue TypeandIssue Referencewith the vulnerability's type and identifier (name):env:...MEND_AZURETYPE:'SCAIssue'MEND_CUSTOMFIELDS:'IssueType::MEND:policyViolations.vulnerability.type;IssueReference::MEND:policyViolations.vulnerability.name'Example 2Populating the Work Item's custom fieldTeam Commentswith the initial text:Mend policy name:POLICY_NAME(scope:POLICY_SCOPE)env:...MEND_AZURETYPE:'SCAIssue'MEND_CUSTOMFIELDS:'TeamComments::Mendpolicyname:&MEND:policy.name&(scope:&MEND:policy.policyContext&)'