Migrate to Integration Builder

Overview

This document offers detailed, step-by-step instructions on utilizing Integration Builder recipes to establish synchronization between Cobalt pentest findings and Jira Cloud issues. The level of automation in your workflow is directly related to the number of recipes you configure to tailor the behavior to your specific requirements.

We’ve added a variety of pre-built recipe templates to the Integration Builder’s library to facilitate seamless bidirectional synchronization between your Jira Cloud instance and the Cobalt Platform. Depending on your workflow, you can choose to configure and use a subset of these recipe templates. The recipe templates are categorized into three groups:

1. Push finding from the Cobalt Platform to Jira Cloud
2. Update the Cobalt Platform from Jira Cloud
3. Update Jira Cloud from the Cobalt Platform

Different types of recipes call for different Jira Cloud workflow configurations. For instance, creating a Jira issue when a pentest finding is moved to the Pending Fix state requires no additional workflow customization. However, if you wish to update the pentest finding’s state in the Cobalt Platform when the Jira issue’s status changes, your workflow must contain specific issue statuses. Additionally, if you want to update your Jira issue’s status based on the pentest finding’s state changes, you need to set up transitions in your Jira workflow. This documentation will provide an example and cover the required Jira workflow changes later on.

Migration

❗ Do not migrate a pentest from the native Jira Cloud integration to the Integration Builder when the pentest is in the live state.

Introduction

To better understand the required migration steps and the recipes’ customization, this tutorial provides an introduction to a sample Jira Cloud project using the default Kanban template. Let’s assume that the workflow for the Task issue type of this sample project includes the following statuses:

Initial Jira workflow

Jira workflow statuses

• To Do (default, ‘To do’ category)
• In Progress (default, ‘In progress’ category)
• Acceptance Testing (custom, ‘In progress’ category)
• Done (default, ‘Done’ category)
• Won’t Do (custom, ‘Done’ category)

Assuming that this project is already set up with the native Jira Cloud integration in the Cobalt application, the native Jira Cloud integration does the following:

1. Creates a Task Jira issue for a finding when it is moved to the Pending Fix state

   ℹ️ The Task can be created via auto-push if configured for the pentest or manually from the pentest finding page.

2. Updates the pentest finding to the Ready for Retest state when the Jira Task status changes to Acceptance Testing.

3. Updates the pentest finding to the Accepted Risk state when the Jira Task status changes to Won’t Do.

Push finding from the Cobalt Platform to Jira Cloud

Use the recipe

1. Open the Integrations page from the sidebar and select Integration Builder tile.

   

2. Open the Library tab, search for the [Cobalt > Jira Cloud] Push pentest finding to Jira recipe by specifying push pentest finding jira and pressing Enter. Select the recipe by clicking on the recipe tile.

   

3. Click on the Use this recipe button to save a copy of the recipe into your workspace.

   

4. Select the Cobalt folder as the copy destination then click on Save and copy.

   ℹ️ You can select any arbitrary folder to save a copy of the recipe.

   ℹ️ You can create a new folder before saving a copy of any recipes. To do so, click on the Projects tab in the Integration Builder and click on the plus sign (+) to Create folder from the project explorer sidebar.

   

5. Click on Customize recipe to adjust the pre-built recipe template to your Jira Cloud configuration.

   ℹ️ The recipe is not ready for use yet. It needs the Jira Cloud project configuration, including the project name and the task Jira issue type to create.

   

Customize the recipe

⚠️ To customize the recipes, you need to have the Jira connection set up. If you haven’t set up a connection to your Jira Cloud instance using the Jira connector yet, you can learn how to manage your Integration Builder connections here.

1. To configure the recipe’s run condition, select the recipe Trigger in the editor and select a pentest from the list.

   ℹ️ By default, this recipe will be activated whenever there is a state change for any pentest finding within the Cobalt Platform. Once a specific pentest is chosen from the list, the recipe will only be triggered if the status change is for a finding related to the selected pentest. If it doesn’t, the recipe will not be activated.

   

2. To customize the issue creation in Jira Cloud, select the Create issue in Jira action and configure your Jira Cloud Project issue type from the dropdown.

   

3. To customize the external ticket reference in Cobalt, select the Create external ticket reference in Cobalt actions.

   This action creates the external ticket reference in the Cobalt Platform. The following properties are required:

1. Save the recipe changes, click on Exit to quit the recipe editor, and click Start recipe to start the recipe.

   

   

Update the Cobalt Platform from Jira Cloud

