Jira Server and Data Center

You can use the Veracode Integration for Jira to import to Jira Server and to Jira Data Center security flaws that Veracode identifies in your application.

Veracode Integration for Jira manages the import of security findings from Veracode and creates issues in Jira for each imported findings. Veracode also provides the Veracode Integration for Jira Cloud, which provides the same functionality for Jira Cloud.

The Jira integration assigns each unique application finding to a unique Jira issue, created in the designated Jira project. Import criteria can include all open findings from all scans, all findings that affect policy, all unmitigated findings from the most recent scan, or other criteria.

You can choose to import findings on a one-time basis or selectively choose which findings to import. You can also schedule findings imports on an hourly, daily, or weekly basis. You can import findings from a specific application scan or from all your application scans. The integration can also update findings comments on the Veracode Platform, but cannot mitigate findings from within the Jira integration.

To keep the status of imported findings in your ticketing system in sync with the status of the actual findings in the Veracode Platform, you must routinely run the integration.

Supported versions

Veracode has tested the following versions, but the integration might work with other versions.

Jira Server or Jira Data Center 9.4.0–10.3.10

Supported libraries

Veracode has tested the following versions, but the integration might work with other versions.

Java 8, 11, and 17

Jira users

There are two types of Jira users that interact with the Jira integration. You need to be aware of these user types when installing and using the integration.

• Jira user: this user is an account inside of Jira with permissions to create and modify all Jira issues for all projects to which you are importing flaws.
• Veracode user: this user has access to the Veracode Platform. The integration can only import findings for applications that this user can access. Veracode recommends that this user is an API service account.

About the finding life cycle in Jira

The Veracode Integration for Jira and the Veracode Integration for Jira Cloud import findings to Jira or Jira Cloud as issues and maintain the status of those issues. The status is based on the configuration settings on the Administration page in Jira or Jira Cloud. The integration sometimes changes the status of issues and, consequently, adds a comment to the issue describing the reason for the action.

The integration considers each issue to be in one of three status types:

• Resolved: considered to be done, but not verified or closed. The Jira status names are Resolved or In Review.
• Closed: someone has verified the issue. The Jira status names are Closed, Done, or Complete.
• Open: every other status.

If an issue is not resolved, the integration tries to transition it to Resolve, Resolve Issue, Complete Work, Close Issue, or Done. If someone reopens an issue, the integration tries to transition the status to Reopen, Reopen Issue, To Do, Queued for Action, Restart Progress, Start Progress, or Start Review.

In addition, the integration tries to change the status of issues in these situations:

• The integration does not find a previously imported finding during a new scan and the corresponding issue is not Resolved or Closed. The integration resolves the issue as Cannot Reproduce.
• The finding still exists, but, based on the import settings, the integration does not re-import it. You could manually resolve the corresponding issue as Won't Fix or Closed, for example.
• The finding still exists and the integration re-imports it, but the corresponding issue is Resolved or Closed. The integration changes the corresponding issue to Reopen or Open.

To change the status of an issue, in Jira, you can search for and execute status transitions for the project of the issue. For each transition there is a list of transition names. To resolve an issue, you can select the Jira transition that matches one of the names on the list. Jira orders the list, searches transitions in the order shown, and uses the first allowed transition. Veracode recommends transitioning an issue to an imperfect status instead of not changing its status.

Reopen transitions

• Open
• Queued for Action
• Reopen
• Reopen Issue
• Restart Progress
• Start Progress
• Start Review
• To Do

Resolve transitions

• Close
• Close Issue
• Complete Work
• Done
• Fixed
• Resolve
• Resolve Issue

Install the Jira Server integration

You can install the Veracode Integration for Jira as a plugin from the Atlassian Marketplace.

Before you begin:

The Veracode Integration for Jira has these prerequisites:

• Ensure you have the supported version of Jira and Java.

• Your Jira instance must use the state names and transition names for the integration to be able to appropriately assign the correct state and automatically make the correct transitions.

• If you are using Jira Data Center, in the cluster.properties file, you must specify the value of the jira.shared.home property as the common file location for processing findings import data. The property could be a local directory or network file system (NFS) directory that all Jira nodes access. If you are using an NFS location, you must perform drive mapping in each Jira node.

• You have the necessary permissions to write to the Jira HOME directory.

• If you are using Jira Data Center, you must have already moved the data, plugins, logos, import, and export folders from the local to shared HOME directory.

• Have an API service account with the Results API and Mitigation API roles. Veracode recommends that the administrator of your account creates a separate API service account specifically for this Jira integration. If your organization uses team access to scan results, add the new API service account to the teams associated with the applications that you are scanning. The integration imports all findings from applications to which the API service account has access.

• Use a Jira user account that has the permissions for creating and modifying all Jira issues for all the projects into which you are importing findings data.

• The system running the Jira server must have network connectivity.

• Veracode has these minimum hardware recommendations for Jira server:

  • Processor (CPU): Quad Core 2GHz
  • Memory: 32GB RAM
  • Storage: 10GB for the database

• Ensure that all required Veracode IP addresses for the Veracode APIs and integrations are on the allowlist for your organization. The integration uses these addresses to authenticate with Veracode. To update your allowlist, you might need to contact your IT team.

