[Feature] Reverse feed — export the Identity Atlas graph to BloodHound via OpenGraph

[WimvandenHeijkant]

Summary

Run the integration the other way: export Identity Atlas's correlated, multi-system authorization graph as BloodHound OpenGraph JSON, so BloodHound can compute attack paths over our superset — on top of, or as a replacement for, its own collected data.

This is 3 of 3 companion feature requests from a feasibility study (docs/architecture/bloodhound-integration-feasibility.md,`` §5.6 / Option E). The three are related but independently buildable.

Why this is more than "the same thing backwards" — it's the platform play

Identity Atlas is a normalizing, identity-correlating superset: our Account Linking engine resolves accounts across systems to real people. BloodHound does not correlate identity across sources — it holds an AD graph, an Entra graph, a GitHub graph, an AWS graph as separate islands.

If we export our nodes/edges as OpenGraph with our identity links as the bridging edges, BloodHound can compute cross-system attack paths it structurally cannot derive on its own, e.g.:

"This GitHub identity is the same person (our link) as this Entra admin who holds GenericAll (our control edge) over an on-prem tier-zero group."

BloodHound alone can't draw that first hop; we can. This reframes Identity Atlas as the authorization system-of-record / shared graph, with our governance analytics and BloodHound's attack-path analytics as two consumers of one substrate — the concrete expression of "if we do our job right, we already have more data from more systems than any single collector."

How

• Emit an OpenGraph payload: { "graph": { "nodes":[…], "edges":[…] }, "metadata": { "source_kind": … } }.
  • Nodes: { id, kinds:[…], properties:{…} }; edges: { kind, start:{value,match_by}, end:{…}, properties }.
  • Constraints to respect: ≤ 3 kinds per node, property values primitives or homogeneous arrays (no null), edge kind matches ^[A-Za-z0-9_]+$, objectid = our stable id (dedup key → idempotent re-ingestion).
• Define custom OpenGraph node/edge kinds for our governance concepts (identities, business roles, governed assignments, our control edges), plus the identity-correlation bridge edges (e.g. a SameIdentity / member-of-Identity edge) that stitch the per-source graphs.
• Deliver to BloodHound via file ingest (drop the JSON) or the /api/v2 upload API. Optionally register an OpenGraph extension-definition (custom kinds + icons + traversal rules) so our nodes render/traverse natively.
• Support both modes: augment BloodHound's existing collected data, or replace it (be the sole source).

The gate — why this shares a dependency with #939 (but stays independent)

