BP-2210: Align glossary with internal source and copy edit #145
Conversation
WalkthroughThis PR updates the glossary ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/resources/glossary/overview.mdx (1)
73-81: Consider minor rephrase for style.The Impact section clearly defines the concept, but line 81 could be rephrased to avoid starting three consecutive sentences with "Impact."
💡 Optional stylistic improvement
-Impact is closely related to [exposure](#exposure), which measures the percentage of principals with a *Tier Zero* attack path. Together, these metrics help organizations prioritize remediation by understanding which attack paths pose the greatest risk. +This metric is closely related to [exposure](#exposure), which measures the percentage of principals with a *Tier Zero* attack path. Together, these metrics help organizations prioritize remediation by understanding which attack paths pose the greatest risk.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/resources/glossary/overview.mdx
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: jeff-matthews
Repo: SpecterOps/bloodhound-docs PR: 89
File: docs/resources/edges/az-role-approver.mdx:14-14
Timestamp: 2025-10-27T15:00:33.251Z
Learning: In the bloodhound-docs repository, documentation content derived from HelpTexts in the code should not be editorially changed unless there's an egregious error. Minor stylistic improvements should be submitted as PRs to the source code instead of being made directly in the documentation.
📚 Learning: 2025-08-22T22:40:24.105Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 53
File: docs/analyze-data/posture-page.mdx:33-41
Timestamp: 2025-08-22T22:40:24.105Z
Learning: BloodHound Enterprise has exactly four severity levels for attack paths: CRITICAL (95%–100%), HIGH (80%–94%), MODERATE (40%–79%), and LOW (0%–39%). There is no "NONE" or similar severity level for 0% exposure.
Applied to files:
docs/resources/glossary/overview.mdx
📚 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/resources/glossary/overview.mdx
🪛 LanguageTool
docs/resources/glossary/overview.mdx
[style] ~80-~80: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... by a specific identity vulnerability. Impact is closely related to [exposure](#expos...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~95-~95: ‘overall structure’ might be wordy. Consider a shorter alternative.
Context: ...t element contributing to the network's overall structure and security posture. An object can als...
(EN_WORDINESS_PREMIUM_OVERALL_STRUCTURE)
[grammar] ~119-~119: Ensure spelling is correct
Context: ...nt is hosted and managed by SpecterOps (SasS), while BloodHound CE is self-hosted an...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (8)
docs/resources/glossary/overview.mdx (8)
1-4: LGTM: Frontmatter enhancementThe addition of the description field improves metadata and SEO for the glossary page.
8-13: LGTM: Enhanced attack path definitionThe expanded definition with cross-references and the addition of identity-based attack path clarification improves the glossary's comprehensiveness.
24-30: LGTM: Valuable new glossary entriesThe Collector and Cypher entries fill important gaps in the glossary with clear, concise definitions and helpful cross-references.
44-46: LGTM: Important security term additionThe Escalation (ESC) entry appropriately documents ADCS attack path terminology used in BloodHound.
52-63: LGTM: Comprehensive finding definitionsThe new Finding entry with its distinction between list-based and relationship-based findings adds important clarity to BloodHound's vulnerability detection concepts.
91-95: LGTM: Important distinction between directory and graph entitiesThe Object entry clearly distinguishes between directory-level entities and their representation as nodes in BloodHound's graph.
113-115: LGTM: Clarifies rights vs. privilegesThe Right entry provides a valuable distinction from Privilege, helping readers understand the difference between system-level permissions and resource-specific actions.
50-50: Fix broken internal link on line 50.Line 50 contains a malformed link:
[Tier Zero](#tier-zerohigh-value)is missing the URL-encoded separator and should match the format on line 20:[Tier Zero](#tier-zero%2Fhigh-value). The current link will not resolve correctly.- [Tier Zero](#tier-zerohigh-value) + [Tier Zero](#tier-zero%2Fhigh-value)⛔ Skipped due to learnings
Learnt from: StephenHinck Repo: SpecterOps/bloodhound-docs PR: 53 File: docs/analyze-data/posture-page.mdx:33-41 Timestamp: 2025-08-22T22:40:24.105Z Learning: BloodHound Enterprise has exactly four severity levels for attack paths: CRITICAL (95%–100%), HIGH (80%–94%), MODERATE (40%–79%), and LOW (0%–39%). There is no "NONE" or similar severity level for 0% exposure.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/resources/glossary/overview.mdx (1)
73-81: Clear impact metrics definition.The new Impact section effectively defines both count and percentage metrics. The bullet-point structure makes the content scannable and easy to understand.
Optional: If you want to address the style hint about repeated sentence starts, consider rephrasing line 81 to something like: "These metrics work alongside exposure..." However, the current structure is perfectly clear and functional.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/resources/glossary/overview.mdx
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: jeff-matthews
Repo: SpecterOps/bloodhound-docs PR: 89
File: docs/resources/edges/az-role-approver.mdx:14-14
Timestamp: 2025-10-27T15:00:33.251Z
Learning: In the bloodhound-docs repository, documentation content derived from HelpTexts in the code should not be editorially changed unless there's an egregious error. Minor stylistic improvements should be submitted as PRs to the source code instead of being made directly in the documentation.
📚 Learning: 2025-08-22T22:40:24.105Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 53
File: docs/analyze-data/posture-page.mdx:33-41
Timestamp: 2025-08-22T22:40:24.105Z
Learning: BloodHound Enterprise has exactly four severity levels for attack paths: CRITICAL (95%–100%), HIGH (80%–94%), MODERATE (40%–79%), and LOW (0%–39%). There is no "NONE" or similar severity level for 0% exposure.
Applied to files:
docs/resources/glossary/overview.mdx
📚 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/resources/glossary/overview.mdx
🪛 LanguageTool
docs/resources/glossary/overview.mdx
[style] ~80-~80: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... by a specific identity vulnerability. Impact is closely related to [exposure](#expos...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~95-~95: ‘overall structure’ might be wordy. Consider a shorter alternative.
Context: ...t element contributing to the network's overall structure and security posture. An object can als...
(EN_WORDINESS_PREMIUM_OVERALL_STRUCTURE)
🔇 Additional comments (8)
docs/resources/glossary/overview.mdx (8)
2-3: LGTM! Clean metadata updates.The title format and new description field are appropriate for MDX frontmatter and improve the page's metadata.
10-22: Well-structured definitions with improved clarity.The rewritten definitions for Attack Path, APM, and Choke Point are more concise and direct. The URL-encoded anchor references maintain proper link integrity.
24-30: Excellent additions to the glossary.The Collector and Cypher definitions are clear, accurate, and include helpful cross-references.
34-34: Strong content improvements.The expanded Directory definition and new Escalation section add valuable context. The EAM section properly references the tiering section with correct URL encoding.
Also applies to: 42-46
52-63: Comprehensive Finding section with clear categorization.The new Finding definition with list-based and relationship-based types is well-structured and provides valuable detail about the different finding types and their metrics.
83-95: Excellent expansion of graph-related terminology.The updated Kind definition and new Object section provide clear distinctions between schema-level classifications, graph entities, and directory-level objects. The terminology hierarchy (Object → Node → Kind) is well-explained.
99-115: Well-differentiated security principal concepts.The expanded definitions for Principal, Privilege, and Right effectively distinguish these related but distinct concepts. The clarification that privileges are "resource-specific actions" while rights are "broad permissions" is particularly helpful.
119-119: Clear and accurate definitions for tenant and tiering concepts.The Tenant, Tier Zero, and Tiering definitions are well-written and properly cross-reference related concepts. The URL-encoded anchors maintain proper link integrity.
Note: The past review comment about a "SasS" → "SaaS" typo is no longer applicable, as the text has been reworded.
Also applies to: 123-123, 127-127
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/resources/glossary/overview.mdx (1)
10-12: LGTM!The revised definition is clearer and more actionable. The identity-based attack path sub-definition adds valuable context.
Minor readability nit: Consider replacing "identity/an" with "an identity or an" for slightly smoother reading:
-- **Identity-based attack path**—An attack path is based on identity/an already authenticated [principal](#principal). BloodHound's main goal is to help visualize and manage attack paths. +- **Identity-based attack path**—An attack path based on an identity or an already authenticated [principal](#principal). BloodHound's main goal is to help visualize and manage attack paths.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/resources/glossary/overview.mdx
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: jeff-matthews
Repo: SpecterOps/bloodhound-docs PR: 89
File: docs/resources/edges/az-role-approver.mdx:14-14
Timestamp: 2025-10-27T15:00:33.251Z
Learning: In the bloodhound-docs repository, documentation content derived from HelpTexts in the code should not be editorially changed unless there's an egregious error. Minor stylistic improvements should be submitted as PRs to the source code instead of being made directly in the documentation.
📚 Learning: 2025-08-22T22:40:24.105Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 53
File: docs/analyze-data/posture-page.mdx:33-41
Timestamp: 2025-08-22T22:40:24.105Z
Learning: BloodHound Enterprise has exactly four severity levels for attack paths: CRITICAL (95%–100%), HIGH (80%–94%), MODERATE (40%–79%), and LOW (0%–39%). There is no "NONE" or similar severity level for 0% exposure.
Applied to files:
docs/resources/glossary/overview.mdx
📚 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/resources/glossary/overview.mdx
🪛 LanguageTool
docs/resources/glossary/overview.mdx
[style] ~80-~80: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... by a specific identity vulnerability. Impact is closely related to [exposure](#expos...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~95-~95: ‘overall structure’ might be wordy. Consider a shorter alternative.
Context: ...t element contributing to the network's overall structure and security posture. An object can als...
(EN_WORDINESS_PREMIUM_OVERALL_STRUCTURE)
🔇 Additional comments (9)
docs/resources/glossary/overview.mdx (9)
2-3: LGTM!The metadata updates are well-formed. The description field is a good addition for SEO and helps users understand the page purpose.
16-22: LGTM!The definitions are clear and accurate. The URL-encoded anchor
#tier-zero%2Fhigh-valueis correctly applied for the internal link.
24-30: LGTM!Good additions. The Collector definition with concrete examples (SharpHound, AzureHound) is helpful, and the Cypher section provides appropriate context with links to both the specification and usage documentation.
34-46: LGTM!The revised Directory definition is more accurate, and the new Escalation section provides valuable context for ADCS attack paths. The URL-encoded anchor reference in EAM is consistent with other links.
50-63: LGTM!The Exposure anchor is now correctly URL-encoded (
#tier-zero%2Fhigh-value). The new Finding section is comprehensive and clearly distinguishes between list-based and relationship-based findings with their associated metrics.
73-85: LGTM!The new Impact section clearly defines the risk measurement concepts with helpful bullet points for count vs. percentage. The relationship to Exposure is well-explained. The Kind definition is appropriately precise about schema-level classification.
89-101: LGTM!The new Object section is a valuable addition, and the updated Node and Principal definitions now correctly cross-reference it. The distinction between directory objects and graph nodes is well-explained.
107-115: LGTM!The new Right section and updated Privilege definition provide a clear distinction between these related concepts. The cross-referencing helps readers understand the relationship.
119-127: LGTM!The Tenant definition is clear and concise. The Tier Zero/High Value and Tiering/Tier Model sections correctly use URL-encoded anchors and maintain proper cross-references to EAM.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/resources/glossary/overview.mdx (1)
58-59: Consider clarifying the exposure metric explanation for list-based findings.The parenthetical "(as they are theoretically completely exposed)" on lines 58-59 may be confusing to readers. If list-based findings are "completely exposed," readers might expect a 100% exposure metric rather than no metric at all. Consider clarifying why the metric is absent or unnecessary rather than framing it as "complete exposure."
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/resources/glossary/overview.mdx
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: jeff-matthews
Repo: SpecterOps/bloodhound-docs PR: 89
File: docs/resources/edges/az-role-approver.mdx:14-14
Timestamp: 2025-10-27T15:00:33.251Z
Learning: In the bloodhound-docs repository, documentation content derived from HelpTexts in the code should not be editorially changed unless there's an egregious error. Minor stylistic improvements should be submitted as PRs to the source code instead of being made directly in the documentation.
📚 Learning: 2025-08-22T22:40:24.105Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 53
File: docs/analyze-data/posture-page.mdx:33-41
Timestamp: 2025-08-22T22:40:24.105Z
Learning: BloodHound Enterprise has exactly four severity levels for attack paths: CRITICAL (95%–100%), HIGH (80%–94%), MODERATE (40%–79%), and LOW (0%–39%). There is no "NONE" or similar severity level for 0% exposure.
Applied to files:
docs/resources/glossary/overview.mdx
📚 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/resources/glossary/overview.mdx
🪛 LanguageTool
docs/resources/glossary/overview.mdx
[style] ~80-~80: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... by a specific identity vulnerability. Impact is closely related to [exposure](#expos...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~95-~95: ‘overall structure’ might be wordy. Consider a shorter alternative.
Context: ...t element contributing to the network's overall structure and security posture. An object can als...
(EN_WORDINESS_PREMIUM_OVERALL_STRUCTURE)
🔇 Additional comments (20)
docs/resources/glossary/overview.mdx (20)
1-4: LGTM! Good addition of metadata description.The description field is a valuable addition to the frontmatter, improving SEO and providing clear context for users.
10-13: LGTM! Clear definition with helpful identity-based context.The rewording improves clarity by leading with the core concept of a chain of abusable privileges, and the new identity-based attack path bullet provides valuable context.
16-16: LGTM! Clearer definition structure.The "The process of..." phrasing provides a more direct and clear definition structure.
18-23: LGTM! Comprehensive definition with correct anchor encoding.The expanded explanation effectively communicates the significance of choke points in network security architecture, and the anchor encoding is correctly formatted.
24-27: LGTM! Valuable addition with concrete examples.The new Collector definition is clear and the examples (SharpHound, AzureHound) help users understand the concept practically.
28-31: LGTM! Clear definition with helpful references.The definition accurately describes Cypher and provides useful links to both the OpenCypher specification and internal documentation.
34-35: LGTM! More accurate technical definition.The redefinition as "a service that stores identities and their attributes" is more technically precise and includes current examples (Entra ID).
40-43: LGTM! Accurate definition with authoritative citation.The definition correctly describes EAM with proper Microsoft documentation citation, and anchor encoding is correct.
44-46: LGTM! Valuable addition for ADCS attack paths.The new Escalation (ESC) definition clearly describes ADCS-based attack paths and their relation to certificate service misconfigurations.
48-51: LGTM! Clear definition with helpful examples.The exposure definition is comprehensive, includes practical examples of one-step and multi-step paths, and uses correct anchor encoding.
73-82: LGTM! Comprehensive new section with clear metrics.The Impact section effectively defines both impact count and impact percentage, and clearly explains their relationship to exposure metrics. This is a valuable addition to the glossary.
83-86: LGTM! Important distinction clearly explained.The clarification that Kind is a schema-level classification (not an instance) is important for understanding BloodHound's data model. The distinction from node instances is well-articulated.
87-90: LGTM! Clear definition with proper object reference.The updated Node definition effectively references directory objects and maintains consistency with the new Object glossary term.
91-96: LGTM! Critical distinction between objects and nodes.The new Object definition is essential for understanding the difference between directory-level entities and their graph representations. The explanation is clear and technically accurate.
97-102: LGTM! Accurate definition with comprehensive examples.The updated Principal definition correctly describes it as a type of object that can authenticate, and provides helpful examples across AD and cloud environments.
103-108: LGTM! Clear distinction between privileges and rights.The expanded Privilege definition effectively distinguishes it from Rights, clarifying that privileges are more granular and resource-specific.
113-116: LGTM! Valuable complement to Privilege definition.The new Right definition effectively complements the Privilege term by clarifying the distinction between broad system-level permissions (rights) and granular resource-specific actions (privileges).
117-120: LGTM! Clear tenant definition.The Tenant definition clearly describes it as a dedicated BloodHound Enterprise instance with appropriate scope.
121-124: LGTM! Clear definition with proper cross-reference.The Tier Zero definition is accurate with correctly encoded anchor reference and appropriate examples.
125-127: LGTM! Accurate definition with appropriate context.The Tiering definition provides valuable historical context while correctly noting that EAM has superseded it in most cases.
jeff-matthews
changed the title
Purpose
This pull request (PR) aligns the external glossary with the internal glossary as described in BP-2210.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.