GitHound

概要

GitHound は、GitHub 用の BloodHound OpenGraph コレクタであり、組織の構造と権限をナビゲート可能な攻撃経路グラフにマッピングするように設計されています。具体的には次のとおりです。

• 主要な GitHub エンティティをモデル化

  • GH_Organization: GitHub 組織のメタデータ
  • GH_User: 組織内の個々のユーザーアカウント
  • GH_Team: 共有アクセスのためにユーザーをグループ化するチーム
  • GH_Repository: 組織内のリポジトリ
  • GH_Branch: 各リポジトリの名前付きブランチ
  • GH_OrgRole、GH_TeamRole、GH_RepoRole: 組織レベル、チームレベル、リポジトリレベルのロール/権限

• BloodHound での可視化と分析

  • アクセス監査: リポジトリとブランチに対する管理者/書き込み/読み取り権限を持つユーザーをひと目で確認
  • コンプライアンスチェック: チームとリポジトリ全体で最小権限を検証
  • インシデント対応: 権限昇格とグループメンバーシップを追跡

GitHound を使用すると、GitHub の権限環境の明確でインタラクティブなグラフが得られ、セキュリティレビュー、コンプライアンス監査、迅速なインシデント調査に最適です。

ドキュメント

詳細なドキュメントについては、BloodHound Docs - GitHound を参照してください。

クイックスタート

# 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

収集が中断された場合は、中断したところから再開できます:

Invoke-GitHound -Session $session -Resume

GitHub App セッション

GitHound は、Personal Access Token セッションと GitHub App インストールセッションの両方をサポートしています。既存の組織スコープの GitHub App ワークフローは変更されません:

. ./githound.ps1

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

Invoke-GitHound -Session $session -CollectAll

同じ関数を使用して、エンタープライズ対応セッションを作成することもできます:

. ./githound.ps1

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

エンタープライズ対応セッションは、返された GitHound.Session 上に複数の認証コンテキストを保持します:

• Headers: 通常の収集に使用される GitHub App インストールトークンのヘッダー
• JwtHeaders: インストール列挙などのアプリレベルのエンドポイントに使用される GitHub App JWT ヘッダー
• PatHeaders: ユーザートークン認証が必要な収集パスのためのオプションの Personal Access Token ヘッダー

認証された GitHub App に属するインストールを列挙するには:

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

ワークフロー分析

ワークフローの解析は、-CollectAll を使用するときに Invoke-GitHound に組み込まれるようになりました。コレクタは次のことを行います:

• 生の GH_Workflow ノードとワークフローの内容を収集します
• それらのワークフローを GH_WorkflowJob と GH_WorkflowStep に分析します
• GH_CanPwnRequest と GH_CanDispatchTo を計算します
• 結果を通常の統合された githound_<orgId>.json 出力にマージします

再開/デバッグの目的で、ワークフロー分析の中間チェックポイントは githound_WorkflowAnalysis_<orgId>.json として書き込まれます。

エンタープライズ収集基盤

GitHound には、Git-HoundEnterprise による最小限のエンタープライズ収集基盤が含まれるようになりました。このコレクタは現在、以下を作成します:

• GH_Enterprise
• メンバー組織のための軽量な GH_Organization スタブノード
• エンタープライズからその組織への GH_Contains エッジ

Git-HoundEnterpriseUser によるエンタープライズユーザー収集では、以下が追加されます:

• GH_User
• エンタープライズからそれらのユーザーへの GH_HasMember エッジ

Git-HoundEnterpriseSamlProvider によるエンタープライズ SAML 収集では、以下が追加されます:

• GH_SamlIdentityProvider
• GH_ExternalIdentity
• エンタープライズからプロバイダーへの GH_HasSamlIdentityProvider
• 組織 SAML コレクタで使用されるものと同じ ID 相関エッジ

このパスには PAT バックのセッションが必要です。GitHub がエンタープライズ SAML を enterprise.ownerInfo を通じて公開するためです。

Git-HoundEnterpriseTeam によるエンタープライズチーム収集では、以下が追加されます:

• GH_EnterpriseTeam
• エンタープライズチームから割り当てられた組織への GH_AssignedTo エッジ
• プロパティマッチングを使用して、エンタープライズチームから組織に表示される ent: GH_Team ノードへの GH_MemberOf エッジ
• エンタープライズチームの members ロールと、ユーザーからそれらのロールへの GH_HasRole エッジ

Git-HoundEnterpriseRole によるエンタープライズロール収集では、以下が追加されます:

• GH_EnterpriseRole
• エンタープライズからそれらのロールへの GH_Contains エッジ
• 直接割り当てられたユーザーとエンタープライズチームからの GH_HasRole エッジ
• PAT バックのエンタープライズ管理者データが利用可能な場合に enterprise.ownerInfo.admins から入力されるデフォルトの owners ロール

現時点では、生のエンタープライズ権限文字列は、専用の権限エッジに展開されるのではなく、GH_EnterpriseRole ノードの permissions プロパティに保持されます。

エンタープライズ SCIM 収集では現在、以下が追加されます:

• SCIM_User
• SCIM_Group
• SCIM_User から GH_ExternalIdentity への SCIM_Provisioned
• GitHub がエンタープライズチームの group_id を公開する場合に、SCIM_Group から GH_EnterpriseTeam への SCIM_Provisioned
• SCIM_User から SCIM_Group への SCIM_MemberOf

これにより、GitHound は共有 SCIM スキーマから GitHub のネイティブなエンタープライズ ID およびチームモデルへのプロバイダーに依存しないブリッジを提供します。

