GitHound

Visão Geral

GitHound é um coletor OpenGraph do BloodHound para GitHub, projetado para mapear a estrutura e as permissões da sua organização em um grafo navegável de caminhos de ataque. Ele:

• Modela as Principais Entidades do GitHub

  • GH_Organization: metadados da sua org no GitHub
  • GH_User: contas de usuário individuais na org
  • GH_Team: equipes que agrupam usuários para acesso compartilhado
  • GH_Repository: repositórios dentro da org
  • GH_Branch: branches nomeados em cada repositório
  • GH_OrgRole, GH_TeamRole, GH_RepoRole: funções/permissões nos níveis de org, equipe e repositório

• Visualize e Analise no BloodHound

  • Auditorias de Acesso: Veja rapidamente quem tem admin/escrita/leitura em repositórios e branches
  • Verificações de Conformidade: Valide o princípio do menor privilégio entre equipes e repositórios
  • Resposta a Incidentes: Trace escalonamentos de privilégio e associações a grupos

Com o GitHound, você obtém um grafo claro e interativo do panorama de permissões do GitHub — perfeito para revisões de segurança, auditorias de conformidade e investigações rápidas de incidentes.

Documentação

Para documentação detalhada, consulte BloodHound Docs - GitHound.

Início 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

Se a coleta for interrompida, retome de onde parou:

Invoke-GitHound -Session $session -Resume

Sessões de GitHub App

O GitHound suporta tanto sessões de Personal Access Token quanto sessões de instalação do GitHub App. O fluxo de trabalho existente do GitHub App com escopo de organização permanece inalterado:

. ./githound.ps1

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

Invoke-GitHound -Session $session -CollectAll

A mesma função também pode criar sessões com capacidade enterprise:

. ./githound.ps1

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

Sessões com capacidade enterprise mantêm múltiplos contextos de autenticação no GitHound.Session retornado:

• Headers: os cabeçalhos do token de instalação do GitHub App usados para a coleta normal
• JwtHeaders: cabeçalhos JWT do GitHub App usados para endpoints de nível de aplicativo, como a enumeração de instalações
• PatHeaders: cabeçalhos opcionais de Personal Access Token para caminhos de coleta que exigem autenticação por token de usuário

Para enumerar as instalações que pertencem ao GitHub App autenticado:

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

Análise de Workflow

O parsing de workflow agora está integrado ao Invoke-GitHound quando você usa -CollectAll. O coletor irá:

• coletar nós brutos GH_Workflow e conteúdos de workflow
• analisar esses workflows em GH_WorkflowJob e GH_WorkflowStep
• calcular GH_CanPwnRequest e GH_CanDispatchTo
• mesclar os resultados na saída consolidada normal githound_<orgId>.json

Para fins de retomada/depuração, o checkpoint intermediário da análise de workflow é gravado como githound_WorkflowAnalysis_<orgId>.json.

Base da Coleta Enterprise

O GitHound agora inclui uma base mínima de coleta enterprise por meio do Git-HoundEnterprise. Esse coletor atualmente cria:

• GH_Enterprise
• nós stub leves de GH_Organization para organizações membro
• arestas GH_Contains da enterprise para suas organizações

A coleta de usuários enterprise por meio do Git-HoundEnterpriseUser adiciona:

• GH_User
• arestas GH_HasMember da enterprise para esses usuários

A coleta SAML enterprise por meio do Git-HoundEnterpriseSamlProvider adiciona:

• GH_SamlIdentityProvider
• GH_ExternalIdentity
• GH_HasSamlIdentityProvider da enterprise para o provedor
• as mesmas arestas de correlação de identidade usadas pelo coletor SAML de organização

Esse caminho exige uma sessão baseada em PAT porque o GitHub expõe o SAML enterprise por meio de enterprise.ownerInfo.

A coleta de equipes enterprise por meio do Git-HoundEnterpriseTeam adiciona:

• GH_EnterpriseTeam
• arestas GH_AssignedTo de equipes enterprise para organizações designadas
• arestas GH_MemberOf de equipes enterprise para nós GH_Team ent: visíveis na org usando correspondência de propriedades
• funções de members de equipe enterprise e arestas GH_HasRole de usuários para essas funções

A coleta de funções enterprise por meio do Git-HoundEnterpriseRole adiciona:

• GH_EnterpriseRole
• arestas GH_Contains da enterprise para essas funções
• arestas GH_HasRole de usuários e equipes enterprise designados diretamente
• uma função padrão owners preenchida a partir de enterprise.ownerInfo.admins quando dados administrativos enterprise baseados em PAT estão disponíveis

Por enquanto, as strings brutas de permissão enterprise são preservadas no nó GH_EnterpriseRole em sua propriedade permissions, em vez de serem expandidas em arestas de permissão dedicadas.

A coleta SCIM enterprise atualmente adiciona:

• SCIM_User
• SCIM_Group
• SCIM_Provisioned de SCIM_User para GH_ExternalIdentity
• SCIM_Provisioned de SCIM_Group para GH_EnterpriseTeam quando o GitHub expõe o group_id da equipe enterprise
• SCIM_MemberOf de SCIM_User para SCIM_Group

Isso dá ao GitHound uma ponte agnóstica de provedor do esquema SCIM compartilhado para o modelo nativo de identidade e equipe enterprise do GitHub.

