chore: update openhound github collector reference docs

[jeff-matthews]

Summary

This is my first attempt at running the docs automation for the openhound-github collector repo.

I'm not sure if all of these changes are expected. It looks like the new docs have stripped out some mermaid diagrams and other info, but I'm not sure if that's expected. It certainly looks like the docs have been out of date since before the latest changes that prompted this PR: SpecterOps/openhound-github#22.

Here's a summary from the script I ran locally:

═══ Summary ═══
  Schema nodes: 34 | Doc nodes: 27
  Schema edges: 144 | Doc edges: 119

  Found 42 issue(s).

Schema consistency check found 42 issue(s).

See terminal output for details:
github-collector-doc-gen.txt

Note

The docs automation tooling failed on my first attempt. I created the following proposed fix in the upstream repo: SpecterOps/og-docs-automation#2.

Related to #376

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 873c1128-545a-441d-b157-7b9b8ea8494d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[JonasBK]

Will take a look before the end of the week

[JonasBK]

It looks like several node and edge kinds in the schema do not have corresponding description files in the OpenHound repository. Also, some documented edge kinds no longer exist in the schema. Unless those edges are expected to be added to the schema, I assume we can delete their documentation.

═══ Documentation vs schema ═══

  --- Edge Kinds ---
  In documentation but NOT in schema:
  [DOC ONLY] GH_HasBranch
  [DOC ONLY] GH_HasEnvironment
  [DOC ONLY] GH_HasJob
  [DOC ONLY] GH_HasStep
  [DOC ONLY] GH_HasWorkflow
  In schema but NOT in documentation:
  [UNDOCUMENTED] GH_AssignedTo
  [UNDOCUMENTED] GH_CanCreateInternalRepositories
  [UNDOCUMENTED] GH_CanCreatePrivateRepositories
  [UNDOCUMENTED] GH_CanCreatePublicRepositories
  [UNDOCUMENTED] GH_CanCreateRepositories
  [UNDOCUMENTED] GH_CanReadSecret
  [UNDOCUMENTED] GH_CanUseRunner
  [UNDOCUMENTED] GH_CreateEnterpriseOrganizations
  [UNDOCUMENTED] GH_EditEnterpriseCustomPropertiesForOrganizations
  [UNDOCUMENTED] GH_ManageEnterpriseAdmins
  [UNDOCUMENTED] GH_ManageEnterpriseIdentityProvider
  [UNDOCUMENTED] GH_ManageEnterpriseMembers
  [UNDOCUMENTED] GH_ManageEnterpriseOrganizationAdmins
  [UNDOCUMENTED] GH_ManageEnterpriseOrganizations
  [UNDOCUMENTED] GH_ManageEnterpriseReferrals
  [UNDOCUMENTED] GH_ManageEnterpriseTeams
  [UNDOCUMENTED] GH_ReadEnterpriseAuditLog
  [UNDOCUMENTED] GH_ReadEnterpriseDomainVerification
  [UNDOCUMENTED] GH_ReadEnterpriseMembers
  [UNDOCUMENTED] GH_ReadEnterpriseOrganizationAdmin
  [UNDOCUMENTED] GH_ReadEnterpriseOrgProjects
  [UNDOCUMENTED] GH_SetEnterpriseInteractionLimits
  [UNDOCUMENTED] GH_ViewEnterpriseActionsUsageMetrics
  [UNDOCUMENTED] GH_ViewEnterpriseBilling
  [UNDOCUMENTED] GH_ViewEnterpriseSecretScanningAlerts
  [UNDOCUMENTED] GH_WriteEnterpriseActionsPolicies
  [UNDOCUMENTED] GH_WriteEnterpriseBilling
  [UNDOCUMENTED] GH_WriteEnterprisePersonalAccessTokenPolicies
  [UNDOCUMENTED] GH_WriteEnterpriseSso
  [UNDOCUMENTED] GH_WriteEnterpriseTeamMembers

  --- Node Kinds ---
  All documented node kinds are in schema.
  In schema but NOT in documentation:
  [UNDOCUMENTED] GH_Enterprise
  [UNDOCUMENTED] GH_EnterpriseManagedUser
  [UNDOCUMENTED] GH_EnterpriseRole
  [UNDOCUMENTED] GH_EnterpriseTeam
  [UNDOCUMENTED] GH_OrgRunner
  [UNDOCUMENTED] GH_RepoRunner
  [UNDOCUMENTED] GH_RunnerGroup

@jaredcatkinson, are you planning to add descriptions for the undocumented node and edge kinds?

There is also an issue with the documentation-generation script / OpenHound repositories causing metadata for nodes and edges to be missing. Before the OH repositories were released, they included a docs/graph directory containing metadata about nodes and edges, for example, the source and destination node kinds for each edge. The script still expects these files to exist because the intention was to restore them to the OpenHound repositories.

@d3vzer0, it looks like the docs/graph directory was never restored in the OH collector repos. Could we add it back? The format does not need to be identical to the original, but we need a place to store the following metadata:

Edges

• Source and destination node kinds
• Properties
• Mermaid diagrams

Nodes

• Properties
• Mermaid diagrams

We do not need to store inbound and outbound edges for nodes because those can be derived from the edge definitions, avoiding redundant data.

[JonasBK]

I fixed the script and pushed the changes here: https://github.com/SpecterOps/og-docs-automation/

It now includes node and edge metadata by using the OpenHound command openhound create docs.

I also opened a PR in the OpenHound GitHub repo that updates the submodule and fixes a few OpenHound modules that caused documentation generation to fail: SpecterOps/openhound-github#51

Once that PR is merged and @jaredcatkinson has added the missing descriptions, we can generate the BloodHound docs with:

pwsh docs/og-docs-automation/scripts/Render-Docs.ps1 -Mode Official

[jeff-matthews]

Thanks @JonasBK!

[jaredcatkinson]

SpecterOps/openhound-github#51 has been merged. I honestly don't recall if I added all of the documentation for the node and edge types. I know I worked on some documentation but that may have been for snowflake. I can take another look here in a bit.

[jeff-matthews]

Closing this PR as outdated, but I'll create a new one when we're ready.

[jeff-matthews]

Thanks for all your help @JonasBK & @jaredcatkinson!

See #428 for the GitHub collector reference refresh.