Skip to main content
Applies to BloodHound Enterprise and CE This guide walks you through creating and testing OpenGraph data using a simple example JSON file. By following these steps, you’ll learn how to:
  • Create a properly structured OpenGraph JSON file and upload it to BloodHound
  • Define custom icons and colors for your node types to enhance visualization
  • Validate the data using search and Cypher queries in the Explore page
  • Remove the example data in the Administration > Database Management page when finished
Use this guide to get hands-on experience with the OpenGraph structure and validate custom nodes and edges in BloodHound.

​
Create example data

This example defines two Person connected by a Knows to demonstrate the structure of an OpenGraph payload. You can expand on this example to create more complex graphs with additional nodes, edges, and properties as needed.
1

Create a new JSON file

First, you need to define your OpenGraph payload in a JSON file.
  1. Create a new file called opengraph-example.json using a plain text editor (UTF-8 encoding).
  2. Copy and paste the following example, which includes two nodes (bob and alice) connected by an edge (Knows). 
    {
  "metadata": {
    "source_kind": "Person"
},
  "graph": {
    "nodes": [
      {
        "id": "123",
        "kinds": [
          "Person",
          "Base"
        ],
        "properties": {
          "displayname": "bob",
          "property1": "property1",
          "objectid": "123",
          "name": "BOB"
        }
      },
      {
        "id": "234",
        "kinds": [
          "Person",
          "Base"
        ],
        "properties": {
          "displayname": "alice",
          "property1": "property1",
          "objectid": "234",
          "name": "ALICE"
        }
      }
    ],
    "edges": [
      {
        "kind": "Knows",
        "start": {
          "value": "123",
          "match_by": "id"
        },
        "end": {
          "value": "234",
          "match_by": "id"
        }
      }
    ]
  }
}
    The following table describes the structure and properties of the example JSON file:
    SectionPropertyDescription
    metadatasource_kindOptional property that identifies the type of data (e.g., “Person”) in the Database Management page for easy clean up later
    graph.nodesidUnique identifier for the node
    kindsArray of node types (first is your custom type, “Base” is required)
    propertiesObject containing node properties (e.g., name, displayname, objectid, and custom properties)
    graph.edgeskindThe edge type name (e.g., “Knows”)
    startSource node reference that must match a node ID in the nodes section
    endTarget node reference that must match a node ID in the nodes section
    DELETE ME: Base kind is required for simple search to work; is that expected?
2

Save the file

Save the opengraph-example.json file to a location you can easily access for uploading in the next step.
3

Upload the JSON file

Use the BloodHound web interface to upload the opengraph-example.json file directly through the browser.
  1. Log in to your BloodHound instance.
  2. In the left menu, click Quick Upload.
  3. Click the Upload Files screen to open a file system dialog or drag and drop the opengraph-example.json file.
  4. Click Upload and wait for the upload to complete. You should see a confirmation message indicating the file was successfully ingested.
    If you receive an error, validate your JSON file using a linter and ensure all required properties are present.

​
Customize nodes

To enhance the visualization of the node types on the graph and in the Entity panel, you can define custom icons and colors.
This is done separately from the OpenGraph data payload and must be uploaded through the BloodHound API.
1

Prepare your custom type definition

This example creates a custom definition for the Person node type defined in the example JSON file. It specifies that the Person node type should display with a user icon and red color.The custom type definition is a JSON object with the following structure:
{
  "custom_types": {
    "Person": {
      "icon": {
        "type": "font-awesome",
        "name": "user",
        "color": "#FF0000"
      }
    },
      ... other custom type definitions ...
  }
}
The following table describes the properties in the custom type definition:
PropertyDescription
custom_typesObject containing custom type definitions, where each key is a node type and the value defines the visualization properties for that type
icon.typeFont Awesome is the icon library used for custom icons
icon.nameFont Awesome icon name (without “fa-” prefix)
icon.colorHex color code (#RGB or #RRGGBB format)
2

Run a POST request

Use a POST request to the BloodHound API to upload your custom type definition.Here’s an example request body for a Person node type with a user icon and red color:
curl -X POST \
  https://your-bloodhound-instance/api/v2/graphs/custom_nodes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_types": {
      "Person": {
        "icon": {
          "type": "font-awesome",
          "name": "user",
          "color": "#FF0000"
        }
      }
    }
  }'
After running this request, any nodes of type Person in your graph display with the specified icon and color.

​
Validate example data

After uploading the OpenGraph example data and custom node icons/colors, it’s important to validate that BloodHound ingested everything correctly and displays it as expected.
1

Open the Explore page

Log in to your BloodHound instance and navigate to the Explore page.
2

Search for nodes and edges

Use the Search features to find the example nodes and edges, and verify that properties and custom icons/colors are displayed correctly.

​
Delete example data

After you’ve finished testing, you should clean up your example data by deleting the example OpenGraph payload.
1

Delete example data

Use the BloodHound web interface to delete nodes by source_kind.
  1. Log in to your BloodHound instance.
  2. In the left menu, click Administration > Database Management.
  3. Under All graph data, check the Person data checkbox.
    The name of the checkbox is based on the value of the source_kind property in the metadata section of the example JSON file.
  4. Click Delete and confirm the deletion.
    This action permanently deletes all nodes with the Person source kind, including any edges connected to those nodes.
2

Verify deletion

Run the following Cypher query to confirm the example OpenGraph data is gone:
MATCH (n:Person)
RETURN n
You should see a No results match your criteria message confirming that the nodes have been deleted.

​
Troubleshooting

This section provides solutions to common issues you may encounter when testing your OpenGraph data.
  • Validate your JSON using JSONLint
  • Ensure all required sections are present
  • Verify all node IDs are unique
  • Check that node IDs referenced in edges match the node IDs in the nodes section exactly
  • Verify the icon name is correct and does not include a prefix, such as fa- (see FontAwesome to confirm available icons)
  • Ensure the color is in valid HEX format (#RGB or #RRGGBB)
  • Run a GET request to api/v2/graphs/custom_nodes to confirm your BloodHound instance contains the custom type definition you want to use
  • Verify the edge kind name is spelled correctly and matches your JSON file
  • Ensure the node IDs in the start and end references match your node IDs exactly
  • Check that both referenced nodes were created successfully

​
Next steps

After you’re comfortable with this process, consider:
  • Creating more complex node types with additional properties
  • Testing multiple edge types between different node kinds
  • Reading the OpenGraph Schema documentation for advanced configurations
  • Reviewing OpenGraph Best Practices before deploying production data