Skip to main content

Documentation Index

Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt

Use this file to discover all available pages before exploring further.

Applies to BloodHound Enterprise and Community Edition 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. 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": [ ... ]
}
​
schema
object
required
Extension metadata identifying the extension, including version and namespace.
​
node_kinds
array
required
Defines custom node types and their visual representations for an extension.
​
relationship_kinds
array
required
Defines custom edge types and their traversability behavior for an extension.
​
environments
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.
​
relationship_findings
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.
  • TAG is a reserved namespace prefix and cannot be used.

​
Findings and metrics

Applies to BloodHound Enterprise only
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.
FieldWhereRequirement
environment_kindExtension definition schemaMust 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_kindData payloadMust be present on nodes for them to be included in findings and metrics.
environmentidData payloadFor 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.
collectedData payloadMust 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"
}
​
name
string
required
Unique name that identifies an extension in BloodHound.
​
display_name
string
required
Human-readable label shown for this extension in BloodHound.
​
version
string
required
Extension schema version in semantic version format, for example v1.0.0.
​
namespace
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"
  }
]
​
name
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.
​
display_name
string
required
Human-readable label shown for this node kind in BloodHound.
​
description
string
Optional description that explains what the node kind represents.
​
is_display_kind
boolean
Determines whether to use the icon and color definitions for nodes of this kind in the graph.
​
icon
string
Optional Font Awesome icon name (without the “fa-” prefix) to show for nodes of this kind in the graph.
​
color
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
  }
]
​
name
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.
​
description
string
Optional description of what the relationship means.
​
is_traversable
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

Applies to BloodHound Enterprise only 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_Group",
      "Okta_Application",
      "Okta_ApiServiceIntegration"
    ]
  }
]
​
environment_kind
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.
​
source_kind
string
required
Source kind that associates this environment definition with a specific platform for environment organization and selection. See Data source for details.
​
principal_kinds
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

Applies to BloodHound Enterprise only 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."
    }
  }
]
​
name
string
required
Unique finding identifier. Must follow namespacing rules and be unique across all schema definition names, including node kinds, relationship kinds, and findings.
​
display_name
string
Human-readable label shown for this finding in BloodHound.
​
environment_kind
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.
​
relationship_kind
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.
​
remediation
object
Remediation guidance to resolve the finding, including both short and long forms.
​
remediation.short_description
string
A concise summary of the recommended remediation action.
​
remediation.long_description
string
A detailed explanation of the finding and its cause, which can include Markdown formatting for better readability.
​
remediation.short_remediation
string
A concise summary of the steps to remediate the finding.
​
remediation.long_remediation
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_Group",
        "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."
      }
    }
  ]
}