収集された GH_SamlIdentityProvider がアップストリーム IdP を識別する場合、GitHound は SCIM サイドカー出力内にプロバイダー対応の SCIM 相関エッジを追加することもできます:

• Okta_User -> SCIM_User
  • Okta_User.id = SCIM_User.externalId によって一致
• Okta_Group -> SCIM_Group
  • Okta_Group.name = SCIM_Group.externalId によって一致
  • および Okta_Group.oktaDomain = GH_SamlIdentityProvider.foreign_environmentid

GitHound は SCIM 層を独自のサイドカー出力に保持するため、SCIM ネイティブノードをメインの GitHub ネイティブエンタープライズグラフに混ぜることなく、これらのマッピングを可視化できます:

• githound_<entId>.json にはエンタープライズの GitHub ネイティブデータが含まれます
• githound_scim_<entId>.json には SCIM ネイティブノードと SCIM ブリッジエッジが含まれます
• githound_saml_<entId>.json には SAML および外部 ID データが含まれます
• githound_hybrid_<entId>.json には、SAML_Implements、SAML_HasAccount、GH_SyncedTo などのクロスモデルエッジが含まれます
• githound_saml_<entId>.json には、SAML_TrustsIssuer と SAML_HasAssertionConsumerService を含む、GitHub サービスプロバイダーの正規化された SAML トポロジも含まれます

ネイティブの GitHub ID プロバイダーモデルは、GitHub/SAML ネイティブ出力でそのまま保持されます:

• GH_ExternalIdentity
• GH_HasExternalIdentity
• GH_MapsToUser

githound_hybrid_<entId>.json の正規化された SAML 層は、SAML_HasAccount を GH_User に直接配置し、リンクされた GH_ExternalIdentity の SAML 向けプロパティ（saml_identity_name_id や saml_identity_username など）から match_values を導出します。

エンタープライズ収集によって出力される GH_Organization スタブは、意図的に collected = false とマークされています。これらはエンタープライズコンテキストからの構造的発見を表し、後で通常の組織収集によって拡張されることを意図しています。

エンタープライズファーストのオーケストレーションの場合、Invoke-GitHoundEnterprise はサポートされているエンタープライズスコープのデータを収集し、関連する組織のインストールを列挙してから、選択したチェックポイントパスの下の各組織の独自のサブディレクトリで既存の Invoke-GitHound ワークフローを実行します。

例:

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

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

関連組織を列挙せずにエンタープライズのみをテストする場合:

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

スキーマ

詳細なドキュメントについては、BloodHound Docs - GitHound Schema を参照してください。

主要なエッジカテゴリ:

主な攻撃経路パターン:

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

使用例

ユーザーが書き込みアクセス権を持つリポジトリ

対象ユーザーのオブジェクト識別子を見つけます:

MATCH (n:GH_User)
RETURN n

ヒント: Table Layout を選択

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

次のクエリの <object_id> の値をユーザーのオブジェクト識別子に置き換えます:

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

リポジトリに書き込みアクセスできるのは誰ですか?

対象リポジトリのオブジェクト識別子を取得します:

MATCH (n:GH_Repository)
RETURN n

対象リポジトリのオブジェクト識別子を取得し、次のクエリの <object_id> の値をそれに置き換えます:

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

組織管理者（Domain Admin 相当）のメンバーは?

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

SSO で管理されるユーザー（Entra のみ）

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

クロスクラウド攻撃経路: GitHub から Azure へ

Azure フェデレーション ID（OIDC 信頼関係）を引き受けることができる GitHub エンティティを見つけます:

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

組織のシークレットにアクセスできるリポジトリはどれですか?

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

シークレットスキャンアラートがあるリポジトリ

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

コントリビューション

コントリビューションを歓迎し、感謝します! プロセスをスムーズかつ効率的に進めるために、次の手順に従ってください:

1. アイデアを議論する

   • バグを発見した場合や新機能を提案したい場合は、まずこのリポジトリで issue を開いてください。問題または拡張機能を明確に説明し、最適なアプローチを議論できるようにしてください。

2. フォークしてブランチを作成する

   • このリポジトリを自分のアカウントにフォークします。

   • 作業用のトピックブランチを作成します:

     root@kitploit:~

     git checkout -b feat/my-new-feature
     

3. 実装とテスト

   • リポジトリ内の既存のスタイルとパターンに従います。

   • 変更をカバーするためにテスト/例を追加または更新します。

   • コードが期待どおりに実行されることを確認します:

     root@kitploit:~

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

4. プルリクエストを送信する

   • ブランチをフォークにプッシュします:

     root@kitploit:~

     git push origin feat/my-new-feature
     

   • このリポジトリの main ブランチに対してプルリクエストを開きます。

   • PR の説明には、以下を含めてください:

     • 変更した内容とその理由。
     • 変更を再現/テストする方法。

5. レビューとマージ

   • PR をレビューし、必要に応じてフィードバックを提供し、すべてが問題なければマージします。
   • 大規模または複雑な変更の場合、レビューに少し時間がかかることがあります。事前にご了承ください。

この拡張機能の改善にご協力いただきありがとうございます! 🎉

ライセンス

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.

下位レベルの LICENSE ファイルまたはライセンスヘッダーで特に注記されていない限り、このリポジトリ内のすべてのファイルは Apache-2.0 ライセンスの下で公開されています。ライセンスの完全なコピーは、最上位の LICENSE ファイルにあります。