Welcome to Bugcrowd's Product Documentation Center

You'll find comprehensive guides and documentation to help you start working with Bugcrowd as quickly as possible.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

JIRA

Our integration with JIRA enables you to bridge the gap between Crowdcontrol and your development team. It will provide you the ability to easily and efficiently integrate vulnerabilities found within your bug bounty program into JIRA, limiting any disruption to your current SDLC processes.

Enabling Bugcrowd's bi-directional JIRA integration will deliver the following functionalities:

  • A JIRA ticket will automatically be generated, transferring all the vulnerability details from Crowdcontrol upon moving a submission from Triaged to a Unresolved state
  • Upon fixing the vulnerability, when a developer moves a JIRA ticket to a Closed state, the associated submission will automatically be closed (moved to a Resolved state) in Crowdcontrol
  • All activity (comments, priority changes, ect.) on a single submission within Crowdcontrol will automatically be updated on the associated ticket within JIRA
  • All JIRA ticket fields can be mapped to Crowdcontrol submission fields using our advanced custom field mapping settings

Every ticket is created with the label "bugcrowd-{program code}" in order to make searching for the tickets within Jira easy. If you're not sure about your program code, you can find it in the URI for your program. For instance, a program available at bugcrowd.com/xyz would have the code "xyz". The label created for every JIRA ticket would be "bugcrowd-xyz."

When you set up the integration between JIRA and Crowdcontrol, you can do it on a per program basis. This just means that you can choose the bounty programs you want to integrate with JIRA.

Specific Role Required to Set Up the JIRA Integration

You must be an owner to set up the JIRA integration with Crowdcontrol, and you must have administrator access to JIRA.

Set-Up On-Premise JIRA

We require clients to whitelist the IPs mentioned below. The IP’s are a cluster of squid proxies that provide high availability for outgoing integration requests.

IPs:

  • 52.1.126.10
  • 52.86.183.27
  • 52.86.229.29

Port:

  • 443

Troubles Setting Up On-Premise JIRA

Please contact us at support@bugcrowd.com. The port may vary depending on your JIRA configuration - most people will put JIRA on 443 SSL / TLS default, however, this can vary from company to company.

Connect Crowdcontrol to JIRA

1. Go to the Program Settings

Select the "Integrations" tab.

Program settings

Program settings

2. Select JIRA Integration

Find the "Atlassian JIRA" option from the list of available services and click the "Configure" button to display the JIRA Integration Page.

Connect to JIRA

Connect to JIRA

3. Authorize Crowdcontrol to Access JIRA

You need to provide Crowdcontrol with the following information on the JIRA Integration Page:

  • Name: A descriptive name for the integration. The name you choose can be anything you want to help you identify the purpose of the integration
  • Site: The public URL for your JIRA domain (e.g., https://bugcrowd.atlassian.net)
  • Username: The username for the administrator account you want to use to connect to your JIRA server
  • Password: The password for the administrator account you want to use to connect to your JIRA server

After you have entered the required information for your JIRA server, click the "Save and Connect" button.

Authorize

Authorize

Project and Issue Type Configuration

Once Crowdcontrol and JIRA are connected, in order to enable the integration you will need to select the JIRA project that issues will be created under, and the issue type that will be created for a Bugcrowd
submission.

In our example, we're going to use the following project / issue type combination:

  • Project: Bugcrowd Jira Example
  • Issue Type: Bug

1. Navigate to the Project Configuration Setting

On the JIRA integration settings page, select the Project Configuration tab on the left-hand side

Select a project from the list

Select a project from the list

2. Map to Your JIRA Project

Use the drop-down selection to select the JIRA project - after you complete this step, your integration settings will be saved and issues will be created in the project that you selected

3. Navigate to the Issue Creation Setting

On the JIRA integration settings page, select the Issue Creation tab on the left-hand side

4. Map the JIRA Issue Type

Use the drop-down selection to select the JIRA issue type - after you complete this step, your integration settings will be saved and the tickets created will be labeled as the issue type you selected

Select and Issue Type from the list

Select and Issue Type from the list

Enabling The Integration

Once you have selected the JIRA project and issue type, the Integration Status button will become available. In it's default state, the integration is off, however if you switch it on at this point you will be able to manually push submissions upstream to Jira.

Integration Status

Integration Status

1. Click the Integration Status toggle

Enable the integration

Enable the integration

Once the integration status is On, you will be able to push Bugcrowd submissions up to JIRA manually.

The screenshot below shows the right hand sidebar on an individual submission. As you can see the push upstream button is available under the References section.

Push Upstream

Push Upstream

Workflow Tip

Currently the Bugcrowd JIRA integration supports automatic creation of a JIRA ticket when the submission is changed to the Unresolved state. This should suit the majority of workflows, as it's often undesirable for a submission to come into JIRA unless it's absolutely know to be a vulnerability. We do, however, understand that a lot of our customers use different vulnerability triage, software development and issue resolution workflows. Because of this we have provided the Push Upstream functionality to enable submissions to be manually pushed into JIRA at any point in the workflow.

Automatic JIRA Ticket Creation

1. Turn On Automatic JIRA Ticket Creation

In the Issue Creation settings, use the sliding toggle to turn the Automatic JIRA Ticket Creation functionality on - after you complete this step, your integration settings will be saved and tickets will be automatically created in JIRA when you move a submission from Triaged to Unresolved in Crowdcontrol

Switching on Automatic JIRA Ticket Creation

Switching on Automatic JIRA Ticket Creation

Activate Bi-Directional JIRA

Activating bi-directional JIRA functionality will enable Crowdcontrol to automatically update an issue in JIRA to a pre-determined closed state when a submission is marked as Resolved in Crowdcontrol. It also allows Crowdcontrol to track when a submission enters the closed state in JIRA, and updates the submission to Resolved in Crowdcontrol.

To set up bi-directional JIRA functionality, follow the following steps:

1. Navigate to the Resolving Issues Setting

On the JIRA integration settings page, select the Resolving Issues tab on the left-hand side

2. Select a JIRA Closed Status

Use the drop-down selection to select the JIRA closed status. This will identify the status within your JIRA workflow that will map to the Bugcrowd Resolved state. Any ticket that is transitioned to the selected closed status in JIRA will automatically be updated to Resolved in Crowdcontrol. Conversely, any submission that is transitioned to the Resolved state in Crowdcontrol will automatically be updated to the selected closed status in JIRA.

In the below example, we choose the Done closed status.

Choosing the Done closed state

Choosing the Done closed state

3. Enable Crowdcontrol to JIRA Updates

Use the check box labeled when I close an issue in Crowdcontrol, automatically close the corresponding issue in JIRA to activate communication from Crowdcontrol to JIRA. In doing so, submissions moved to Resolved in Crowdcontrol associated with issues in JIRA will automatically close the issue - a blue box with a white check mark will indicate this functionality is active

Checkbox enabling Crowdcontrol to JIRA link

Checkbox enabling Crowdcontrol to JIRA link

4. Turn On Bi-Directional JIRA

Use the sliding toggle to turn on the Two Way JIRA Integration - once turned on, Crowdcontrol will generate a webhook and, if you are a JIRA admin, the webhook will automatically update in your JIRA settings. At this time, bi-directional functionality will be activated without having to create the webhook manually in your JIRA settings.

JIRA Webhook Permissions

Creating a webhook automatically in JIRA requires system administrator privileges. We understand that many of our customers don't have direct access to the JIRA webhook configuration, so we provide you with step by step instructions detailing how to clearly and concisely communicate the webhook requirements to your JIRA administrator.

To learn more click here

Toggling on the Two Way JIRA Integration

Toggling on the Two Way JIRA Integration

Workflow Tip

By default the JIRA webhook is created with JQL scoping issue monitoring to the project selected in the basic configuration section. If you move JIRA tickets between projects regularly, any ticket updated in a project outside of the project scope will be ignored.

In the below screenshot, we show an example JIRA webhook configuration with the default JQL set to Project = 10400 (corresponding to the ID of the project selected in the basic config).

If you would like to monitor JIRA issues across multiple projects, you can manually adjust the JQL in the webhook to encompass different selection criteria.

One example might be to use the label that is automatically set on JIRA tickets when created through Bugcrowd. More information about configuring labels can be found in the Advanced Field Mapping section below, but for now let's assume all tickets will be created with the label bugcrowd-bugcrowdongoing. We can create a custom JQL query that, instead of scopes issues to the project, looks for any issues with that label.

The screenshot below shows JQL scoping issues to the project with ID 10400.

The screenshot below shows an updated JIRA webhook with scoping changed to the label bugcrowd-bugcrowdongoing.

5. Activate Communication From JIRA to Crowdcontrol

Use the check box labeled when I close an issue in JIRA, automatically close the corresponding issue in Crowdcontrol to activate communication from JIRA to Crowdcontrol. In doing so, closed issues in JIRA associated with submissions in Crowdcontrol will automatically move the submission to Resolved - a blue box with a white check mark will indicate this functionality is active

Finishing this setup will activate bi-directional JIRA integration between JIRA and Crowdcontrol enabling your team to automatically track vulnerabilities from validation to remediation

Default Field Mapping

By default the JIRA integration maps certain elements of a Bugcrowd submission to fields in JIRA. The most basic case consists of the JIRA Description and Summary fields.

The Description Field and Comments

Crowdcontrol uses a template to map submission details and comments into the Description field in JIRA. This field keeps an up-to-date representation of what the submission looks like in Crowdcontrol. The following fields are output into the template.

  • A link to the issue in Crowdcontrol
  • The current submission substate (e.g. Unresolved, Resolved)
  • Priority
  • Reward Amount
  • Reference Number
  • Description
  • HTTP Request
  • Chosen VRT Category
  • Bug URL
  • A list of comments

Comments are appended to the description automatically as they are added in Crowdcontrol. Regularly the conversation between Bugcrowd Application Security Engineers and the researcher reveals more information about a submission and helps to clarify certain details. It's important that we provide that information in the JIRA ticket.

The screenshot below displays the output of the comments feed into the JIRA ticket.

Default Mapped Fields

By default, the Crowdcontrol submission Title field is mapped to the JIRA Summary field.

Advanced Field Mapping

Crowdcontrol provides an intuitive UI to make it easy for you to map Crowdcontrol submission fields to your JIRA ticket fields. We support the following mapping types:

  • Apply a Bugcrowd submission attribute to a text field in JIRA
  • Apply a Bugcrowd submission custom field to a text field in JIRA
  • Apply a static string to a text field in JIRA
  • Apply one or more text strings to the labels field in JIRA
  • Apply one or more text strings to a custom label field in JIRA
  • Select a predefined option from a single select list field in JIRA
  • Select one or more predefined options from a multiple select list field in JIRA

Any fields that are required to create an issue will be denoted by an asterisk. You must map these for the integration to successfully create issues.

To map your JIRA ticket fields to Crowdcontrol, follow the steps below:

Apply a Bugcrowd submission attribute to a text field in JIRA

1. On the JIRA integration settings page, select the Field Mapping tab on the left-hand side

2. Select the JIRA field

To add a custom mapped field use the drop-down field selection process under the add a field mapping section - Crowdcontrol uses an API to pull all fields in your JIRA project, these fields will be selectable using drop-down selection. First, select the JIRA field to be mapped to Crowdcontrol.

In the below example, we have a custom field configured in JIRA called Reference Number so we select that from the list.

3. Map the JIRA field to the Crowdcontrol field

Once you have selected the desired JIRA field, then map that field to the associated Crowdcontrol submission field.

In the example below we choose the Crowdcontrol Reference Number field to map to the JIRA Reference Number field.

4. To finalize and add the mapping, select the + sign on the right-hand side

You can remove a mapping at any time by clicking the little trashcan icon in the mapped fields list.

Apply a Bugcrowd submission custom field to a text field in JIRA

Crowdcontrol allows administrators to define custom submission fields at the program level. This means that you can add information specific to your organization on a per-submission basis. The following example outlines how to map a custom Crowdcontrol field to a JIRA field.

1. Choose a JIRA field

In this example we have a custom JIRA field configured called Root Cause. We will be mapping this to a custom Crowdcontrol field.

2. Map the JIRA field to the Crowdcontrol field

In Crowdcontrol we have a custom Root Cause field configured.

When we drop down the list of fields available for JIRA mapping, the Root Cause custom field is available. Choose the [Custom Field] Root Cause item and click the small + to map the field.

Additional Field Mapping

The sky is pretty much the limit with advanced field mapping. In the following screenshot we display a large array of different field mappings.

Set Up Webhook (Non-JIRA Admin Users)

If you are not a JIRA administrator, the Crowdcontrol generated webhook used to set up bi-directional JIRA functionality will not automatically update in your JIRA settings. Therefore, to ensure the bi-directional JIRA functionality works, you will have to reach out to your JIRA admin to set up the webhook in JIRA.

If you try to enable the Two Way JIRA Integration option and you do not have permission to create webhooks, Crowdcontrol will detect this and display the following instructions customized for your project configuration.

JIRA