diff --git a/docs/opengraph/extensions/manage.mdx b/docs/opengraph/extensions/manage.mdx index bb57d5b2..29b0bdbe 100644 --- a/docs/opengraph/extensions/manage.mdx +++ b/docs/opengraph/extensions/manage.mdx @@ -1,13 +1,98 @@ --- -title: Manage Schemas +title: Extension-Based Data Ingestion +description: Learn how extension-based data ingestion works and how to manage OpenGraph extensions in BloodHound. +sidebarTitle: Data Ingestion --- -OpenGraph extensions are modular components that enhance the functionality of BloodHound by allowing users to integrate data from various platforms and technologies. These extensions enable users to collect, analyze, and visualize data from a wide range of sources, making it easier to identify relationships and patterns within their environment. +Applies to BloodHound Enterprise and CE -- New admin-focused page in OpenGraph section. +Extension-based data ingestion is available under early access. -- Document extension management workflows (upload, validate, search, delete bundles), data deletion guidance, edition-specific features, permissions, early access limitations. +When OpenGraph was introduced in BloodHound v8.0.0, it supported a generic data ingestion model that enabled rapid iteration and flexibility for early OpenGraph projects. This model required data payloads to conform to basic node, edge, and metadata schemas only. -- Include UI screenshots, callout for deletion behavior change (moved from Database Management page), and third-party bundle disclaimer. +To enable enhanced features and improve consistency across OpenGraph projects, BloodHound now supports an extension-based data ingestion model. This model allows you to register and manage the structures that shape your OpenGraph data in BloodHound. It requires data payloads to conform to an extension schema. -- Add link to OpenGraph Library for obtaining bundles. \ No newline at end of file +BloodHound still supports generic data ingestion. For new OpenGraph projects and updates to existing projects, use extension-based data ingestion to take advantage of enhanced platform capabilities. + +## Key concepts + +OpenGraph extensions are defined by a schema that specifies the structure and behavior of OpenGraph data for a specific identity provider, cloud service, or other platform. + +Review the following key concepts to understand how extension-based data ingestion works in BloodHound: + +| Concept | Description | +|---|---| +| **Extension schema** | A schema that defines the structure and behavior of OpenGraph data, including source, custom node and edge definitions, environment identification, and findings. | +| **Data payload** | The extension-based or generic data generated by an OpenGraph collector that you upload to BloodHound. | +| **Extension-based data** | Data payloads that conform to an extension schema, enabling enhanced features and support in BloodHound. | +| **Generic data** | Data payloads that conform to basic OpenGraph node, edge, and metadata schemas only. | +| **Collector** | A tool that authenticates to a third-party platform and generates a data payload that BloodHound can ingest. | + +Any OpenGraph collector can leverage extension-based data ingestion by updating its data payloads to conform to an extension schema. See OktaHound for an example. For collectors that have not yet been updated, you can continue to upload generic data payloads while working with the extension author to update your collector and data payloads. + +## Enhanced features + +The extension schema enables enhanced features for OpenGraph data in BloodHound that are not available for generic data. + +The following table summarizes the key features enabled by extension-based data ingestion and their availability in Community and Enterprise editions of BloodHound: + +| Feature |BloodHound Community logo|BloodHound Enterprise logo| +|---|---|---| +| Pathfinding | | | +| Environment filtering | | | +| Custom node icons and colors | (API-only) | (schema-defined) | +| Findings and remediation | | (coming soon) | + +BloodHound supports extension-specific [Cypher queries](/analyze-data/explore/cypher-search) that you can import separately. This allows extension authors to provide curated queries that you can use to perform general searches and create [Cypher-based](/analyze-data/privilege-zones/rules#cypher) rules for Privilege Zones. + +## Workflow + +The general workflow for extension-based data ingestion involves three main stages that include different steps. + +Not all steps are required (for example, uploading Cypher queries and creating Privilege Zone rules are optional), and the workflow is not strictly linear. However, the following diagram provides a high-level overview of the recommended workflow for extension-based data ingestion in BloodHound: + +```mermaid +flowchart LR + subgraph prepare[Install and Configure] + a["Download extension
and collector"] + a-->b["Register
extension"] + b-->c["Configure and
run collector"] + c-->d["Generate data
payload"] + end + + subgraph upload[Upload and Manage] + f["Upload data
payload"] + f-->g["Import Cypher
queries"] + g-->h["Update Privilege
Zone rules"] + end + + subgraph use[Explore and Analyze] + i["Explore data in
BloodHound"] + end + prepare-->upload-->use +``` + +## Before you begin + +Complete the following steps before registering an extension or uploading extension-based data: + + + + How you obtain extensions and collectors depends on your edition of BloodHound: + + - **BloodHound Community** users can download and use Community extensions and collectors from public GitHub repositories + + - **BloodHound Enterprise** customers can use both Community and Enterprise extensions and collectors; contact your Technical Account Manager to obtain Enterprise versions + + + After you obtain an extension and collector, review the prerequisites in the extension-specific setup documentation. + + For example, review collector permissions and required platform configurations, such as API service application registration. + + + Confirm that your [role](/manage-bloodhound/auth/users-and-roles#user-role-definitions) includes extension management permissions. + + + Verify the extension and collector versions are compatible with each other and with the version of BloodHound running on your tenant. + + diff --git a/docs/opengraph/overview.mdx b/docs/opengraph/overview.mdx index 0616989a..41366d14 100644 --- a/docs/opengraph/overview.mdx +++ b/docs/opengraph/overview.mdx @@ -7,7 +7,7 @@ description: "Learn about OpenGraph in BloodHound." ## Extensions - + Learn how to register and manage the structures that shape your OpenGraph data in BloodHound.