Definition Schema

An extension definition schema tells BloodHound how to interpret, interact with, and represent extension-specific data payloads. Use it when you want your extension to produce a and enable advanced analysis features in BloodHound.

If you only need support, upload a valid OpenGraph data payload and skip this page.

An extension definition schema is a JSON file that OpenGraph extension developers provide for BloodHound users to install on the OpenGraph Management page before they upload data payloads that conform to the schema.

In BloodHound Enterprise, supported platform extensions (GitHub, Jamf, and Okta) are pre-installed. Other SpecterOps-supported schemas, such as SCIM, must still be uploaded manually.

This page describes the components of an extension definition schema. For a full example of how these components work together, see the example schema section at the end of the page.

{
  "schema": { ... },
  "node_kinds": [ ... ],
  "relationship_kinds": [ ... ],
  "environments": [ ... ]
}

object

required

Extension metadata identifying the extension, including version and namespace.

array

required

Defines custom node types, visual representations, and Entity Panel content for an extension.

array

required

Defines custom edge types, traversability behavior, and Entity Panel content for an extension.

array

Defines the environments for a platform and identifies which node kinds an extension treats as principals within each environment.BloodHound Enterprise uses these environment definitions to group analysis, findings, and metrics.

Namespacing

BloodHound uses namespaces to organize graph data. Each extension has a namespace key, which is used as a prefix in relevant name fields to indicate that the data belongs to that namespace. Namespacing allows multiple extensions to define similar graph data without conflicts, because the namespace prefix makes each name unique. With the exception of schema.name, all name fields must follow these namespacing rules to avoid collisions with built-in graph elements and other extensions. This does not apply to display_name fields, which are used only for human-readable labels.

Must be unique within the extension
Must be prefixed with the extension’s namespace separated by an underscore (for example, namespace_Name)
Must include more than just the namespace prefix

Although the schema.name field does not use a namespace prefix, it must still be unique for each extension. BloodHound treats extensions with matching schema.name fields as the same extension and overwrites existing extension definition schemas when uploaded.

If names are not unique or properly namespaced, schema uploads fail validation.
The tag namespace prefix is reserved in any letter case, including tag, Tag, and TAG. Do not use this prefix in an extension definition schema. If you do, BloodHound rejects the upload.

`schema`

Defines metadata about the extension itself.

{
  "name": "SOOkta",
  "display_name": "Okta Extension (by SpecterOps)",
  "version": "v2.8.1",
  "namespace": "Okta"
}

string

required

Unique name that identifies an extension in BloodHound.

string

required

Human-readable label shown for this extension in BloodHound.

string

required

Extension schema version, prefixed with v followed by semantic version format, for example v1.0.0.

string

required

Namespace key used as a prefix for all name fields in the node_kinds and relationship_kinds arrays to indicate that the data belongs to that namespace.

`node_kinds`

Defines all node types in your extension. Each node kind represents an entity type (for example: user, device, or environment).

[
  {
    "name": "Okta_User",
    "display_name": "Okta User",
    "description": "An Okta user account",
    "is_display_kind": true,
    "icon": "user",
    "color": "#d33115",
    "info": {
      "overview": {
        "title": "Overview",
        "position": 1,
        "markdown": {
          "content": "Okta user accounts represent identities that can authenticate to Okta."
        }
      }
    }
  }
]

string

required

Unique node kind identifier. Must follow namespacing rules. For each node in a data payload to be included in a structured graph, at least one value in its kinds array must match a node_kinds.name defined in the extension definition schema.The node schema for an environment must be defined here to be used for findings and metrics in BloodHound Enterprise.

string

required

Human-readable label shown for this node kind in BloodHound.

string

Optional description that explains what the node kind represents.

boolean

Determines whether to use the icon and color definitions for nodes of this kind in the graph.

string

Optional Font Awesome icon name (without the “fa-” prefix) to show for nodes of this kind in the graph.

string

