GitHound

Übersicht

GitHound ist ein BloodHound OpenGraph-Collector für GitHub, der entwickelt wurde, um die Struktur und Berechtigungen Ihrer Organisation in einem navigierbaren Angriffspfad-Graphen abzubilden. Er:

• Modelliert wichtige GitHub-Entitäten

  • GH_Organization: Metadaten Ihrer GitHub-Organisation
  • GH_User: Einzelne Benutzerkonten in der Organisation
  • GH_Team: Teams, die Benutzer für gemeinsamen Zugriff gruppieren
  • GH_Repository: Repositories innerhalb der Organisation
  • GH_Branch: Benannte Branches in jedem Repository
  • GH_OrgRole, GH_TeamRole, GH_RepoRole: Rollen/Berechtigungen auf Organisations-, Team- und Repository-Ebene

• Visualisieren und Analysieren in BloodHound

  • Zugriffsprüfungen: Auf einen Blick sehen, wer Admin-/Schreib-/Lesezugriff auf Repos und Branches hat
  • Compliance-Prüfungen: Least-Privilege über Teams und Repos hinweg validieren
  • Incident Response: Privilegieneskalationen und Gruppenmitgliedschaften nachverfolgen

Mit GitHound erhalten Sie einen klaren, interaktiven Graphen Ihrer GitHub-Berechtigungslandschaft – perfekt für Sicherheitsüberprüfungen, Compliance-Audits und schnelle Incident-Untersuchungen.

Dokumentation

Ausführliche Dokumentation finden Sie unter BloodHound Docs - GitHound.

Schnellstart

# 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

Falls die Sammlung unterbrochen wird, setzen Sie an der Stelle fort, an der Sie aufgehört haben:

Invoke-GitHound -Session $session -Resume

GitHub-App-Sitzungen

GitHound unterstützt sowohl Personal-Access-Token-Sitzungen als auch GitHub-App-Installationssitzungen. Der bestehende, auf Organisationen bezogene GitHub-App-Workflow bleibt unverändert:

. ./githound.ps1

$session = New-GitHubJwtSession `
  -OrganizationName "YourOrgName" `
  -ClientId $clientId `
  -PrivateKeyPath $privateKeyPath `
  -InstallationId $installationId

Invoke-GitHound -Session $session -CollectAll

Dieselbe Funktion kann auch enterprise-fähige Sitzungen erstellen:

. ./githound.ps1

