> ## Documentation Index > Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt > Use this file to discover all available pages before exploring further. # List domain attack paths details > Lists detailed data about attack paths for a domain. __Note:__ `ImpactCount`, `ImpactPercentage`, `ExposureCount`, `ExposurePercentage` and `Severity` will have a value other than zero when butterfly analysis is enabled. Applies to BloodHound Enterprise only ## OpenAPI ````yaml get /api/v2/domains/{domain_id}/details openapi: 3.0.3 info: title: BloodHound API contact: name: BloodHound Enterprise Support url: https://bloodhound.specterops.io/ email: support@specterops.io license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: v2 description: > This is the API that drives BloodHound Enterprise and Community Edition. Endpoint availability is denoted using the `Community` and `Enterprise` tags. Contact information listed is for BloodHound Enterprise customers. To get help with BloodHound Community Edition, please join our [Slack community](https://ghst.ly/BHSlack/). ## Authentication The BloodHound API supports two kinds of authentication: JWT bearer tokens and Signed Requests. For quick tests or one-time calls, the JWT used by your browser may be the simplest route. For more secure and long lived API integrations, the recommended option is signed requests. ### JWT Bearer Token The API will accept calls using the following header structure in the HTTP request: ``` Authorization: Bearer $JWT_TOKEN ``` If you open the Network tab within your browser, you will see calls against the API made utilizing this structure. JWT bearer tokens are supported by the BloodHound API, however it is recommended they only be used for temporary access. JWT tokens expire after a set amount of time and require re-authentication using secret credentials. ### Signed Requests Signed requests are the recommended form of authentication for the BloodHound API. Not only are signed requests better for long lived integrations, they also provide more security for the requests being sent. They provide authentication of the client, as well as verification of request integrity when received by the server. Signed requests consist of three main parts: The client token ID, the request timestamp, and a base64 encoded HMAC signature. These three pieces of information are sent with the request using the following header structure: ``` Authorization: bhesignature $TOKEN_ID RequestDate: $RFC3339_DATETIME Signature: $BASE64ENCODED_HMAC_SIGNATURE ``` To use signed requests, you will need to generate an API token. Each API token generated in the BloodHound API comes with two parts: The Token ID, which is used in the `Authorization` header, and the Token Key, which is used as part of the HMAC hashing process. The token ID should be considered as public (like a username) and the token key should be considered secret (like a password). Once an API token is generated, you can use the key to sign requests. For more documentation about how to work with authentication in the API, including examples of how to generate an API token in the BloodHound UI, please refer to this support doc: [Working with the BloodHound API](https://bloodhound.specterops.io/integrations/bloodhound-api/working-with-api). #### Signed Request Pseudo-code Example First, a digest is initiated with HMAC-SHA-256 using the token key as the digest key: ```python digester = hmac.new(sha256, api_token_key) ``` OperationKey is the first HMAC digest link in the signature chain. This prevents replay attacks that seek to modify the request method or URI. It is composed of concatenating the request method and the request URI with no delimiter and computing the HMAC digest using the token key as the digest secret: ```python # Example: GET /api/v2/test/resource HTTP/1.1 # Signature Component: GET/api/v2/test/resource digester.write(request_method + request_uri) # Update the digester for further chaining digester = hmac.New(sha256, digester.hash()) ``` DateKey is the next HMAC digest link in the signature chain. This encodes the RFC3339 formatted datetime value as part of the signature to the hour to prevent replay attacks that are older than max two hours. This value is added to the signature chain by cutting off all values from the RFC3339 formatted datetime from the hours value forward: ```python # Example: 2020-12-01T23:59:60Z # Signature Component: 2020-12-01T23 request_datetime = date.now() digester.write(request_datetime[:13]) # Update the digester for further chaining digester = hmac.New(sha256, digester.hash()) ``` Body signing is the last HMAC digest link in the signature chain. This encodes the request body as part of the signature to prevent replay attacks that seek to modify the payload of a signed request. In the case where there is no body content the HMAC digest is computed anyway, simply with no values written to the digester: ```python if request.body is not empty: digester.write(request.body) ``` Finally, base64 encode the final hash and write the three required headers before sending the request: ```python encoded_hash = base64_encode(digester.hash()) request.header.write('Authorization', 'bhesignature ' + token_id) request.header.write('RequestDate', request_datetime) request.header.write('Signature', encoded_hash) ``` servers: - url: https://your-tenant.bloodhoundenterprise.io description: >- This is the base path for all endpoints, relative to the domain where the API is being hosted. security: - JWTBearerToken: [] - SignedRequest: [] RequestDate: [] HMACSignature: [] paths: /api/v2/domains/{domain_id}/details: parameters: - $ref: '#/components/parameters/header.prefer' - name: domain_id description: Domain, Tenant, or Environment ID in: path required: true schema: type: string - $ref: '#/components/parameters/query.asset-group-tag-id' get: tags: - Attack Paths - Enterprise summary: List domain attack paths details description: > Lists detailed data about attack paths for a domain. __Note:__ `ImpactCount`, `ImpactPercentage`, `ExposureCount`, `ExposurePercentage` and `Severity` will have a value other than zero when butterfly analysis is enabled. operationId: ListDomainAttackPathsDetails parameters: - name: Accept in: query description: >- Media type to determine the response format (application/json or text/csv). required: false schema: $ref: '#/components/schemas/api.params.predicate.filter.string' enum: - application/json - text/csv - name: finding in: query required: true schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: sort_by description: >- Sortable columns are `domain_sid`, `index`, `AcceptedUntil`, `id`, `created_at`, `updated_at`, `deleted_at`, `exposure_percentage`, `impact_percentage`. Relationship risks can be sorted on `FromPrincipal` and `ToPrincipal` in addition to the sortable columns for List Risks. in: query schema: $ref: '#/components/schemas/api.params.query.sort-by' - name: FromPrincipal deprecated: true in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: ToPrincipal deprecated: true in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: from_principal in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: to_principal in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: principals_hash in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: Accepted deprecated: true in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: AcceptedUntil deprecated: true in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.time' - name: accepted_until in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.time' - name: Principal in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: domain_sid in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.string' - name: id in: query schema: $ref: '#/components/schemas/api.params.predicate.filter.integer' - $ref: '#/components/parameters/query.created-at' - $ref: '#/components/parameters/query.updated-at' - $ref: '#/components/parameters/query.deleted-at' - $ref: '#/components/parameters/query.skip' - $ref: '#/components/parameters/query.limit' enum: - application/json - text/csv responses: '200': description: OK content: text/csv: schema: type: string format: binary examples: Butterfly Relationship Finding: value: > id,finding_type,exposure_count,exposure_percentage,impact_count,impact_percentage,domain_sid,from_principal_name,from_principal,from_principal_kind,to_principal_name,to_principal,to_principal_kind,combo_graph_relation_id,domain,accepted,accepted_until,principals_hash,created_at,updated_at,is_inherited 1,Tier Zero Generic Write,500,0.6711,1000,0.9961,5,S-1-5-21-123-123-123,RPATTON@TITANCORP.LOCAL,S-1-5-21-123-123-123,User,RPATTON DELEGATION TEST@TITANCORP.LOCAL,S-1-5-21-124-124-124,User,2,TITANCORP,true,0001-01-01T00:00:00Z,1lQiVG3hOuM=,2022-08-17T23:44:24Z,2024-12-18T15:01:00.176572729Z,Yes Metatree Relationship Finding: value: > id,finding_type,exposure_count,exposure_percentage,impact_count,impact_percentage,domain_sid,from_principal_name,from_principal,from_principal_kind,to_principal_name,to_principal,to_principal_kind,combo_graph_relation_id,domain,accepted,accepted_until,principals_hash,created_at,updated_at,is_inherited 1,Tier Zero Generic Write,0,0,0,0,5,S-1-5-21-123-123-123,RPATTON@TITANCORP.LOCAL,S-1-5-21-123-123-123,User,RPATTON DELEGATION TEST@TITANCORP.LOCAL,S-1-5-21-124-124-124,User,0,TITANCORP,true,0001-01-01T00:00:00Z,1lQiVG3hOuM=,2022-08-17T23:44:24Z,2024-12-18T15:01:00.176572729Z,Yes Butterfly List Finding: value: > id,finding_type,impact_count,impact_percentage,domain,domain_sid,principal_name,principal_kind,principal,accepted,accepted_until,created_at,updated_at 1,Kerberoasting,800,0.9961,TITANCORP,S-1-5-21-123-123-123,RPATTON@TITANCORP.LOCAL,User,S-1-5-21-124-124-124,true,0001-01-01T00:00:00Z,2022-08-17T23:44:24Z,2024-12-18T15:01:00.176572729Z Metatree List Finding: value: > id,finding_type,impact_count,impact_percentage,domain,domain_sid,principal_name,principal_kind,principal,accepted,accepted_until,created_at,updated_at 1,Kerberoasting,0,0,TITANCORP,S-1-5-21-123-123-123,RPATTON@TITANCORP.LOCAL,User,S-1-5-21-124-124-124,true,0001-01-01T00:00:00Z,2022-08-17T23:44:24Z,2024-12-18T15:01:00.176572729Z application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/api.response.pagination' - type: object properties: data: type: array items: $ref: '#/components/schemas/model.relationship-finding' type: object properties: Accepted: type: boolean - allOf: - $ref: '#/components/schemas/api.response.pagination' - type: object properties: data: type: array items: $ref: '#/components/schemas/model.list-finding' type: object properties: Accepted: type: boolean examples: Butterfly Relationship Finding: summary: Butterfly Relationship Finding description: >- When the butterfly analysis feature flag is on, impact count/percentage and exposure count/percentage will have a value other than zero. value: count: 0 skip: 0 limit: 0 data: - id: 0 created_at: '2024-08-28T21:21:40.845Z' updated_at: '2024-08-28T21:21:40.845Z' deleted_at: time: '2024-08-28T21:21:40.845Z' valid: true FromPrincipal: string ToPrincipal: string FromPrincipalProps: additionalProp1: {} additionalProp2: {} additionalProp3: {} FromPrincipalKind: string ToPrincipalProps: additionalProp1: {} additionalProp2: {} additionalProp3: {} ToPrincipalKind: string RelProps: additionalProp1: {} additionalProp2: {} additionalProp3: {} ComboGraphRelationID: int64: 0 valid: true Finding: string DomainSID: string PrincipalHash: string AcceptedUntil: '2024-08-28T21:21:40.845Z' ImpactPercentage: 0.12 ImpactCount: 2 ExposurePercentage: 0.24 ExposureCount: 4 Severity: high Accepted: true Metatree Relationship Finding: summary: Metatree Relationship Finding description: >- When the butterfly analysis feature flag is off and metatree is running, impact count/percentage and exposure count/percentage will have a value of zero. value: count: 0 skip: 0 limit: 0 data: - id: 0 created_at: '2024-08-28T21:21:40.845Z' updated_at: '2024-08-28T21:21:40.845Z' deleted_at: time: '2024-08-28T21:21:40.845Z' valid: true FromPrincipal: string ToPrincipal: string FromPrincipalProps: additionalProp1: {} additionalProp2: {} additionalProp3: {} FromPrincipalKind: string ToPrincipalProps: additionalProp1: {} additionalProp2: {} additionalProp3: {} ToPrincipalKind: string RelProps: additionalProp1: {} additionalProp2: {} additionalProp3: {} ComboGraphRelationID: int64: 0 valid: true Finding: string DomainSID: string PrincipalHash: string AcceptedUntil: '2024-08-28T21:21:40.845Z' ImpactPercentage: 0 ImpactCount: 0 ExposurePercentage: 0 ExposureCount: 0 Severity: '' Accepted: true Butterfly List Finding: summary: Butterfly List Finding description: >- When the butterfly analysis feature flag is on, impact count/percentage and exposure count/percentage will have a value other than zero. value: count: 0 skip: 0 limit: 0 data: - id: 0 created_at: '2024-08-28T21:42:18.844Z' updated_at: '2024-08-28T21:42:18.844Z' deleted_at: time: '2024-08-28T21:42:18.844Z' valid: true Principal: string PrincipalKind: string Finding: string DomainSID: string Props: additionalProp1: {} additionalProp2: {} additionalProp3: {} AcceptedUntil: '2024-08-28T21:42:18.844Z' ImpactPercentage: 0.12 ImpactCount: 2 Severity: high Accepted: true Metatree List Finding: summary: Metatree List Finding description: >- When the butterfly analysis feature flag is off and metatree is running, impact count/percentage and exposure count/percentage will have a value of zero. value: count: 0 skip: 0 limit: 0 data: - id: 0 created_at: '2024-08-28T21:42:18.844Z' updated_at: '2024-08-28T21:42:18.844Z' deleted_at: time: '2024-08-28T21:42:18.844Z' valid: true Principal: string PrincipalKind: string Finding: string DomainSID: string Props: additionalProp1: {} additionalProp2: {} additionalProp3: {} AcceptedUntil: '2024-08-28T21:42:18.844Z' ImpactPercentage: 0 ImpactCount: 0 Severity: '' Accepted: true '400': $ref: '#/components/responses/bad-request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/not-found' '429': $ref: '#/components/responses/too-many-requests' '500': $ref: '#/components/responses/internal-server-error' components: parameters: header.prefer: name: Prefer description: >- Prefer header, used to specify a custom timeout in seconds using the wait parameter as per RFC7240. Passing in wait=-1 bypasses all timeout limits when the feature is enabled. in: header required: false schema: type: string default: wait=30 pattern: ^wait=(-1|[0-9]+)$ query.asset-group-tag-id: name: asset_group_tag_id description: >- The asset group tag id of the zone requested. If not supplied, the asset group tag id associated with 'Tier Zero' and 'Hygiene' is used. in: query schema: type: integer query.created-at: name: created_at in: query description: >- Filter results by `created_at` value. See filter schema details for valid predicates. schema: $ref: '#/components/schemas/api.params.predicate.filter.time' query.updated-at: name: updated_at in: query description: >- Filter results by `updated_at` value. See filter schema details for valid predicates. schema: $ref: '#/components/schemas/api.params.predicate.filter.time' query.deleted-at: name: deleted_at in: query description: >- Filter results by `deleted_at` value. See filter schema details for valid predicates. schema: $ref: '#/components/schemas/api.params.predicate.filter.time' query.skip: name: skip description: >- This query parameter is used for determining the number of objects to skip in pagination. in: query schema: $ref: '#/components/schemas/api.params.query.skip' query.limit: name: limit description: >- This query parameter is used for setting an upper limit of objects returned in paginated responses. in: query schema: $ref: '#/components/schemas/api.params.query.limit' schemas: api.params.predicate.filter.string: type: string pattern: ^((eq|~eq|neq):)?[^:]+$ description: > Filter results by column string value. Valid filter predicates are `eq`, `~eq`, `neq`. api.params.query.sort-by: type: string description: > Sort by column. Can be used multiple times; prepend a hyphen for descending order. See parameter description for details about which columns are sortable. api.params.predicate.filter.time: type: string pattern: >- ^((eq|neq|gt|gte|lt|lte):)?[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?([Zz]|-[0-9]{2}:[0-9]{2})$ description: > Filter results by column timestamp value formatted as an RFC-3339 string. Valid filter predicates are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`. api.params.predicate.filter.integer: type: string pattern: ^((eq|neq|gt|gte|lt|lte):)?-?[0-9]+$ description: > Filter results by column integer value. Valid filter predicates are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`. api.response.pagination: type: object properties: count: type: integer minimum: 0 description: The total number of results. skip: $ref: '#/components/schemas/api.params.query.skip' limit: $ref: '#/components/schemas/api.params.query.limit' model.relationship-finding: allOf: - $ref: '#/components/schemas/model.components.int32.id' - $ref: '#/components/schemas/model.components.timestamps' - type: object properties: FromPrincipal: type: string ToPrincipal: type: string FromPrincipalProps: type: object additionalProperties: type: object FromPrincipalKind: type: string ToPrincipalProps: type: object additionalProperties: type: object ToPrincipalKind: type: string RelProps: type: object additionalProperties: type: object ComboGraphRelationID: $ref: '#/components/schemas/null.int64' Finding: type: string DomainSID: type: string PrincipalHash: type: string AcceptedUntil: type: string format: date-time ImpactPercentage: type: number format: double ImpactCount: type: integer format: int64 ExposurePercentage: type: number format: double ExposureCount: type: integer format: int64 Severity: type: string enum: - critical - high - moderate - low - '' model.list-finding: allOf: - $ref: '#/components/schemas/model.components.int32.id' - $ref: '#/components/schemas/model.components.timestamps' - type: object properties: Principal: type: string PrincipalKind: type: string Finding: type: string DomainSID: type: string Props: type: object additionalProperties: type: object AcceptedUntil: type: string format: date-time ImpactPercentage: type: number format: double ImpactCount: type: integer format: int64 Severity: type: string enum: - critical - high - moderate - low - '' api.params.query.skip: type: integer minimum: 0 description: The number of items to skip in a paginated response. api.params.query.limit: type: integer minimum: 0 description: The limit of results requested by the client. model.components.int32.id: type: object properties: id: type: integer format: int32 readOnly: true description: This is the unique identifier for this object. model.components.timestamps: type: object properties: created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true deleted_at: readOnly: true allOf: - $ref: '#/components/schemas/null.time' null.int64: type: object properties: int64: type: integer format: int64 valid: description: Valid is true if `int64` is not `null`. type: boolean api.error-wrapper: type: object description: '' properties: http_status: type: integer description: The HTTP status code minimum: 100 maximum: 600 timestamp: type: string format: date-time description: The RFC-3339 timestamp in which the error response was sent request_id: type: string format: uuid description: The unique identifier of the request that failed errors: type: array items: $ref: '#/components/schemas/api.error-detail' description: The error(s) that occurred from processing the request null.time: type: object properties: time: type: string format: date-time description: An RFC-3339 formatted string valid: description: Valid is true if `time` is not `null`. type: boolean api.error-detail: type: object properties: context: type: string description: The context in which the error took place message: type: string description: A human-readable description of the error responses: bad-request: description: > **Bad Request** This could be due to one of the following reasons: - JSON payload is missing or malformed - Path or query parameters are missing or invalid/malformed - The data sent is not valid (ex- sending a `string` in an `integer` field) content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 400 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: The JSON payload could not be unmarshalled. unauthorized: description: > **Unauthorized** This endpoint failed an authentication requirement. Either the client tried to access a protected endpoint without being authenticated, or an auth validation failed (ex- invalid credentials or expired token). content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 401 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: login message: Unauthorized forbidden: description: | **Forbidden** This is most commonly caused by an authenticated client trying to access a resource that it does not have permission for. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 403 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: You do not have permission to access this resource not-found: description: > **Not Found** This error typically comes from operations where a valid ID was passed to the request to look up an entity but the entity could not be found. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 404 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: The requested client could not be found. too-many-requests: description: | **Too Many Requests** The client has sent too many requests within a certain time window and tripped the rate limiting middleware. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 429 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: middleware message: Too many requests. Please try again later. internal-server-error: description: > **Internal Server Error** This is usually the result of either an unexpected database or application error. The client may try modifying or resending the request, but the error is likely not related to the client doing something wrong. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 500 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: >- The request could not be handled due to an unexpected database error. securitySchemes: JWTBearerToken: description: | `Authorization: Bearer $JWT_TOKEN` type: http scheme: bearer bearerFormat: JWT SignedRequest: description: | `Authorization: bhesignature $TOKEN_ID` type: apiKey name: Authorization in: header RequestDate: description: | `RequestDate: $RFC3339_DATETIME` type: apiKey name: RequestDate in: header HMACSignature: description: | `Signature: $BASE64ENCODED_HMAC_SIGNATURE` type: apiKey name: Signature in: header ````