To complete this task:

1. Go to the Atlassian Marketplace.

2. Search for Veracode.

3. In the search results, select the link for the Veracode Integration for Jira.

4. Download the plugin and follow the installation instructions.

5. If prompted, re-index Jira.

6. In Jira, select Administration > Manage apps > Manage apps.

   If the installation completes successfully, you see the Veracode Integration for Jira on the Manage apps page.

Update the Jira Server integration

You can check the Atlassian Marketplace for updates to the Veracode Integration for Jira or update the integration from within the Jira interface.

Before you begin:

You must have Jira administrator permissions.

To complete this task:

1. In Jira, select Administration > Manage apps > Manage apps.
2. Select the Action required filter.
3. If Veracode Integration for Jira appears in the list, select Update.

Upgrade an old version of the Jira Server integration

Use this procedure only if you are upgrading to the latest version of the Veracode Integration for Jira from a version earlier than 3.5.0.

Before you begin:

You must have Jira administrator permissions.

To complete this task:

1. Sign in to Jira as administrator and uninstall any previous versions of the Veracode Link plugin.

   note

   Do not remove the Veracode Link custom field that the integration created during the installation.

2. Run this SQL query in the Jira database to confirm that there is only one record for the Veracode Link custom field:

   SELECT
       ID, CUSTOMFIELDTYPEKEY, CUSTOMFIELDSEARCHERKEY
   FROM
       customfield
   WHERE
       cfname = 'Veracode Link';

   If the SQL query returns multiple records for the Veracode Link custom field, before continuing to the next step, you must remove the duplicate Jira issues.

3. Stop the Jira server.

4. Create a backup of your current Jira database, including triggers, stored procedures, functions, and events.

5. Delete these files from directory {jira-directory}/atlassian-jira/WEB-INF/lib:

   • Any previous versions of the Veracode Jira import plugin file veracode-jira-flaws-synchronizer*.jar
   • vosp-api-wrapper-java{version}.jar
   • esapi.jar
   • ESAPI.properties

6. Run this SQL query in the Jira database to remove any unnecessary Veracode Link custom field definitions:

   DELETE FROM customfield
   WHERE CUSTOMFIELDTYPEKEY='com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-field' 
   AND CUSTOMFIELDSEARCHERKEY='com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-searcher';

7. Run this SQL query in the Jira database to update the Veracode Link custom field definition:

   UPDATE customfield
   SET CUSTOMFIELDTYPEKEY='com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-field',
   CUSTOMFIELDSEARCHERKEY='com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-searcher'
   WHERE CUSTOMFIELDTYPEKEY='com.veracode.jira.plugin.link.VeracodeLink:veracode-link-field'
       AND CUSTOMFIELDSEARCHERKEY='com.veracode.jira.plugin.link.VeracodeLink:veracode-link-searcher';

8. Commit the changes to the Jira database.

9. Start and re-index the Jira server.

Remove duplicate issues in Jira Server

If you are upgrading from a version of the Veracode Integration for Jira that is earlier than 3.5.0 and notice duplicate Jira issues during the upgrade, use this procedure to remove duplicate issues.

To complete this task:

