BP-2432: Extension management tasks

docs/opengraph/extensions/manage.mdx

@@ -1,39 +1,19 @@
 ---
 title: Extension-Based Data Ingestion
-description: Learn how extension-based data ingestion works and how to manage OpenGraph extensions in BloodHound.
+description: Learn how to use extensions to enable enhanced features and support for your OpenGraph data in BloodHound.
 sidebarTitle: Data Ingestion
 ---
 
 <img noZoom src="/assets/enterprise-AND-community-edition-pill-tag.svg" alt="Applies to BloodHound Enterprise and CE"/>
 
 <Callout icon="bullhorn" color="#FFC107">Extension-based data ingestion is available under early access.</Callout>
 
-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.
+When OpenGraph was introduced in BloodHound v8.0.0, it supported generic data ingestion to enable rapid iteration and flexibility for early OpenGraph projects. Generic data ingestion required data payloads to conform to basic node, edge, and metadata schemas only.
 
-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.
-
-<Note>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.</Note>
-
-## 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. |
-
-<Tip>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.</Tip>
+To enable enhanced features and improve consistency across OpenGraph projects, BloodHound now also supports extension-based data ingestion.
 
 ## 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 |<img src="/assets/community-edition-pill-tag.svg" alt="BloodHound Community logo" style={{ width: "50%" }}/>|<img src="/assets/enterprise-edition-pill-tag.svg" alt="BloodHound Enterprise logo" style={{ width: "50%" }}/>|
@@ -43,36 +23,29 @@ The following table summarizes the key features enabled by extension-based data
 | Custom node icons and colors | <Icon icon="square-check" iconType="solid" color="#22c55e"/> (API-only) | <Icon icon="square-check" iconType="solid" color="#22c55e"/> (schema-defined) |
 | Findings and remediation | <Icon icon="square-xmark" iconType="solid" color="#ef4444"/> | <Icon icon="square-check" iconType="solid" color="#22c55e"/> |
 
-<Tip>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.</Tip>
+## Extensions
 
-## Workflow
+Extensions define the structures that shape OpenGraph data in BloodHound for specific identity providers, cloud services, or other third-party platforms. They require data payloads to conform to an extension schema.
 
-The general workflow for extension-based data ingestion involves three main stages that include different steps.
+<Tip>
+Any OpenGraph project can leverage extension-based data ingestion by defining an extension schema and ensuring that collected data payloads conform to that schema.
+</Tip>
 
-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:
+See the following table for important terms and definitions related to OpenGraph data and extensions:
 
-```mermaid
-flowchart LR
-	subgraph prepare[Install and Configure]
-		a["Download extension<br/>and collector"]
-        a-->b["Register<br/>extension"]
-        b-->c["Configure and<br/>run collector"]
-        c-->d["Generate data<br/>payload"]
-    end
+| 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. |
 
-	subgraph upload[Upload and Manage]
-		f["Upload data<br/>payload"]
-        f-->g["Import Cypher<br/>queries"]
-		g-->h["Update Privilege<br/>Zone rules"]
-	end
+## Manage extensions
 
-	subgraph use[Explore and Analyze]
-		i["Explore data in<br/>BloodHound"]
-	end
-    prepare-->upload-->use
-```
+Use the **OpenGraph Management** page in BloodHound to upload new extension schemas, view active extensions, and delete extensions that you no longer need.
 
-## Before you begin
+### Before you begin
 
 Complete the following steps before registering an extension or uploading extension-based data:
 
@@ -96,3 +69,110 @@ Complete the following steps before registering an extension or uploading extens
 		Verify the extension and collector versions are compatible with each other and with the version of BloodHound running on your tenant.
 	</Step>
 </Steps>
