Cortex XSOAR integration design reference

This document provides technical design details and API reference information for the BloodHound Enterprise integration with Cortex XSOAR. For configuration instructions, see Configure the integration.

Integration type

The SpecterOps BloodHound Enterprise integration is a vulnerability management integration that enables automated retrieval of attack path findings from BloodHound Enterprise into Cortex XSOAR. This streamlines incident creation and investigation for Active Directory and Microsoft Azure environments.

Use cases

Automated attack path detection and incident creation

Automatically fetch new attack paths from BloodHound Enterprise
Create incidents in XSOAR for each detected attack path
Filter incidents by domain and finding type
Track attack paths with granular timestamp-based deduplication

Asset information retrieval

Retrieve detailed information about Active Directory and Azure assets
Enrich incident data with asset details including object IDs, names, and properties
Support for both directory types (User, Computer, Group, Container, Domain, GPO, etc.) and Azure types (AZApp, AZGroup, AZUser, AZRole, AZTenant, AZServicePrincipal, etc.)

Path analysis and investigation

Check if attack paths exist between two principals in the environment
Search for objects by name to retrieve their object IDs
Analyze relationships between principals and assets

Multi-domain and multi-finding type support

Support for multiple Active Directory domains
Filter by specific domains or finding types
Track attack paths per domain and finding type combination

Authentication

The integration uses HMAC-based signature authentication with the following process:

Generate HMAC signature using SHA-256 with the token key
Include token ID, request date, and signature in request headers
Format: Authorization: bhesignature {token_id}
Include RequestDate header in ISO format
Include Signature header as base64-encoded HMAC digest

Configuration parameters

Parameter	Display Name	Type	Required	Description
`url`	Server URL	String	Yes	The BloodHound Enterprise server URL (e.g., `bhe.example.com` or `https://bhe.example.com`)
`token_id`	Token ID	String	Yes	The API token ID for authentication
`token_key`	Token Key	Password	Yes	The API token key for HMAC signature authentication
`finding_domain`	Selected Environments	String	No	Comma-separated list of domain names to monitor, or “all” for all domains. Default: “all”
`finding_category`	Selected Finding Types	String	No	Comma-separated list of finding types to monitor, or “all” for all types. Default: “all”
`incidentFetchInterval`	Incident Fetch Interval (minutes)	Number	No	The interval in minutes between incident fetches. Default: 10 minutes
`isFetch`	Fetch incidents	Boolean	No	Enable automatic incident fetching. Default: false
`proxy_url`	Custom Proxy URL	String	No	Custom proxy server URL (optional)
`proxy_username`	Proxy Username	String	No	Username for proxy authentication (if required)
`proxy_password`	Proxy Password	Password	No	Password for proxy authentication (if required)
`insecure`	Trust any certificate (not secure)	Boolean	No	Skip SSL certificate verification. Default: false
`proxy`	Use system proxy settings	Boolean	No	Use system proxy settings. Default: false

Commands and outputs

test-module

Tests the connection to the BloodHound Enterprise API. Arguments: None Context outputs: None Human-readable output:

Success: “ok”
Failure: Error message indicating the specific failure reason (Unauthorized, Bad Request, Forbidden, Server Error, DNS resolution error, etc.)

bhe-get-object-id

Retrieves object IDs for one or more objects by their names. Arguments:

Argument	Type	Description	Required
`object_names`	String	Comma-separated list of object names to search for	Yes

Context outputs:

Path	Type	Description
`SpecterOpsBHE.Object.Name`	String	The object name that was searched
`SpecterOpsBHE.Object.Status`	String	Status of the search (“success” or “error”)
`SpecterOpsBHE.Object.Message`	String	Status message
`SpecterOpsBHE.Object.Data`	Array	Array of matching objects with id, name, and type

Human-readable output: Object ID Search Results

Object Name	Status	Object ID	Type
`user@example.com`	success	S-1-5-21-…	User
`COMPUTER01`	success	S-1-5-21-…	Computer

bhe-fetch-asset-info

Retrieves detailed information about one or more assets by their object IDs. Arguments:

Argument	Type	Description	Required
`object_ids`	String	Comma-separated list of object IDs to fetch information for	Yes

Context outputs:

Path	Type	Description
`SpecterOpsBHE.Asset.ObjectId`	String	The object ID
`SpecterOpsBHE.Asset.Name`	String	Asset name
`SpecterOpsBHE.Asset.Type`	String	Asset type (User, Computer, AZUser, AZApp, etc.)
`SpecterOpsBHE.Asset.Status`	String	Status of the fetch operation
`SpecterOpsBHE.Asset.Data`	Object	Complete asset data including properties and related entity counts

Human-readable output: Asset Information

Object ID	Name	Type	Status
S-1-5-21-…	`user@example.com`	User	success

For Azure objects, the response includes additional related entity counts such as group membership counts, role assignments, inbound/outbound control counts, and abusable app role assignments (for service principals).

bhe-does-path-exist

Checks if an attack path exists between two principals in the BloodHound Enterprise graph. Arguments:

Argument	Type	Description	Required
`FromPrincipal`	String	Object ID of the source principal	Yes
`ToPrincipal`	String	Object ID of the target principal	Yes

Context outputs:

Path	Type	Description
`SpecterOpsBHE.Path.Exists`	Boolean	Whether a path exists between the principals
`SpecterOpsBHE.Path.FromPrincipal`	String	Source principal object ID
`SpecterOpsBHE.Path.ToPrincipal`	String	Target principal object ID
`SpecterOpsBHE.Path.Status`	String	Status of the path check operation

Human-readable output: Path Existence Check

From Principal	To Principal	Path Exists	Status
S-1-5-21-…	S-1-5-21-…	true	success

fetch-incidents

Fetches attack path findings from BloodHound Enterprise and creates incidents in XSOAR (automatically executed when isFetch is enabled). Arguments: None Context outputs:

Path	Type	Description
`SpecterOpsBHE.Incident.Name`	String	Incident name (format: `{INSTANCE} - {DOMAIN} - {PATH_TITLE}`)
`SpecterOpsBHE.Incident.Type`	String	Incident type: “SpecterOpsBHE Attack Path”
`SpecterOpsBHE.Incident.Severity`	Number	Severity level (1=Low, 2=Medium, 3=High, 4=Critical)
`SpecterOpsBHE.Incident.AttackId`	String	Unique attack path ID
`SpecterOpsBHE.Incident.Domain`	String	Domain name where the attack path was detected
`SpecterOpsBHE.Incident.PathTitle`	String	Human-readable title of the attack path
`SpecterOpsBHE.Incident.FindingType`	String	Finding type identifier
`SpecterOpsBHE.Incident.ImpactPercentage`	Number	Impact percentage (0-100)
`SpecterOpsBHE.Incident.ImpactCount`	Number	Number of impacted principals
`SpecterOpsBHE.Incident.ExposurePercentage`	Number	Exposure percentage (0-100)
`SpecterOpsBHE.Incident.ExposureCount`	Number	Number of exposed principals
`SpecterOpsBHE.Incident.ImpactedPrincipal`	String	Object ID of the impacted principal
`SpecterOpsBHE.Incident.ImpactedPrincipalName`	String	Name of the impacted principal
`SpecterOpsBHE.Incident.ImpactedPrincipalKind`	String	Type of the impacted principal
`SpecterOpsBHE.Incident.ImpactedPrincipalObjectId`	String	Object ID of the impacted principal
`SpecterOpsBHE.Incident.NonTierZeroPrincipal`	String	Object ID of the non-tier-zero principal (if applicable)
`SpecterOpsBHE.Incident.NonTierZeroPrincipalName`	String	Name of the non-tier-zero principal (if applicable)
`SpecterOpsBHE.Incident.ObjectIds`	String	Comma-separated list of object IDs involved
`SpecterOpsBHE.Incident.ObjectNames`	String	Comma-separated list of object names involved
`SpecterOpsBHE.Incident.ShortDescription`	String	Short description of the attack path
`SpecterOpsBHE.Incident.ShortRemediation`	String	Short remediation guidance
`SpecterOpsBHE.Incident.LongRemediation`	String	Detailed remediation guidance
`SpecterOpsBHE.Incident.CreatedAt`	String	Timestamp when the attack path was created
`SpecterOpsBHE.Incident.UpdatedAt`	String	Timestamp when the attack path was last updated
`SpecterOpsBHE.Incident.Accepted`	Boolean	Whether the attack path has been accepted
`SpecterOpsBHE.Incident.AcceptedUntil`	String	Date until which the attack path is accepted (if applicable)

