feat: Synthetic Zone Node - BED-8916

[kpowderly]

Description

This change:

Adds synthetic Zone nodes and MemberOfZone relationships to represent privilege zones directly in the graph. Zone nodes and memberships are automatically reconciled when zones are created, renamed, deleted, or updated. The behavior is controlled by the new zone_node feature flag.

This new behavior will be used to calculate hop count for Findings Prioritization. There are also additional plans to use it with pathfinding.

More information can be found here

Motivation and Context

Resolves BED-8916

How Has This Been Tested?

Integration Testing, Manual Testing

Screenshots (optional):

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist:

• I have met the contributing prerequisites
  • Assigned myself to this PR
  • Added the appropriate labels
  • Associated an issue: Issues and Pull Requests README #672
  • Read the Contributing guide: https://github.com/SpecterOps/BloodHound/wiki/Contributing
• I have ensured that related documentation is up-to-date
  • Open API docs
  • Code comments (GoDocs / JSDocs)
• I have followed proper test practices
  • Added/updated tests to cover my changes
  • All new and existing tests passed

Summary by CodeRabbit

• New Features

  • Added support for zone nodes in asset-group tiering.
  • Added membership relationships connecting nodes to their corresponding zones.
  • Added a configurable feature flag for zone-node functionality.
  • Added Zone and MemberOfZone graph types for display and analysis.

• Bug Fixes

  • Improved reconciliation of zone data, including stale and duplicate entries.
  • Ensured repeated processing produces consistent results.

• Tests

  • Added coverage for zone generation, membership updates, error handling, and reruns.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Essentials

Run ID: 27df8d57-2efc-4866-8406-19cb3241f7a6

📥 Commits

Reviewing files that changed from the base of the PR and between 15e4df7 and 61cb994.

📒 Files selected for processing (1)

• packages/go/analysis/agt_internal_test.go

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/go/analysis/agt_internal_test.go

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds Zone and MemberOfZone graph kinds, registers the zone_node feature flag, generates and reconciles zone nodes and memberships during tiering, and adds unit and integration coverage.

Changes

Zone Node Generation

Layer / File(s)	Summary
Zone graph and feature contracts cmd/api/src/database/migration/migrations/..., cmd/api/src/model/appcfg/flag.go, cmd/api/src/model/kind.go, packages/go/graphschema/*	The migration registers zone_node. The API exposes the flag constant and helper. The graph schema and kind mappings include Zone and MemberOfZone.
Zone reconciliation workflow packages/go/analysis/agt.go	When zone nodes are enabled, tiering creates, updates, deletes, and reloads zone nodes. It then reconciles MemberOfZone edges.
Zone reconciliation validation packages/go/analysis/agt_internal_test.go, packages/go/analysis/agt_integration_test.go, packages/go/analysis/analysis_integration_test.go	Unit and integration tests cover reconciliation, stale and duplicate data removal, membership replacement, idempotent reruns, error handling, feature-flag setup, and teardown changes.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant TagAssetGroupsAndTierZero
  participant generateZoneNodesAndMemberEdges
  participant graphDB
  TagAssetGroupsAndTierZero->>generateZoneNodesAndMemberEdges: invoke zone generation when zone nodes are enabled
  generateZoneNodesAndMemberEdges->>graphDB: read tier tags and existing zone nodes
  generateZoneNodesAndMemberEdges->>graphDB: reconcile zone nodes
  generateZoneNodesAndMemberEdges->>graphDB: reconcile MemberOfZone edges

Loading

Merge Risk: ⚪ Minimal · up to 61cb9

No actionable merge-blocking behavior is identified in the supplied change context.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.96% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 46 functions across 9 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: adding synthetic Zone nodes. It is concise and includes the associated ticket.
Description check	✅ Passed	The description explains the synthetic Zone nodes, MemberOfZone relationships, feature flag, motivation, associated ticket, testing, change type, and checklist status. The testing section is brief but…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

Warning

Some tools did not complete. Review the errors below.

🔧 golangci-lint (2.13.2)

Error: build linters: plugin(integrationparallel): plugin "integrationparallel" not found
The command is terminated due to an error: build linters: plugin(integrationparallel): plugin "integrationparallel" not found

---

_{Comment @coderabbitai help to get the list of available commands.}

[bsheth711]

LGTM but I might be a little biased 😅