GitHound

Aperçu

GitHound est un collecteur OpenGraph pour GitHub, conçu pour cartographier la structure et les permissions de votre organisation sous forme de graphe de chemins d'attaque navigable. Il permet de :

• Modéliser les entités GitHub clés

  • GH_Organization : les métadonnées de votre organisation GitHub
  • GH_User : les comptes utilisateurs individuels de l'organisation
  • GH_Team : les équipes qui regroupent les utilisateurs pour un accès partagé
  • GH_Repository : les dépôts de l'organisation
  • GH_Branch : les branches nommées de chaque dépôt
  • GH_OrgRole, GH_TeamRole, GH_RepoRole : les rôles/permissions au niveau organisation, équipe et dépôt

• Visualiser et analyser dans BloodHound

  • Audits d'accès : voir d'un coup d'œil qui dispose des droits admin/écriture/lecture sur les dépôts et les branches
  • Contrôles de conformité : valider le moindre privilège entre équipes et dépôts
  • Réponse aux incidents : tracer les escalades de privilèges et les appartenances aux groupes

Avec GitHound, vous obtenez un graphe clair et interactif de votre paysage de permissions GitHub, idéal pour les revues de sécurité, les audits de conformité et les investigations rapides d'incidents.

Documentation

Pour une documentation détaillée, consultez BloodHound Docs - GitHound.

Démarrage rapide

# 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

Si la collecte est interrompue, reprenez là où vous vous étiez arrêté :

Invoke-GitHound -Session $session -Resume

Sessions GitHub App

GitHound prend en charge à la fois les sessions à jeton d'accès personnel et les sessions d'installation d'application GitHub. Le flux de travail existant de l'application GitHub à portée d'organisation est inchangé :

. ./githound.ps1

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

Invoke-GitHound -Session $session -CollectAll

La même fonction peut également créer des sessions compatibles entreprise :

. ./githound.ps1

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

Les sessions compatibles entreprise conservent plusieurs contextes d'authentification sur le GitHound.Session retourné :

• Headers : les en-têtes de jeton d'installation de l'application GitHub utilisés pour la collecte normale
• JwtHeaders : les en-têtes JWT de l'application GitHub utilisés pour les points de terminaison au niveau de l'application, comme l'énumération des installations
• PatHeaders : en-têtes optionnels de jeton d'accès personnel pour les chemins de collecte nécessitant une authentification par jeton utilisateur

Pour énumérer les installations appartenant à l'application GitHub authentifiée :

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

Analyse des workflows

L'analyse des workflows est désormais intégrée à Invoke-GitHound lorsque vous utilisez -CollectAll. Le collecteur va :

• collecter les nœuds bruts GH_Workflow et les contenus des workflows
• analyser ces workflows en GH_WorkflowJob et GH_WorkflowStep
• calculer GH_CanPwnRequest et GH_CanDispatchTo
• fusionner les résultats dans la sortie consolidée normale githound_<orgId>.json

Pour les besoins de reprise/débogage, le point de contrôle intermédiaire de l'analyse des workflows est écrit sous la forme githound_WorkflowAnalysis_<orgId>.json.

Fondation de collecte entreprise

GitHound inclut désormais une base minimale de collecte entreprise via Git-HoundEnterprise. Ce collecteur crée actuellement :

• GH_Enterprise
• des nœuds factices légers GH_Organization pour les organisations membres
• des arêtes GH_Contains de l'entreprise vers ses organisations

La collecte des utilisateurs d'entreprise via Git-HoundEnterpriseUser ajoute :

• GH_User
• des arêtes GH_HasMember de l'entreprise vers ces utilisateurs

La collecte SAML d'entreprise via Git-HoundEnterpriseSamlProvider ajoute :

• GH_SamlIdentityProvider
• GH_ExternalIdentity
• GH_HasSamlIdentityProvider de l'entreprise vers le fournisseur
• les mêmes arêtes de corrélation d'identité que celles utilisées par le collecteur SAML d'organisation

Ce chemin nécessite une session adossée à un PAT car GitHub expose le SAML d'entreprise via enterprise.ownerInfo.

La collecte des équipes d'entreprise via Git-HoundEnterpriseTeam ajoute :

• GH_EnterpriseTeam
• des arêtes GH_AssignedTo des équipes d'entreprise vers les organisations assignées
• des arêtes GH_MemberOf des équipes d'entreprise vers les nœuds GH_Team visibles par l'organisation, de type ent:, via la correspondance de propriétés
• les rôles members des équipes d'entreprise et les arêtes GH_HasRole des utilisateurs vers ces rôles

La collecte des rôles d'entreprise via Git-HoundEnterpriseRole ajoute :

• GH_EnterpriseRole
• des arêtes GH_Contains de l'entreprise vers ces rôles
• des arêtes GH_HasRole depuis les utilisateurs et équipes d'entreprise directement assignés
• un rôle owners par défaut, alimenté à partir de enterprise.ownerInfo.admins lorsque les données d'administration d'entreprise adossées à un PAT sont disponibles

Pour l'instant, les chaînes brutes de permissions d'entreprise sont conservées sur le nœud GH_EnterpriseRole dans sa propriété permissions, plutôt que d'être développées en arêtes de permissions dédiées.

La collecte SCIM d'entreprise ajoute actuellement :

• SCIM_User
• SCIM_Group
• SCIM_Provisioned de SCIM_User vers GH_ExternalIdentity
• SCIM_Provisioned de SCIM_Group vers GH_EnterpriseTeam lorsque GitHub expose le group_id de l'équipe d'entreprise
• SCIM_MemberOf de SCIM_User vers SCIM_Group

Cela donne à GitHound un pont agnostique au fournisseur entre le schéma SCIM partagé et le modèle natif d'identité et d'équipe de GitHub.

