GitHound

Resumen

GitHound es un recopilador OpenGraph de BloodHound para GitHub, diseñado para mapear la estructura y los permisos de tu organización en un grafo navegable de rutas de ataque. Permite:

• Modela entidades clave de GitHub

  • GH_Organization: Los metadatos de tu organización de GitHub
  • GH_User: Cuentas de usuario individuales en la organización
  • GH_Team: Equipos que agrupan usuarios para acceso compartido
  • GH_Repository: Repositorios dentro de la organización
  • GH_Branch: Ramas con nombre en cada repositorio
  • GH_OrgRole, GH_TeamRole, GH_RepoRole: Roles/permisos a nivel de organización, equipo y repositorio

• Visualiza y analiza en BloodHound

  • Auditorías de acceso: Ve de un vistazo quién tiene permisos de administración/escritura/lectura en repositorios y ramas
  • Comprobaciones de cumplimiento: Valida el principio de mínimo privilegio en equipos y repositorios
  • Respuesta a incidentes: Traza escaladas de privilegios y pertenencias a grupos

Con GitHound, obtienes un grafo claro e interactivo del panorama de permisos de GitHub, ideal para revisiones de seguridad, auditorías de cumplimiento e investigaciones rápidas de incidentes.

Documentación

Para documentación detallada, consulta BloodHound Docs - GitHound.

Inicio rápido

# 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 recopilación se interrumpe, reanúdala desde donde la dejaste:

Invoke-GitHound -Session $session -Resume

Sesiones de GitHub App

GitHound admite tanto sesiones con Personal Access Token como sesiones de instalación de GitHub App. El flujo de trabajo existente de GitHub App con ámbito de organización no cambia:

. ./githound.ps1

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

Invoke-GitHound -Session $session -CollectAll

La misma función también puede crear sesiones compatibles con enterprise:

. ./githound.ps1

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

Las sesiones compatibles con enterprise conservan múltiples contextos de autenticación en el GitHound.Session devuelto:

• Headers: las cabeceras de token de instalación de GitHub App que se usan para la recopilación normal
• JwtHeaders: las cabeceras JWT de GitHub App que se usan para endpoints a nivel de aplicación, como la enumeración de instalaciones
• PatHeaders: cabeceras opcionales de Personal Access Token para rutas de recopilación que requieren autenticación con token de usuario

Para enumerar las instalaciones que pertenecen a la GitHub App autenticada:

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

Análisis de flujos de trabajo

El análisis de flujos de trabajo ahora está integrado en Invoke-GitHound cuando se usa -CollectAll. El recopilador:

• recopilará nodos GH_Workflow sin procesar y contenidos de flujos de trabajo
• analizará esos flujos de trabajo en GH_WorkflowJob y GH_WorkflowStep
• calculará GH_CanPwnRequest y GH_CanDispatchTo
• fusionará los resultados en la salida consolidada habitual githound_<orgId>.json

Para fines de reanudación/depuración, el punto de control intermedio del análisis de flujos de trabajo se escribe como githound_WorkflowAnalysis_<orgId>.json.

Base de recopilación enterprise

GitHound ahora incluye una base mínima de recopilación enterprise mediante Git-HoundEnterprise. Ese recopilador actualmente crea:

• GH_Enterprise
• nodos GH_Organization stub ligeros para las organizaciones miembro
• aristas GH_Contains desde la empresa hacia sus organizaciones

La recopilación de usuarios enterprise mediante Git-HoundEnterpriseUser añade:

• GH_User
• aristas GH_HasMember desde la empresa hacia esos usuarios

La recopilación SAML enterprise mediante Git-HoundEnterpriseSamlProvider añade:

• GH_SamlIdentityProvider
• GH_ExternalIdentity
• GH_HasSamlIdentityProvider desde la empresa hacia el proveedor
• las mismas aristas de correlación de identidades que usa el recopilador SAML de organizaciones

Esta ruta requiere una sesión respaldada por PAT porque GitHub expone el SAML enterprise a través de enterprise.ownerInfo.

La recopilación de equipos enterprise mediante Git-HoundEnterpriseTeam añade:

• GH_EnterpriseTeam
• aristas GH_AssignedTo desde los equipos enterprise hacia las organizaciones asignadas
• aristas GH_MemberOf desde los equipos enterprise hacia los nodos GH_Team ent: visibles en la organización mediante coincidencia de propiedades
• roles members de los equipos enterprise y aristas GH_HasRole desde los usuarios hacia esos roles

La recopilación de roles enterprise mediante Git-HoundEnterpriseRole añade:

• GH_EnterpriseRole
• aristas GH_Contains desde la empresa hacia esos roles
• aristas GH_HasRole desde los usuarios asignados directamente y los equipos enterprise
• un rol owners predeterminado poblado a partir de enterprise.ownerInfo.admins cuando hay datos de administradores enterprise respaldados por PAT disponibles

Por ahora, las cadenas de permisos enterprise sin procesar se conservan en el nodo GH_EnterpriseRole dentro de su propiedad permissions, en lugar de expandirse en aristas de permisos dedicadas.

La recopilación SCIM enterprise añade actualmente:

• SCIM_User
• SCIM_Group
• SCIM_Provisioned desde SCIM_User hacia GH_ExternalIdentity
• SCIM_Provisioned desde SCIM_Group hacia GH_EnterpriseTeam cuando GitHub expone el group_id del equipo enterprise
• SCIM_MemberOf desde SCIM_User hacia SCIM_Group

Esto le proporciona a GitHound un puente independiente del proveedor desde el esquema SCIM compartido hacia el modelo nativo de identidad y equipos enterprise de GitHub.