There are two pre-built recipe templates available in the Integration Builder library that can be used to update the status of the pentest finding in the Cobalt Platform when the issue status changes in Jira Cloud.

1. Use the recipe by saving a copy into your workspace and click on Customize recipe to configure it according to your Jira Cloud project issue type.

2. Configure the recipe trigger and specify a datetime before the pentest is launched.

   1. Select New/updated issue in Jira recipe trigger in the editor.
   2. Specify a datetime before your pentest is in the live state using the From setting.

      ℹ️ The From setting allows recipes to retrieve past trigger events from a specified date and time. Instead of only picking up new trigger events (events created since the recipe was started), this setting enables the selection of events that have already occurred. When you start a recipe for the first time, it retrieves new or updated issues starting from the specified date and time. Once a recipe has been ran or tested, this value cannot be changed.

      In the example below, the trigger for new or updated Jira issues has a From date of 7 Aug 2024, midnight PST.

   3. Refresh the editor to resolve the validation errors in the recipe.

   

3. Configure the recipe filter to only include issues from the relevant Jira Cloud project with a specified Jira issue status.

   1. Select the IF condition in the editor.
   2. Specify the expected Jira Cloud project key value. For example, NJC.
   3. Specify the name of the expected Jira issue status. For example, Acceptance Testing, based on the example Jira workflow statuses.

   

   ⚠️ Remember to use the exact case-sensitive label of the expected Jira status.

   You can check the workflow statuses in your Jira Cloud project:

   • Open the board of your Jira Cloud project.
   • Click on the kebab menu (⋯).
   • Select Manage workflow.
   • Click on the expected status see its name.

   

   1. Save the editor, click on Exit to close the editor, and select Start recipe.

ℹ️ Follow the same customization steps for the [Jira Cloud > Cobalt] Move pentest finding to ‘Accepted Risk’ recipe. Make sure to use the correct Jira issue status, such as Won't Do, as indicated in the example Jira workflow.

Update Jira Cloud from the Cobalt Platform

Manage Jira workflow transitions

⚠️ The Integration Builder-based Jira Cloud integration has more capabilities than the native Jira Cloud integration. It offers the ability to automatically update the status of your Jira Cloud issues when the state of the corresponding pentest finding changes. Configuring Jira workflow transitions is necessary for this functionality. Without a transition, the Jira issue status cannot be programmatically altered. Reference the official Jira Cloud documentation regarding adding a new transition to a workflow for more details.

Modify the example Jira workflow by adding the following workflow transitions:

⚠️ By default, all Jira statuses allow issues from any other status to be moved into them. The Any Jira status label indicates this “global” transition capability. Although it’s not mandatory, it’s highly recommended to restrict issues from any status to move into them. This is to prevent accidental movements of Jira issues, such as moving from the In Progress status to the Done status, thereby avoiding invalid Jira transitions. An invalid Jira workflow transition, for example, would attempt to automatically change the pentest finding state from Pending Fix to Fixed, which is invalid and would consistently fail.

• Select Manage workflow from your Jira Cloud board.
• Select the Jira status, for example, Won’t Do.
• Uncheck the checkmark next to Allow issues in any status to move to this one.
• Click on Update workflow to confirm the changes.
• Apply the workflow updates on the appropriate Jira issue type.

There are two pre-built recipe templates available in the Integration Builder library that can be used to update the status of an issue in Jira Cloud when the state of the pentest finding changes in the Cobalt Platform.

1. Use the recipe by saving a copy into your workspace and click on Customize recipe to configure it according to your Jira Cloud project issue type.

2. Customize the recipe trigger and filter the events by a pentest or by an asset. Reference the recipe customization section on how to configure the trigger.

3. Configure the recipe to update the Jira issue status to In Progress.

   1. Select the Update status of issue in Jira action.
   2. Specify the Jira workflow Transition name that will transition the issue from the Acceptance Testing status to the In Progress status. For example, reject_fix, based on the example Jira workflow transitions.

   

   ⚠️ Remember to use the exact case-sensitive name of the expected Jira workflow transition.

   1. Save the editor, click on Exit to close the editor, and select Start recipe.

ℹ️ Follow the same customization steps for the [Cobalt > Jira Cloud] Move Jira issue to ‘Done’ when pentest finding fixed recipe. Make sure to use the correct Jira workflow transition name, such as accept_fix to move the issue status from Acceptance Testing to Done, as indicated in the example Jira workflow.

Frequently Asked Questions

Click to view answers.