[Feature] BloodHound attack-path risk scoring — the `attack-path` risk plugin (external data)

[WimvandenHeijkant]

Summary

Consume BloodHound's attack-path analytics — distance to Tier Zero, node exposure, reachable high-value targets, ADCS ESC findings, choke points — and surface them as risk findings on principals/identities. This is the attack-path plugin already named as "framework-ready, not built here" in docs/architecture/risk-scoring-plugins.md (§ Future plugins, flagged needsExternalData).

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

Plugs into #672

This belongs to the risk-scoring plugin tier being introduced in #672 ("[Refactor] Re-architect risk scoring into a plugin tier — findings + explainability + override"). It's a concrete needsExternalData plugin that fits that framework's finding + reason-context shape. Build order isn't strict, but this plugin lands cleanest on top of #672's plugin substrate.

This was the original motivation

Worth recording: the earlier BloodHound exploration was specifically about pulling risk metrics (attack paths) — not data-source ingestion. That instinct was right; this issue is the clean home for it. The two other companion issues (data ingestion #939, reverse feed) grew out of realizing BloodHound could be more than a risk source — but this remains the place where BloodHound is irreplaceable.

Why BloodHound is irreplaceable here (unlike #939)

The feasibility study sorts BloodHound's graph into three buckets:

• (A) Authorization facts — memberships, roles, ownership, and control edges (GenericAll, AdminTo, WriteDacl, …). These are data → companion issue [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939 ingests them.
• (B) Runtime session telemetry — dropped.
• (C) Derived attack computations — ESC classifications, shortest-path-to-Tier-Zero, choke-point scores. This is bucket C, and it is BloodHound's unique layer — analytics computed over the graph, not raw data. This issue consumes bucket C as findings.

Bucket C is exactly what a governance product cannot easily compute itself and what makes BloodHound worth talking to.

How

• Requires a running BloodHound CE instance (this is the key difference from [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939, which needs no server). BloodHound CE is free/OSS; no Enterprise licence needed for the read API.
• Read via BloodHound CE's /api/v2 REST API — auth by JWT or HMAC-signed request — and/or the raw Cypher endpoint POST /api/v2/graphs/cypher, or the official SDKs (SpecterOps/bloodhound-python-sdk, bloodhound-go-sdk).
• Pull per-principal attack-path metrics; attach as RiskFinding-shaped records (score/severity + rationale + structured evidence), consistent with [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672's plugin contract. Findings, never ResourceAssignments.
• Caveat: the Cypher endpoint has documented rough edges (SpecterOps/BloodHound#79) — validate large/whole-graph queries early.

Relationship to the other two issues

• Independent of [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939, but complementary: [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939 (control-edge ingestion) can tag the bucket-C-relevant edges at ingest so this plugin has richer local context; not a hard dependency.
• Naturally pairs with the reverse feed (companion issue Nightly test suite: fix 10 failures + comprehensive coverage expansion (Tier 1/2/3) #3): if we feed our correlated superset into BloodHound via OpenGraph, the attack paths this plugin reads back become cross-system — paths BloodHound could not compute without our identity correlation.

Acceptance criteria

• An attack-path risk plugin registered in the risk-plugin tier ([Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672), needsExternalData.
• Configurable BloodHound CE connection (base URL + JWT/HMAC credentials, vaulted).
• Pulls attack-path metrics via /api/v2 / Cypher / SDK and emits findings on principals/identities with rationale + evidence.
• Findings only — nothing written to ResourceAssignments.
• Graceful handling of Cypher endpoint limits / large graphs.
• Tests per repo conventions (coverage ratchet respected); external dependency mocked.

References

• Feasibility study §5.4 (Option C), and the three-bucket model in §4.2.
• docs/architecture/risk-scoring-plugins.md (§ Future plugins → attack-path).
• Risk-plugin tier refactor: [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672.

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. This issue — attack-path risk scoring (plugs into [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672).
3. Reverse feed — export our correlated graph to BloodHound via OpenGraph (data out).

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) ← this issue
• [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 one is where BloodHound is irreplaceable, and it's the only one of the three that needs a running BloodHound CE instance (free/OSS). It pairs especially well with #941: feed our correlated superset in, read cross-system attack paths back out.

---

Generated by Claude Code

[github-actions]

@WimvandenHeijkant — DoR probe result for #940: the intent and scope are unusually complete, but the spec cannot certify yet because the thing it plugs into does not exist in code. Routing to awaiting-design with one sequencing decision to make, plus a batch of proposals to ratify inline — everything is in this single comment so no ping-pong is needed.

What the probe found (against the real code)

1. The risk-plugin tier is a design document, not code. docs/architecture/risk-scoring-plugins.md opens with "Status: Proposal for review — not yet implemented." There is no riskscoring/plugins/ registry, and no migration creates RiskFindings, RiskScoringAlgorithms, or RiskScoringRuns. The only risk code today is the hard-wired engine (app/api/src/riskscoring/engine.js + routes/riskScores.js / riskProfiles.js / riskScoringRuns.js), whose runs still wipe RiskScores wholesale. Every acceptance criterion in this issue ("registered in the risk-plugin tier", "emits findings", "findings only") targets a contract and storage with no real table and no real module — Phase B's "trace every value to its real storage" fails at the first hop.
2. [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672 — the precondition — is itself parked at state:decompose, and the design doc's delivery plan (§10) places attack-path at slice 5, after framework + schema (slice 1) and the app-consent wedge plugin (slice 2).
3. No BloodHound code exists anywhere in the repo (clean grep) — this is greenfield and, as the issue says, genuinely independent of [Feature] BloodHound collector file ingestion — one crawler, three dialects (AD / Entra / GitHub / AWS) #939.
4. The referenced feasibility study is not on main. The link points to branch claude/bloodhound-integration-feasibility-2tgoy0. This issue is the durable spine; its key reference shouldn't live on a deletable branch.

Adversarial finding — CE vs Enterprise analytics (must be verified before certification)

The issue frames bucket C as analytics we read back: "distance to Tier Zero, node exposure, reachable high-value targets, ADCS ESC findings, choke points." Best available knowledge says several of these are BloodHound Enterprise capabilities (precomputed attack-path findings, exposure percentages, choke-point scoring), while CE exposes the graph, the Cypher endpoint, pathfinding, and Tier-Zero asset-group tagging — but not a packaged findings API. If that holds, the v1 plugin is really a curated Cypher query pack that we author and run via POST /api/v2/graphs/cypher, with us owning analytic correctness — a materially different build (and risk profile) from "consume BloodHound's computed findings", and one that makes the already-noted Cypher rough edges (SpecterOps/BloodHound#79) more central, not a footnote. This needs pinning against a live CE instance during design; the metric list in the issue should then be re-cut into "readable from CE" vs "we compute via Cypher" vs "Enterprise-only (out of scope)".

Decision needed — D1, sequencing (architect / product owner)

• (a) Proposed: park [Feature] BloodHound attack-path risk scoring — the attack-path risk plugin (external data) #940 as an explicit dependent of [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672, buildable once [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672's slice 1 (framework + schema: RiskFindings, registry/runner, shared reconcile()) and ideally slice 2 (the wedge plugin that proves the framework end-to-end) have landed. [Feature] BloodHound attack-path risk scoring — the attack-path risk plugin (external data) #940's spec then gets finalized against real tables and a real plugin contract, and should certify quickly.
• (b) Pull the substrate forward: re-activate [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672, decompose it, and build slice 1 now with attack-path as its second consumer. Bigger commitment, same end state.
• (Deliberately not offered: building attack-path against today's hard-wired engine — that forks the engine exactly the way the plugin design exists to prevent, and violates "fix at the source".)

Proposals to ratify (answer inline — no separate round-trip)

• P1 — v1 metric set (assuming the CE reality above): (1) path-to-Tier-Zero per principal — exists + hop count, via shortest path to the Tier Zero asset group; (2) ADCS ESC exposure — principals on ESC-vulnerable certificate-template paths; (3) defer exposure-% and choke-point scoring to phase 2, pending the CE/Enterprise verification. Findings carry a stable factor key (bh:tier-zero-path, bh:adcs-esc), severity derived from hop count / ESC class, and rationale + structured evidence (path snapshot, node ids) per the [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672 contract. This is the ambition cut — say so if you want the wider metric set as v1 instead.
• P2 — node→principal matching: match BloodHound nodes to Principals by externalId (Entra objectId / AD SID). Unmatched nodes are counted and surfaced in the run summary — never silently dropped, never auto-created as principals.
• P3 — no new UI surface in this issue: findings render through [Refactor] Re-architect risk scoring into a plugin tier (findings + explainability + override) #672's finding/override UI and the matrix's RiskFactor contexts; [Feature] BloodHound attack-path risk scoring — the attack-path risk plugin (external data) #940 ships the vaulted connection config (existing secrets/vault.js pattern: base URL + JWT/HMAC credentials) plus the plugin itself.
• P4 — validation-data plan: BloodHound CE runs in Docker for build-time validation, seeded with a public SharpHound sample dataset (pinned fixture); unit tests mock the HTTP client. This keeps the issue out of blocked-external — CE is free OSS and self-hostable, unlike a real tenant.
• P5 — merge the feasibility study to main as a docs-only PR so this issue's references survive branch cleanup.

Backlog scan (A3)

No duplicates. Related: #672 (precondition — see D1), #939 (complementary and independent; its control-edge ingestion could later tag richer local evidence for these findings), #921 (adjacent SPN/directory-permission visibility; no overlap). The third companion ("reverse feed via OpenGraph") is referenced as "#3" in the body but does not appear in the open backlog — if it has been filed, cross-link the real number; if not, that reference currently dangles.

---

Route: state:awaiting-design. D1 is the gate. Once it's decided — and P1–P5 are ratified or amended — the probe re-runs against the landed #672 substrate and this issue is well positioned to certify in one pass.