OpenGraph extensions expand BloodHound’s ability to map attack paths beyond Microsoft platforms to other identity providers, developer infrastructure, and device management platforms. For example:
How extensions structure data has important implications for how you explore and analyze it in BloodHound. It’s important to understand the differences between generic and structured graphs and how to manage extensions effectively.
Structured graphs are available under early access.
Generic graphs
When OpenGraph was introduced in BloodHound v8.0.0, it required data payloads to conform to the basic node, edge, and metadata format only and produced generic graphs to support basic exploration through Cypher queries (and later, node search). This enabled rapid iteration and flexibility for early OpenGraph extensions. However, it also meant that OpenGraph data was not integrated with other BloodHound features and capabilities.Structured graphs
Extension developers can now create extension bundles to enable enhanced features and capabilities for OpenGraph data. Currently, an extension bundle consists of the extension definition schema only. In a future release, extension bundles will include additional components. After you install an extension and upload a data payload that conforms to the extension definition schema, BloodHound produces a structured graph that provides enhanced features compared to generic graphs, such as:| Feature | Structured | Generic | Release Status |
|---|---|---|---|
| Node search | Structured: Early access Generic: Generally available | ||
| Cypher search | Structured: Early access Generic: Generally available | ||
| Bulk data removal | Structured: Early access Generic: Generally available | ||
| Pathfinding | Early access | ||
| Relationship-based findings1 | Coming soon | ||
| Remediations1 | Coming soon | ||
| Posture metrics2 | Coming soon |
1 Extensions that include findings and remediations work in both Community and Enterprise, but are visible in Enterprise only.2 Posture metrics are available in Enterprise only.
Key terms
See the following table for important terms and definitions related to OpenGraph extensions:| Term | Definition |
|---|---|
| Collector | A tool that authenticates to a third-party platform, collects the data of interest, and packages it into a standardized data payload that BloodHound can ingest. |
| Data payload | The formatted data generated by an OpenGraph collector that is provided to BloodHound for ingest. |
| Extension | A modular collection of OpenGraph components, including an extension definition schema, collector, Cypher saved queries, Privilege Zone rules, and findings. |
| Extension definition schema | A file that defines an extension’s structure, including node types, edge types, and visual configurations. Enables BloodHound to validate incoming data payloads and produce structured graphs. Both BloodHound Community and BloodHound Enterprise use the same extension definition schema format. |
| Generic graph | OpenGraph data conforming to the basic node, edge, and metadata format required for a data payload, with no associated extension definition schema. |
| Structured graph | OpenGraph data conforming to the basic node, edge, and metadata format required for a data payload and associated with an installed extension definition schema. Structured graphs are fully integrated with BloodHound’s features and functionality. |
Manage extensions
Use the OpenGraph Management page in BloodHound to install new extensions, view active extensions, and delete extensions that you no longer need.Only users with the Administrator role can manage extensions.
Before you begin
Complete the following steps before installing an extension or uploading structured graph data:Confirm OpenGraph Extension Management availability
Ensure the OpenGraph Extension Management feature is enabled before you continue.
- BloodHound Community: OpenGraph Extension Management is planned for BloodHound v9.0.0 as part of the MVP launch.
- BloodHound Enterprise: This is a SpecterOps-managed feature. If it is not enabled in your environment, contact your account team for assistance.
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 extensions and collectors from GitHub repositories.
- BloodHound Enterprise: Customers can use publicly available extensions and collectors. Customers may also acquire official SpecterOps-provided extensions; contact your account team for availability.
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, Administrators and users follow the same recurring cycle to keep extension data current and use it in BloodHound.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 diagram illustrates the recurring cycle of operations to keep extension data current: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. After installing, BloodHound produces structured graphs for data payloads that conform to the extension.Upload the extension definition schema
- Click Upload File to open a file system dialog or drag and drop an extension definition schema file onto the canvas.
-
Click Upload to begin the schema installation and validation process.
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.
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. Follow these steps to upload and explore structured graph data:Upload data
Upload a data payload that conforms to the installed extension definition schema.
- In the left menu, click Quick Upload.
- Click the Upload File canvas to open a file system dialog or drag and drop the data payload file(s) onto the canvas.
- Click Upload to begin the data ingestion and validation process.
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 relationships across all platforms and environments, including both built-in and custom extensions. |
| 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. |