Cuando un GH_SamlIdentityProvider recopilado identifica el IdP de origen, GitHound también puede añadir aristas de correlación SCIM conscientes del proveedor dentro de la salida sidecar de SCIM:

• Okta_User -> SCIM_User
  • se emparejan mediante Okta_User.id = SCIM_User.externalId
• Okta_Group -> SCIM_Group
  • se emparejan mediante Okta_Group.name = SCIM_Group.externalId
  • y mediante Okta_Group.oktaDomain = GH_SamlIdentityProvider.foreign_environmentid

GitHound mantiene la capa SCIM en su propia salida sidecar para que estas asignaciones sigan siendo visibles sin mezclar nodos nativos de SCIM en el grafo enterprise principal, nativo de GitHub:

• githound_<entId>.json contiene datos enterprise nativos de GitHub
• githound_scim_<entId>.json contiene nodos nativos de SCIM y aristas puente de SCIM
• githound_saml_<entId>.json contiene datos SAML y de identidades externas
• githound_hybrid_<entId>.json contiene aristas entre modelos, como SAML_Implements, SAML_HasAccount y GH_SyncedTo
• githound_saml_<entId>.json también contiene la topología SAML normalizada para el proveedor de servicios de GitHub, incluyendo SAML_TrustsIssuer y SAML_HasAssertionConsumerService

El modelo nativo de proveedor de identidad de GitHub permanece intacto en las salidas nativas de GitHub/SAML:

• GH_ExternalIdentity
• GH_HasExternalIdentity
• GH_MapsToUser

La capa SAML normalizada en githound_hybrid_<entId>.json ahora coloca SAML_HasAccount directamente sobre GH_User, a la vez que deriva match_values de las propiedades orientadas a SAML del GH_ExternalIdentity vinculado, como saml_identity_name_id y saml_identity_username.

Los nodos GH_Organization stub emitidos por la recopilación enterprise están marcados intencionadamente como collected = false. Representan el descubrimiento estructural desde el contexto enterprise y están pensados para enriquecerse más adelante con la recopilación normal de organizaciones.

Para la orquestación enterprise-first, Invoke-GitHoundEnterprise recopilará los datos compatibles con ámbito enterprise, enumerará las instalaciones de las organizaciones relacionadas y, a continuación, ejecutará el flujo de trabajo existente de Invoke-GitHound para cada organización en su propio subdirectorio dentro de la ruta de punto de control elegida.

Ejemplo:

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

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

Para pruebas solo enterprise sin enumerar las organizaciones relacionadas:

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

Esquema

Para documentación detallada, consulta BloodHound Docs - GitHound Schema.

Categorías clave de aristas:

Patrón principal de ruta de ataque:

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

Ejemplos de uso

¿A qué repositorios tiene acceso de escritura un usuario?

Encuentra el identificador de objeto de tu usuario objetivo:

MATCH (n:GH_User)
RETURN n

PISTA: Selecciona Table Layout

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

Reemplaza el valor <object_id> de la consulta siguiente con el identificador de objeto del usuario:

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én tiene acceso de escritura a un repositorio?

Obtén el identificador de objeto de tu repositorio objetivo:

MATCH (n:GH_Repository)
RETURN n

Toma el identificador de objeto de tu repositorio objetivo y reemplaza con él el valor <object_id> de la consulta siguiente:

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

¿Miembros de los administradores de la organización (equivalente a Domain Admin)?

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

Usuarios que se gestionan mediante SSO (solo Entra)

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

Rutas de ataque multi-nube: de GitHub a Azure

Encuentra entidades de GitHub que pueden asumir identidades federadas de Azure (relaciones de confianza 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

¿Qué repositorios tienen acceso a los secretos de la organización?

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

Repositorios con alertas de Secret Scanning

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

Contribuciones

¡Agradecemos y valoramos tus contribuciones! Para que el proceso sea ágil y eficiente, sigue estos pasos:

1. Comenta tu idea

   • Si has encontrado un bug o quieres proponer una nueva funcionalidad, empieza abriendo un issue en este repositorio. Describe claramente el problema o la mejora para que podamos discutir el mejor enfoque.

2. Haz un fork y crea una rama

   • Haz un fork de este repositorio en tu propia cuenta.

   • Crea una rama temática para tu trabajo:

     root@kitploit:~

     git checkout -b feat/my-new-feature
     

3. Implementa y prueba

   • Sigue el estilo y los patrones existentes en el repositorio.

   • Añade o actualiza las pruebas/ejemplos necesarios para cubrir tus cambios.

   • Verifica que tu código funciona como se espera:

     root@kitploit:~

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

4. Envía un Pull Request

   • Sube tu rama a tu fork:

     root@kitploit:~

     git push origin feat/my-new-feature
     

   • Abre un Pull Request contra la rama main de este repositorio.

   • En la descripción de tu PR, incluye:

     • Qué has cambiado y por qué.
     • Cómo reproducir/probar tus cambios.

5. Revisión y fusión

   • Revisaré tu PR, daré comentarios si es necesario y lo fusionaré una vez que todo esté correcto.
   • Para cambios más grandes o complejos, la revisión puede llevar un poco más de tiempo. ¡Gracias de antemano por tu paciencia!

¡Gracias por ayudar a mejorar esta extensión! 🎉

Licencia

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.

Salvo que se indique lo contrario mediante un archivo LICENSE o un encabezado de licencia de nivel inferior, todos los archivos de este repositorio se publican bajo la licencia Apache-2.0. Puedes encontrar una copia completa de la licencia en el archivo LICENSE de nivel superior.