OpenGraph FAQ entry for vanishing nodes #105
Conversation
WalkthroughAdded two FAQ accordion entries to the OpenGraph documentation explaining why OpenGraph nodes (and AD/AZ nodes tied to OpenGraph) can disappear after ingestion or after OpenGraph data deletion, detailing source_kind/reconciliation behavior and providing two-step workarounds with JSON payload examples. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/opengraph/faq.mdx (1)
60-60: Minor: Consider clarifying what makes the root node "lightweight".The workaround mentions "a lightweight root node" but the distinguishing characteristics could be more explicit. The example shows a minimal two-property node, but a brief clarification (e.g., "with just an id and basic properties") would help readers understand what "lightweight" means in this context and encourage lean designs.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/opengraph/faq.mdx(1 hunks)
🔇 Additional comments (2)
docs/opengraph/faq.mdx (2)
48-96: Comprehensive and well-structured FAQ entry addressing the vanishing nodes issue.The new entry clearly explains the reconciliation behavior, the distinction between BloodHound editions, and provides three practical workarounds with increasing sophistication. The JSON example effectively demonstrates the recommended anchoring pattern. The structure and tone align well with existing FAQ entries.
49-49: Fix broken external schema URL reference in JSON code examples.The internal anchor
#post-processingexists (line 246 in schema.mdx as### Post-processing) and the link is valid. However, the external schema URLhttps://raw.githubusercontent.com/SpecterOps/bloodhound-opengraph/main/bloodhound-opengraph.schema.jsonreturns HTTP 404. The URL appears in JSON code examples at lines 30 and 69 in faq.mdx. Either provide a current, accessible URL or document the correct source for the schema.⛔ Skipped due to learnings
Learnt from: StephenHinck Repo: SpecterOps/bloodhound-docs PR: 67 File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7 Timestamp: 2025-10-02T18:01:39.059Z Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/opengraph/faq.mdx (1)
53-53: Minor style refinement: Remove "of" for conciseness.LanguageTool flagged this line. The phrasing "all of the nodes" can be simplified to "all the nodes" without losing clarity.
Apply this diff:
- Ingesting nodes without edges in BloodHound Community Edition (BHCE) successfully creates and displays all of the nodes, including orphaned nodes. + Ingesting nodes without edges in BloodHound Community Edition (BHCE) successfully creates and displays all the nodes, including orphaned nodes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/opengraph/faq.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-10-02T18:01:39.059Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 67
File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7
Timestamp: 2025-10-02T18:01:39.059Z
Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
Applied to files:
docs/opengraph/faq.mdx
🪛 LanguageTool
docs/opengraph/faq.mdx
[style] ~53-~53: Consider removing “of” to be more concise
Context: ...BHCE) successfully creates and displays all of the nodes, including orphaned nodes. - For ...
(ALL_OF_THE)
🔇 Additional comments (3)
docs/opengraph/faq.mdx (3)
48-49: Clear explanation of reconciliation behavior.The opening establishes the key distinction and clarifies that this behavior is specific to BHE. Good alignment with the previous feedback to distinguish between editions clearly.
51-54: Terminology and phrasing effectively distinguish edition behavior.The bullet points clearly state that BHCE successfully creates and displays orphaned nodes while BHE deletes them during reconciliation. This directly addresses the earlier feedback to avoid ambiguity about whether reconciliation exists in both editions. Well done incorporating that clarification.
56-62: Two-step workaround is practical and well-documented.The workaround description aligns well with the earlier guidance about hybrid paths and
source_kindmetadata. Specifying that the first payload should have internal relationships (including the containment edge example) and avoid AD/AZ links, then linking in the second payload, is a clear and actionable approach that avoids the cross-source side effects mentioned in prior feedback.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/opengraph/faq.mdx (1)
48-64: Terminology and wording are clear; minor redundancy to remove.The new accordion entry effectively addresses the reconciliation behavior difference between BHE and BHCE, and the distinction in lines 53-54 is now much clearer than earlier drafts. The two recommended workarounds are practical and well-explained.
However, line 53 contains a minor redundancy: "all of the nodes" can be tightened to "all the nodes" without loss of clarity.
Apply this diff:
- Ingesting nodes without edges in BloodHound Community Edition (BHCE) successfully creates and displays all of the nodes, including orphaned nodes. + Ingesting nodes without edges in BloodHound Community Edition (BHCE) successfully creates and displays all the nodes, including orphaned nodes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/opengraph/faq.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-10-02T18:01:39.059Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 67
File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7
Timestamp: 2025-10-02T18:01:39.059Z
Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
Applied to files:
docs/opengraph/faq.mdx
🪛 LanguageTool
docs/opengraph/faq.mdx
[style] ~53-~53: Consider removing “of” to be more concise
Context: ...BHCE) successfully creates and displays all of the nodes, including orphaned nodes. - For ...
(ALL_OF_THE)
🔇 Additional comments (1)
docs/opengraph/faq.mdx (1)
65-81: Two-step workaround is clearly articulated and technically sound.The explanation of
source_kindbehavior in hybrid paths is accurate, and the two-step upload strategy is well-defined:
- First payload: isolated subgraph with
source_kindand internal edges, no AD/AZ references.- Second payload: linking isolated subgraph to AD/AZ nodes without
source_kindre-application.The Note on line 68 appropriately signals that this is a workaround pending a more comprehensive solution, which sets proper expectations for users. The concrete examples (
:OGRoot,:OGContains) make the guidance actionable.
craigw-SO
left a comment
There was a problem hiding this comment.
Provided a couple alternatives to provide potential clarifications.
|
Thanks for the review @craigw-SO! I addressed all of your comments. Please take another look when you get a chance. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/opengraph/faq.mdx (1)
48-68: Excellent treatment of the reconciliation behavior with clear workarounds.The accordion properly opens with an explicit BHE-only disclaimer and provides concrete guidance. The two workaround strategies (direct edge linking and root node approach) are clear and actionable, and the example of
(:OGRoot)-[:OGContains]->(:YourNode)is helpful.Consider applying a minor stylistic improvement on line 57: change "all of the nodes" to "all the nodes" for conciseness.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/opengraph/faq.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-10-02T18:01:39.059Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 67
File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7
Timestamp: 2025-10-02T18:01:39.059Z
Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
Applied to files:
docs/opengraph/faq.mdx
🪛 LanguageTool
docs/opengraph/faq.mdx
[style] ~57-~57: Consider removing “of” to be more concise
Context: ...BHCE) successfully creates and displays all of the nodes, including orphaned nodes. - For ...
(ALL_OF_THE)
🔇 Additional comments (1)
docs/opengraph/faq.mdx (1)
69-87: Solid explanation of source_kind side-effects with a practical two-step workaround.The accordion clearly explains the problem (source_kind applies to referenced AD/AZ nodes), the consequence (those nodes get deleted), and the solution (isolate the OpenGraph subgraph first, then link separately). The explicit guidance to exclude AD/AZ links from the first payload directly prevents the unintended side-effects.
The Note about the forthcoming comprehensive solution appropriately frames this as a temporary workaround, managing user expectations.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/opengraph/faq.mdx (1)
57-57: Minor style improvement: Simplify "all of the nodes."Replace "all of the nodes" with "all the nodes" for conciseness.
-- Ingesting nodes without edges in BloodHound Community Edition (BHCE) successfully creates and displays all of the nodes, including orphaned nodes. +- Ingesting nodes without edges in BloodHound Community Edition (BHCE) successfully creates and displays all the nodes, including orphaned nodes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/opengraph/faq.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-10-02T18:01:39.059Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 67
File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7
Timestamp: 2025-10-02T18:01:39.059Z
Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
Applied to files:
docs/opengraph/faq.mdx
🪛 LanguageTool
docs/opengraph/faq.mdx
[style] ~57-~57: Consider removing “of” to be more concise
Context: ...BHCE) successfully creates and displays all of the nodes, including orphaned nodes. - For ...
(ALL_OF_THE)
🔇 Additional comments (2)
docs/opengraph/faq.mdx (2)
48-68: Well-structured response to previous feedback on the first entry.The entry effectively addresses all of craigw-SO's prior concerns: the Note prominently clarifies BHE-only applicability, the bullets use definitive language ("successfully creates" vs "immediately deleted") to avoid ambiguity, and the workarounds are clearly presented with practical examples. The contextual framing around active data management helps users understand the purpose of reconciliation.
69-87: Excellent incorporation of feedback on the second entry.The entry effectively addresses all prior concerns: it provides concrete context about the source_kind implementation and its preliminary nature (lines 70–72), includes the disclaimer that this is a temporary workaround (line 74), and delivers the two-step upload process with clear guidance on payload separation to prevent cross-source side effects (lines 82–86). The structure guides users to success without introducing the edge-case complications that were flagged in earlier reviews.
|
Thanks @craigw-SO! I applied your latest suggestions. Please have another look when you get a chance. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/opengraph/faq.mdx (1)
64-65: Minor: Clarify the relative simplicity of the two linking approaches.Based on prior feedback, linking to an existing object versus linking to a node defined in the payload are equally simple. The method overall is simpler than the anchor node approach. Consider rephrasing to emphasize that the linking method itself is the simplest overall approach, rather than characterizing existing object linking as specifically simpler.
Suggested revision:
- Ensure each node defined in the payload has at least one edge connecting it to another node (either predefined or otherwise defined in the payload). Including an edge that links the node to an existing object is the simplest method. + Ensure each node defined in the payload has at least one edge connecting it to another node (either predefined or otherwise defined in the payload). This is the simplest method to resolve orphaned nodes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/opengraph/faq.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-10-02T18:01:39.059Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 67
File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7
Timestamp: 2025-10-02T18:01:39.059Z
Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
Applied to files:
docs/opengraph/faq.mdx
🔇 Additional comments (1)
docs/opengraph/faq.mdx (1)
48-87: Comprehensive and well-structured FAQ additions.The two new accordion entries effectively explain the orphaned node and source_kind side-effect behaviors, with clear distinctions between BHE and BHCE, actionable workarounds, and concrete examples. The structure (Note → context → "What this means" → "Recommended workaround") is consistent and easy to follow. All major feedback from prior review appears to be incorporated, including:
- Clear BHE-only disclaimer for reconciliation behavior
- Precise bullet points contrasting ingestion outcomes between editions
- Detailed source_kind context and side effects
- Two-step hybrid path guidance with specific payload instructions
- Acknowledgment of the interim nature of the source_kind workaround
Purpose
This pull request (PR) adds a new OpenGraph FAQ entry for "vanishing nodes" as requested in BED-6771.
Staging
https://specterops-bed-6771-og-orphaned-nodes.mintlify.app/opengraph/faq
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.