From 40880af35ae9b56c93fa89a0a00f7978f08648ff Mon Sep 17 00:00:00 2001 From: Jeff Matthews Date: Mon, 27 Jul 2026 10:52:26 -0500 Subject: [PATCH 1/2] wip: initial draft of info object updates --- docs/opengraph/developer/graph-definition.mdx | 83 +++++++++++++++++-- 1 file changed, 77 insertions(+), 6 deletions(-) diff --git a/docs/opengraph/developer/graph-definition.mdx b/docs/opengraph/developer/graph-definition.mdx index 02fd2d6e..b857d237 100644 --- a/docs/opengraph/developer/graph-definition.mdx +++ b/docs/opengraph/developer/graph-definition.mdx @@ -40,10 +40,10 @@ This page describes the components of an extension definition schema. For a full Extension metadata identifying the extension, including version and namespace. - Defines custom node types and their visual representations for an extension. + Defines custom node types, visual representations, and Entity panel content for an extension. - Defines custom edge types and their traversability behavior for an extension. + Defines custom edge types, traversability behavior, and Entity panel content for an extension. Defines the environments for a platform and identifies which node kinds an extension treats as principals within each environment. @@ -71,6 +71,35 @@ Although the `schema.name` field does not use a namespace prefix, it must still - 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. +## Custom Entity panel content + +Use the `info` object to define custom Entity panel sections for node kinds and relationship kinds. When a user selects a node or relationship in Explore, BloodHound renders matching `info` entries as accordion sections in the Entity panel. + +Each `info` object is a map of section identifiers to rendered sections. Use stable identifiers for the keys so future schema updates can modify the same section without changing its identity. + +```json +"info": { + "overview": { + "title": "Overview", + "position": 1, + "markdown": { + "content": "This content appears in the Entity panel." + } + } +} +``` + +| Field | Requirement | Description | +| --- | --- | --- | +| `info` key | Required | Stable section identifier. Must match `^[a-z0-9_-]{1,128}$`, which allows lowercase letters, numbers, hyphens, and underscores. | +| `title` | Required | Section title shown in the Entity panel accordion. | +| `position` | Required | Integer that controls section order. Lower values render first. Use `1` or greater. | +| `markdown.content` | Required | Markdown content rendered in the section body. | + +For a single kind, BloodHound orders sections by `position`. If a node has multiple kinds and more than one kind defines `info` entries, BloodHound orders the sections by `position`, then `title`, and then the contributing node kind. Relationship panels use the same ordering behavior with the contributing relationship kind as the final tiebreaker. + +If no `info` entries are defined for the selected kind, BloodHound does not render extension-defined Entity panel sections. + ## Findings and metrics Optional Hex color code (in `#RGB` or `#RRGGBB` format, the `#` is required) to apply to nodes of this kind in the graph. + + Optional [custom Entity panel content](/opengraph/developer/graph-definition#custom-entity-panel-content) for nodes of this kind. + ## `relationship_kinds` @@ -157,7 +198,16 @@ Defines what kind of connections exist. Each relationship kind represents a spec { "name": "Okta_ResetPassword", "description": "Ability to reset passwords or temporary credentials for scoped Okta users", - "is_traversable": true + "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." + } + } + } } ] ``` @@ -173,6 +223,9 @@ Defines what kind of connections exist. Each relationship kind represents a spec When `is_traversable` is set to `true` on a relationship kind, all edges of that kind inherit the same traversability behavior. Only traversable edges are included in pathfinding and considered for findings and metrics. + + Optional [custom Entity panel content](/opengraph/developer/graph-definition#custom-entity-panel-content) for relationships of this kind. + ## `environments` @@ -301,14 +354,32 @@ The following example schema is based on Okta to illustrate how the different co "description": "An Okta user account", "is_display_kind": true, "icon": "user", - "color": "#d33115" + "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 + "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": [ From f14f949772972481017c9b43f370481e72614c8a Mon Sep 17 00:00:00 2001 From: Jeff Matthews Date: Mon, 27 Jul 2026 13:02:01 -0500 Subject: [PATCH 2/2] docs: apply suggestions from PM review --- docs/opengraph/developer/graph-definition.mdx | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/opengraph/developer/graph-definition.mdx b/docs/opengraph/developer/graph-definition.mdx index b857d237..9fb8d2c9 100644 --- a/docs/opengraph/developer/graph-definition.mdx +++ b/docs/opengraph/developer/graph-definition.mdx @@ -40,10 +40,10 @@ This page describes the components of an extension definition schema. For a full Extension metadata identifying the extension, including version and namespace. - Defines custom node types, visual representations, and Entity panel content for an extension. + Defines custom node types, visual representations, and Entity Panel content for an extension. - Defines custom edge types, traversability behavior, and Entity panel content for an extension. + Defines custom edge types, traversability behavior, and Entity Panel content for an extension. Defines the environments for a platform and identifies which node kinds an extension treats as principals within each environment. @@ -71,9 +71,9 @@ Although the `schema.name` field does not use a namespace prefix, it must still - 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. -## Custom Entity panel content +## Custom Entity Panel content -Use the `info` object to define custom Entity panel sections for node kinds and relationship kinds. When a user selects a node or relationship in Explore, BloodHound renders matching `info` entries as accordion sections in the Entity panel. +Use the `info` object to define custom Entity Panel sections for node kinds and relationship kinds. When a user selects a node or relationship in Explore, BloodHound renders an Entity Panel with the specified accordion sections as defined by the `info` entries. Each `info` object is a map of section identifiers to rendered sections. Use stable identifiers for the keys so future schema updates can modify the same section without changing its identity. @@ -83,7 +83,7 @@ Each `info` object is a map of section identifiers to rendered sections. Use sta "title": "Overview", "position": 1, "markdown": { - "content": "This content appears in the Entity panel." + "content": "This content appears in the Entity Panel." } } } @@ -92,13 +92,15 @@ Each `info` object is a map of section identifiers to rendered sections. Use sta | Field | Requirement | Description | | --- | --- | --- | | `info` key | Required | Stable section identifier. Must match `^[a-z0-9_-]{1,128}$`, which allows lowercase letters, numbers, hyphens, and underscores. | -| `title` | Required | Section title shown in the Entity panel accordion. | -| `position` | Required | Integer that controls section order. Lower values render first. Use `1` or greater. | +| `title` | Required | Section title displayed in the Entity Panel accordion header. | +| `position` | Required | Integer that controls the order of extension-defined sections. Lower values render first. Use `1` or greater. | | `markdown.content` | Required | Markdown content rendered in the section body. | -For a single kind, BloodHound orders sections by `position`. If a node has multiple kinds and more than one kind defines `info` entries, BloodHound orders the sections by `position`, then `title`, and then the contributing node kind. Relationship panels use the same ordering behavior with the contributing relationship kind as the final tiebreaker. +Every Entity Panel starts with **Object Information** at position `0`. This section lists all properties for the selected node or relationship. -If no `info` entries are defined for the selected kind, BloodHound does not render extension-defined Entity panel sections. +BloodHound renders additional `info` entries for the selected node's primary kind or the selected relationship's kind after **Object Information**. BloodHound orders those extension-defined sections by `position`, then `title`. + +If no `info` entries are defined for the selected kind, BloodHound still renders **Object Information**, but does not render additional extension-defined Entity Panel sections. ## Findings and metrics @@ -186,7 +188,7 @@ Defines all node types in your extension. Each node kind represents an entity ty Optional Hex color code (in `#RGB` or `#RRGGBB` format, the `#` is required) to apply to nodes of this kind in the graph. - Optional [custom Entity panel content](/opengraph/developer/graph-definition#custom-entity-panel-content) for nodes of this kind. + Optional [custom Entity Panel content](/opengraph/developer/graph-definition#custom-entity-panel-content) for nodes of this kind. ## `relationship_kinds` @@ -224,7 +226,7 @@ Defines what kind of connections exist. Each relationship kind represents a spec When `is_traversable` is set to `true` on a relationship kind, all edges of that kind inherit the same traversability behavior. Only traversable edges are included in pathfinding and considered for findings and metrics. - Optional [custom Entity panel content](/opengraph/developer/graph-definition#custom-entity-panel-content) for relationships of this kind. + Optional [custom Entity Panel content](/opengraph/developer/graph-definition#custom-entity-panel-content) for relationships of this kind. ## `environments`