Fetch logic:

Lock Mechanism: Uses integration context to prevent concurrent fetch operations
Domain Filtering: Fetches available domains and filters by finding_domain parameter
Finding Type Collection: Collects available finding types for each domain
Finding Type Filtering: Filters finding types by finding_category parameter
Path Metadata Fetching: Retrieves titles, descriptions, and remediation guidance for each finding type
Incremental Fetching: Uses timestamp-based filtering to only fetch new attack paths since last run
Granular Tracking: Tracks timestamps per {domain_name}:{finding_type} combination for precise deduplication
Pagination: Handles pagination for large result sets (up to 1000 results per page)
Incident Creation: Creates one incident per attack path with all relevant metadata

API endpoints

The integration uses the following BloodHound Enterprise API v2 endpoints:

Endpoint	Path	Description
`available_domain`	`/api/v2/available-domains`	Get list of available domains
`search`	`/api/v2/search?q={query}`	Search for objects by name
`dictionary_types`	`/api/v2/{obj_type}s/{object_id}`	Get directory object details

Supported object types

Active Directory types

User
Computer
Group
Container
Domain
GPO (Group Policy Object)
Aiaca
Rootca
Enterpriseca
Ntauthstore
Certtemplate
OU (Organizational Unit)

Azure types

AZApp (Azure Application)
AZGroup (Azure Group)
AZUser (Azure User)
AZRole (Azure Role)
AZTenant (Azure Tenant)
AZServicePrincipal (Azure Service Principal)
AZAutomationAccount (Azure Automation Account)

Error handling

The integration implements comprehensive error handling with specific exception types:

Exception Type	HTTP Status	Description
`BloodHoundBadRequestException`	400	Invalid request parameters
`BloodHoundUnauthorizedException`	401	Authentication failure
`BloodHoundForbiddenException`	403	Insufficient permissions
`BloodHoundNotFoundException`	404	Resource not found
`BloodHoundRateLimitException`	429	Rate limit exceeded
`BloodHoundServerErrorException`	500+	Server errors

Retry logic

Automatic retry for rate limit (429) and server errors (500, 502, 503, 504)
Maximum of 3 retry attempts
Immediate retry without exponential backoff

Memory limitation handling

Gracefully handles memory limitation errors for large queries (especially for AZTenant)
Returns appropriate error messages when memory limits are encountered
Sets related entity counts to 0 when memory limitations occur

Get Started with BloodHound

Install a Data Collector

Collect Data

OpenGraph

OpenHound

Analyze Attack Path Data

Manage BloodHound

API & Integrations

On-premises BloodHound Enterprise

Resources

Cortex XSOAR integration design reference

Integration type

Use cases

Authentication

Configuration parameters

Commands and outputs

test-module

bhe-get-object-id

bhe-fetch-asset-info

bhe-does-path-exist

fetch-incidents

API endpoints

Supported object types

Active Directory types

Azure types

Error handling

Retry logic

Memory limitation handling

​Integration type

​Use cases

​Authentication

​Configuration parameters

​Commands and outputs

​test-module

​bhe-get-object-id

​bhe-fetch-asset-info

​bhe-does-path-exist

​fetch-incidents

​API endpoints

​Supported object types

​Active Directory types

​Azure types

​Error handling

​Retry logic

​Memory limitation handling

Integration type

Use cases

Authentication

Configuration parameters

Commands and outputs

test-module

bhe-get-object-id

bhe-fetch-asset-info

bhe-does-path-exist

fetch-incidents

API endpoints

Supported object types

Active Directory types

Azure types

Error handling

Retry logic

Memory limitation handling