Configure the Collector

Configure the GitHub collector to gather data from your GitHub organization or enterprise.

This page covers configuring the OpenHound GitHub collector for your GitHub organization or enterprise account. Use this page to choose an authentication method and configure the collector settings in the secrets.toml file or environment variables.

Prerequisites

• OpenHound installed with the GitHub collector included.

  Follow the OpenHound installation instructions to set up OpenHound for BloodHound Community Edition. The GitHub collector is included by default in the OpenHound container image.

• One of the following authentication setups configured:

  • Enterprise GitHub App installation (recommended)
  • Organization GitHub App installation
  • Fine-grained Personal Access Token (PAT)

The OpenHound setup instructions for BloodHound Community Edition also apply to BloodHound Enterprise users, for now.

Configure OpenHound

The GitHub collector needs different settings based on the authentication method you choose. You can set those values in one of two places:

Method	Set the values here
secrets.toml file	[sources.source.github.credentials] section
Environment variables	SOURCES__SOURCE__GITHUB__CREDENTIALS

Click the tab that matches your authentication setup for details and example configurations.

Enterprise GitHub App

Use this option when you need enterprise-scoped collection.

Setting	Description	Environment Variable
client_id	The GitHub App Client ID used to authenticate to the GitHub API.	SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID
app_id	The GitHub App ID used to authenticate to the GitHub API.	SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID
key_path	The path to the GitHub App private key file.	SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH
enterprise_name	The slug of the GitHub enterprise to collect data from.	SOURCES__SOURCE__GITHUB__CREDENTIALS__ENTERPRISE_NAME
api_uri	The GitHub API base URI. For GitHub.com, use https://api.github.com.	SOURCES__SOURCE__GITHUB__CREDENTIALS__API_URI

secrets.toml

secrets.toml

[sources.source.github.credentials]
client_id = "your-client-id"
app_id = "your-app-id"
key_path = "/path/to/private/key.pem"
enterprise_name = "your-enterprise-slug"
api_uri = "https://api.github.com"

Environment variables

SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID=your-client-id
SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID=your-app-id
SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH=/path/to/private/key.pem
SOURCES__SOURCE__GITHUB__CREDENTIALS__ENTERPRISE_NAME=your-enterprise-slug
SOURCES__SOURCE__GITHUB__CREDENTIALS__API_URI=https://api.github.com

Organization GitHub App

Use this option for organization-scoped collection with higher GitHub API rate limits.

Setting	Description	Environment Variable
org_name	The name of the GitHub organization to collect data from.	SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME
app_id	The GitHub App ID used to authenticate to the GitHub API.	SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID
client_id	The GitHub App Client ID used to authenticate to the GitHub API.	SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID
key_path	The path to the GitHub App private key file.	SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH

secrets.toml

secrets.toml

[sources.source.github.credentials]
org_name = "your-github-org"
key_path = "/path/to/private/key.pem"
app_id = "123456"
client_id = "your-client-id"

Environment variables

SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME=your-github-org
SOURCES__SOURCE__GITHUB__CREDENTIALS__KEY_PATH=/path/to/private/key.pem
SOURCES__SOURCE__GITHUB__CREDENTIALS__APP_ID=123456
SOURCES__SOURCE__GITHUB__CREDENTIALS__CLIENT_ID=your-client-id

Fine-grained PAT

Use this option for smaller environments or testing.

Setting	Description	Environment Variable
org_name	The name of the GitHub organization to collect data from.	SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME
token	The fine-grained Personal Access Token (PAT) used to authenticate to the GitHub API.	SOURCES__SOURCE__GITHUB__CREDENTIALS__TOKEN

secrets.toml

secrets.toml

[sources.source.github.credentials]
org_name = "your-github-org"
token = "github_pat_xxxxxxxxxxxxx"

Environment variables

SOURCES__SOURCE__GITHUB__CREDENTIALS__ORG_NAME=your-github-org
SOURCES__SOURCE__GITHUB__CREDENTIALS__TOKEN=github_pat_xxxxxxxxxxxxx

Running OpenHound and Collecting Data

After you set the required configuration parameters, run OpenHound to start the collector and collect data from your . The collector will generate JSON files in the output directory that can be uploaded to BloodHound for analysis.

Large GitHub organizations or enterprises can trigger GitHub’s API rate limits during collection. If you see failed or retried requests, tune the HTTP request parameters to ride out rate limits instead of failing the run.