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_Contains, GH_Owns	組織階層
ロール割り当て	GH_HasRole, GH_MemberOf, GH_HasBaseRole	誰がどのロールを持っているか
リポジトリ権限	GH_AdminTo, GH_CanPush, GH_CanPull	ロールが実行できる操作
ブランチ保護	GH_BypassPullRequestAllowances, GH_RestrictionsCanPush	ブランチレベルのアクセス
シークレット	GH_HasSecret	シークレットアクセスのマッピング
クロスクラウド	GH_CanAssumeIdentity, GH_SyncedTo	Azure/AWS への攻撃経路

主な攻撃経路パターン:

(: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 を選択