To feed BloodHound useful attack paths, our exported graph must carry the control edges at fidelity (GenericAll vs WriteDacl changes what's abusable). A coarse "has access" flag exports nodes and memberships but no abuse-relevant edges. So this depends on the fine-grained control-edge modelling (PrincipalRelationships / migration 057 + object-as-resource control assignments) — the same investment that lets #939 absorb control data. Model the control edges once; both directions light up. The exporter itself is independently buildable and can ship first for the membership/role/ownership subset.

Acceptance criteria

• An OpenGraph exporter: Identity Atlas graph → valid OpenGraph JSON (kinds ≤ 3, primitives-only, no null, stable ids).
• Custom node/edge-kind definitions for our governance concepts + identity-correlation bridge edges.
• Output validated against the OpenGraph spec and ingestible by BloodHound CE (file ingest and/or /api/v2).
• Augment and replace modes.
• Demonstrated cross-system path enabled by our identity correlation (the multi-source bridge) that BloodHound could not derive from its own collectors alone.
• Tests per repo conventions (coverage ratchet respected).

References

• Feasibility study §5.6 (Option E), §4.3 (control-edge modelling), §4.4 (correlation is ours).
• OpenGraph format: p0dalirius/bhopengraph; SpecterOps/OpenHound; BloodHound OpenGraph docs.

Related feature requests (BloodHound integration set — independent, not interdependent)

1. Collector file ingestion (data in, no BloodHound needed) — [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939.
2. Attack-path risk scoring (plugs into [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672) — [Feature] BloodHound attack-path risk scoring — the attack-path risk plugin (external data) #940.
3. This issue — reverse feed (data out, via OpenGraph).

Cross-links in a comment below.

[WimvandenHeijkant]

BloodHound integration set — related but independently buildable, in any order or subset:

• [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939 — collector file ingestion (data in; no BloodHound server needed)
• [Feature] BloodHound attack-path risk scoring — the attack-path risk plugin (external data) #940 — attack-path risk scoring (consume BH analytics as findings; plugs into [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672)
• [Feature] Reverse feed — export the Identity Atlas graph to BloodHound via OpenGraph #941 — reverse feed (data out; export our correlated graph to BloodHound via OpenGraph) ← this issue

Shares one enabling investment with #939 — modelling the fine-grained control edges (PrincipalRelationships / migration 057) — but the exporter itself can ship first for the membership/role/ownership subset. Feeds #940 its cross-system paths.

---

Generated by Claude Code

[github-actions]

@WimvandenHeijkant — DoR probe complete for #941 (reverse feed → BloodHound OpenGraph). I drafted the implementation against the live code and schema on main. The feature is well-motivated and most of it is buildable today, but the probe surfaced one factual correction and three scope-ambition choices that are yours to make. Everything else is packaged below as proposed decisions you can ratify in a single reply.

Probe findings (verified against main)

1. The stated dependency is mischaracterized — and largely moot for v1. Migration 057 (app/api/src/db/migrations/057_principal_relationships.sql) already exists on main, but it models only Owner / Sponsor principal-to-principal links (AI-agent owners, guest sponsors) — not GenericAll/WriteDacl-grade control edges. ACL-fidelity control-edge modelling does not exist anywhere in the schema, has no tracking issue of its own, and Identity Atlas has no AD collector — AD ACL data would only ever arrive via [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939 or CSV. So "model the control edges once; both directions light up" refers to work that is not yet defined anywhere.
2. What is exportable today is already attack-path-relevant. The live model gives us: all principals (incl. ServicePrincipal / ManagedIdentity / AIAgent), all resources (groups, EntraDirectoryRole, AppRole, DelegatedPermission, ApplicationPermission, BusinessRole), assignments (Direct/Indirect/Eligible + governed), resource relationships, ownership edges (GroupOwnership / ApplicationOwnership / ServicePrincipalOwnership — these are abuse-relevant control edges: a group owner can add members; an app-registration owner can mint credentials and authenticate as the app), Owner/Sponsor principal links, manager links, and — the differentiator — Identities + IdentityMembers as the cross-system bridge edges.
3. The flagship demonstration is feasible on demo data, no tenant needed. The demo dataset spans 5 systems (EntraID, HR, IGA, SAP ERP, AzureRM) with cross-system identities (e.g. Hassan Ibrahim: 3 accounts in 3 systems), so a path like SAP account → (same identity) → Entra account → (member of) → privileged directory role is constructible from demo data alone.
4. A natural home exists. The Data Export surface (app/api/src/routes/dataExport.js: read API tokens + Excel workbook download) is the exact precedent for "get our data into another tool"; an OpenGraph download slots straight into it.
5. The feasibility study is not on main. docs/architecture/bloodhound-integration-feasibility.md exists only on the claude/bloodhound-integration-feasibility-2tgoy0 branch (the issue's link is also malformed). The spec's foundation needs to land durably.

Backlog scan (A3): #939 and #940 confirmed as related-but-independently-buildable companions. #84 (export for all object types, awaiting-requestor) is an adjacent generic-export ask — this issue should not silently be treated as its answer. Sequencing note, not a blocker: landing #939 first multiplies this issue's value, since AD/GitHub/AWS data ingested there would then flow out here with real cross-source bridges.

Proposed decisions — ratify or veto in bulk (D1–D8)

• D1 — Placement & trigger. A read-only exporter module (app/api/src/export/openGraph.js) behind GET /api/export/opengraph, guarded like the existing export flows (data.export.ui for the UI button; fgr_ read tokens usable for scripted pulls). UI trigger: a "BloodHound (OpenGraph)" card on the existing Admin → Data Export page, next to the Excel workbook. No worker/crawler involvement — it's a read, not a sync.
• D2 — Node identity / merge strategy. objectid = the source externalId where present (uppercased for Entra GUIDs, so in augment mode our edges stitch onto the nodes AzureHound already created), falling back to our internal UUID; Identity nodes always use our UUID (they have no external counterpart). Stable across runs ⇒ idempotent re-ingestion, per the OpenGraph dedup contract.
• D3 — Kind taxonomy. A fixed mapping table in the exporter: node kinds like IAIdentity, IAUser, IAServicePrincipal, IAGroup, IADirectoryRole, IABusinessRole, IAAppRole…; edge kinds like IASameIdentity, IAMemberOf, IAEligibleFor, IAOwns, IAHasAppRole, IAHasPermission. All matching ^[A-Za-z0-9_]+$, ≤ 3 kinds per node, properties primitives / homogeneous arrays only, nulls dropped.
• D4 — Validation bar. CI validates the output against a vendored OpenGraph JSON schema plus fixture-backed unit + contract tests (including: empty database ⇒ valid empty graph; principal with no externalId; multi-account identity ⇒ bridge edges). The live BloodHound CE ingestion and the cross-system-path demonstration happen once, manually, during your functional-validation step — not as an automated CI dependency on a running BloodHound.
• D5 — "Replace" mode. Read as a documented deployment choice (the BloodHound operator simply doesn't run collectors; our feed is the sole source), enabled by the full-graph export + stable ids — not a separate code path. Augment is the same payload; the merging comes from D2.
• D6 — Extension definition. Registering custom kinds/icons/traversal rules in BloodHound ("render natively") = deferred phase 2; it lives on BloodHound's side, needs its API, and is not required for ingestion.
• D7 — Docs & DoD. New doc docs/sync/bloodhound-export.md, changelog fragment, and the new route documented in openapi.yaml (the drift gate requires it).
• D8 — Feasibility study. Fold its relevant content (§5.6 payload/constraints) into this issue's spec so the spec stands alone on main; landing the full doc is desirable but not a gate for this issue.

Questions only you can answer (scope-ambition — please choose, don't let these default)

1. Delivery ambition. Is v1 file-download only (you drop/upload the JSON into BloodHound yourself) acceptable, with authenticated push to BloodHound's /api/v2 (connection settings + credential in the vault + a push action) split out as an explicit phase-2 issue? Or must push ship in this issue? (Push makes it materially bigger: a new outbound-integration surface, credential storage, and live-instance validation — if you want it now, my route recommendation becomes a two-slice decomposition.)
2. Control-edge fidelity gate. Given finding 1: do you ratify v1 = full export of the graph as modelled today (memberships, roles, ownerships, app permissions, governance, identity bridges), with ACL-grade control edges as a separate follow-on issue to be created once that modelling exists? Or do you want this issue gated on the control-edge modelling work (which would first need its own defined issue and is otherwise unscheduled)?
3. "Augment and replace modes" AC. Does D5's reading match your intent — or did you mean the exporter should actively clear/overwrite BloodHound's own collected data? (That would force the push/API route and a live-BloodHound dependency into v1.)

Once you answer 1–3 and ratify (or amend) D1–D8 in one comment, the next pass pins the fixture ACs and time-travel criteria into the issue body and — barring surprises — certifies this ready for approval, or proposes the two-slice split if you chose push-in-v1.

Route: state:awaiting-requestor.