1. Run the appropriate SQL query to obtain a comma-separated list of IDs of the duplicate issues.

   note

   If you have non-terminal values, other than Open and To Do, in the Status field defined in your Jira workflow, you must update the SQL query to include those additional Status field values.

   • For a MySQL database:

     SELECT GROUP_CONCAT(ID) FROM jiraissue WHERE ID IN (SELECT ISSUE
     FROM customfieldvalue
     WHERE
         customfieldvalue.CUSTOMFIELD = (SELECT
              ID
         FROM
              customfield
         WHERE
              CUSTOMFIELDTYPEKEY = 'com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-field'
              AND CUSTOMFIELDSEARCHERKEY = 'com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-searcher')
              AND customfieldvalue.STRINGVALUE IN (SELECT STRINGVALUE FROM customfieldvalue WHERE
              CUSTOMFIELD = (SELECT ID
         FROM
             customfield
         WHERE
             CUSTOMFIELDTYPEKEY = 'com.veracode.jira.plugin.link.VeracodeLink:veracode-link-field'
             AND CUSTOMFIELDSEARCHERKEY = 'com.veracode.jira.plugin.link.VeracodeLink:veracode-link-searcher')))
             AND (issuestatus IN (SELECT ID FROM issuestatus WHERE pname = 'Open' OR pname = 'To Do')) LIMIT 0,500)
             AS jiraissue_temp_2  ON jiraissue_temp_1.ID = jiraissue_temp_2.jiraissue_id;

   • For an Oracle database:

     SELECT LISTAGG(ID, ', ') WITHIN GROUP (ORDER BY ID) jiraissue_ids FROM jiraissue jiraissue_temp_1 INNER JOIN (SELECT jiraissue_id FROM (SELECT ID AS jiraissue_id, ROW_NUMBER() OVER( order by ID asc ) rn  FROM jiraissue WHERE ID IN (SELECT ISSUE FROM customfieldvalue
     WHERE
        customfieldvalue.CUSTOMFIELD = (SELECT
            ID
        FROM
            customfield
        WHERE
            CUSTOMFIELDTYPEKEY = 'com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-field'
            AND CUSTOMFIELDSEARCHERKEY = 'com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-searcher')
     AND customfieldvalue.STRINGVALUE IN (SELECT STRINGVALUE FROM customfieldvalue WHERE
     CUSTOMFIELD = (SELECT
            ID
        FROM
            customfield
        WHERE
            CUSTOMFIELDTYPEKEY = 'com.veracode.jira.plugin.link.VeracodeLink:veracode-link-field'
            AND CUSTOMFIELDSEARCHERKEY = 'com.veracode.jira.plugin.link.VeracodeLink:veracode-link-searcher')))
            AND (issuestatus IN (SELECT ID FROM issuestatus WHERE pname = 'Open' OR pname = 'To Do'))) where rn BETWEEN 1 AND 500)
            jiraissue_temp_2  ON jiraissue_temp_1.ID = jiraissue_temp_2.jiraissue_id;

   • For a PostgreSQL database:

     SELECT ARRAY_AGG(ID) FROM jiraissue AS jiraissue_temp_1 INNER JOIN (SELECT ID AS jiraissue_id  FROM jiraissue WHERE ID IN (SELECT ISSUE
     FROM customfieldvalue
     WHERE
         customfieldvalue.CUSTOMFIELD = (SELECT
             ID
         FROM
             customfield
         WHERE
             CUSTOMFIELDTYPEKEY = 'com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-field'
             AND CUSTOMFIELDSEARCHERKEY = 'com.veracode.jira.plugin.synchronize.veracode-jira-flaws-synchronizer:veracode-link-searcher')
     AND customfieldvalue.STRINGVALUE IN (SELECT STRINGVALUE FROM customfieldvalue WHERE
     CUSTOMFIELD = (SELECT
             ID
         FROM
             customfield
         WHERE
             CUSTOMFIELDTYPEKEY = 'com.veracode.jira.plugin.link.VeracodeLink:veracode-link-field'
             AND CUSTOMFIELDSEARCHERKEY = 'com.veracode.jira.plugin.link.VeracodeLink:veracode-link-searcher')))
             AND (issuestatus IN (SELECT ID FROM issuestatus WHERE pname = 'Open' OR pname = 'To Do')) LIMIT 500)
             AS jiraissue_temp_2  ON jiraissue_temp_1.ID = jiraissue_temp_2.jiraissue_id;

   note

   If you are using a database other than MySQL, Oracle, or PostgreSQL, contact Veracode Technical Support for assistance.

2. In Jira, select Issues > Search for issues.

3. Switch to advanced search and enter this JQL search query, replacing {duplicate_ticket_ids} with the output of the SQL query you ran in step 1:

   issuekey in ({duplicate_ticket_ids})

   For example, if the SQL query output is 10400,10401,10402,10403,10404,10405,10406,10408, then your search query in Jira would be: issuekey in (10400,10401,10402,10403,10404,10405,10406,10408)

   A text area opens, into which you can enter JQL queries.

4. Run the Issue search to view the list of Jira issues that match the IDs you specified.

5. Select Tools > Bulk Change to start the bulk change for all issues that the advanced search returned.

6. In the Choose Issues step, select the Select All checkbox and select Next.

7. In the Choose Operation step, select Delete Issues and select Next.

8. When prompted, select Confirm.

9. Repeat steps 1-8 until the SQL query output on the Choose Issues step no longer returns any results, which means that there are no more duplicate issues to delete.

Next steps:

If you suspended your upgrade procedure to remove these duplicate issues, you can now go back to that procedure and continue from step 3.

Configuring the Jira Server integration

After you install the Veracode Integration for Jira, you configure it to add your Veracode credentials for accessing Veracode and to set up your findings import settings.

Add your credentials

Add your Veracode API credentials to the Veracode Integration for Jira. The integration uses the credentials to access Veracode.

Before you begin:

You have generated Veracode API credentials.

To complete this task:

1. In Jira, select Administration > Manage apps > Login Credentials.
2. Enter your Veracode API credentials.
3. Select Test Credentials to ensure the credentials are valid. If this step fails, verify that there is network connectivity and try again.
4. Select Save.

Configure import settings

You can configure the Veracode Integration for Jira to specify the findings identified during Veracode scanning to import into Jira.

You can import findings from the Veracode Platform into either a:

• Default project that you select from the provided dropdown menu in this procedure.
• Project that you have named in a custom field on the Metadata page of each Veracode application profile.

Before you begin:

Before you can link imported findings to other issues, ensure the issue linking feature in Jira is activated: Administration > Issues > Issue linking.

To complete this task:

1. In Jira, select Administration > Manage apps > Findings Import.

2. In the Import section, select the types of findings to import. Other sections on this page become enabled or disabled depending on your selections.

   note

   If you select Sandbox static findings or Sandbox SCA findings, the corresponding options for importing sandbox findings are disabled.

3. In the Filter Import By section, select which findings to import:

   • All findings: from all scans, including closed findings
   • Only findings from the most recent scan: all open findings that were found in the most recent scan
   • All unmitigated findings: from all scans, including closed findings
   • Only unmitigated findings from most recent scan: all open, unmitigated findings from most recent scan
   • All findings that affect policy: all open findings from all scans that affect policy
   • All unmitigated findings that affect policy: all unmitigated, open findings from all scans that affect policy

   During each import, the integration checks previously-imported findings to verify if it can close the findings. For example, if you select the import selection criteria Only findings from the most recent scan and the most recent scan resulted in a finding that was fixed, the integration closes the Jira issue for this particular finding.