Optional Hex color code (in #RGB or #RRGGBB format, the # is required) to apply to nodes of this kind in the graph.

object

Optional custom Entity Panel content for nodes of this kind.

`relationship_kinds`

Defines what kind of connections exist. Each relationship kind represents a specific type of connection that can exist between nodes.

[
  {
    "name": "Okta_ResetPassword",
    "description": "Ability to reset passwords or temporary credentials for scoped Okta users",
    "is_traversable": true,
    "info": {
      "abuse": {
        "title": "Abuse",
        "position": 1,
        "markdown": {
          "content": "An attacker can use this relationship to reset a user's password and access the account."
        }
      }
    }
  }
]

string

required

Unique relationship kind identifier. Must follow namespacing rules. For each edge in a data payload to be included in a structured graph, kind must match a relationship_kinds.name defined in the extension definition schema.

string

Optional description of what the relationship means.

boolean

Controls whether edges of this relationship kind are used for pathfinding and Attack Path detection.When is_traversable is set to true on a relationship kind, all edges of that kind inherit the same traversability behavior. Only are included in pathfinding and considered for findings and metrics.

object

Optional custom Entity Panel content for relationships of this kind.

`environments`

Environments are platform-specific groupings of nodes that BloodHound Enterprise uses to scope findings and metrics. Each environment definition specifies which node kinds represent within each environment.

[
  {
    "environment_kind": "Okta_Organization",
    "source_kind": "Okta",
    "principal_kinds": [
      "Okta_User",
      "Okta_Application",
      "Okta_ApiServiceIntegration"
    ]
  }
]

string

required

Represents which node type within the extension is considered an environment for organizational and analytics purposes. Must match a node kind defined in the node_kinds array.For findings and metrics in BloodHound Enterprise, the graph.nodes.properties.environmentid field for applicable nodes in the data payload must match this field.

string

required

Source kind that associates this environment definition with a specific platform for environment organization and selection. See Data source for details.

array

required

Node kinds defined by this extension/schema that BloodHound should treat as . Must match a node_kinds.name defined in this schema.BloodHound Enterprise incorporates these node kinds in findings and metrics.

Example schema

The following example schema is based on Okta to illustrate how the different components of the schema work together.

{
  "schema": {
    "name": "SOOkta",
    "display_name": "Okta Extension (by SpecterOps)",
    "version": "v1.0.0",
    "namespace": "Okta"
  },
  "node_kinds": [
    {
      "name": "Okta_User",
      "display_name": "Okta User",
      "description": "An Okta user account",
      "is_display_kind": true,
      "icon": "user",
      "color": "#d33115",
      "info": {
        "overview": {
          "title": "Overview",
          "position": 1,
          "markdown": {
            "content": "Okta user accounts represent identities that can authenticate to Okta."
          }
        }
      }
    }
  ],
  "relationship_kinds": [
    {
      "name": "Okta_ResetPassword",
      "description": "Ability to reset passwords or temporary credentials for scoped Okta users",
      "is_traversable": true,
      "info": {
        "abuse": {
          "title": "Abuse",
          "position": 1,
          "markdown": {
            "content": "An attacker can use this relationship to reset a user's password and access the account."
          }
        }
      }
    }
  ],
  "environments": [
    {
      "environment_kind": "Okta_Organization",
      "source_kind": "Okta",
      "principal_kinds": [
        "Okta_User",
        "Okta_Application",
        "Okta_ApiServiceIntegration"
      ]
    }
  ]
}

Get Started with BloodHound

Install a Data Collector

Collect Data

OpenGraph

OpenHound

Analyze Attack Path Data

Manage BloodHound

API & Integrations

On-premises BloodHound Enterprise

Resources

Namespacing

`schema`

`node_kinds`

`relationship_kinds`

`environments`

Example schema

​Namespacing

​schema

​node_kinds

​relationship_kinds

​environments

​Example schema

Namespacing

`schema`

`node_kinds`

`relationship_kinds`

`environments`

Example schema