diff --git a/docs/docs.json b/docs/docs.json index 8832cd32..98a9df8a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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": [ diff --git a/docs/integrations/atlassian/jira/configure.mdx b/docs/integrations/atlassian/jira/configure.mdx new file mode 100644 index 00000000..ef8e1335 --- /dev/null +++ b/docs/integrations/atlassian/jira/configure.mdx @@ -0,0 +1,198 @@ +--- +title: Integrate BloodHound Enterprise with Jira +description: Learn how to install and configure the Jira integration for BloodHound Enterprise. +sidebarTitle: Install and configure +hidden: true +--- + +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** | | +| **BloodHound Enterprise** | | + +## Install the integration + +Install the integration in your Jira Cloud instance. + + + Atlassian requires **Organization Administrator** or **Site Administrator** privileges to install Marketplace apps in Jira Cloud. + + + + + Go to [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for the BloodHound Enterprise Jira integration. + + + + 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. + + + Review the installation details, then start the installation. + + + +## Configure connection settings + +Configure the connection between Jira and BloodHound Enterprise using your BloodHound Enterprise non-personal API key/ID pair. + + + + 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. + + + 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 | + + + + + 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. + + + +## 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 | + + + 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 + + + + + Select the Jira issue type that should represent BloodHound Enterprise findings (for example, Task, Bug, or Story). + + + + 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 + + + + + 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 | + + + Use **None** to disable due dates for specific priorities. + + + + + 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. + + + 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. + + + + + 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. + + + +## 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) diff --git a/docs/integrations/atlassian/jira/reference.mdx b/docs/integrations/atlassian/jira/reference.mdx new file mode 100644 index 00000000..2f231fac --- /dev/null +++ b/docs/integrations/atlassian/jira/reference.mdx @@ -0,0 +1,165 @@ +--- +title: Jira integration design reference +description: Technical reference for the Jira integration, including its Atlassian Forge architecture, schedules, and API usage. +sidebarTitle: Design reference +hidden: true +--- + +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. + + + For setup instructions, see [Install and configure the integration](/integrations/atlassian/jira/configure). + + +## 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 | diff --git a/docs/integrations/atlassian/jira/troubleshoot.mdx b/docs/integrations/atlassian/jira/troubleshoot.mdx new file mode 100644 index 00000000..0ddbfa0b --- /dev/null +++ b/docs/integrations/atlassian/jira/troubleshoot.mdx @@ -0,0 +1,97 @@ +--- +title: Troubleshoot the Jira integration +description: Learn how to diagnose and resolve common Jira integration issues with BloodHound Enterprise. +sidebarTitle: Troubleshoot +hidden: true +--- + +Applies to BloodHound Enterprise only + +Use this page to troubleshoot common issues with the BloodHound Enterprise Jira integration. Start with the connection test, then validate the project configuration and synchronization scope. + +## Test Connection fails + +If **Test Connection** fails, the most common causes are: + +- The **Domain**, **Token ID**, or **Token Key** value is incorrect +- The BloodHound Enterprise token is expired or revoked +- The BloodHound Enterprise URL does not include `https://` +- Jira Cloud cannot reach the BloodHound Enterprise tenant + +To resolve the issue: + +1. Verify the **Domain**, **Token ID**, and **Token Key** values in the **Connection Settings** tab. +1. Confirm that the API token is still active in BloodHound Enterprise. +1. Generate a new token if the current token is invalid or compromised. +1. Confirm that the BloodHound Enterprise tenant is reachable from the internet. + +## Configuration tab is unavailable + +The **Configuration** tab stays unavailable until the connection test succeeds. + +To unlock the configuration options: + +1. Re-enter the Jira connection values. +1. Run **Test Connection** again. +1. Wait for Jira to confirm that it retrieved the available BloodHound Enterprise domains. + +## Jira does not create issues + +If the integration does not create issues after a synchronization, check the following: + +- At least one **BHE Domain** is selected +- At least one **BHE Zone** is selected +- BloodHound Enterprise currently has active findings in the selected domains and zones +- The issues were not already created by an earlier synchronization + +To verify the configuration: + +1. Open the **Configuration** tab. +1. Confirm the selected domains and zones. +1. Click **Run Sync Now**. +1. Check the target Jira project again after the synchronization starts. + +## Jira uses the wrong priority or due date + +The integration applies the priority and due date values from your configured mappings. + +To correct the issue: + +1. Review the **Priority Mapping** values for each BloodHound Enterprise zone. +1. Review the **Due Days** values for the Jira priorities that the integration assigns. +1. Save the updated configuration. +1. Run a manual synchronization to apply the new mapping to future updates and new issues. + +## Auto-closure does not close remediated issues + +If remediated findings do not close in Jira, the most common causes are: + +- **Enable Auto-Closure** is disabled +- The configured cleanup interval has not elapsed yet +- The Jira workflow does not provide a transition to **Done** +- The integration has not completed a recent synchronization for the configured scope + +To resolve the issue: + +1. Confirm that **Enable Auto-Closure** is enabled. +1. Review the configured **Cleanup Interval**. +1. Confirm that the Jira project workflow supports the transition to **Done**. +1. Run a manual synchronization, then wait for the hourly cleanup scheduler to evaluate orphaned issues. + +## Jira Service Management request types do not appear + +If the request type selector is empty in Jira Service Management: + +1. Confirm that the target project is a Jira Service Management project. +1. Confirm that the project has incident request types available. +1. Refresh the configuration page and rerun **Test Connection** if needed. + +## Common configuration messages + +The following error messages may appear in the configuration screen when performing actions: + +| Message | Cause | Solution | +| --- | --- | --- | +| `Sync already in progress` | Another synchronization is still running | Wait for the current synchronization to finish before you run another manual synchronization | +| `No domains configured` | No BloodHound Enterprise domains are selected | Select one or more domains in the **Configuration** tab and save the change | +| `Invalid domain format` | The BloodHound Enterprise URL is malformed | Enter the full tenant URL and include `https://` | diff --git a/docs/integrations/atlassian/jira/use.mdx b/docs/integrations/atlassian/jira/use.mdx new file mode 100644 index 00000000..6fed49c8 --- /dev/null +++ b/docs/integrations/atlassian/jira/use.mdx @@ -0,0 +1,104 @@ +--- +title: Use Jira with BloodHound Enterprise +description: Learn how to review and manage Jira issues created from BloodHound Enterprise findings. +sidebarTitle: Manage Jira issues +hidden: true +--- + +Applies to BloodHound Enterprise only + +After you complete the [installation and configuration](/integrations/atlassian/jira/configure), the integration synchronizes BloodHound Enterprise findings into Jira every five minutes. This page explains how the synchronized issues are structured and how to work with them in Jira. + +## Jira issue model + +The integration creates one Jira issue or incident for each synchronized BloodHound Enterprise finding. + +| Jira object | Purpose | +| --- | --- | +| **Issue or incident** | Represents one BloodHound Enterprise finding | +| **Priority** | Reflects the zone-to-priority mapping that you configured | +| **Due date** | Uses the due-day rule for the mapped Jira priority | +| **Labels** | Adds zone and domain labels so you can filter and report on the findings | +| **Auto-closure comment** | Explains that the finding was remediated when Jira closes the issue automatically | + + + If you connect a Jira Service Management project, the integration uses the configured request type and incident workflow instead of a standard Jira Software issue type. + + +## Jira issue format + +When the integration creates a Jira issue, it follows a specific format to ensure that all relevant information is included: + + + + The issue summary includes the zone, domain, affected principal, and finding ID. + + **Example**: [Tier-Zero] CORP.LOCAL - Administrator (12345) + + + + The issue description includes the finding title, Graph View link, finding description, impact details, context, and remediation guidance. + + | Field | Contents | + | --- | --- | + | **Finding Title** | The name of the attack path finding, such as _GenericWrite Privileges on Tier Zero Objects_ | + | **BHE Link** | A direct link to the finding in the BloodHound Enterprise graph view | + | **Description** | An explanation of what the privilege allows and why it is a concern | + | **Impact** | The number of affected assets and exposure paths | + | **Context** | The severity level, finding type, environment details, and finding IDs | + | **Affected Entities** | Details about the source and target principals involved, including name, type, domain, object ID, and status | + | **Relationship** | Information about the relationship, including whether it is ACL-based and inherited | + | **Status** | Whether the finding is accepted plus its creation and update timestamps | + | **Remediation Guidance** | Both the quick fix and the detailed, step-by-step remediation steps | + + + + Labels include zone and domain identifiers, which allow you to filter and report on the findings in Jira. + + - **Example (zone)**: tier-zero, tier-one, hygiene + + - **Example (domain)**: corp-local + + + + The dates include the start date, which Jira sets when it creates the issue, and the due date, which the integration calculates from the configured priority mapping. + + **Example**: + + - Start date: Jun 20, 2026 + - Due date: Jun 23, 2026 + + + + The priority reflects the zone-to-priority mapping in the integration's configuration settings. + + **Example**: Highest + + + +## Synchronization behavior + +The integration keeps Jira aligned with BloodHound Enterprise automatically: + +- It runs synchronization every five minutes +- It creates issues for new findings and updates existing issues when finding details change +- It avoids duplicates by tracking synchronization metadata on the Jira issues +- It runs a cleanup scheduler hourly and closes orphaned issues when **Auto-closure** is enabled and the cleanup interval is met + + + No action is required for automatic synchronization. The integration will automatically create and update Jira issues based on the configured settings. + + If you need to manually trigger a synchronization, you can do so from the integration's [configuration settings](/integrations/atlassian/jira/configure#configure-synchronization-settings) in Jira. + + +## Review synchronized findings + +Reviewing the synchronized findings in Jira allows you to triage and manage security issues identified by BloodHound Enterprise. + +Use the synchronized issues the same way you manage other operational work in Jira: + +- Filter by labels, priority, or due date to focus on the findings you want to triage first. +- Assign findings to the team that owns remediation +- Update workflow state as triage and remediation progress +- Add comments or work notes that document investigation and closure decisions +- Use the Graph View link to move from Jira back to the BloodHound Enterprise finding when you need more context diff --git a/docs/integrations/overview.mdx b/docs/integrations/overview.mdx index f078b25a..d0a3ae09 100644 --- a/docs/integrations/overview.mdx +++ b/docs/integrations/overview.mdx @@ -78,15 +78,28 @@ The following integrations are officially supported by SpecterOps. title="Google SecOps" href="/integrations/google-secops/configure" > - The BloodHound Enterprise Google Security Operations (SecOps) is an integration that automatically syncs Bloodhound Enterprise (BHE) Attack Path findings to SecOps cases for remediation tracking. This integration enables security teams to manage and track the remediation of Active Directory and Azure Attack Paths directly within their existing SecOps workflows. + The BloodHound Enterprise Google Security Operations (SecOps) is an integration that automatically synchronizes Bloodhound Enterprise (BHE) Attack Path findings to SecOps cases for remediation tracking. This integration enables security teams to manage and track the remediation of Active Directory and Azure Attack Paths directly within their existing SecOps workflows. | | | | --- | --- | | **Supported actions** | | - | **Common use cases** | | + | **Common use cases** | | | **Integration instructions** | Configure the Google SecOps integration | +{/* + The BloodHound Enterprise Jira integration is a Jira Cloud app built on Atlassian Forge that automatically synchronizes BloodHound Enterprise Attack Path findings to Jira issues for remediation tracking. This integration enables security teams to manage and track the remediation of Active Directory and Azure Attack Paths directly within Jira Software and Jira Service Management workflows. + + | | | + | --- | --- | + | **Supported actions** | | + | **Common use cases** | | + | **Integration instructions** | Configure the Jira integration | + */} +