Configure the Collector

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:

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
Organization GitHub App
Fine-grained PAT

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

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

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.

Get Started with BloodHound

Install a Data Collector

Collect Data

OpenGraph

OpenHound

Analyze Attack Path Data

Manage BloodHound

API & Integrations

On-premises BloodHound Enterprise

Resources

Configure the Collector

Prerequisites

Configure OpenHound

Running OpenHound and Collecting Data

​Prerequisites

​Configure OpenHound

​Running OpenHound and Collecting Data

Prerequisites

Configure OpenHound

Running OpenHound and Collecting Data