4. Select to assign imported findings to a specific epic or link them to a related issue.

   note

   If you selected to import sandbox findings, these options are disabled.

   • Assign to Epic: select to assign imported findings to a specific epic. Then, from the dropdown menu, select the Veracode custom field that contains the exact epic issue key. If you leave this custom field empty, your import results in an error. The integration assigns imported findings from every Veracode application with this exact epic issue key value in the same custom field. For example, you have added the same epic issue key value to Custom Field 5 in every application profile.
   • Link to Issue: select to link imported findings to a related issue. Then, from the dropdown menu, select the Veracode custom field that contains the exact issue key for the related issue to which to link imported findings. If you leave this custom field empty, your import results in an error. The integration links imported findings from every Veracode application with this exact issue key value in the same custom field. For example, you have added the same issue key value to Custom Field 7 in every application profile.

5. From the Import Static and Dynamic Findings As dropdown menu, select the issue type to apply to each imported static and dynamic finding.

   For SCA findings, the integration imports components as stories and imports vulnerabilities for those components as subtasks of the related stories.

6. In the Import Issues Into section, select the Jira project into which you want to import the security findings or select the Veracode custom field that maps to the appropriate Jira project.

   note

   You cannot enter custom metadata for sandbox scans of the application using the Veracode Platform. To enter custom metadata for sandbox scans, use the Development Sandbox API.

7. In the Add Values To Issues section, select the labels, or enter a string for a custom label, to add to the issues for all imported findings. You can also select to assign the issues to the next fix version scheduled for your Jira project.

   For example, you can assign issues to the next fix version of your software build, add a custom label to help you triage or sort your findings, and add a label for the CWE that corresponds to the type of finding discovered during scanning.

8. If you selected to import sandbox findings, specify the Jira project into which to import findings, the labels to add to the issues during import, and whether to assign each issue to the next fix version.

9. In the Automated Issue Management section, select whether to automatically close findings mitigated in the Veracode Platform or manually update the status of mitigated findings.

10. In the JIRA User field, enter the username of the Jira user who can create and modify issues.

note

This Jira user must have the necessary permissions for all Jira projects into which the integration imports findings.

11. Select Test JIRA User to verify the Jira username.
12. Optionally, in the Override Description section, select the Override the Jira Description field checkbox.
13. Enter the text to add to the Description field in each issue or leave the text field blank. During the next findings import, the contents of this field replace any content in the issue Description field for each imported finding.
14. Select Save to save all import settings.
15. If Jira prompts you to perform a re-index, you can proceed with re-indexing. However, Veracode only recommends re-indexing when it is required.

Results:

The Import Settings section reports any errors detected in your configuration. If there are no errors, the configuration is complete, and you can proceed with importing findings using the Veracode Integration for Jira.

Associate Veracode fields with Jira project screens

You configure your screen template in Jira to include two Veracode custom fields. When importing findings to Jira, the Veracode Integration for Jira automatically adds the custom fields to each Jira issue of imported findings and populates the values.

Before you begin:

Before a custom field can display on the Issues page in Jira, the specific value intended for that custom field must already exist in the Veracode Platform.

You configure these Veracode custom fields:

• Veracode Link: manages the association of the Jira issue with the application findings in the scan results on the Veracode Platform. After completing this procedure, this custom field provides links back to the specific application, policy, and findings in the Veracode Platform.
• Mitigation Status and Comments: describes the current mitigation status, with optional comments, for an imported finding.

To complete this task:

1. In Jira, select Administration > Issues > Screens.
2. Find the screen template that you use for importing Veracode security findings.
3. Select Configure to display the Configure Screen page for the selected template.
4. From the Field name dropdown menu, select Veracode Link and select Add.
5. From the Field name dropdown menu, select Mitigation Status and Comments and select Add. The custom fields appear on the Configure Screen page.

Next steps:

To prevent your users from changing the Mitigation Status and Comments field, Veracode recommends that you make the field read-only.

Set the Mitigations field to read-only

To prevent Jira users from editing the Mitigations Status and Comments field for imported findings, we recommend that you set th field it to read-only.

To complete this task:

1. On your Jira system, download and install ScriptRunner for Jira from the Atlassian Marketplace.
2. In Jira, select Administration > Manage apps > Behaviours.
3. In the Add Behaviour section, in the Name field, enter Make Mitigation Status and Comments read-only.
4. Select Add.
5. Select Add Mapping next to the behaviour you added.
6. In the Fields section, select Readonly.
7. In the Add Field dropdown menu, select Mitigation Status and Comments and select Add.
8. Select Save. In the Jira issues of imported findings, the Mitigation Status and Comments field is shaded to indicate that it is read-only.

Mapping Veracode fields to Jira fields

The Veracode Integration for Jira and the Veracode Integration for Jira Cloud can map data from custom fields in the Veracode Platform to fields in Jira or Jira Cloud issues. The integration can also map values from the Veracode Detailed XML Report.

