Work With the BloodHound API

The BloodHound product family are API-first products, meaning everything functions on the underlying API layer. All data displayed in the portal, all commands given to SharpHound or AzureHound Enterprise collectors, and all data uploaded pass through the BloodHound APIs. Customers may utilize these APIs to extend the use of the BloodHound product to function with other tools in their environment. This article will show how to access the API and include some example use cases.

API Documentation

Our API reference is available here.

Additionally, API documentation is hosted utilizing Swagger behind authentication within your tenant environment. After logging in, you may access it by clicking the cog in the top right corner of your tenant and clicking API Explorer.

Authentication

The BloodHound API accepts two forms of authentication, each with its own limitations for security.

• A JWT is generated through the login process using your email address, password, and 2FA token (or SAML-based authentication flow). These JWT tokens are active for 8 hours and are primarily for end-user access to the web-based application.
• An API key/ID pair is generated within the Administration interface. These do not expire and are primarily for long-term API integrations.

There are two methods for creating API key/ID pairs, each serving a different purpose:

• Non-personal API key/ID pairs for integrations like Splunk
• Personal API key/ID pairs for day-to-day use like BloodHound Operator

Create a non-personal API key/ID pair

Administrators can create non-personal BloodHound users solely meant for API integrations.

1. Log in as a user with the Administrator role.
2. Create a new BloodHound user.
   • Give the user a long and unique password.
3. Optional recommendation: Log in as the newly created user and enable MFA.
4. Optional recommendation: Securely dispose of the password and MFA configuration as they are not needed for authenticating with a key/ID pair and they can be reset by an Administrator if needed.
5. As the Administrator, go back to the Manage Users page.
6. On the API user, click the hamburger menu > Generate / Revoke API Tokens.

7. Click Create Token.
8. Give the token a descriptive name and click Save.
9. Save the presented API key/ID pair and click Close.
   • The API key will never be shown again. If you lose it, you must revoke the previous key and regenerate a new one.
10. You may now use this key ID pair for calling the API

Create a personal API Key and ID pair

Create a personal API Key/ID pair from the My Profile section.

1. In the top-right corner click My Profile.

2. Click API Key Management.

3. Click Create Token.

4. Give the token a descriptive name and click Save.

5. Save the presented API key/ID pair and click Close.
   • The API key will never be shown again. If you lose it, you must revoke the previous key and regenerate a new one.

Use this key/ID pair for calling the API.

Call the API

Once you have your token, you can call the BloodHound API.

Use a JWT/bearer token

For quick tests or one-time calls, the JWT used by your browser may be the simplest route. The API accepts calls using the following header structure in the HTTP request:

'Authorization': Bearer $JWT_TOKEN

If you open the Network tab in your browser, you’ll see calls against the API made using this structure.

Use your API Key/ID pair

For long-running API integrations, BloodHound’s API uses hash-based message authentication code (HMAC) authentication using the API key as the secret key to verify the authenticity and integrity of the request. Calls against the API must include the following in the signed hash:

• API key
• HTTP method and URI
• Current time
• Body content (if applicable to the request)

Calls against the API would need to include the following headers in the HTTP request:

'Authorization': bhesignature $TOKEN_ID
'RequestDate': $RFC3339_DATETIME
'Signature': $BASE64ENCODED_HMAC_SIGNATURE

By validating the hash signature against the request, the API can validate that the calls were made by the original requestor, within a reasonable timeframe, against the proper API endpoint, including the original content body, and that no replay or content modification has occurred.

For a complete implementation example, see apiclient.py in the specterops/bloodhound-docs GitHub repository. The following code snippet from the apiclient.py script illustrates the authentication process:

def _request(self, method: str, uri: str, body: Optional[bytes] = None) -> requests.Response:
    # Digester is initialized with HMAC-SHA-256 using the token key as the HMAC digest key.
    digester = hmac.new(self._credentials.token_key.encode(), None, hashlib.sha256)

    # 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.
    #
    # Example: GET /api/v2/test/resource HTTP/1.1
    # Signature Component: GET/api/v2/test/resource
    digester.update(f'{method}{uri}'.encode())

    # Update the digester for further chaining
    digester = hmac.new(digester.digest(), None, hashlib.sha256)

    # 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:
    #
    # Example: 2020-12-01T23:59:60Z
    # Signature Component: 2020-12-01T23
    datetime_formatted = datetime.datetime.now().astimezone().isoformat('T')
    digester.update(datetime_formatted[:13].encode())

    # Update the digester for further chaining
    digester = hmac.new(digester.digest(), None, hashlib.sha256)

    # 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.
    if body is not None:
        digester.update(body)

    # Perform the request with the signed and expected headers
    return requests.request(
        method=method,
        url=self._format_url(uri),
        headers={
            'User-Agent': 'bhe-python-sdk 0001',
            'Authorization': f'bhesignature {self._credentials.token_id}',
            'RequestDate': datetime_formatted,
            'Signature': base64.b64encode(digester.digest()),
            'Content-Type': 'application/json',
        },
        data=body,
    )

Examples for other languages:

• PowerShell
• C#