Lorsqu'un GH_SamlIdentityProvider collecté identifie le fournisseur d'identité en amont, GitHound peut également ajouter des arêtes de corrélation SCIM tenant compte du fournisseur dans la sortie sidecar SCIM :

• Okta_User -> SCIM_User
  • correspondance par Okta_User.id = SCIM_User.externalId
• Okta_Group -> SCIM_Group
  • correspondance par Okta_Group.name = SCIM_Group.externalId
  • et Okta_Group.oktaDomain = GH_SamlIdentityProvider.foreign_environmentid

GitHound conserve la couche SCIM dans sa propre sortie sidecar afin que ces correspondances restent visibles sans mélanger les nœuds natifs SCIM dans le graphe principal natif GitHub de l'entreprise :

• githound_<entId>.json contient les données natives GitHub de l'entreprise
• githound_scim_<entId>.json contient les nœuds natifs SCIM et les arêtes de pont SCIM
• githound_saml_<entId>.json contient les données SAML et d'identité externe
• githound_hybrid_<entId>.json contient les arêtes inter-modèles telles que SAML_Implements, SAML_HasAccount et GH_SyncedTo
• githound_saml_<entId>.json contient également la topologie SAML normalisée pour le fournisseur de services GitHub, y compris SAML_TrustsIssuer et SAML_HasAssertionConsumerService

Le modèle natif de fournisseur d'identité GitHub reste intact dans les sorties natives GitHub/SAML :

• GH_ExternalIdentity
• GH_HasExternalIdentity
• GH_MapsToUser

La couche SAML normalisée dans githound_hybrid_<entId>.json place désormais SAML_HasAccount directement sur GH_User, tout en dérivant match_values des propriétés orientées SAML du GH_ExternalIdentity lié, telles que saml_identity_name_id et saml_identity_username.

Les nœuds d'organisation GH_Organization émis par la collecte entreprise sont intentionnellement marqués collected = false. Ils représentent une découverte structurelle à partir du contexte entreprise et sont destinés à être enrichis ultérieurement par la collecte d'organisation normale.

Pour une orchestration axée entreprise d'abord, Invoke-GitHoundEnterprise collecte les données prises en charge au niveau de l'entreprise, énumère les installations d'organisations associées, puis exécute le flux de travail existant Invoke-GitHound pour chaque organisation dans son propre sous-répertoire sous le chemin de point de contrôle choisi.

Exemple :

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

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

Pour un test uniquement entreprise sans énumérer les organisations associées :

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

Schéma

Pour une documentation détaillée, consultez BloodHound Docs - GitHound Schema.

Catégories d'arêtes clés :

Modèle de chemin d'attaque principal :

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

Exemples d'utilisation

À quels dépôts un utilisateur a-t-il accès en écriture ?

Trouvez l'identifiant d'objet de votre utilisateur cible :

MATCH (n:GH_User)
RETURN n

ASTUCE : Sélectionnez la disposition en tableau

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

Remplacez la valeur <object_id> dans la requête suivante par l'identifiant d'objet de l'utilisateur :

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

Qui a accès en écriture à un dépôt ?

Obtenez l'identifiant d'objet de votre dépôt cible :

MATCH (n:GH_Repository)
RETURN n

Prenez l'identifiant d'objet de votre dépôt cible et remplacez la valeur <object_id> dans la requête suivante par celui-ci :

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

Membres de l'équipe des administrateurs d'organisation (équivalent d'Administrateur du domaine) ?

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

Utilisateurs gérés via SSO (Entra uniquement)

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

Chemins d'attaque multi-cloud : GitHub vers Azure

Recherchez les entités GitHub pouvant assumer des identités fédérées Azure (relations de confiance OIDC) :

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

Quels dépôts ont accès aux secrets d'organisation ?

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

Dépôts avec alertes de scan de secrets

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

Contribuer

Nous accueillons et apprécions vos contributions ! Pour rendre le processus fluide et efficace, veuillez suivre ces étapes :

1. Discutez de votre idée

   • Si vous avez trouvé un bug ou souhaitez proposer une nouvelle fonctionnalité, commencez par ouvrir une issue dans ce dépôt. Décrivez clairement le problème ou l'amélioration afin que nous puissions discuter de la meilleure approche.

2. Fork & créez une branche

   • Forkez ce dépôt sur votre propre compte.

   • Créez une branche thématique pour votre travail :

     root@kitploit:~

     git checkout -b feat/my-new-feature
     

3. Implémentez et testez

   • Suivez le style et les modèles existants du dépôt.

   • Ajoutez ou mettez à jour les tests/exemples pour couvrir vos modifications.

   • Vérifiez que votre code s'exécute comme prévu :

     root@kitploit:~

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

4. Soumettez une pull request

   • Poussez votre branche vers votre fork :

     root@kitploit:~

     git push origin feat/my-new-feature
     

   • Ouvrez une pull request contre la branche main de ce dépôt.

   • Dans la description de votre PR, veuillez inclure :

     • Ce que vous avez modifié et pourquoi.
     • Comment reproduire/tester vos modifications.

5. Revue et fusion

   • Je passerai en revue votre PR, donnerai des retours si nécessaire et fusionnerai une fois que tout sera vérifié.
   • Pour les modifications plus importantes ou plus complexes, la revue peut prendre un peu plus de temps — merci d'avance pour votre patience !

Merci d'aider à améliorer cette extension ! 🎉

Licence

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.

Sauf mention contraire par un fichier LICENSE de niveau inférieur ou un en-tête de licence, tous les fichiers de ce dépôt sont publiés sous la licence Apache-2.0. Une copie complète de la licence se trouve dans le fichier LICENSE au niveau racine.