$session = New-GitHubJwtSession `
  -EnterpriseName "YourEnterpriseSlug" `
  -ClientId $clientId `
  -PrivateKeyPath $privateKeyPath `
  -InstallationId $installationId `
  -PersonalAccessToken $pat

Enterprise-fähige Sitzungen behalten mehrere Authentifizierungskontexte auf der zurückgegebenen GitHound.Session bei:

• Headers: die GitHub-App-Installationstoken-Header, die für die normale Sammlung verwendet werden
• JwtHeaders: JWT-Header der GitHub-App, die für App-Ebene-Endpunkte wie die Installationsaufzählung verwendet werden
• PatHeaders: optionale Personal-Access-Token-Header für Sammlungspfade, die eine Benutzer-Token-Authentifizierung erfordern

Um die Installationen aufzulisten, die zur authentifizierten GitHub-App gehören:

Get-GitHubAppInstallation -Session $session |
  Select-Object TargetType, InstallationId, Login, Name, SuspendedAt

Workflow-Analyse

Das Workflow-Parsing ist jetzt in Invoke-GitHound integriert, wenn Sie -CollectAll verwenden. Der Collector wird:

• rohe GH_Workflow-Knoten und Workflow-Inhalte sammeln
• diese Workflows in GH_WorkflowJob und GH_WorkflowStep analysieren
• GH_CanPwnRequest und GH_CanDispatchTo berechnen
• die Ergebnisse in die normale konsolidierte githound_<orgId>.json-Ausgabe einfügen

Für Wiederaufnahme-/Debugging-Zwecke wird der Zwischenprüfpunkt der Workflow-Analyse als githound_WorkflowAnalysis_<orgId>.json geschrieben.

Enterprise-Sammlungsgrundlage

GitHound enthält jetzt eine minimale Enterprise-Sammlungsgrundlage über Git-HoundEnterprise. Dieser Collector erstellt derzeit:

• GH_Enterprise
• leichte GH_Organization-Stub-Knoten für Mitgliedsorganisationen
• GH_Contains-Kanten vom Enterprise zu seinen Organisationen

Enterprise-Benutzersammlung über Git-HoundEnterpriseUser fügt hinzu:

• GH_User
• GH_HasMember-Kanten vom Enterprise zu diesen Benutzern

Enterprise-SAML-Sammlung über Git-HoundEnterpriseSamlProvider fügt hinzu:

• GH_SamlIdentityProvider
• GH_ExternalIdentity
• GH_HasSamlIdentityProvider vom Enterprise zum Anbieter
• dieselben Identitätskorrelationskanten, die vom Organisations-SAML-Collector verwendet werden

Dieser Pfad erfordert eine PAT-gestützte Sitzung, da GitHub Enterprise-SAML über enterprise.ownerInfo bereitstellt.

Enterprise-Team-Sammlung über Git-HoundEnterpriseTeam fügt hinzu:

• GH_EnterpriseTeam
• GH_AssignedTo-Kanten von Enterprise-Teams zu zugewiesenen Organisationen
• GH_MemberOf-Kanten von Enterprise-Teams zu für die Organisation sichtbaren ent: GH_Team-Knoten mittels Eigenschaftsabgleich
• Enterprise-Team-members-Rollen und GH_HasRole-Kanten von Benutzern zu diesen Rollen

Enterprise-Rollen-Sammlung über Git-HoundEnterpriseRole fügt hinzu:

• GH_EnterpriseRole
• GH_Contains-Kanten vom Enterprise zu diesen Rollen
• GH_HasRole-Kanten von direkt zugewiesenen Benutzern und Enterprise-Teams
• eine standardmäßige owners-Rolle, die aus enterprise.ownerInfo.admins befüllt wird, wenn PAT-gestützte Enterprise-Administratordaten verfügbar sind

Derzeit werden rohe Enterprise-Berechtigungszeichenfolgen auf dem GH_EnterpriseRole-Knoten in seiner permissions-Eigenschaft beibehalten, anstatt in dedizierte Berechtigungskanten erweitert zu werden.

Enterprise-SCIM-Sammlung fügt derzeit hinzu:

• SCIM_User
• SCIM_Group
• SCIM_Provisioned von SCIM_User zu GH_ExternalIdentity
• SCIM_Provisioned von SCIM_Group zu GH_EnterpriseTeam, wenn GitHub die Enterprise-Team-group_id bereitstellt
• SCIM_MemberOf von SCIM_User zu SCIM_Group

Dies gibt GitHound eine anbieteragnostische Brücke vom gemeinsamen SCIM-Schema in das native Enterprise-Identitäts- und Team-Modell von GitHub.

Wenn ein gesammelter GH_SamlIdentityProvider den vorgelagerten IdP identifiziert, kann GitHound auch anbieterbewusste SCIM-Korrelationsecken innerhalb der SCIM-Sidecar-Ausgabe hinzufügen:

• Okta_User -> SCIM_User
  • abgeglichen durch Okta_User.id = SCIM_User.externalId
• Okta_Group -> SCIM_Group
  • abgeglichen durch Okta_Group.name = SCIM_Group.externalId
  • und Okta_Group.oktaDomain = GH_SamlIdentityProvider.foreign_environmentid

GitHound behält die SCIM-Ebene in einer eigenen Sidecar-Ausgabe, sodass diese Zuordnungen sichtbar bleiben, ohne SCIM-native Knoten in den Haupt-GitHub-nativen Enterprise-Graphen zu mischen:

• githound_<entId>.json enthält native GitHub-Enterprise-Daten
• githound_scim_<entId>.json enthält SCIM-native Knoten und SCIM-Brückenkanten
• githound_saml_<entId>.json enthält SAML- und externe Identitätsdaten
• githound_hybrid_<entId>.json enthält modellübergreifende Kanten wie SAML_Implements, SAML_HasAccount und GH_SyncedTo
• githound_saml_<entId>.json enthält auch die normalisierte SAML-Topologie für den GitHub-Dienstanbieter, einschließlich SAML_TrustsIssuer und SAML_HasAssertionConsumerService

Das native GitHub-Identitätsanbietermodell bleibt in den GitHub/SAML-nativen Ausgaben intakt:

• GH_ExternalIdentity
• GH_HasExternalIdentity
• GH_MapsToUser

Die normalisierte SAML-Ebene in githound_hybrid_<entId>.json platziert jetzt SAML_HasAccount direkt auf GH_User, während match_values aus den verknüpften GH_ExternalIdentity-SAML-Eigenschaften wie saml_identity_name_id und saml_identity_username abgeleitet werden.

Die von der Enterprise-Sammlung ausgegebenen GH_Organization-Stubs sind absichtlich als collected = false markiert. Sie stellen eine strukturelle Erkennung aus dem Enterprise-Kontext dar und sollen später durch die normale Organisationssammlung angereichert werden.

Für eine Enterprise-first-Orchestrierung sammelt Invoke-GitHoundEnterprise die unterstützten Enterprise-bezogenen Daten, zählt die zugehörigen Organisationsinstallationen auf und führt dann den vorhandenen Invoke-GitHound-Workflow für jede Organisation in einem eigenen Unterverzeichnis unter dem gewählten Prüfpunktpfad aus.

Beispiel:

$session = New-GitHubJwtSession `
  -EnterpriseName "your-enterprise-slug" `
  -ClientId $clientId `
  -PrivateKeyPath $privateKeyPath `
  -InstallationId $enterpriseInstallationId `
  -PersonalAccessToken $pat