To improve the import of Veracode findings into your Jira or Jira Cloud issues, you can map Custom Field 1 through Custom Field 10 in the Veracode Platform to standard or custom fields in Jira or Jira Cloud issues.

When importing findings to Jira or Jira Cloud, the integration imports the values from the mapped Veracode fields, including data from the Veracode Detailed XML Report, which you can download as detailedreport.xml. The integration has specific requirements for data types in Veracode fields and field types in Jira and Jira Cloud.

After adding field mappings, during the findings import process, the integration:

• Applies the mappings.
• Updates the values in Jira or Jira Cloud fields with any changed values in Veracode fields.
• Overrides any default values in Jira or Jira Cloud fields with the values in Veracode fields.
• Logs a WARN message in the Jira or Jira Cloud logs to warn you about any invalid Veracode field value. The import process omits these values and continues uninterrupted.

Default Veracode fields

The Veracode Platform provides the following categories of default fields that you can map to Jira issues using the Veracode Integration for Jira or the Veracode Integration for Jira Cloud:

• Common Fields: information pertaining to a specific Veracode application and also applicable to static analysis and SCA findings
• Static Fields: details for static analysis, dynamic analysis, and manual penetration test scan results
• SCA Components: security findings details for SCA components
• SCA Vulnerabilities: security findings details for SCA vulnerabilities

Jira fields that map to Veracode fields

This table lists the standard fields in Jira and Jira Cloud to which you can map Veracode custom fields on the Veracode to Jira Field Mappings page. The Veracode to Jira Field Mappings page is available with the Veracode Integration for Jira and the Veracode Integration for Jira Cloud.

Standard Jira field	Description
Affected Version/s
Assignee	User assigned to the issue. The Veracode Integration for Jira uses these criteria when populating the Assignee field in Jira: If the Assignee field is mapped to a Veracode custom field, and the value is a valid username in Jira, the Assignee field value is that username. The custom field value must be a valid username in Jira and cannot be the user display name or full name. If the Assignee field is mapped to a Veracode custom field, but the custom field value is blank or is not a valid username, the Assignee field value is Unassigned. If neither the Assignee field nor the Component/s field are mapped to a Veracode custom field, the Assignee field value is the default assignee value of the Jira project. If the Component/s field is mapped to a Veracode custom field, the Assignee field value is the default assignee value assigned to the component in Jira. If the Component/s field contains multiple components: The integration alphabetizes the components by name. The Assignee field value is the default assignee value from the first component value in the alphabetized list.
Component/s	Comma-separated list of component values defined in custom fields in the Veracode Platform. Use this format for each component: ComponentName:ComponentDescription:ComponentLeadName:DefaultAssigneeType For example: ComponentA:ComponentAdesc: :0,ComponentB:ComponentBdesc:Carl:1 This example defines these components: ComponentA has a description, no component lead, and uses the project default of 0 for the assignee. ComponentB has a description and uses Carl for the component lead name and default assignee, which is 1. If you omit part of the string, enter a space after each colon for an omitted value. For example, if you only specify a component called comp1, enter comp1: : : For the default assignee type, use these numeric values: 0 or empty for Project Default 1 for Component Lead 2 for Project Lead 3 for Unassigned The numeric values correspond to the actual default assignee type values such as Project Default or Component Lead in Jira or Jira Cloud. See the Jira or Jira Cloud documentation.
Description	Adds the finding description value from the Veracode detailedreport.xml file and appends it to the existing description in the issue. The Description (overwrite) option replaces the Description field in Jira or Jira Cloud with the value from the selected field in the Veracode Platform. If the Veracode Platform field is empty, the mapping erases the contents of the Description field in Jira or Jira Cloud.
Environment
Fix Version/s
Issue Type	Issue type, such as story, bug, or epic. If there is no mapping for this field, the integration uses the issue type set in Jira or Jira Cloud.
Labels	Comma-separated list of labels to add to the issue. These labels do not affect any existing labels. During import, the integration removes any spaces between labels and concatenates any strings.
Original Estimate	Original estimate of the work required to resolve this issue. To map this field, you must have Time Tracking configured on the screen.
Reporter	User designated as the reporter for an issue. If there is no mapping for this field, the integration uses the reporter specified in Jira or Jira Cloud.
Time Spent	Time spent working on an issue. The value is based on the Time Tracking setting in Jira or Jira Cloud. You can set the default unit to Minute, Hour, Day, or Week. The integration converts the input long value to the default unit. To map this field, you must have Log Work configured in Jira or Jira Cloud.

Map Jira data types and field types

The Veracode Integration for Jira and the Veracode Integration for Jira Cloud support importing string, number, and date/time data types from Veracode fields to text, number, and date/time field types in Jira or Jira Cloud.

On the Veracode to Jira Field Mappings page, when you select a Veracode custom field or Jira field, you see the supported data type or field type below your selection.

When adding a custom field in Jira or Jira Cloud, you select a field type. The integration supports these field types only:

• Date Time Picker: if the value is in a Veracode custom field, which uses free-form text, the value must be in this format: dd/MMM/yy HH:mm. For example, 14/Jan/20 11:52
• Number Field: if the value is in a Veracode custom field, which uses free-form text, the value must be an integer or decimal.
• Select List (multiple choices) and Select List (single choice): if the values are in Veracode custom fields, ensure each value is enclosed in square brackets. For example:
  • Custom 1: [value 1]
  • Custom 2: [value 1][value 2][value 3]
• Text Field (multi-line) and Text Field (single line)

If you select an unsupported field type, Jira and Jira Cloud accept it without error, but you cannot select it from the Veracode Platform dropdown menu on the Veracode to Jira Field Mappings page. For text fields only, if a Veracode custom field has a value of -1, the integration imports it as [-1]. All other negative values import to text fields without square brackets.

You can configure mappings between custom fields in the Veracode Platform and fields in Jira. The Veracode Integration for Jira uses these mappings to import specific information when importing findings as Jira issues.

To complete this task:

1. In Jira, select Administration > Manage apps > Field Mappings.

2. In the Veracode Platform column, select the dropdown menu and select the name of the Veracode field you want to map. For example, Application Name.

3. In the Jira column, from the dropdown menu, select the Jira field you want to map to the Veracode field.

4. Select Add Mapping.

5. Repeat these steps until you have mapped all the desired fields.

   note

   Custom field names do not support commas (,) or colons (:).

6. To delete any mappings you do not want to keep, select Remove.

Example: Mapping Veracode fields to Jira fields

This example demonstrates mapping fields from application profiles in the Veracode Platform to fields in Jira or Jira Cloud issues.

This example creates a mapping between these fields:

• Default field Application Name in the Veracode Platform to the Labels field in Jira or Jira Cloud.
• Custom 1 field in the Veracode Platform to the Assignee field in Jira or Jira Cloud.

In this example, when creating the application named VeracodeDemoApp in the Veracode Platform, you edit the metadata and assign a value for custom field Custom 1. For example, enter assignee John Smith as the value.

In Jira or Jira Cloud, these field mappings are configured on the Veracode to Jira Field Mappings page:

• The application name field is mapped to the Labels field.
• Custom field Custom 1 is mapped to the Assignee field.

A sample issue shows the result of the field mappings.

Map Veracode severities to Jira priorities

The Veracode Integration for Jira can map Veracode flaw severities in the Veracode Platform to your custom priorities in Jira.

The Veracode Platform severity scale uses six flaw severities: Very High, High, Medium, Low, Very Low, and Informational. In Jira, you can create any number of priorities using any names you want, but you are limited to mapping the six severities to a maximum of six priorities. The severity mapping applies to all new flaws during the next import to Jira. You configure severity mapping on the Veracode Severity Mappings page, which you can access in the Jira interface from: Administration > Add-ons > Severity Mappings.

Default severity mappings

After you install the integration, it checks for an existing mapping between Veracode severities and your Jira priorities. If a mapping exists, the integration leaves the mapping configuration intact and applies it to the next flaw import. If no mapping exists, the integration creates a default mapping based on the number of priorities in the Jira system. You can change the default mapping at any time.

The five default priorities available in Jira are: Highest, High, Medium, Low, and Lowest.

For a Jira system with exactly six priorities, the integration creates this default mapping:

• The Very High severity maps to the Highest priority.
• The High severity maps to the High priority.
• The Medium severity maps to the Medium priority, and so on.

If the Jira system has more than six priorities, the integration maps the Veracode severities to the six highest priorities. The remaining lower priorities are not mapped. If necessary, you can map a severity to a lower priority. For a Jira system with less than six priorities, the integration maps the highest severities to the highest priorities. The remaining severities all map to the same lowest priority.

Severity mapping limitations

A severity mapping has these limitations:

• You can only create a single mapping. When you change and save the mapping, which must be valid, it replaces the previous configuration. If you add, edit, or delete priorities, you must manually update and save the mapping to reflect the new priorities or the mapping might be invalid.
• The mapping only applies to new flaws you import to Jira. It does not apply to flaws (issues) already imported to Jira.
• You cannot disable severity mapping.

Invalid severity mappings

If there are issues with the mapped priorities in Jira, the severity mapping could be invalid. You must manually correct any issues with your priorities and, then, update your mapping to be in sync with the mapped priorities.

A mapping can be invalid for these reasons:

• The mapped priorities no longer exist in the Jira system, but the configured mapping still contains the previous priorities. Someone might have deleted or renamed one or more priorities after you saved the mapping or while you were creating the mapping, but had not yet saved it. The invalid mapping causes these issues:
  • After importing flaws from the Veracode Platform to Jira, the Priority field in all issues mapped to the missing priority is blank. The integration records this warning message in the Jira logs: Invalid priority set in Severity Mappings page with priority: <PriorityName>
  • After configuring the mapping, when you select Save, the mapping fails to save, and you see this error message: One or more of the priorities selected are not valid Jira priorities. Please try again.
• Flaws in the Veracode Platform have a severity that is outside the severity scale. After importing the flaws into Jira, the Priority field in all issues mapped to that severity is blank. The integration records this warning message in the Jira logs: Invalid severity received from Veracode Platform, setting priority to null. Severity received: <SeverityName>

Map findings to Jira priorities

You can map Veracode flaw severities to your customized priorities in Jira Server.

To complete this task:

