OpenHound is a standardized framework for building and running OpenGraph collectors and converters. It is built in Python and powered by the Data Load Tool (DLT) library, giving you a consistent workflow to collect, process, and convert data from any source into BloodHound-compatible graphs.
The openhound-github extension collects resources from Github organizations and transforms these into useable nodes and edges for BloodHound.
Enterprise GitHub App credentials accept either client_id or app_id as the
JWT issuer. When both are configured, client_id is preferred. At least one
identifier must be supplied together with key_path and enterprise_name.
GitHub.com is the default deployment and does not require endpoint configuration.
To collect from GitHub Enterprise Server, set both API endpoints in config.toml:
[sources.github]
rest_api_url = "https://ghe.example/api/v3"
graphql_url = "https://ghe.example/api/graphql"Both values must be provided together when overriding the GitHub.com defaults.
Endpoint URLs must use HTTPS and share the same origin. GitHub App
credentials.api_uri may override only the path on that same origin.
A token with enterprise SCIM access is used to collect both /scim/v2/enterprises/{enterprise}/Users and /scim/v2/enterprises/{enterprise}/Groups. The collector emits normalized SCIM_Organization, SCIM_User, and SCIM_Group nodes plus SCIM_Contains, SCIM_MemberOf, and SCIM_Provisioned relationships. Install the BloodHound SCIM extension alongside this extension to register the shared SCIM kinds.
SOURCES__GITHUB__EMIT_LEGACY_SCIM_CORRELATIONS=true temporarily reproduces GitHound-style Okta-to-SCIM correlation relationships. It defaults to false because a dedicated hybrid correlator should own IdP-to-SCIM matching; GitHub remains authoritative for GitHub's SCIM resources and target-system provisioning relationships.
Enterprise roles, including the built-in members role, are emitted through GH_HasRole and granular enterprise capability relationships. Only capability relationships with a confirmed privilege path are traversable; descriptive permissions such as GH_WriteEnterpriseSso remain non-traversable.
The collector runs successfully with the documented read-only permission set. Some higher-fidelity relationships require optional non-read-only permissions because GitHub exposes the supporting read APIs behind privileged permission names:
- Organization
Members: writeenables external group mapping collection for IdP-synced teams, which allows the converter to emitSCIM_Provisionededges fromSCIM_GrouptoGH_Team. This is useful when the organization uses team synchronization with an external identity provider; if no GitHub teams are linked to external groups, this permission does not add graph data. - Classic PAT scope
manage_runners:enterpriseenables enterprise self-hosted runner group and runner collection. This is useful when the enterprise has enterprise-scoped runner groups or runners, especially runner groups shared into organizations; if all runners are organization- or repository-scoped, this scope does not add graph data.
If these optional permissions are not granted, OpenHound skips the affected resources and continues collecting the rest of the GitHub environment.
Follow the OpenHound GitHub collector docs to get started: