Skip to content

BP-2407: Pathfinding for OpenGraph #200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeff-matthews merged 5 commits into from
Feb 27, 2026
Merged

BP-2407: Pathfinding for OpenGraph #200

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
781ee33
wip: opengraph pathfinding for users
jeff-matthews Feb 24, 2026
5e1e9cd
wip: opengraph pathfinding for developers
jeff-matthews Feb 25, 2026
e6d0c59
wip: disambiguate payload format and schema requirements
jeff-matthews Feb 25, 2026
fb361cf
fix: heading levels
jeff-matthews Feb 25, 2026
9d0413d
docs: apply suggestions from review
jeff-matthews Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/analyze-data/explore/search.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,6 @@ The **Explore** page provides the following methods for searching for objects an
</Card>
</CardGroup>

<Note>BloodHound currently supports the **Search** and **Cypher** search methods for OpenGraph data, with support for Pathfinding coming soon.</Note>

Which method you choose depends on your specific use case and what you're trying to accomplish. This page describes each of the search methods in more detail and provides guidance on when to use each one.

<Tip>You can interact with objects in the [graph](#graph-view) and customize the view to explore the data more effectively, regardless of which search method you use.</Tip>
Expand Down Expand Up @@ -67,9 +65,7 @@ group:admin

## Pathfinding

The **Pathfinding** tab allows you to discover relationships between objects by finding paths between them. This is particularly useful for investigating potential attack paths in an environment.

<Note>BloodHound currently supports the **Search** and **Cypher** search methods for OpenGraph data, with support for Pathfinding coming soon.</Note>
The **Pathfinding** tab allows you to discover relationships between objects by finding paths between them. This is particularly useful for investigating potential attack paths in an environment or exploring how different objects are connected in specific OpenGraph data sources.
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

Use cases for the pathfinding search method include:

Expand All @@ -89,6 +85,10 @@ Pathfinding also includes options to customize your search:

* **Filter edges** <Icon icon="filter" iconType="solid" />—Select which edge types to include in the results. By default, all edge types are selected; deselect any you don't want included in the paths to focus on relevant relationships.

<Note>
Filtering options are available for [schema-based data](/opengraph/schema) only. If you're exploring generic (schema-less) OpenGraph data, edge filtering options are not available.
</Note>

Comment thread
jeff-matthews marked this conversation as resolved.
Outdated
## Cypher

The **Cypher** tab allows you to perform complex searches using <Tooltip headline="Cypher" tip="A query language for graph databases (similar to SQL for relational databases). It uses an ASCII-art style syntax to describe nodes and relationships. If you can describe the path you're looking for, you can write it in Cypher." cta="See the docs" href="/analyze-data/explore/cypher-search">Cypher</Tooltip> queries.
Expand Down
4 changes: 1 addition & 3 deletions docs/opengraph/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,7 @@ You can remove generic data by using one of the following three (3) options:

</Accordion>
<Accordion title="Do custom nodes & edges work with Search and Pathfinding?">
**Search:** Yes! As of v8.5.0, OpenGraph nodes are partially supported in the search functionality on the **Explore** page. You can search for OpenGraph nodes by display name or object ID, and visualize them in the graph with custom icons and colors. However, you cannot yet prepend search queries by OpenGraph node types.

**Pathfinding:** Not yet. OpenGraph edges are not currently supported in the **Pathfinding** tab on the **Explore** page. For pathfinding queries involving OpenGraph data, you must use the Cypher tab to query the data manually.
Yes! BloodHound supports custom nodes in **Search** and **Pathfinding**. However, prepending queries with custom node types is not yet supported.
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated
</Accordion>
<Accordion title="How can I add my project to the OpenGraph library?">
Have you built a cool project using OpenGraph and want it featured here? Already got your project in the list and need to update something? Open a ["Library Change" issue](https://github.com/SpecterOps/bloodhound-docs/issues) on the BloodHound Docs repo and we'll get it added for you!
Expand Down
47 changes: 29 additions & 18 deletions docs/opengraph/schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,30 @@ description: "Description of the OpenGraph JSON Schema"

<img noZoom src="/assets/enterprise-AND-community-edition-pill-tag.svg" alt="Applies to BloodHound Enterprise and CE"/>

# Schema
This page explains the JSON payload structure and minimum JSON schema requirements that BloodHound uses to ingest OpenGraph nodes and edges.

In this section, you will find all the information to create a JSON file that BloodHound can ingest and use to display your Nodes and Edges.
Terms used on this page:

The most up-to-date JSON Schema can always be found in our CE repository. Currently, the location of the node and edge schema files in our source code can be found [here](https://github.com/SpecterOps/BloodHound/tree/main/cmd/api/src/services/upload/jsonschema).
- **Schema-less (generic) data** refers to OpenGraph payloads that follow the minimum node and edge JSON schemas on this page.
- **Schema-based data** refers to OpenGraph payloads that use an extension-defined schema outside the payload itself.

# Ingesting Generic Formatted Data
This page focuses on the JSON requirements for generic data.

## File Requirements
<Tip>You can find the latest node and edge schemas in the BloodHound [source code](https://github.com/SpecterOps/BloodHound/tree/main/cmd/api/src/services/upload/jsonschema) on GitHub.</Tip>

@craigw-SO craigw-SO Feb 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RE: tighter definitions/descriptions

This is specifically pointing to the JSON schema for data payload files.


## Ingesting Schema-less (Generic) Data

### File Requirements

Acceptable formats: `.json`, `.zip`

You can mix file types in a single upload (e.g. Sharphound + Generic).

Compressed ZIPs containing multiple file types are supported.

## JSON Format
### JSON Payload Structure
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

The standard BloodHound UI upload screen now accepts files in a generic format. You can continue using it as before.
The standard BloodHound UI upload screen accepts schema-less (generic) OpenGraph payloads. You can continue using it as before.
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

At minimum, your JSON file should have these elements:

Expand All @@ -37,16 +42,22 @@ At minimum, your JSON file should have these elements:
}
```

The `nodes` and `edges` must conform to our JSON Schema, see details below. The validation of the data occurs at upload time.
The `nodes` and `edges` must conform to the minimum JSON schemas (see details below). BloodHound validates that the JSON is well-formed and that nodes and edges meet these schema requirements, but it does not enforce additional structure or constraints beyond them.

@craigw-SO craigw-SO Feb 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is an area where we can tighten up "schema" referencing.


When ingest completes, generic data is available through all [Explore](/analyze-data/explore/search) options:
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

- **Search**
- **Pathfinding**
- **Cypher**

When ingest completes, the generic data will be available via **Cypher search ONLY**. Generic data is not searchable via the pathfinding feature (yet).
<Note>In **Pathfinding**, edge filtering options are available for schema-based data only. For generic data, edge filtering options are not available.</Note>
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

**Entity Panels**: clicking on a generic node or edge will only render the entity’s property bag. At this time there is no support for defining entity panels for generic entities.
**Entity Panels**: clicking on a generic node or edge will only render the entity's property bag. At this time there is no support for defining entity panels for generic entities.
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated


## Nodes
### Nodes

### Property Rules
#### Property Rules

Properties must be primitive types or arrays of primitive types

Expand All @@ -56,7 +67,7 @@ Arrays must be homogeneous (e.g. all strings or all numbers)

An array of kind labels for the node. The first element is treated as the node's primary kind and is used to determine which icon to display in the graph UI. This primary kind is only used for visual representation and has no semantic significance for data processing.

### Node JSON
#### Node JSON

The following is the <a href="/assets/opengraph/opengraph-node.json" download>JSON schema</a> that all nodes must conform to.

Expand Down Expand Up @@ -112,15 +123,15 @@ The following is the <a href="/assets/opengraph/opengraph-node.json" download>JS
}
```

## Edges
### Edges

Edges names cannot contain dash `-`. It is highly recommended to use Pascal Case and no special characters.

From [tuple.nl](https://www.tuple.nl/en/knowledge-base/pascal-case): Pascal Case is a naming convention used in programming where compound words are written without spaces, and each word starts with an uppercase letter. It is commonly used for naming variables, functions, classes, and other identifiers in code. Pascal Case helps create descriptive and easily distinguishable names, contributing to the clarity of your code.

See Neo4j [Naming and Conventions](https://neo4j.com/docs/cypher-manual/current/syntax/naming/) for more details.

### Edge JSON
#### Edge JSON

The following is the <a href="/assets/opengraph/opengraph-edge.json" download>JSON schema</a> that all edges must conform to.

Expand Down Expand Up @@ -247,7 +258,7 @@ The following is the <a href="/assets/opengraph/opengraph-edge.json" download>JS
}
```

### Post-processing
#### Post-processing

Post-processing in BloodHound refers to the analysis phase where the system creates certain edges after ingesting data to identify attack paths.
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

Expand Down Expand Up @@ -338,7 +349,7 @@ See the following example OpenGraph payload that produces the effect:
}
```
Comment on lines 322 to 346

@craigw-SO craigw-SO Feb 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this actually sufficient to generate the pattern? We seem to be implying that the user would need to create both edges to have the post-processed edge created. But in this example we only create one of two edges.

@jeff-matthews jeff-matthews Feb 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure. That's good feedback. I'll make a note for the rewrite since it's out of scope for this PR.


## Optional Metadata Field
### Optional Metadata Field

@craigw-SO craigw-SO Feb 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should add to this section to specify that adding a source_kind via metadata is what registers that kind as a source_kind in the first place. So if they want to track data via sources, they'll need to upload a data payload with this source_kind explicitly called out at least once. It can even be a blank payload aside from the source_kind, I think (we should double check that).

Once they've done that, anytime that kind is used, it's pre-defined as a source_kind and will be treated as such.

@jeff-matthews jeff-matthews Feb 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's good feedback. I'll make a note for the rewrite since it's out of scope for this PR.

FWIW, the unmerged quickstart #155 attempts to provide more details about this.


You can optionally include a metadata object at the top level of your JSON payload. This metadata currently supports a single field:
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

Expand All @@ -360,7 +371,7 @@ Example:

If present, the `source_kind` will be added to the `kinds` list of all nodes in the file during ingest. This feature is optional.

@craigw-SO craigw-SO Feb 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I specified in my earlier comment how source_kind is properly handled: https://github.com/SpecterOps/bloodhound-docs/pull/200/changes#r2855480768

The main aspect that I think we should highlight here is that – once the source_kind has been registered – the main benefit of using the metadata field is that it automatically applies the source_kind to all of the nodes in the payload.

This is accurate, but actually undesirable behavior. It should only apply the source_kind to the nodes defined within the payload, but not the ones just referenced within it. This is the source of bug behavior, and the reason we have an FAQ and workaround in place.

@jeff-matthews jeff-matthews Feb 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's good feedback. I'll make a note for the rewrite since it's out of scope for this PR.


## Minimal Working JSON
### Minimal Working JSON
Comment thread
jeff-matthews marked this conversation as resolved.
Outdated

The following is a minimal example payload that conforms to the node and edge schemas above. You can use this as a starting point to build your own OpenGraph. Copy and paste the following example into a new `.json` file or <a href="/assets/opengraph/opengraph-minimal.json" download>download this example file</a>.

Expand Down