README
¶
A Go library to create BloodHound OpenGraphs easily
This library also exists in: Go | Python
Features
This module provides Go types and helpers for creating and managing graph structures that are compatible with BloodHound OpenGraph. The APIs follow the BloodHound OpenGraph schema and best practices.
If you don't know about BloodHound OpenGraph yet, a great introduction can be found here: https://bloodhound.specterops.io/opengraph/best-practices
Installation
Install with:
go get github.com/TheManticoreProject/bhopengraph
Examples
Here is an example of a Go program using the bhopengraph Go library to model the Minimal Working JSON from the OpenGraph Schema documentation:
package main
import (
"github.com/TheManticoreProject/bhopengraph"
"github.com/TheManticoreProject/bhopengraph/edge"
"github.com/TheManticoreProject/bhopengraph/node"
"github.com/TheManticoreProject/bhopengraph/properties"
)
func main() {
// Create an OpenGraph instance
graph := bhopengraph.NewOpenGraph("Base")
// Create nodes
bobProps := properties.NewProperties()
bobProps.SetProperty("displayname", "bob")
bobProps.SetProperty("property", "a")
bobProps.SetProperty("objectid", "123")
bobProps.SetProperty("name", "BOB")
bobNode, _ := node.NewNode("123", []string{"Person", "Base"}, bobProps)
aliceProps := properties.NewProperties()
aliceProps.SetProperty("displayname", "alice")
aliceProps.SetProperty("property", "b")
aliceProps.SetProperty("objectid", "234")
aliceProps.SetProperty("name", "ALICE")
aliceNode, _ := node.NewNode("234", []string{"Person", "Base"}, aliceProps)
// Add nodes to graph
graph.AddNode(bobNode)
graph.AddNode(aliceNode)
// Create edge: Bob knows Alice
knowsEdge, _ := edge.NewEdge(
bobNode.GetID(), // Bob is the start
aliceNode.GetID(), // Alice is the end
"Knows",
nil,
)
// Add edge to graph
graph.AddEdge(knowsEdge)
// Export to file
graph.ExportToFile("minimal_working_json.json")
}
This gives us the following Minimal Working JSON as per the documentation:
{
"graph": {
"edges": [
{
"end": {
"match_by": "id",
"value": "234"
},
"kind": "Knows",
"start": {
"match_by": "id",
"value": "123"
}
}
],
"nodes": [
{
"id": "123",
"kinds": [
"Person",
"Base"
],
"properties": {
"displayname": "bob",
"name": "BOB",
"objectid": "123",
"property": "a"
}
},
{
"id": "234",
"kinds": [
"Person",
"Base"
],
"properties": {
"displayname": "alice",
"name": "ALICE",
"objectid": "234",
"property": "b"
}
}
]
},
"metadata": {
"source_kind": "Base"
}
}
Contributing
Pull requests are welcome. Feel free to open an issue if you want to add other features.
References
Documentation
¶
Index ¶
- type OpenGraph
- func (g *OpenGraph) AddEdge(edge *edge.Edge) bool
- func (g *OpenGraph) AddEdgeWithoutValidation(edge *edge.Edge) bool
- func (g *OpenGraph) AddNode(node *node.Node) bool
- func (g *OpenGraph) AddNodeWithoutValidation(node *node.Node) bool
- func (g *OpenGraph) Clear()
- func (g *OpenGraph) ExportJSON(includeMetadata bool) (string, error)
- func (g *OpenGraph) ExportToFile(filename string) error
- func (g *OpenGraph) FindPaths(startID, endID string, maxDepth int) [][]string
- func (g *OpenGraph) GetConnectedComponents() []map[string]bool
- func (g *OpenGraph) GetEdgeCount() int
- func (g *OpenGraph) GetEdgesByKind(kind string) []*edge.Edge
- func (g *OpenGraph) GetEdgesFromNode(id string) []*edge.Edge
- func (g *OpenGraph) GetEdgesToNode(id string) []*edge.Edge
- func (g *OpenGraph) GetNode(id string) *node.Node
- func (g *OpenGraph) GetNodeCount() int
- func (g *OpenGraph) GetNodesByKind(kind string) []*node.Node
- func (g *OpenGraph) Len() int
- func (g *OpenGraph) RemoveNodeByID(id string) bool
- func (g *OpenGraph) String() string
- func (g *OpenGraph) ValidateGraph() []string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type OpenGraph ¶
type OpenGraph struct {
// contains filtered or unexported fields
}
OpenGraph struct for managing a graph structure compatible with BloodHound OpenGraph.
Follows BloodHound OpenGraph schema requirements and best practices.
Sources: - https://bloodhound.specterops.io/opengraph/schema#opengraph - https://bloodhound.specterops.io/opengraph/schema#minimal-working-json - https://bloodhound.specterops.io/opengraph/best-practices
func NewOpenGraph ¶
NewOpenGraph creates a new OpenGraph instance
func (*OpenGraph) AddEdge ¶
AddEdge adds an edge to the graph after performing validation checks.
It verifies that both the start and end nodes referenced by the edge exist in the graph, and that the edge is not a duplicate of an existing edge. If any validation fails, the edge is not added.
Arguments:
edge *edge.Edge: The edge to be added to the graph.
Returns:
bool: True if the edge was successfully added, false if validation failed
(e.g., nodes do not exist or the edge is a duplicate).
func (*OpenGraph) AddEdgeWithoutValidation ¶ added in v1.0.2
AddEdgeWithoutValidation adds an edge to the graph without validating the nodes.
This is a convenience function for adding edges without the validation checks performed by AddEdge. It is useful when you are sure that the nodes and edge already exist in the graph, or when you want to add an edge without performing the validation checks.
Arguments:
edge *edge.Edge: The edge to be added to the graph.
Returns:
bool: True if the edge was successfully added.
func (*OpenGraph) AddNode ¶
AddNode adds a node to the graph after performing validation checks.
It verifies that the node does not already exist in the graph, and that the node has a valid ID. If any validation fails, the node is not added.
Arguments:
node *node.Node: The node to be added to the graph.
Returns:
bool: True if the node was successfully added, false if validation failed
(e.g., node already exists or has an invalid ID).
func (*OpenGraph) AddNodeWithoutValidation ¶ added in v1.0.2
AddNodeWithoutValidation adds a node to the graph without validating the node.
This is a convenience function for adding nodes without the validation checks performed by AddNode. It is useful when you are sure that the node already exists in the graph, or when you want to add a node without performing the validation checks.
Arguments:
node *node.Node: The node to be added to the graph.
Returns:
bool: True if the node was successfully added.
func (*OpenGraph) Clear ¶
func (g *OpenGraph) Clear()
Clear removes all nodes and edges after performing validation checks.
It verifies that the nodes and edges exist in the graph, and that the nodes and edges have valid IDs. If any validation fails, the nodes and edges are not removed.
Arguments:
Returns:
nil: If the nodes and edges were successfully removed, nil if validation failed
(e.g., nodes or edges do not exist or have an invalid ID).
func (*OpenGraph) ExportJSON ¶
ExportJSON exports the graph to JSON format after performing validation checks.
It verifies that the nodes and edges exist in the graph, and that the nodes and edges have valid IDs. If any validation fails, the JSON is not returned.
Arguments:
includeMetadata bool: Whether to include metadata in the JSON.
Returns:
string: The JSON if it exists, nil if validation failed
(e.g., nodes or edges do not exist or have an invalid ID).
error: An error if the JSON is not returned.
func (*OpenGraph) ExportToFile ¶
ExportToFile exports the graph to a JSON file after performing validation checks.
It verifies that the nodes and edges exist in the graph, and that the nodes and edges have valid IDs. If any validation fails, the file is not written.
Arguments:
filename string: The name of the file to export the graph to.
Returns:
error: An error if the file is not written.
func (*OpenGraph) FindPaths ¶
FindPaths finds all paths between two nodes using BFS after performing validation checks.
It verifies that the start and end nodes exist in the graph, and that the start and end nodes have valid IDs. If any validation fails, the paths are not returned.
Arguments:
startID string: The ID of the start node. endID string: The ID of the end node. maxDepth int: The maximum depth of the paths to find.
Returns:
[][]string: The paths if they exist, nil if validation failed
(e.g., start or end node does not exist or has an invalid ID).
func (*OpenGraph) GetConnectedComponents ¶
GetConnectedComponents finds all connected components after performing validation checks.
It verifies that the nodes exist in the graph, and that the nodes have valid IDs. If any validation fails, the connected components are not returned.
Arguments:
Returns:
[]map[string]bool: The connected components if they exist, nil if validation failed
(e.g., nodes do not exist or have an invalid ID).
func (*OpenGraph) GetEdgeCount ¶
GetEdgeCount returns the total number of edges after performing validation checks.
It verifies that the edges exist in the graph, and that the edges have valid IDs. If any validation fails, the edge count is not returned.
Arguments:
Returns:
int: The number of edges if they exist, nil if validation failed
(e.g., edges do not exist or have an invalid ID).
func (*OpenGraph) GetEdgesByKind ¶
GetEdgesByKind returns all edges of a specific kind after performing validation checks.
It verifies that the kind is valid, and that the edges exist in the graph. If any validation fails, the edges are not returned.
Arguments:
kind string: The kind of edges to be returned from the graph.
Returns:
[]*edge.Edge: The edges if they exist, nil if validation failed
(e.g., kind is not valid or edges do not exist).
func (*OpenGraph) GetEdgesFromNode ¶
GetEdgesFromNode returns all edges starting from a node after performing validation checks.
It verifies that the node exists in the graph, and that the node has a valid ID. If any validation fails, the edges are not returned.
Arguments:
id string: The ID of the node to get edges from.
Returns:
[]*edge.Edge: The edges if they exist, nil if validation failed
(e.g., node does not exist or has an invalid ID).
func (*OpenGraph) GetEdgesToNode ¶
GetEdgesToNode returns all edges ending at a node after performing validation checks.
It verifies that the node exists in the graph, and that the node has a valid ID. If any validation fails, the edges are not returned.
Arguments:
id string: The ID of the node to get edges to.
Returns:
[]*edge.Edge: The edges if they exist, nil if validation failed
(e.g., node does not exist or has an invalid ID).
func (*OpenGraph) GetNode ¶
GetNode returns a node by ID after performing validation checks.
It verifies that the node exists in the graph, and that the node has a valid ID. If any validation fails, the node is not returned.
Arguments:
id string: The ID of the node to be returned from the graph.
Returns:
*node.Node: The node if it exists, nil if validation failed
(e.g., node does not exist or has an invalid ID).
func (*OpenGraph) GetNodeCount ¶
GetNodeCount returns the total number of nodes after performing validation checks.
It verifies that the nodes exist in the graph, and that the nodes have valid IDs. If any validation fails, the node count is not returned.
Arguments:
Returns:
int: The number of nodes if they exist, nil if validation failed
(e.g., nodes do not exist or have an invalid ID).
func (*OpenGraph) GetNodesByKind ¶
GetNodesByKind returns all nodes of a specific kind after performing validation checks.
It verifies that the kind is valid, and that the nodes exist in the graph. If any validation fails, the nodes are not returned.
Arguments:
kind string: The kind of nodes to be returned from the graph.
Returns:
[]*node.Node: The nodes if they exist, nil if validation failed
(e.g., kind is not valid or nodes do not exist).
func (*OpenGraph) Len ¶
Len returns the total number of nodes and edges after performing validation checks.
It verifies that the nodes and edges exist in the graph, and that the nodes and edges have valid IDs. If any validation fails, the length is not returned.
Arguments:
Returns:
int: The total number of nodes and edges if they exist, nil if validation failed
(e.g., nodes or edges do not exist or have an invalid ID).
func (*OpenGraph) RemoveNodeByID ¶
RemoveNodeByID removes a node and its associated edges after performing validation checks.
It verifies that the node exists in the graph, and that the node has a valid ID. If any validation fails, the node is not removed.
Arguments:
id string: The ID of the node to be removed from the graph.
Returns:
bool: True if the node was successfully removed, false if validation failed
(e.g., node does not exist or has an invalid ID).
func (*OpenGraph) String ¶
String returns a string representation of the graph after performing validation checks.
It verifies that the nodes and edges exist in the graph, and that the nodes and edges have valid IDs. If any validation fails, the string representation is not returned.
Arguments:
Returns:
string: The string representation if it exists, nil if validation failed
(e.g., nodes or edges do not exist or have an invalid ID).
func (*OpenGraph) ValidateGraph ¶
ValidateGraph checks for common graph issues after performing validation checks.
It verifies that the edges and nodes exist in the graph, and that the edges and nodes have valid IDs. If any validation fails, the errors are not returned.
Arguments:
Returns:
[]string: The errors if they exist, nil if validation failed
(e.g., edges or nodes do not exist or have an invalid ID).
Source Files
Directories