bloodhound-opengraph.schema.json

{
    "$schema": "https://json-schema.org/draft-07/schema#",
    "$id": "https://bloodhound.specterops.io/schema/v8",
    "title": "BloodHound OpenGraph Schema",
    "description": "A schema for representing BloodHound OpenGraph data.",
    "type": "object",
    "properties": {
        "$schema": {
            "type": "string",
            "description": "The URL of the schema that this document conforms to."
        },
        "metadata": {
            "title": "Metadata",
            "description": "Optional metadata about the ingest payload",
            "type": "object",
            "properties": {
                "source_kind": {
                    "type": [
                        "string",
                        "null"
                    ]
                }
            },
            "additionalProperties": false
        },
        "graph": {
            "type": "object",
            "properties": {
                "nodes": {
                    "type": "array",
                    "items": {
                        "title": "Generic Ingest Node",
                        "description": "A node used in a generic graph ingestion system. Each node must have a unique identifier (`id`) and at least one kind describing its role or type. Nodes may also include a `properties` object containing custom attributes.",
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "properties": {
                                "type": [
                                    "object",
                                    "null"
                                ],
                                "description": "A key-value map of node attributes. Values must not be objects. If a value is an array, it must contain only primitive types (e.g., strings, numbers, booleans) and must be homogeneous (all items must be of the same type).",
                                "additionalProperties": {
                                    "type": [
                                        "string",
                                        "number",
                                        "boolean",
                                        "array"
                                    ],
                                    "items": {
                                        "not": {
                                            "type": "object"
                                        }
                                    }
                                }
                            },
                            "kinds": {
                                "type": [
                                    "array"
                                ],
                                "items": {
                                    "type": "string"
                                },
                                "minItems": 0,
                                "maxItems": 3,
                                "description": "An array of kind labels for the node. The first element is treated as the node's primary kind and is used to determine which icon to display in the graph UI. This primary kind is only used for visual representation and has no semantic significance for data processing."
                            }
                        },
                        "required": [
                            "id",
                            "kinds"
                        ],
                        "examples": [
                            {
                                "id": "user-1234",
                                "kinds": [
                                    "Person"
                                ]
                            },
                            {
                                "id": "device-5678",
                                "properties": {
                                    "manufacturer": "Brandon Corp",
                                    "model": "4000x",
                                    "isActive": true,
                                    "rating": 43.50
                                },
                                "kinds": [
                                    "Device",
                                    "Asset"
                                ]
                            },
                            {
                                "id": "location-001",
                                "properties": null,
                                "kinds": [
                                    "Location"
                                ]
                            }
                        ]
                    }
                },
                "edges": {
                    "type": "array",
                    "items": {
                        "title": "Generic Ingest Edge",
                        "description": "Defines an edge between two nodes in a generic graph ingestion system. Each edge specifies a start and end node using either a unique identifier (id) or a name-based lookup. A kind is required to indicate the relationship type. Optional properties may include custom attributes. You may optionally constrain the start or end node to a specific kind using the kind field inside each reference.",
                        "type": "object",
                        "properties": {
                            "start": {
                                "type": "object",
                                "properties": {
                                    "match_by": {
                                        "type": "string",
                                        "enum": [
                                            "id",
                                            "name"
                                        ],
                                        "default": "id",
                                        "description": "Whether to match the start node by its unique object ID or by its name property."
                                    },
                                    "value": {
                                        "type": "string",
                                        "description": "The value used for matching — either an object ID or a name, depending on match_by."
                                    },
                                    "kind": {
                                        "type": "string",
                                        "description": "Optional kind filter; the referenced node must have this kind."
                                    }
                                },
                                "required": [
                                    "value"
                                ]
                            },
                            "end": {
                                "type": "object",
                                "properties": {
                                    "match_by": {
                                        "type": "string",
                                        "enum": [
                                            "id",
                                            "name"
                                        ],
                                        "default": "id",
                                        "description": "Whether to match the start node by its unique object ID or by its name property."
                                    },
                                    "value": {
                                        "type": "string",
                                        "description": "The value used for matching — either an object ID or a name, depending on match_by."
                                    },
                                    "kind": {
                                        "type": "string",
                                        "description": "Optional kind filter; the referenced node must have this kind."
                                    }
                                },
                                "required": [
                                    "value"
                                ]
                            },
                            "kind": {
                                "type": "string"
                            },
                            "properties": {
                                "type": [
                                    "object",
                                    "null"
                                ],
                                "description": "A key-value map of edge attributes. Values must not be objects. If a value is an array, it must contain only primitive types (e.g., strings, numbers, booleans) and must be homogeneous (all items must be of the same type).",
                                "additionalProperties": {
                                    "type": [
                                        "string",
                                        "number",
                                        "boolean",
                                        "array"
                                    ],
                                    "items": {
                                        "not": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        },
                        "required": [
                            "start",
                            "end",
                            "kind"
                        ],
                        "examples": [
                            {
                                "start": {
                                    "match_by": "id",
                                    "value": "user-1234"
                                },
                                "end": {
                                    "match_by": "id",
                                    "value": "server-5678"
                                },
                                "kind": "has_session",
                                "properties": {
                                    "timestamp": "2025-04-16T12:00:00Z",
                                    "duration_minutes": 45
                                }
                            },
                            {
                                "start": {
                                    "match_by": "name",
                                    "value": "alice",
                                    "kind": "User"
                                },
                                "end": {
                                    "match_by": "name",
                                    "value": "file-server-1",
                                    "kind": "Server"
                                },
                                "kind": "accessed_resource",
                                "properties": {
                                    "via": "SMB",
                                    "sensitive": true
                                }
                            },
                            {
                                "start": {
                                    "value": "admin-1"
                                },
                                "end": {
                                    "value": "domain-controller-9"
                                },
                                "kind": "admin_to",
                                "properties": {
                                    "reason": "elevated_permissions",
                                    "confirmed": false
                                }
                            },
                            {
                                "start": {
                                    "match_by": "name",
                                    "value": "Printer-007"
                                },
                                "end": {
                                    "match_by": "id",
                                    "value": "network-42"
                                },
                                "kind": "connected_to",
                                "properties": null
                            }
                        ]
                    }
                }
            },
            "required": [
                "nodes",
                "edges"
            ]
        }
    },
    "additionalProperties": false
}