Quando um GH_SamlIdentityProvider coletado identifica o IdP upstream, o GitHound também pode adicionar arestas de correlação SCIM cientes do provedor dentro da saída sidecar SCIM:

• Okta_User -> SCIM_User
  • correspondidos por Okta_User.id = SCIM_User.externalId
• Okta_Group -> SCIM_Group
  • correspondidos por Okta_Group.name = SCIM_Group.externalId
  • e Okta_Group.oktaDomain = GH_SamlIdentityProvider.foreign_environmentid

O GitHound mantém a camada SCIM em sua própria saída sidecar para que esses mapeamentos permaneçam visíveis sem misturar nós nativos SCIM no grafo enterprise principal nativo do GitHub:

• githound_<entId>.json contém dados enterprise nativos do GitHub
• githound_scim_<entId>.json contém nós nativos SCIM e arestas de ponte SCIM
• githound_saml_<entId>.json contém dados de identidade SAML e externa
• githound_hybrid_<entId>.json contém arestas entre modelos, como SAML_Implements, SAML_HasAccount e GH_SyncedTo
• githound_saml_<entId>.json também contém a topologia SAML normalizada para o provedor de serviços GitHub, incluindo SAML_TrustsIssuer e SAML_HasAssertionConsumerService

O modelo nativo de provedor de identidade do GitHub permanece intacto nas saídas nativas GitHub/SAML:

• GH_ExternalIdentity
• GH_HasExternalIdentity
• GH_MapsToUser

A camada SAML normalizada em githound_hybrid_<entId>.json agora coloca SAML_HasAccount diretamente em GH_User, ao mesmo tempo que deriva match_values das propriedades voltadas para SAML do GH_ExternalIdentity vinculado, como saml_identity_name_id e saml_identity_username.

Os stubs GH_Organization emitidos pela coleta enterprise são intencionalmente marcados como collected = false. Eles representam a descoberta estrutural a partir do contexto enterprise e devem ser enriquecidos posteriormente pela coleta normal de organizações.

Para orquestração enterprise-first, o Invoke-GitHoundEnterprise coletará os dados com escopo enterprise suportados, enumerará as instalações de organizações relacionadas e, em seguida, executará o fluxo de trabalho existente do Invoke-GitHound para cada organização em seu próprio subdiretório sob o caminho de checkpoint escolhido.

Exemplo:

$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 testes apenas enterprise, sem enumerar as organizações relacionadas:

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

Esquema

Para documentação detalhada, consulte BloodHound Docs - GitHound Schema.

Principais categorias de arestas:

Padrão principal de caminho de ataque:

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

Exemplos de Uso

A quais Repositórios um Usuário tem Acesso de Escrita?

Encontre o identificador de objeto para o usuário-alvo:

MATCH (n:GH_User)
RETURN n

DICA: Selecione Table Layout

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

Substitua o valor <object_id> na consulta subsequente pelo identificador de objeto do usuário:

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

Quem tem Acesso de Escrita a um Repositório?

Obtenha o identificador de objeto para o repositório-alvo:

MATCH (n:GH_Repository)
RETURN n

Pegue o identificador de objeto do repositório-alvo e substitua o valor <object_id> na consulta subsequente por ele:

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

Membros dos Administradores da Organização (equivalente a Domain Admin)?

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

Usuários gerenciados via SSO (somente Entra)

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

Caminhos de Ataque entre Nuvens: GitHub para Azure

Encontre entidades do GitHub que podem assumir identidades federadas do Azure (relações de confiança 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

Quais Repositórios Têm Acesso aos Segredos da Organização?

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

Repositórios com Alertas de Secret Scanning

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

Contribuindo

Agradecemos e valorizamos suas contribuições! Para tornar o processo tranquilo e eficiente, siga estas etapas:

1. Discuta sua Ideia

   • Se você encontrou um bug ou deseja propor um novo recurso, comece abrindo uma issue neste repositório. Descreva claramente o problema ou a melhoria para que possamos discutir a melhor abordagem.

2. Faça um Fork e Crie um Branch

   • Faça um fork deste repositório para sua própria conta.

   • Crie um branch de tópico para o seu trabalho:

     root@kitploit:~

     git checkout -b feat/my-new-feature
     

3. Implemente e Teste

   • Siga o estilo e os padrões existentes no repositório.

   • Adicione ou atualize testes/exemplos para cobrir suas alterações.

   • Verifique se o seu código executa conforme o esperado:

     root@kitploit:~

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

4. Envie um Pull Request

   • Faça push do seu branch para o seu fork:

     root@kitploit:~

     git push origin feat/my-new-feature
     

   • Abra um Pull Request contra o branch main deste repositório.

   • Na descrição do seu PR, inclua:

     • O que você alterou e porquê.
     • Como reproduzir/testar suas alterações.

5. Revise e Mescle

   • Vou revisar seu PR, dar feedback se necessário e mesclar assim que tudo estiver certo.
   • Para alterações maiores ou mais complexas, a revisão pode demorar um pouco mais — desde já, obrigado pela paciência!

Obrigado por ajudar a melhorar esta extensão! 🎉

Licenciamento

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 indicação em contrário por um arquivo LICENSE de nível inferior ou cabeçalho de licença, todos os arquivos deste repositório são disponibilizados sob a licença Apache-2.0. Uma cópia completa da licença pode ser encontrada no arquivo LICENSE no nível raiz.