Metadata-Version: 2.4
Name: bloodhound-opengraph
Version: 1.0.1
Summary: A Python library for creating BloodHound OpenGraph JSON data
Home-page: https://github.com/rookuu/bloodhound-opengraph
Author: Luke Roberts
Author-email: Luke Roberts <rookuu@github.com>
Project-URL: Homepage, https://github.com/rookuu/bloodhound-opengraph
Project-URL: Documentation, https://github.com/rookuu/bloodhound-opengraph/blob/main/README.md
Project-URL: Repository, https://github.com/rookuu/bloodhound-opengraph
Project-URL: Bug Tracker, https://github.com/rookuu/bloodhound-opengraph/issues
Keywords: bloodhound,opengraph,security,graph,json
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: coverage>=6.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# BloodHound OpenGraph Helper Library

A Python library for creating BloodHound OpenGraph JSON data that conforms to the [BloodHound OpenGraph schema specification](https://bloodhound.specterops.io/opengraph/schema).

## Features

- **Type-safe**: Uses Python dataclasses and type hints for better code quality
- **Schema compliant**: Validates data against BloodHound OpenGraph requirements

## Installation

```bash
pip install bloodhound-opengraph
```

## Quick Start

```python
from opengraph import OpenGraphBuilder

# Create a builder
builder = OpenGraphBuilder(source_kind="MySystem")

# Add nodes
user = builder.create_node(
    id="alice@company.com",
    kinds=["User", "Person"],
    properties={
        "email": "alice@company.com",
        "displayname": "Alice Johnson",
        "active": True
    }
)

server = builder.create_node(
    id="web-server-01",
    kinds=["Computer", "Server"],
    properties={
        "hostname": "web-server-01.company.com",
        "ip_address": "10.0.1.100"
    }
)

# Add relationships
builder.create_edge(
    start_value="alice@company.com",
    end_value="web-server-01",
    kind="has_admin_access",
    properties={"granted_date": "2025-01-15"}
)

# Export as JSON
json_output = builder.to_json()
print(json_output)

# Or save to file
builder.save_to_file("opengraph_data.json")
```

## Core Classes

### OpenGraphBuilder
The main class for building OpenGraph structures:
- `add_node(node)`: Add a Node object
- `add_edge(edge)`: Add an Edge object  
- `create_node(id, kinds, properties=None)`: Create and add a node
- `create_edge(start_value, end_value, kind, ...)`: Create and add an edge
- `to_json(indent=2)`: Export as JSON string
- `save_to_file(filepath)`: Save to JSON file

### Node
Represents a graph node:
- `id`: Unique identifier (required)
- `kinds`: List of 0-3 kind labels (required, 0 only acceptable if source kind is set)
- `properties`: Optional dictionary of attributes

### Edge  
Represents a relationship between nodes:
- `start`: NodeReference to start node (required)
- `end`: NodeReference to end node (required)
- `kind`: Relationship type string (required)
- `properties`: Optional dictionary of attributes

### NodeReference
References a node in an edge:
- `value`: ID or name to match (required)
- `match_by`: MatchBy.ID or MatchBy.NAME (default: ID)
- `kind`: Optional kind filter

## Property Rules

Properties must follow BloodHound schema rules:
- Only primitive types: string, number, boolean
- Arrays of primitive types (must be homogeneous)
- No nested objects or arrays of objects
- Empty arrays are allowed

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [SpecterOps](https://specterops.io/) for BloodHound development and documentation