1. In Jira, select Administration > Manage apps > Severity Mappings.
2. On the Veracode Integration Severity Mappings page, go to the JIRA Priority column.
3. Select a dropdown menu and select the name of the Jira priority you want to map to the corresponding Veracode severity.
4. Repeat the previous step to map each severity to a priority.
5. Select Save to save the mapping.

If the mapping is valid, you see a success message. If the mapping is invalid, you see an error message and the mapping fails to save.

You can now import security findings to Jira, which applies the mapping to new flaws.

Example: Map Veracode severities to Jira priorities

This section provides an example of using the Veracode Integration for Jira to map Veracode flaw severities in the Veracode Platform to priorities in Jira.

In this example, the Triage Flaws page in the Veracode Platform lists nine flaws with different severities: Very High, High, Medium, and Low.

In the Jira system, the Priorities page lists the five default priorities, in order, with default names.

In Jira, the Veracode Integration Severity Mappings page shows these mappings:

• The Very High severity is mapped to the High priority, instead of the default Highest priority.
• The High severity is mapped to the Medium priority, instead of the default High priority.
• The Medium severity is mapped to the Low priority, instead of the default Medium priority.
• The lower severities are all mapped to the Low priority.

After you import the flaws from the Veracode Platform to Jira as issues, the issues show these assigned priorities:

• The Very High severity flaw has a High priority.
• The High severity flaw has a Medium priority.
• All Medium severity flaws have a Low priority.
• The Low severity flaw has a Lowest priority.

Clicking an issue ID link in Jira displays the Details view showing the priority value. In this example, issue SEV-858 for flaw ID 6, which has a High severity in the Veracode Platform, has a Medium priority in Jira.

Clear the Jira Server integration cache

You can clear the cache for the Veracode Integration for Jira when attempting to troubleshoot various issues. If you clear the cache during an import, the import stops. To restart the import, you can start it manually or wait for the next automatic import.

Occasionally, defects might cause the integration to enter an unstable state. Clearing the cache provides a partial fresh start and enables the integration to re-gather information that can avoid the originating defect or temporarily prevent a return to the unstable state.

To complete this task:

1. On the Veracode Integration page in Jira, go to the Troubleshooting section.
2. Select Clear Cache to start again.

After clearing the cache, the next selective or one-time import might take longer to complete as Jira has to download all new detailed reports.

Enable logging

You can configure Jira to log the actions that the Veracode Integration for Jira performs. The log messages are located in the standard Jira log.

You can enable logging in the Jira interface and the log4j.properties file. If you enable logging in the Jira interface and restart Jira Server, you must re-enable logging. If you enable logging in the log4j.properties file and restart Jira Server, logging remains enabled.

note

Jira Cloud does not support logging.

The location of the Jira logs depends on the Jira installation location. For example:

Windows

C:\Program Files (x86)\Atlassian\Application Data\Jira\log\atlassian-jira.log

Linux

/opt/atlassian/jira/logs/catalina.out

To complete this task:

1. In Jira, select Administration > System > Logging & Profiling.

2. In the Default Loggers section, select Configure logging level for another package.

3. In the window, in the Package name field, enter com.veracode.jira.plugin.

4. From the Logging Level dropdown menu, select INFO or DEBUG.

5. Select Add.

6. If you want logging to remain enabled after restarting Jira Server, edit the file {Jira home}/JIRA/atlassian-jira/WEB-INF/classes/log4j.properties.

7. Add these two properties to log4j.properties:

   log4j.logger.com.veracode.jira.plugin = INFO, filelog
   log4j.additivity.com.veracode.jira.plugin = false

   For log4j.logger.com.veracode.jira.plugin, you can enter one of these logging levels: DEBUG, ERROR, INFO, or WARNING.

Results:

The Veracode Integration for Jira saves all retrieved findings information. You can review the flaw report XML files to understand the actions the integration performed. Example flaw report locations include:

Windows

C:\Program Files (x86)\Atlassian\Application Data\Jira\log\atlassian-jira.log

Linux

/var/atlassian/application-data/jira/jira_home/veracode/flawreportxml

Import findings

You can use the Veracode Integration for Jira to automate imports of findings into Jira. You can also perform one-time imports and selective imports of specific findings.

The Veracode Integration for Jira automatically sets the Priority field of an imported finding if that field is available and has default values. The integration uses this formula to set the priority based on the severity of the finding in the Veracode scan Results:

• If Severity = 5, the bug priority is set to Highest
• If Severity = 4, the bug priority is set to High
• If Severity = 3, the bug priority is set to Medium
• If Severity <= 2, the bug priority is set to Lowest

After importing findings to Jira, you can see them assigned to the user.

The title and description of all imported sandbox findings are prefixed with the word Sandbox to differentiate them from regular policy scan findings.

When the integration creates a Jira issue for each finding, it also adds a comment to the finding in the Veracode Platform.

To keep the status of imported findings in your ticketing system in sync with the status of the actual findings in the Veracode Platform, you must routinely run the integration.

Import findings on a schedule

You can use the Veracode Integration for Jira to schedule automated imports of findings from the Veracode Platform to Jira.

The integration imports findings in order of severity, with higher severity taking precedence, then in order of creation date, with earlier findings taking precedence.

