Skip to main content
Applies to BloodHound Enterprise and CE This page covers downloading and running the GitHub collector against your GitHub organization.

​
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.
  • A Personal Access Token (PAT) or GitHub App Installation configured with the required permissions

​
Required Permissions

Both PAT and GitHub App authentication methods require the same set of Read-only permissions. The table below maps each permission to the collection functions it enables.

​
Repository permissions

  • Actions
  • Administration
  • Contents
  • Environments
  • Metadata
  • Secret scanning alerts
  • Secrets
  • Variables

​
Organization permissions

  • Administration
  • Custom organization roles
  • Custom repository roles
  • Members
  • Personal access tokens
  • Personal access token requests
  • Secrets
  • Variables

​
Configure OpenHound

The following OpenHound configuration parameters are required to run the Github collector. These can either be set via the [sources.source.github.credentials] section of the secrets file or via environment variables using the SOURCES__GITHUB__CREDENTIALS prefix.

​
Option 1: Github app installation

Parameter NameEnvironment VariableDescription
org_name{PREFIX}__ORG_NAMEThe name of the GitHub organization to collect data from.
app_id{PREFIX}__APP_IDThe GitHub App ID used to authenticate to the GitHub API.
client_id{PREFIX}__CLIENT_IDThe GitHub App Client ID used to authenticate to the GitHub API.
key_path{PREFIX}__KEY_PATHThe path to the GitHub App private key file.

​
Option 2: Fine-grained Personal Access Token (PAT)

Parameter NameEnvironment VariableDescription
org_name{PREFIX}__ORG_NAMEThe name of the GitHub organization to collect data from.
token{PREFIX}__TOKENThe fine-grained Personal Access Token (PAT) used to authenticate to the GitHub API.

​
Example Configuration

secrets.toml
[sources.source.github.credentials]
org_name = "my-github-org"
key_path = "/path/to/private/key.pem"
app_id = "123456"
client_id = "myclientid"

​
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.