Skip to content

BP-2638: Jira integration #321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jeff-matthews wants to merge 3 commits into
base: main
Choose a base branch
from
+589 −2
Open

BP-2638: Jira integration #321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
644fd62
wip: initial draft (no screenshots)
jeff-matthews Jun 23, 2026
9c1d46e
docs: copyedit initial draft of jira integration docs
jeff-matthews Jun 23, 2026
28fbc14
fix: broken link
jeff-matthews Jun 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -638,6 +638,20 @@
"integrations/google-secops/reference"
]
},
{
"group": "Atlassian",
"pages": [
{
"group": "Jira",
"pages": [
"integrations/atlassian/jira/configure",
"integrations/atlassian/jira/use",
"integrations/atlassian/jira/troubleshoot",
"integrations/atlassian/jira/reference"
]
}
]
},
{
"group": "ServiceNow",
"pages": [
Expand Down
197 changes: 197 additions & 0 deletions docs/integrations/atlassian/jira/configure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
---
title: Integrate BloodHound Enterprise with Jira
description: Learn how to install and configure the Jira integration for BloodHound Enterprise.
sidebarTitle: Install and configure
---

<img noZoom src="/assets/enterprise-edition-pill-tag.svg" alt="Applies to BloodHound Enterprise only" />

The BloodHound Enterprise Jira integration is a Jira Cloud app built on Atlassian Forge. It synchronizes BloodHound Enterprise attack path findings to Jira issues for remediation tracking.

This page shows you how to install the integration, connect a Jira project to BloodHound Enterprise, and configure synchronization behavior for Jira Software or Jira Service Management.

Use this integration to:

- Automatically synchronize BloodHound Enterprise findings with Jira every five minutes
- Map BloodHound zones to Jira priorities and due dates
- Automatically close Jira issues when findings are remediated

## Prerequisites

Before you configure the integration, confirm that you have the following:

| Platform | Requirements |
| --- | --- |
| **Jira** | <ul><li>A Jira Cloud instance (Data Center and Server are not supported)</li><li>A Jira Software or Jira Service Management project where you want the integration to create issues</li><li>Project Administrator or Site Administrator access in Jira</li><li>Atlassian Forge CLI installed (for self-hosted installations)</li><li>Network connectivity between Jira and BloodHound Enterprise</li></ul> |
| **BloodHound Enterprise** | <ul><li>A BloodHound Enterprise tenant</li><li>A BloodHound Enterprise [non-personal API key/ID pair](/integrations/bloodhound-api/working-with-api#create-a-non-personal-api-key%2Fid-pair) with the **Auditor** role</li></ul> |

## Install the integration

Install the integration in your Jira Cloud instance.

<Note>
Atlassian requires **Organization Administrator** or **Site Administrator** privileges to install Marketplace apps in Jira Cloud.
</Note>

<Steps>
<Step title="Open Atlassian Marketplace">
Go to [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for the BloodHound Enterprise Jira integration.
</Step>

<Step title="Start the installation">
1. Open the BloodHound Enterprise Jira integration listing.

1. Select **Get it now**.

1. Select the Jira Cloud site where you want to install the integration.
</Step>
<Step title="Review and install">
Review the installation details, then start the installation.
</Step>
</Steps>

## Configure connection settings

Configure the connection between Jira and BloodHound Enterprise using your BloodHound Enterprise non-personal API key/ID pair.

<Steps>
<Step title="Navigate to Connection Settings">
Navigate to the project where you want the integration to create issues.

1. Go to **Space Settings**.

1. In the **Apps** section, select **BloodHound Enterprise Integration**.

1. Click the **Connection Settings** tab.
</Step>
<Step title="Enter the connection values">
Enter the BloodHound Enterprise connection details.

| Field | Description |
| --- | --- |
| **BloodHound Enterprise Domain** | The URL of your BloodHound Enterprise tenant |
| **Token ID** | The API token ID used to authenticate requests |
| **Token Key** | The API token key used to sign and authorize requests |
</Step>

<Step title="Test the connection">

Before you can access the **Configuration** tab, you must successfully test the connection.

Click **Test Connection** and wait for Jira to confirm that it can reach your BloodHound Enterprise tenant.
</Step>
</Steps>

## Configure synchronization settings

After successfully testing the connection, you can configure how the integration should synchronize BloodHound Enterprise findings with your Jira project.

The **Configuration** tab provides the following settings:

| Setting | Purpose |
| --- | --- |
| **Issue Type / Request Type** | Chooses the Jira issue type for Jira Software projects or the request type for Jira Service Management projects |
| **BHE Domains** | Limits synchronization to the selected BloodHound Enterprise environments |
| **BHE Zones** | Limits synchronization to the selected BloodHound Enterprise zones, such as Tier Zero, Tier One, and Hygiene |
| **Priority Mapping** | Maps BloodHound Enterprise zones to Jira priorities |
| **Due Days** | Sets the due date window for each Jira priority |
| **Enable Auto-Closure** | Enables automatic closure of Jira issues when the corresponding BloodHound Enterprise finding is no longer detected (remediated) |
| **Cleanup Interval** | Defines how often the integration checks for orphaned issues |

<Note>
For Jira Service Management projects, the integration detects the project type automatically and replaces the **Issue Type** selector with a **Request Type** selector filtered to incident request types.

When the integration detects a Jira Service Management project, it automatically manages the following fields:

- Service Desk ID
- Request Type ID
- Request Type Field ID
- Incident Request Type Name
</Note>

<Steps>
<Step title="Choose the Jira issue model">
Select the Jira issue type that should represent BloodHound Enterprise findings (for example, Task, Bug, or Story).
</Step>

<Step title="Select the synchronization scope">
The integration dynamically fetches the available domains and zones from your BloodHound Enterprise tenant.

Select the domains and zones that you want to include in the synchronization.

1. Choose one or more **BHE Domains**.

1. Choose the **BHE Zones** that you want to synchronize with Jira.

- **Tier Zero**: Critical attack paths to high-value targets
- **Tier One**: Significant attack paths that require attention
- **Hygiene**: General security hygiene and best practices issues
</Step>

<Step title="Map priority and due dates">

Customize the priority and due date settings for each BloodHound Enterprise zone.

1. Map each BloodHound Enterprise zone to the Jira priority you want to use based on your organization's policies. The default priorities are:

| Zone | Default Jira Priority |
| --- | --- |
| **Tier Zero** | Highest |
| **Tier One** | Low |
| **Hygiene** | Lowest |

1. Set the number of due days for each priority. The default due days are:

| Jira Priority | Default Due Days |
| --- | --- |
| **Highest** | 3 days |
| **High** | 7 days |
| **Medium** | 14 days |
| **Low** | 30 days |
| **Lowest** | 90 days |

<Note>
Use **None** to disable due dates for specific priorities.
</Note>
</Step>

<Step title="Set auto-closure behavior">
The integration can automatically close Jira issues when the corresponding BloodHound Enterprise finding is no longer detected (remediated).

|Setting | Description | Options |
| --- | --- | --- |
| **Enable Auto-Closure** | Enables automatic closure of Jira issues when the corresponding BloodHound Enterprise finding is no longer detected (remediated) | Yes / No |
| **Cleanup Interval** | Defines how often the integration checks for (and closes) orphaned issues | 1-10 days |

When **Auto-Closure** is enabled:

- The cleanup interval runs hourly to check for orphaned issues.
- An issue is considered orphaned if the corresponding BloodHound Enterprise finding is no longer detected.
- The integration transitions orphaned issues to a **Done** status and adds a comment indicating that the issue has been automatically closed.

<Note>
The integration closes remediated issues according to the cleanup interval that you set. For example, if you set the interval to 3 days, the integration closes eligible issues no more than once every 3 days.
</Note>
</Step>

<Step title="Save and run the first synchronization">
After you have configured the integration, you can save the configuration and run the first synchronization from the **Configuration** tab.

1. Click **Save Configuration**.
1. Click **Run Sync Now** to trigger the first synchronization immediately.
</Step>
</Steps>

## Verify the configuration

After you save the configuration and run the first synchronization, confirm the following:

- Jira starts the synchronization successfully
- The configured project receives issues for findings that match the selected domains and zones
- The created issues use the expected priority and due date values
- Jira adds zone and domain labels that you can use for filtering

## Next steps

- [Use Jira with BloodHound Enterprise](/integrations/atlassian/jira/use)
- [Troubleshoot the Jira integration](/integrations/atlassian/jira/troubleshoot)
164 changes: 164 additions & 0 deletions docs/integrations/atlassian/jira/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
---
title: Jira integration design reference
description: Technical reference for the Jira integration, including its Atlassian Forge architecture, schedules, and API usage.
sidebarTitle: Design reference
---

<img noZoom src="/assets/enterprise-edition-pill-tag.svg" alt="Applies to BloodHound Enterprise only" />

This page explains how the BloodHound Enterprise Jira integration works. It covers the Atlassian Forge app architecture, authentication model, configuration inputs, scheduler behavior, and BloodHound API dependencies.

<Note>
For setup instructions, see [Install and configure the integration](/integrations/atlassian/jira/configure).
</Note>

## Integration type

The BloodHound Enterprise Jira integration is a **vulnerability management and remediation tracking** integration. It synchronizes BloodHound Enterprise attack path findings into Jira so security and operations teams can manage remediation work in Jira Software or Jira Service Management.

## Use cases

- Create Jira issues automatically for BloodHound Enterprise findings
- Route findings into Jira Software or Jira Service Management workflows
- Map BloodHound Enterprise zones to Jira priorities and due dates
- Keep Jira aligned with BloodHound Enterprise by closing remediated findings automatically

## Core design

The integration is built on the Atlassian Forge platform and uses a combination of scheduled tasks and API calls to synchronize data between BloodHound Enterprise and Jira.

| Component | Purpose |
| --- | --- |
| **Configuration UI** | Provides the Forge project settings page where Jira administrators enter BloodHound Enterprise connection details and synchronization settings |
| **Sync scheduler** | Pulls findings from BloodHound Enterprise every five minutes and creates Jira issues or incidents |
| **Cleanup scheduler** | Runs hourly and closes orphaned Jira issues after the corresponding BloodHound Enterprise findings no longer exist and auto-closure is enabled |
| **Jira project** | Hosts the created issues or incidents and provides the remediation workflow |

The integration follows the following workflow:

1. A Jira administrator installs the app from the Atlassian Marketplace.
1. A project administrator opens the Forge project settings page in Jira and enters the BloodHound Enterprise connection values.
1. The integration validates the credentials with **Test Connection**.
1. The sync scheduler polls BloodHound Enterprise every five minutes and creates one Jira issue or incident per matching finding.
1. The cleanup scheduler runs hourly and closes orphaned issues when the corresponding finding no longer exists in BloodHound Enterprise.

## Authentication and secrets

The integration uses the following security measures:

| Control | Implementation |
| --- | --- |
| **BloodHound Enterprise authentication** | HMAC-SHA256 signed requests |
| **Jira authorization** | Atlassian Forge OAuth 2.0 app scopes |
| **Secret storage** | Atlassian Forge encrypted Key-Value Storage (KVS) |
| **Data in transit** | HTTPS/TLS |
| **Data flow** | Direct API calls from Atlassian Forge to BloodHound Enterprise |

Each BloodHound Enterprise request includes:

1. `Authorization: bhesignature {token_id}`
1. `RequestDate: {rfc3339_timestamp}`
1. `Signature: {base64_hmac_signature}`

## Configuration inputs

The integration exposes the following user-configurable inputs:

| Input | Required | Description |
| --- | --- | --- |
| **BloodHound Enterprise Domain** | Yes | The URL of your BloodHound Enterprise tenant |
| **Token ID** | Yes | The API token ID used to authenticate requests |
| **Token Key** | Yes | The API token key used to sign requests |
| **Issue Type / Request Type** | Yes | The Jira issue type for Jira Software or the request type for Jira Service Management |
| **BHE Domains** | Yes | The BloodHound Enterprise environments to synchronize |
| **BHE Zones** | Yes | The BloodHound Enterprise zones to synchronize |
| **Priority Mapping** | Yes | The mapping between BloodHound Enterprise zones and Jira priorities |
| **Due Days** | Yes | The number of due days to assign for each mapped priority |
| **Enable Auto-Closure** | Yes | Enables or disables automatic closure of orphaned Jira issues |
| **Cleanup Interval** | Yes | The number of days between orphaned-issue closure checks |

The integration does not allow the Jira project key to be configured by the user because the app derives it from the Forge extension context.

## Jira project behavior

The integration adjusts its configuration model based on the Jira project type:

| Capability | Jira Software | Jira Service Management |
| --- | --- | --- |
| **Issue model** | Standard Jira issue type | Incident issue type with a selected request type |
| **Configuration field** | **Issue Type** | **Request Type** |
| **Project detection** | Uses the configured Jira Software issue type | Detects the JSM project automatically and populates incident request types |

## Sync model

The integration follows the following synchronization behavior:

| Setting | Value |
| --- | --- |
| **Sync interval** | Every 5 minutes |
| **Cleanup scheduler** | Every hour |
| **Cleanup interval** | 1 to 10 days, based on configuration |
| **Synchronization scope** | Selected BloodHound Enterprise domains and zones |
| **Manual action** | **Run Sync Now** triggers an immediate synchronization |

The integration creates one Jira issue or incident for each finding that matches the selected domains and zones. It prevents duplicate issue creation by storing Jira Entity Properties in `sync_metadata`, including `findingId` and `updatedAt`.

The provided Jira source documents also describe the following operational values for the synchronization workflow:

| Setting | Value |
| --- | --- |
| **Batch size** | 500 findings per batch |
| **Bulk Jira operations** | 50 issues per API call |
| **Invocation timeout** | 15 minutes |

## Synced Jira issue content

The integration requires each Jira issue or incident to store the attack path data needed for remediation tracking.

| Field | Contents |
| --- | --- |
| **Issue correspondence** | One unique Jira issue or incident for each BloodHound Enterprise finding |
| **Attack path title** | The issue corresponds to the attack path title |
| **Graph View link** | A deep link to the finding in BloodHound Enterprise |
| **Attack path data** | Relevant finding data retrieved from BloodHound Enterprise |
| **Remediation guidance** | Remediation steps associated with the finding |
| **Priority and due date** | Values derived from the configured zone-to-priority and due-day mappings |

## API endpoints

The integration depends on the following BloodHound Enterprise API endpoints:

| Endpoint | Purpose |
| --- | --- |
| [`GET /api/v2/available-domains`](/reference/search/get-available-domains) | Lists the environments available to the configured API token |
| [`GET /api/v2/asset-group-tags`](/reference/asset-isolation/get-asset-group-tags) | Lists the available BloodHound Enterprise zones used for synchronization filtering |
| [`GET /api/v2/domains/{domain_id}/available-types`](/reference/attack-paths/list-available-attack-paths) | Lists the attack path finding types for a selected environment |
| [`GET /api/v2/domains/{domain_id}/details`](/reference/attack-paths/list-domain-attack-paths-details) | Returns detailed attack path records for a selected environment and finding type |
| `GET /api/v2/assets/findings/{finding_type}/title.md` | Returns the title for a finding type |
| `GET /api/v2/assets/findings/{finding_type}/short_description.md` | Returns the short description for a finding type |
| `GET /api/v2/assets/findings/{finding_type}/short_remediation.md` | Returns the short remediation text for a finding type |
| `GET /api/v2/assets/findings/{finding_type}/long_remediation.md` | Returns the long remediation text for a finding type |

## Error handling

The integration calls for centralized API error handling with logging and graceful recovery when possible.

| Status | Meaning | Expected behavior |
| --- | --- | --- |
| `400` | Bad Request | Log the error and stop the current request gracefully |
| `401` | Unauthorized | Log the authentication failure and skip the request |
| `403` | Forbidden | Log the authorization failure and skip the request |
| `404` | Not Found | Log the missing endpoint or resource and skip retry |
| `429` | Too Many Requests | Log the rate-limit condition and apply a cooldown before a later run |
| `5xx` | Server Error | Log the failure and treat it as a critical synchronization error |

If an API request fails, the integration skips the failed operation, logs the error, and retries during a later synchronization interval.

## Platform dependencies

The integration relies on the following external dependencies:

| Dependency | Role |
| --- | --- |
| **BloodHound Enterprise API** | Source of attack path findings and finding metadata |
| **Atlassian Forge and Jira Cloud API** | Hosts the app runtime, configuration UI, and Jira issue handling |
Loading
Loading