Graph Definition

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 v9.3.0 and later, 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": [ ... ],
  "relationship_findings": [ ... ]
}

object

required

Extension metadata identifying the extension, including version and namespace.

array

required

Defines custom node types and their visual representations for an extension.

array

required

Defines custom edge types and their traversability behavior 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.

array

Defines the findings and remediation guidance BloodHound Enterprise uses when relationships of the specified kind represent potential Attack Paths in a target environment (based on Privilege Zone rules).

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.

Findings and metrics

This is a SpecterOps-managed feature. If it is not enabled in your environment, contact your account team for assistance.

To produce and metrics, your data payload and extension definition schema must adhere to specific requirements that enable BloodHound Enterprise to identify and analyze the relevant nodes, edges, and environments in the graph.

Field	Where	Requirement
`environment_kind`	Extension definition schema	Must match the environment node kind defined in the `node_kinds.name` field. If a relationship-based finding exists for the environment, `relationship_findings.environment_kind` must also match.
`source_kind`	Data payload	Must be present on nodes for them to be included in findings and metrics.
`environmentid`	Data payload	For nodes that belong to an environment, must be set to the `graph.nodes.id` of that environment node. That environment’s node kind must match the `node_kinds.name` with the corresponding `environments.environment_kind` definition.
`collected`	Data payload	Must be set to `true` on nodes with an environment kind to indicate that data has actually been collected for that environment. For example, your payload might include multiple environment nodes, but only nodes for environments with successfully collected data should have `collected: true`.

Users must also create Privilege Zone rules after installing an extension and prior to uploading a data payload to see findings in BloodHound Enterprise.

`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 in semantic version format, for example v1.0.0.

string

required

Namespace key used as a prefix for all name fields in the node_kinds, relationship_kinds, and relationship_findings 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"
  }
]

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.

`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
  }
]

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.

`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.

`relationship_findings`

Defines findings based on relationships. Each finding represents a single instance of an . BloodHound Enterprise identifies instances of a traversable edge targeting a node of higher privilege (violating a Privilege Zone boundary), analyzes the risk, and provides remediation guidance.

Best practiceIf a finding name would match its associated relationship_kind, include _Finding as a suffix in the name to distinguish them.For example:

Relationship kind name: Okta_ResetPassword
Finding name: Okta_ResetPassword_Finding

[
  {
    "name": "Okta_ResetPassword_Finding",
    "display_name": "Password Reset Permission Across Privilege Zones",
    "environment_kind": "Okta_Organization",
    "relationship_kind": "Okta_ResetPassword",
    "remediation": {
      "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "long_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
      "short_remediation": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "long_remediation": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur."
    }
  }
]

string

required

Unique finding identifier. Must follow namespacing rules and be unique across all schema definition names, including node kinds, relationship kinds, and findings.

string

Human-readable label shown for this finding in BloodHound.

string

required

Environment kind where this finding should be evaluated. Must match an environments.environment_kind and node_kinds.name defined in any installed extension definition schema.For intra-extension findings, this typically matches the environment kind defined by the same extension schema. For cross-platform findings (for example, hybrid relationships), the impacted environment kind may be different.

string

required

Relationship kind that contributes to this finding when matching edges are present and the edge crosses a Privilege Zone boundary. Must match a relationship_kinds.name defined in any installed extension definition schema.

object

Remediation guidance to resolve the finding, including both short and long forms.

string

A concise summary of the recommended remediation action.

string

A detailed explanation of the finding and its cause, which can include Markdown formatting for better readability.

string

A concise summary of the steps to remediate the finding.

string

A detailed, step-by-step guide to remediate the finding, which can include Markdown formatting for better readability.

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"
    }
  ],
  "relationship_kinds": [
    {
      "name": "Okta_ResetPassword",
      "description": "Ability to reset passwords or temporary credentials for scoped Okta users",
      "is_traversable": true
    }
  ],
  "environments": [
    {
      "environment_kind": "Okta_Organization",
      "source_kind": "Okta",
      "principal_kinds": [
        "Okta_User",
        "Okta_Application",
        "Okta_ApiServiceIntegration"
      ]
    }
  ],
  "relationship_findings": [
    {
      "name": "Okta_ResetPassword_Finding",
      "display_name": "Password Reset Permission Across Privilege Zones",
      "environment_kind": "Okta_Organization",
      "relationship_kind": "Okta_ResetPassword",
      "remediation": {
        "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
        "long_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
        "short_remediation": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
        "long_remediation": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur."
      }
    }
  ]
}

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

Findings and metrics

`schema`

`node_kinds`

`relationship_kinds`

`environments`

`relationship_findings`

Example schema

​Namespacing

​Findings and metrics

​schema

​node_kinds

​relationship_kinds

​environments

​relationship_findings

​Example schema

Namespacing

Findings and metrics

`schema`

`node_kinds`

`relationship_kinds`

`environments`

`relationship_findings`

Example schema