Invoke-GitHoundEnterprise -Session $session -CheckpointPath "./output/your-enterprise" -CollectAll

Für reine Enterprise-Tests ohne Aufzählung der zugehörigen Organisationen:

Invoke-GitHoundEnterprise -Session $session -CheckpointPath "./output/your-enterprise" -EnterpriseOnly

Schema

Ausführliche Dokumentation finden Sie unter BloodHound Docs - GitHound Schema.

Wichtige Kantenkategorien:

Primäres Angriffspfadmuster:

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

Anwendungsbeispiele

Welche Repos hat ein Benutzer mit Schreibzugriff?

Finden Sie die Objektkennung für Ihren Zielbenutzer:

MATCH (n:GH_User)
RETURN n

HINWEIS: Wählen Sie Tabellenlayout

https://github.com/user-attachments/assets/1ddfd075-2a15-4aa9-bad7-74c43e6c82d6

Ersetzen Sie den <object_id>-Wert in der folgenden Abfrage durch die Objektkennung des Benutzers:

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

Wer hat Schreibzugriff auf ein Repo?

Ermitteln Sie die Objektkennung für Ihr Zielrepository:

MATCH (n:GH_Repository)
RETURN n

Nehmen Sie die Objektkennung für Ihr Zielrepository und ersetzen Sie den <object_id>-Wert in der folgenden Abfrage damit:

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

Mitglieder der Organisationsadministratoren (entspricht Domain-Admin)?

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

Benutzer, die über SSO verwaltet werden (nur Entra)

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

Cloud-übergreifende Angriffspfade: GitHub zu Azure

Finden Sie GitHub-Entitäten, die Azure-Verbundidentitäten annehmen können (OIDC-Vertrauensbeziehungen):

// 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

Welche Repositories haben Zugriff auf Organisationsgeheimnisse?

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

Repositories mit Secret-Scanning-Benachrichtigungen

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

Mitwirken

Wir begrüßen und schätzen Ihre Beiträge! Um den Prozess reibungslos und effizient zu gestalten, befolgen Sie bitte diese Schritte:

1. Ihre Idee besprechen

   • Wenn Sie einen Fehler gefunden haben oder eine neue Funktion vorschlagen möchten, öffnen Sie zunächst ein Issue in diesem Repo. Beschreiben Sie das Problem oder die Verbesserung klar, damit wir den besten Ansatz besprechen können.

2. Forken und einen Branch erstellen

   • Forken Sie dieses Repository in Ihr eigenes Konto.

   • Erstellen Sie einen Topic-Branch für Ihre Arbeit:

     root@kitploit:~

     git checkout -b feat/my-new-feature
     

3. Implementieren und testen

   • Folgen Sie dem vorhandenen Stil und den Mustern im Repo.

   • Fügen Sie Tests/Beispiele hinzu oder aktualisieren Sie sie, um Ihre Änderungen abzudecken.

   • Überprüfen Sie, ob Ihr Code wie erwartet funktioniert:

     root@kitploit:~

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

4. Einen Pull Request einreichen

   • Pushen Sie Ihren Branch zu Ihrem Fork:

     root@kitploit:~

     git push origin feat/my-new-feature
     

   • Öffnen Sie einen Pull Request gegen den main-Branch dieses Repositorys.

   • Fügen Sie in Ihrer PR-Beschreibung bitte Folgendes ein:

     • Was Sie geändert haben und warum.
     • Wie Sie Ihre Änderungen reproduzieren/testen können.

5. Überprüfen und zusammenführen

   • Ich werde Ihren PR überprüfen, bei Bedarf Feedback geben und zusammenführen, sobald alles in Ordnung ist.
   • Bei größeren oder komplexeren Änderungen kann die Überprüfung etwas länger dauern – vielen Dank im Voraus für Ihre Geduld!

Vielen Dank, dass Sie helfen, diese Erweiterung zu verbessern! 🎉

Lizenzierung

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.

Sofern nicht durch eine untergeordnete LICENSE-Datei oder einen Lizenzheader anders gekennzeichnet, werden alle Dateien in diesem Repository unter der Apache-2.0-Lizenz veröffentlicht. Eine vollständige Kopie der Lizenz finden Sie in der obersten LICENSE-Datei.