OpenGraph Extensions

Learn about extension components and management workflows, including initial setup and ongoing maintenance.

As described in the OpenGraph Overview, extensions that include an extension definition schema enrich collector-generated data payloads to produce structured graphs. Structured graphs enable enhanced features in BloodHound, such as pathfinding, findings, and metrics.

Extensions that do not include an extension definition schema produce generic graphs.

Extensions can include the following components:

Component	Description
Extension definition schema	A file that defines graph structure, including node types, edge types, traversability behavior, and visual configurations. Both BloodHound Community and BloodHound Enterprise use the same extension definition schema format.
Collector	A tool (for example, OpenHound, AzureHound, or SharpHound) that authenticates to a third-party platform, collects the data of interest, and packages it into a standardized data payload that BloodHound can ingest.
Cypher saved queries	Custom Cypher queries provided by extension developers.
Privilege Zone rules	Custom rules provided by extension developers to categorize nodes into Privilege Zones based on their properties and relationships.
Findings	Insights or observations provided by extension developers derived from the ingested data, which can be used to identify risk and remediation guidance. Findings are visible in BloodHound Enterprise only.

SpecterOps has developed several extensions that follow this model, including:

GitHub

Visualize and analyze your GitHub configurations in BloodHound.

Jamf

Visualize and analyze your Jamf configurations in BloodHound.

Okta

Visualize and analyze your Okta configurations in BloodHound.

SCIM

Visualize SCIM-provisioned users and groups as nodes in BloodHound.

Only users with the Administrator role can upload and delete extension definition schemas. Non-administrator users can view installed extensions, findings, and edges.

Before you begin

Complete the following steps before installing an extension or uploading structured graph data:

Only users with the Administrator role can manage extensions.

1. Confirm OpenGraph Extension Management availability

   The OpenGraph Extension Management feature must be enabled before you can manage extensions.

   Enable this feature on the Administration > Early Access Features page.

   Support for extension-defined Findings in BloodHound Enterprise is a SpecterOps-managed feature. If it is not enabled in your environment, contact your account team for assistance.

2. Get extension artifacts

   How you obtain extensions and collectors depends on your BloodHound edition and how they are distributed:

   • BloodHound Community: Users can download and use publicly available community-built extensions and collectors from GitHub repositories.

   • BloodHound Enterprise: Customers can also use publicly available extensions and collectors, but they may also acquire official SpecterOps-provided extensions. Official extensions include detailed findings and remediation guidance.

     Contact your account team for availability.

3. Review prerequisites

   After you obtain an extension and collector, review the prerequisites in the extension-specific setup documentation.

   For OpenHound-based collectors (GitHub, Jamf, and Okta), review edition-specific deployment information (Enterprise or Community) and the collector-specific documentation for details on permissions, platform API configuration, and deployment options.

Workflow

The workflow for generic and structured OpenGraph data is largely the same. The main difference is that structured graphs require an Administrator to install the extension during initial setup. After that, users with read access can view installed extensions and use the resulting structured graph data, while only Administrators can upload or delete extension definition schemas. See User Role Definitions for a full breakdown of permissions.

For OpenHound collectors (GitHub, Jamf, and Okta), upload behavior depends on both deployment model and BloodHound edition. Only BloodHound Enterprise can accept payloads directly through the API. BloodHound Community requires manual file upload.

Initial setup

The following diagram provides a high-level overview of the recommended workflow to prepare BloodHound for producing structured graphs from OpenGraph extensions.

The initial setup workflow is not strictly linear and not all steps are required. For example, importing Saved Queries and creating extension-specific Privilege Zone rules are optional.

For generic graphs, the workflow is minimal: users may optionally import Saved Queries (if any). Installing an extension definition schema and updating Privilege Zone rules is not required.

Operational cycle

After initial setup, the following diagrams illustrate the recurring cycle of operations to keep extension data current.

For OpenHound collectors, upload behavior depends on edition and runtime model: Enterprise can ingest through the API (often automatic when using a collector client), while Community requires manual file upload from locally run collector executables.

The following diagrams illustrate the OpenHound workflow for both Enterprise and Community editions.

BloodHound Enterprise (containerized)

BloodHound Community (CLI)

Install an extension

Installing an extension involves uploading the extension definition schema to BloodHound, which validates the schema and makes it available for use with compatible data payloads.

Only users with the Administrator role can upload and delete extension definition schemas.

After installing, BloodHound produces structured graphs for data payloads that conform to the extension.

1. Open the OpenGraph Management page

   In the left menu, click Administration > OpenGraph Management.

2. Upload the extension definition schema

   1. Click Upload File to open a file system dialog or drag and drop an extension definition schema file onto the canvas.

   2. Click Upload to begin the schema installation and validation process.

      
3. Confirm installation

   Confirm the extension appears in the list of active extensions.

   You may need to refresh the page to see the newly installed extension in the list of active extensions.

   

Update an extension

Collectors and extensions are versioned separately to allow for more flexible updates, but this requires coordination to maintain compatibility and support. Follow these guidelines for managing updates:

• Do not update collectors independently without confirming extension definition schema compatibility.
• Update collectors and extension definition schemas together whenever possible.
• If you use SpecterOps-provided extensions or collectors, coordinate update cycles with your account team.

To update an extension, upload the new version using the same process as installing a new extension. BloodHound validates the new extension definition schema and replaces the old version with the new one.

Delete an extension

Deleting an extension removes the extension definition schema from BloodHound, but leaves the underlying data intact. Associated data reverts to generic graphs—structured graph capabilities are no longer available—but you can still use node search and Cypher queries on the Explore page to explore the data.

If you want to delete the data associated with an extension, you can do so separately on the Database Management page.

To delete an extension, click the (trash) icon next to it in the list of active extensions and confirm the deletion in the prompt.

You cannot delete built-in extensions that come with BloodHound, but you can delete custom extensions that you have installed.

Upload data

After an Administrator installs an extension, users can upload data payloads that conform to the extension definition schema and take advantage of structured graph capabilities in BloodHound.

For extensions that use OpenHound collectors (GitHub, Jamf, and Okta), AzureHound, or SharpHound, how data is uploaded depends on your BloodHound edition:

• BloodHound Enterprise: The collector client can upload data directly through the API. In containerized deployments, upload is typically automatic.

• BloodHound Community: After running the OpenHound, AzureHound, or SharpHound collector executables locally and generating data files, follow the manual upload steps below.

  For extensions that do not use OpenHound collectors, follow the manual upload steps below.

1. Upload data

   Upload a data payload that conforms to the installed extension definition schema.

   1. In the left menu, click Quick Upload.

   2. Click the Upload File canvas to open a file system dialog or drag and drop the data payload file(s) onto the canvas.

   3. Click Upload to begin the data ingestion and validation process.

      The file either uploads successfully or fails in the modal. You can then go to the File Ingest page to review ingest and analysis progress.

2. Explore and analyze

   Use the enhanced features enabled by the extension to explore and analyze your OpenGraph data in BloodHound.

   Feature	Description
   Pathfinding	Use Pathfinding to identify attack paths and analyze traversable relationships across all platforms and environments, including built-in and extension-defined kinds.
   Saved queries	Import extension-specific saved queries so you can quickly run pre-defined Cypher queries on the Explore page.
   Privilege Zone rules	If your Administrator configured extension-specific Privilege Zone rules during initial setup, BloodHound automatically assigns matching nodes to zones, giving you clearer prioritization and zone-aware analysis.
   Findings and remediation	When available, use findings and remediation information to prioritize and address issues in your environment.