+
+### Workflow
+
+The general workflow for extension-based data ingestion involves three main stages that include different steps.
+
+The workflow is not strictly linear and not all steps are required. For example, uploading Cypher queries and creating Privilege Zone rules are optional. However, the following diagram provides a high-level overview of the recommended workflow:
+
+```mermaid
+flowchart TB
+	subgraph prepare[Configure and Collect]
+		a["Download extension<br/>and collector"]
+        a-->b["Configure and<br/>run collector"]
+        b-->c["Generate data<br/>payload"]
+    end
+
+	subgraph upload[Upload and Manage]
+		f["Register<br/>extension schema"]
+		f-->g["Upload data<br/>payload"]
+        g-->h["Import Cypher<br/>queries"]
+		h-->i["Update Privilege<br/>Zone rules"]
+	end
+
+	subgraph use[Explore and Analyze]
+		j["Explore data in<br/>BloodHound"]
+	end
+    prepare-->upload-->use
+```
+
+### Register an extension
+
+Registering an extension involves uploading the extension schema to BloodHound, which validates the schema and makes it available for use with compatible data payloads. Once registered, you can upload data payloads that conform to the extension schema and take advantage of enhanced features in BloodHound.
+
+<Steps>
+  <Step title="Open the OpenGraph Management page">
+	In the left menu, click **Administration** > **OpenGraph Management**.
+  </Step>
+  <Step title="Upload the extension schema">
+	1. Click **Upload File** to open a file system dialog or drag and drop an extension schema file onto the canvas.
+
+	1. Click **Upload** to begin the schema registration and validation process.
+
+	   <img
+		src="/images/opengraph/extensions/manage/upload-extension-schema.png"
+		alt="A screenshot showing the OpenGraph Management page with the Upload Schema Files dialog open, allowing the user to select a file and upload it."
+		style= {{ width: "50%" }}
+	   />
+  </Step>
+  <Step title="Confirm installation">
+	Confirm the extension appears in the list of active extensions.
+
+	<Frame>
+	  <img
+	    src="/images/opengraph/extensions/manage/active-extensions-list.png"
+		alt="A screenshot showing the OpenGraph Management page with the list of active extensions, highlighting the newly installed extension."
+	  />
+	</Frame>
+  </Step>
+</Steps>
+
+### Delete an extension
+
+Deleting an extension removes the extension schema from BloodHound, which disables enhanced features for any data payloads that conformed to that schema. However, the underlying data payloads remain in BloodHound and can still be explored in [Search](/analyze-data/explore/search#search).
+
+If you want to delete the data payloads associated with an extension, you can do so separately on the **Database Management** page.
+
+To delete an extension schema, click the <Icon icon="trash"/> (trash) icon next to the extension in the list of active extensions and confirm the deletion in the prompt.
+
+<Note>You cannot delete built-in extensions that come with BloodHound, but you can delete custom extensions that you have uploaded.</Note>
+
+### Update an extension
+
+Collectors and extension schemas are versioned separately to allow for more flexible updates, but this requires coordination to maintain compatibility and support. Follow these guidelines for managing updates:
+
+- Do not update collectors independently without confirming extension schema compatibility.
+- Update collectors and extension schemas together whenever possible.
+- For Enterprise, coordinate update cycles with your Technical Account Manager.
+
+To update an extension, upload the new version using the same process as registering a new extension. BloodHound validates the new schema and replaces the old version with the new one.
+
+## Upload data
+
+After an admin registers an extension, users can upload compatible data payloads and take advantage of enhanced features in BloodHound. Follow these steps to use extension-based data:
+
+<Steps>
+  <Step title="Upload data">
+	Upload a data payload that conforms to the registered extension schema.
+
+	1. In the left menu, click <Icon icon="arrow-up-from-bracket"/> **Quick Upload**.
+
+	1. Click the **Upload File** canvas to open a file system dialog or drag and drop the data payload file(s) onto the canvas.
+
+	1. Click **Upload** to begin the data ingestion and validation process.
+
+	   <Tip>You can monitor the progress of the upload and validation process on the [File Ingest](/collect-data/enterprise-collection/monitor#file-ingest) page.</Tip>
+  </Step>
+
+  <Step title="Explore and analyze">
+    Use the enhanced features enabled by the extension schema to explore and analyze your OpenGraph data in BloodHound.
+
+	| Feature | Description |
+	|---|---|
+	| Pathfinding | Use [Pathfinding](/analyze-data/explore/search#pathfinding) to identify attack paths and analyze relationships between entities in your environment |
+	| Cypher queries | [Import](/analyze-data/explore/cypher-search#import-and-export) and use extension-specific Cypher queries to perform general searches and create Privilege Zone rules |
+	| Environment filtering | Filter on schema-defined environments to focus on specific contexts in the **Attack Paths**, **Posture**, and **Zone Builder** pages |
+	| Findings and remediation | Use findings and remediation information to prioritize and address issues in your environment |
+  </Step>
+</Steps>