To complete this task:

1. In Jira, select Administration > Manage apps > Import Automation.

2. Select the Automate Flaw Import checkbox.

3. Select an import frequency: Hourly, Daily, or Weekly.

4. If you selected Daily, select a time. If you selected Weekly, select a day and time.

5. In the Import Limit field, enter the maximum number of static findings you want to import at one time for any application. Import limits do not apply to SCA findings. If you do not provide an import limit, the integration imports all findings found in Veracode scans.

6. If you want to override the general import limit for a particular application:

   a. Select the Override by Application checkbox.

   b. Select the Veracode custom field that determines the import limit for the application. If the Veracode custom field configuration is invalid, the integration ignores the override and applies the general import limit.

7. To receive email notifications when an import fails, select the Import failure Emails checkbox. The integration uses your Jira SMTP server settings to send these alerts.

note

For details on configuring your Jira SMTP mail server, see Configuring an SMTP mail server to send notifications (Atlassian Docs).

8. Under Import missing flaws, select the checkbox to attempt to import any flaws that have not imported into Jira. During the next automatic import only, the integration checks for and imports flaws that it has not imported. After the import has completed, this option clears automatically.

   For example, an application with flaws might have been in error during previous automatic imports. These flaws are likely in the Veracode Platform, but there are no issues for them in Jira. On the Monitoring and Troubleshooting page, if you see errors indicating that issues failed to import, select this option to attempt to import the missing flaws during the next automatic import.

9. Select Save.

Import findings one time

You can use the Veracode Integration for Jira to perform one-time imports of findings from the Veracode Platform to Jira.

The integration imports findings in order of severity, with higher severity taking precedence, then in order of creation date, with earlier findings taking precedence.

To complete this task:

1. In Jira, select Administration > Manage apps > One Time Import.

2. In the Import Limit field, enter the maximum number of static findings you want to import for any application. Import limits do not apply to SCA findings. If you do not provide an import limit, the integration imports all findings found in Veracode scans.

3. If you want to override the general import limit for a specific application:

   a. Select the Override by Application checkbox.

   b. Select the Veracode custom field that determines the import limit for the application. If the Veracode custom field configuration is invalid, the integration ignores the override and applies the general import limit.

4. Select Import to JIRA.

Import specific findings

You can use the Veracode Integration for Jira to select specific findings from the Veracode Platform to Jira.

To complete this task:

1. In Jira, select Administration > Manage apps > Selective Import.

2. In the Import Limit field, enter the maximum number of static findings you want to import for any individual application. Import limits do not apply to SCA findings.

3. If you want to override the general import limit for a particular application:

   a. Select the Override by Application checkbox.

   b. Select the Veracode custom field that determines the import limit for the application. If the Veracode custom field configuration is invalid, the integration ignores the override and applies the general import limit.

4. Select the findings you want to import.

5. Select Import to JIRA.

Monitor and troubleshoot imports

You can review information about the last four imports to Jira Server or Jira Data Center. This information is useful when you want to monitor imports and troubleshoot errors.

To complete this task:

1. In Jira, select Administration > Manage apps > Troubleshooting.

2. Review the following information about the last import:

   • Import Type: One-Time Import, Selective Import, or Import Automation.
   • Started Time: date and time when the import started.
   • Status: current status of the import:
     • IN PROGRESS: the integration is importing findings.
     • PENDING: for Selective Import, the findings you can import are listed on the Selective Import page, but the integration has not yet imported them. When the import is complete, the status changes to COMPLETED.
     • CACHE CLEARED: indicates that you selected Clear Cache during a status of IN PROGRESS or PENDING. This button stops any running import process. To restart the import, you can start it manually or wait for the next automatic import.
     • COMPLETED: the import has completed. Check the Remarks column for any errors, which appear in red text.
     • FAILED: the import has failed due to one or more issues. See the Remarks column for errors, which appear in red text. For more information about each error, review the log files.
   • Completed Time: date and time when the import completed.
   • Remarks: results of the import, including the phases of the import process and any errors, which are highlighted red.

3. Optionally, select Refresh to update the page with the latest information about the imports.

4. If you notice error messages in the Remarks column, you can select Clear Cache to attempt to troubleshoot the issue. If the errors are related to failed report downloads, select the checkbox under Retry Failed Report Downloads to retry during the next import. If you continue to see errors, contact Veracode Technical Support.

5. To view past diagnostics data, under the Diagnostics History section, select a date from the date picker, then select Refresh. By default, this section shows diagnostics from the last 10 days.

Examples

The following example shows one-time imports that had errors, with the last import completing without errors. The statuses indicate that the user cleared the cache during the imports.

The following example shows one-time imports that completed successfully, but the last import had errors. In the Remarks column, the red error messages state that the Jira plugin failed to download the Detailed Reports of the imported flaws.

Uninstall the Jira Server integration

Uninstall the Veracode Integration for Jira from within the Jira interface.

To complete this task:

1. In Jira, select Administration > Manage apps > Manage apps.
2. In the Filter visible apps field, enter Veracode to display only Veracode applications.
3. From the filter dropdown menu, select User-installed.
4. Expand the Veracode Integration for JIRA row.
5. Select Uninstall.