GitHound is a BloodHound OpenGraph collector for GitHub, designed to map your organization’s structure and permissions into a navigable attack‑path graph. It:

• Models Key GitHub Entities

  • GH_Organization: Your GitHub org metadata
  • GH_User: Individual user accounts in the org
  • GH_Team: Teams that group users for shared access
  • GH_Repository: Repositories within the org
  • GH_Branch: Named branches in each repo
  • GH_OrgRole, GH_TeamRole, GH_RepoRole: Org‑, team‑, and repo‑level roles/permissions

• Visualize & Analyze in BloodHound

  • Access Audits: See at a glance who has admin/write/read on repos and branches
  • Compliance Checks: Validate least‑privilege across teams and repos
  • Incident Response: Trace privilege escalations and group memberships

With GitHound, you get a clear, interactive graph of your GitHub permissions landscape—perfect for security reviews, compliance audits, and rapid incident investigations.

For detailed documentation, see BloodHound Docs - GitHound.

# 1. Load the collector
. ./githound.ps1

# 2. Create a session with your Personal Access Token
$session = New-GitHubSession -OrganizationName "YourOrgName" -Token (Get-Clipboard)

# 3. Run the collection
Invoke-GitHound -Session $session

# 4. Upload the resulting githound_<orgId>.json file to BloodHound

If collection is interrupted, resume from where you left off:

Invoke-GitHound -Session $session -Resume

For detailed setup instructions, see:

• Personal Access Token Collection — Standard collection using PATs
• App Installation Collection — Higher rate limits via GitHub App
• Troubleshooting — Common issues and solutions

For detailed documentation, see BloodHound Docs - GitHound Schema.

Key edge categories:

Primary attack path pattern:

(:GH_User)-[:GH_HasRole|GH_MemberOf|GH_AddMember*1..]->(:GH_RepoRole)-[:GH_AdminTo|GH_CanPush]->(:GH_Repository)

Find the object identifier for your target user:

MATCH (n:GH_User)
RETURN n

HINT: Select Table Layout

Replace the <object_id> value in the subsequent query with the user's object identifier:

MATCH p = (:GH_User {objectid:"<object_id>"})-[:GH_MemberOf|GH_AddMember|GH_HasRole|GH_HasBaseRole|GH_Owns*1..]->(:GH_RepoRole)-[:GH_WriteRepoContents]->(:GH_Repository)
RETURN p

Obtain the object identifier for your target repository:

MATCH (n:GH_Repository)
RETURN n

Take the object identifier for your target repository and replace the <object_id> value in the subsequent query with it:

MATCH p = (:GH_User)-[:GH_MemberOf|GH_HasRole|GH_HasBaseRole|GH_Owns|GH_AddMember*1..]->(:GH_RepoRole)-[:GH_WriteRepoContents]->(:GH_Repository {objectid:"<object_id>"})
RETURN p

MATCH p = (:GH_User)-[:GH_HasRole|GH_HasBaseRole]->(:GH_OrgRole {short_name: "owners"})
RETURN p

MATCH p = (:AZUser)-[:GH_SyncedTo]->(:GH_User)
RETURN p

Find GitHub entities that can assume Azure federated identities (OIDC trust relationships):

// All GitHub → Azure OIDC attack paths
MATCH p = (:GH_Repository|GH_Branch|GH_Environment)-[:GH_CanAssumeIdentity]->(:AZFederatedIdentityCredential)
RETURN p

// Users with paths to Azure via GitHub Actions
MATCH p = (:GH_User)-[:GH_HasRole|GH_MemberOf|GH_AddMember*1..]->(:GH_RepoRole)-[:GH_CanPush]->(:GH_Repository)-[:GH_CanAssumeIdentity]->(:AZFederatedIdentityCredential)
RETURN p

MATCH p = (:GH_Repository)-[:GH_HasSecret]->(:GH_OrgSecret)
RETURN p

MATCH p = (:GH_Repository)-[:GH_Contains]->(:GH_SecretScanningAlert)
RETURN p

We welcome and appreciate your contributions! To make the process smooth and efficient, please follow these steps:

1. Discuss Your Idea

   • If you’ve found a bug or want to propose a new feature, please start by opening an issue in this repo. Describe the problem or enhancement clearly so we can discuss the best approach.

2. Fork & Create a Branch

   • Fork this repository to your own account.

   • Create a topic branch for your work:

     git checkout -b feat/my-new-feature

3. Implement & Test

   • Follow the existing style and patterns in the repo.

   • Add or update any tests/examples to cover your changes.

   • Verify your code runs as expected:

     # e.g. dot-source the collector and run it, or load the model.json in BloodHound

4. Submit a Pull Request

   • Push your branch to your fork:

     git push origin feat/my-new-feature

   • Open a Pull Request against the main branch of this repository.

   • In your PR description, please include:

     • What you’ve changed and why.
     • How to reproduce/test your changes.

5. Review & Merge

   • I’ll review your PR, give feedback if needed, and merge once everything checks out.
   • For larger or more complex changes, review may take a little longer—thanks in advance for your patience!

Thank you for helping improve this extension! 🎉

Copyright 2025 Jared Atkinson

Licensed under the Apache License, Version 2.0
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Unless otherwise annotated by a lower-level LICENSE file or license header, all files in this repository are released under the Apache-2.0 license. A full copy of the license may be found in the top-level LICENSE file.