specterops/githoundBloodHound OpenGraph collector per GitHub che mappa la struttura organizzativa, le autorizzazioni e i percorsi di attacco cross-cloud in un grafo navigabile per audit di sicurezza e risposta agli incidenti.
# GitHound
## Panoramica
**GitHound** è un collector OpenGraph di BloodHound per GitHub, progettato per mappare la struttura e le autorizzazioni della tua organizzazione in un grafico di percorsi di attacco navigabile. Esso:
- **Modella le Entità Chiave di GitHub**
- **GH_Organization**: I metadati della tua org GitHub
- **GH_User**: Gli account utente individuali nell'org
- **GH_Team**: I team che raggruppano gli utenti per l'accesso condiviso
- **GH_Repository**: I repository all'interno dell'org
- **GH_Branch**: I branch nominati in ogni repo
- **GH_OrgRole**, **GH_TeamRole**, **GH_RepoRole**: Ruoli/autorizzazioni a livello di org, team e repo
- **Visualizza e Analizza in BloodHound**
- **Audit degli Accessi**: Scopri a colpo d'occhio chi ha accesso admin/scrittura/lettura su repo e branch
- **Controlli di Conformità**: Valida il principio del minimo privilegio tra team e repo
- **Risposta agli Incidenti**: Traccia le escalation di privilegi e le appartenenze ai gruppi
Con GitHound ottieni un grafico chiaro e interattivo del panorama delle autorizzazioni GitHub—perfetto per revisioni di sicurezza, audit di conformità e rapide indagini sugli incidenti.
## Documentazione
Per la documentazione dettagliata, consulta [BloodHound Docs - GitHound](https://bloodhound.specterops.io/opengraph/extensions/githound).
## Avvio Rapido
```powershell
# 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 la raccolta viene interrotta, riprendi da dove eri rimasto:
```powershell
Invoke-GitHound -Session $session -Resume
```
## Sessioni GitHub App
GitHound supporta sia le sessioni con Personal Access Token sia le sessioni di installazione GitHub App.
Il flusso di lavoro esistente per GitHub App con ambito organizzazione è invariato:
```powershell
. ./githound.ps1
$session = New-GitHubJwtSession `
-OrganizationName "YourOrgName" `
-ClientId $clientId `
-PrivateKeyPath $privateKeyPath `
-InstallationId $installationId
Invoke-GitHound -Session $session -CollectAll
```
La stessa funzione può anche creare sessioni abilitate per l'enterprise:
```powershell
. ./githound.ps1
$session = New-GitHubJwtSession `
-EnterpriseName "YourEnterpriseSlug" `
-ClientId $clientId `
-PrivateKeyPath $privateKeyPath `
-InstallationId $installationId `
-PersonalAccessToken $pat
```
Le sessioni abilitate per l'enterprise mantengono più contesti di autenticazione sulla `GitHound.Session` restituita:
- `Headers`: gli header del token di installazione della GitHub App usati per la raccolta normale
- `JwtHeaders`: gli header JWT della GitHub App usati per gli endpoint a livello di app, come l'enumerazione delle installazioni
- `PatHeaders`: header opzionali del Personal Access Token per i percorsi di raccolta che richiedono l'autenticazione con token utente
Per enumerare le installazioni che appartengono alla GitHub App autenticata:
```powershell
Get-GitHubAppInstallation -Session $session |
Select-Object TargetType, InstallationId, Login, Name, SuspendedAt
```
## Analisi dei Workflow
Il parsing dei workflow è ora integrato in `Invoke-GitHound` quando usi `-CollectAll`. Il collector:
- raccoglie i nodi `GH_Workflow` grezzi e i contenuti dei workflow
- analizza i workflow in `GH_WorkflowJob` e `GH_WorkflowStep`
- calcola `GH_CanPwnRequest` e `GH_CanDispatchTo`
- unisce i risultati nell'output consolidato normale `githound_<orgId>.json`
Per scopi di ripresa/debug, il checkpoint intermedio dell'analisi dei workflow viene scritto come `githound_WorkflowAnalysis_<orgId>.json`.
## Base di Raccolta Enterprise
GitHound ora include una base minima di raccolta enterprise tramite `Git-HoundEnterprise`. Questo collector attualmente crea:
- `GH_Enterprise`
- nodi stub leggeri `GH_Organization` per le organizzazioni membro
- archi `GH_Contains` dall'enterprise alle sue organizzazioni
La raccolta degli utenti enterprise tramite `Git-HoundEnterpriseUser` aggiunge:
- `GH_User`
- archi `GH_HasMember` dall'enterprise a quegli utenti
La raccolta SAML enterprise tramite `Git-HoundEnterpriseSamlProvider` aggiunge:
- `GH_SamlIdentityProvider`
- `GH_ExternalIdentity`
- `GH_HasSamlIdentityProvider` dall'enterprise al provider
- gli stessi archi di correlazione delle identità usati dal collector SAML dell'organizzazione
Questo percorso richiede una sessione basata su PAT perché GitHub espone il SAML enterprise tramite `enterprise.ownerInfo`.
La raccolta dei team enterprise tramite `Git-HoundEnterpriseTeam` aggiunge:
- `GH_EnterpriseTeam`
- archi `GH_AssignedTo` dai team enterprise alle organizzazioni assegnate
- archi `GH_MemberOf` dai team enterprise ai nodi `GH_Team` `ent:` visibili all'org usando il matching delle proprietà
- ruoli `members` dei team enterprise e archi `GH_HasRole` dagli utenti a questi ruoli
La raccolta dei ruoli enterprise tramite `Git-HoundEnterpriseRole` aggiunge:
- `GH_EnterpriseRole`
- archi `GH_Contains` dall'enterprise a questi ruoli
- archi `GH_HasRole` dagli utenti assegnati direttamente e dai team enterprise
- un ruolo `owners` predefinito popolato da `enterprise.ownerInfo.admins` quando i dati admin enterprise basati su PAT sono disponibili
Per ora, le stringhe grezze delle autorizzazioni enterprise sono conservate sul nodo `GH_EnterpriseRole` nella sua proprietà `permissions` invece di essere espanse in archi di autorizzazione dedicati.
La raccolta SCIM enterprise attualmente aggiunge:
- `SCIM_User`
- `SCIM_Group`
- `SCIM_Provisioned` da `SCIM_User` a `GH_ExternalIdentity`
- `SCIM_Provisioned` da `SCIM_Group` a `GH_EnterpriseTeam` quando GitHub espone il `group_id` del team enterprise
- `SCIM_MemberOf` da `SCIM_User` a `SCIM_Group`
Questo offre a GitHound un ponte indipendente dal provider dallo schema SCIM condiviso al modello nativo di identità e team enterprise di GitHub.
Quando un `GH_SamlIdentityProvider` raccolto identifica l'IdP a monte, GitHound può anche aggiungere archi di correlazione SCIM consapevoli del provider nell'output sidecar SCIM:
- `Okta_User -> SCIM_User`
- abbinati tramite `Okta_User.id = SCIM_User.externalId`
- `Okta_Group -> SCIM_Group`
- abbinati tramite `Okta_Group.name = SCIM_Group.externalId`
- e `Okta_Group.oktaDomain = GH_SamlIdentityProvider.foreign_environmentid`
GitHound mantiene il layer SCIM nel proprio output sidecar, così queste mappature restano visibili senza mescolare i nodi nativi SCIM nel grafico enterprise principale nativo di GitHub:
- `githound_<entId>.json` contiene i dati enterprise nativi di GitHub
- `githound_scim_<entId>.json` contiene i nodi nativi SCIM e gli archi ponte SCIM
- `githound_saml_<entId>.json` contiene i dati SAML e delle identità esterne
- `githound_hybrid_<entId>.json` contiene gli archi tra modelli come `SAML_Implements`, `SAML_HasAccount` e `GH_SyncedTo`
- `githound_saml_<entId>.json` contiene anche la topologia SAML normalizzata per il service provider GitHub, inclusi `SAML_TrustsIssuer` e `SAML_HasAssertionConsumerService`
Il modello nativo del provider di identità GitHub rimane intatto negli output nativi GitHub/SAML:
- `GH_ExternalIdentity`
- `GH_HasExternalIdentity`
- `GH_MapsToUser`
Il layer SAML normalizzato in `githound_hybrid_<entId>.json` ora colloca `SAML_HasAccount` direttamente su `GH_User`, derivando `match_values` dalle proprietà SAML della `GH_ExternalIdentity` collegata, come `saml_identity_name_id` e `saml_identity_username`.
Gli stub `GH_Organization` emessi dalla raccolta enterprise sono intenzionalmente marcati `collected = false`. Rappresentano la scoperta strutturale dal contesto enterprise e sono destinati a essere arricchiti in seguito dalla normale raccolta delle organizzazioni.
Per un'orchestrazione enterprise-first, `Invoke-GitHoundEnterprise` raccoglie i dati supportati con ambito enterprise, enumera le installazioni delle organizzazioni correlate e poi esegue il flusso di lavoro esistente `Invoke-GitHound` per ogni organizzazione nella propria sottodirectory sotto il percorso di checkpoint scelto.
Esempio:
```powershell
$session = New-GitHubJwtSession `
-EnterpriseName "your-enterprise-slug" `
-ClientId $clientId `
-PrivateKeyPath $privateKeyPath `
-InstallationId $enterpriseInstallationId `
-PersonalAccessToken $pat
Invoke-GitHoundEnterprise -Session $session -CheckpointPath "./output/your-enterprise" -CollectAll
```
Per testare solo l'enterprise senza enumerare le organizzazioni correlate:
```powershell
Invoke-GitHoundEnterprise -Session $session -CheckpointPath "./output/your-enterprise" -EnterpriseOnly
```
## Schema
Per la documentazione dettagliata, consulta [BloodHound Docs - GitHound Schema](https://bloodhound.specterops.io/opengraph/extensions/githound/reference/schema).
**Principali categorie di archi:**
| Categoria | Archi Chiave | Descrizione |
|---|---|---|
| **Contenimento** | `GH_Contains`, `GH_Owns` | Gerarchia organizzativa |
| **Assegnazione dei Ruoli** | `GH_HasRole`, `GH_MemberOf`, `GH_HasBaseRole` | Chi ha quali ruoli |
| **Autorizzazioni dei Repository** | `GH_AdminTo`, `GH_CanPush`, `GH_CanPull` | Cosa possono fare i ruoli |
| **Protezioni dei Branch** | `GH_BypassPullRequestAllowances`, `GH_RestrictionsCanPush` | Accesso a livello di branch |
| **Segreti** | `GH_HasSecret` | Mappatura degli accessi ai segreti |
| **Cross-Cloud** | `GH_CanAssumeIdentity`, `GH_SyncedTo` | Percorsi di attacco verso Azure/AWS |
**Principale pattern di percorso di attacco:**
```cypher
(:GH_User)-[:GH_HasRole|GH_MemberOf|GH_AddMember*1..]->(:GH_RepoRole)-[:GH_AdminTo|GH_CanPush]->(:GH_Repository)
```
## Esempi di Utilizzo
### A quali Repo un Utente ha Accesso in Scrittura?
Trova l'identificatore dell'oggetto per il tuo utente target:
```cypher
MATCH (n:GH_User)
RETURN n
```
SUGGERIMENTO: Seleziona Table Layout
<https://github.com/user-attachments/assets/1ddfd075-2a15-4aa9-bad7-74c43e6c82d6>
Sostituisci il valore `<object_id>` nella query successiva con l'identificatore dell'oggetto dell'utente:
```cypher
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
```
### Chi ha Accesso in Scrittura a una Repo?
Ottieni l'identificatore dell'oggetto per il tuo repository target:
```cypher
MATCH (n:GH_Repository)
RETURN n
```
Prendi l'identificatore dell'oggetto per il tuo repository target e sostituiscilo al valore `<object_id>` nella query successiva:
```cypher
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
```
### Membri degli Admin dell'Organizzazione (equivalente dei Domain Admin)?
```cypher
MATCH p = (:GH_User)-[:GH_HasRole|GH_HasBaseRole]->(:GH_OrgRole {short_name: "owners"})
RETURN p
```
### Utenti gestiti tramite SSO (solo Entra)
```cypher
MATCH p = (:AZUser)-[:GH_SyncedTo]->(:GH_User)
RETURN p
```
### Percorsi di Attacco Cross-Cloud: da GitHub ad Azure
Trova le entità GitHub che possono assumere identità federate Azure (relazioni di trust OIDC):
```cypher
// 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
```
### Quali Repository Hanno Accesso ai Segreti dell'Organizzazione?
```cypher
MATCH p = (:GH_Repository)-[:GH_HasSecret]->(:GH_OrgSecret)
RETURN p
```
### Repository con Avvisi di Secret Scanning
```cypher
MATCH p = (:GH_Repository)-[:GH_Contains]->(:GH_SecretScanningAlert)
RETURN p
```
## Contributi
Apprezziamo e accogliamo con piacere i tuoi contributi! Per rendere il processo fluido ed efficiente, segui questi passaggi:
1. **Discuti la Tua Idea**
- Se hai trovato un bug o vuoi proporre una nuova funzionalità, inizia aprendo una issue in questo repo. Descrivi chiaramente il problema o il miglioramento così possiamo discutere l'approccio migliore.
2. **Fork & Crea un Branch**
- Fai il fork di questo repository nel tuo account.
- Crea un branch tematico per il tuo lavoro:
```bash
git checkout -b feat/my-new-feature
```
3. **Implementa & Testa**
- Segui lo stile e i pattern esistenti nel repo.
- Aggiungi o aggiorna test/esempi per coprire le tue modifiche.
- Verifica che il tuo codice funzioni come previsto:
```bash
# e.g. dot-source the collector and run it, or load the model.json in BloodHound
```
4. **Invia una Pull Request**
- Fai push del tuo branch sul tuo fork:
```bash
git push origin feat/my-new-feature
```
- Apri una Pull Request verso il branch `main` di questo repository.
- Nella descrizione della PR, includi:
- **Cosa** hai modificato e **perché**.
- **Come** riprodurre/testare le tue modifiche.
5. **Revisione & Merge**
- Revisionerò la tua PR, fornirò feedback se necessario e farò il merge una volta che tutto sarà a posto.
- Per modifiche più ampie o complesse, la revisione potrebbe richiedere un po' più di tempo—grazie in anticipo per la pazienza!
Grazie per aver contribuito a migliorare questa estensione! 🎉
## Licenza
```text
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 diversa indicazione da un file LICENSE di livello inferiore o da un'intestazione di licenza, tutti i file in questo repository sono rilasciati sotto la licenza `Apache-2.0`. Una copia completa della licenza è disponibile nel file [LICENSE](https://github.com/specterops/githound/blob/main/LICENSE) nella directory principale.