GitHound

نظرة عامة

GitHound هو أداة جمع بيانات OpenGraph من BloodHound لـ GitHub، مصممة لرسم هيكل مؤسستك وأذوناتها في رسم بياني قابل للتصفح لمسارات الهجوم. يقوم بـ:

• نمذجة الكيانات الرئيسية لـ 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

يدعم GitHound كلًا من جلسات رمز الوصول الشخصي وجلسات تثبيت تطبيق GitHub. سير عمل تطبيق GitHub الموجود على نطاق المنظمة لم يتغير:

. ./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 المستخدمة للتجميع العادي
• JwtHeaders: رؤوس JWT لتطبيق GitHub المستخدمة لنقاط النهاية على مستوى التطبيق مثل تعداد التثبيتات
• PatHeaders: رؤوس رمز الوصول الشخصي الاختيارية لمسارات التجميع التي تتطلب مصادقة رمز المستخدم

لتعداد التثبيتات التي تنتمي إلى تطبيق GitHub المُوثق:

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

تحليل سير العمل

تم دمج تحليل سير العمل الآن في Invoke-GitHound عند استخدام -CollectAll. سيقوم المُجمّع بـ:

• جمع العقد الأولية 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 من المؤسسة إلى هؤلاء المستخدمين

جمع SAML للمؤسسة من خلال Git-HoundEnterpriseSamlProvider يضيف:

• GH_SamlIdentityProvider
• GH_ExternalIdentity
• GH_HasSamlIdentityProvider من المؤسسة إلى الموفر
• نفس حواف ارتباط الهوية المستخدمة بواسطة جامع SAML للمنظمة

يتطلب هذا المسار جلسة مدعومة بـ PAT لأن GitHub يعرض SAML للمؤسسة من خلال enterprise.ownerInfo.

جمع فريق المؤسسة من خلال Git-HoundEnterpriseTeam يضيف:

• GH_EnterpriseTeam
• حواف GH_AssignedTo من فرق المؤسسة إلى المنظمات المعينة
• حواف GH_MemberOf من فرق المؤسسة إلى عُقد GH_Team المرئية للمنظمة ent: باستخدام مطابقة الخصائص
• أدوار members في فريق المؤسسة وحواف GH_HasRole من المستخدمين إلى تلك الأدوار

جمع دور المؤسسة من خلال Git-HoundEnterpriseRole يضيف:

• GH_EnterpriseRole
• حواف GH_Contains من المؤسسة إلى تلك الأدوار
• حواف GH_HasRole من المستخدمين المعينين مباشرة وفرق المؤسسة
• دور owners افتراضي يتم ملؤه من enterprise.ownerInfo.admins عندما تكون بيانات مشرف المؤسسة المدعومة بـ PAT متاحة

في الوقت الحالي، يتم الاحتفاظ بسلاسل أذونات المؤسسة الأولية على عقدة GH_EnterpriseRole في خاصية permissions الخاصة بها بدلاً من توسيعها إلى حواف أذونات مخصصة.

جمع SCIM للمؤسسة يضيف حاليًا:

• SCIM_User
• SCIM_Group
• SCIM_Provisioned من SCIM_User إلى GH_ExternalIdentity
• SCIM_Provisioned من SCIM_Group إلى GH_EnterpriseTeam عندما يعرض GitHub group_id لفريق المؤسسة
• SCIM_MemberOf من SCIM_User إلى SCIM_Group

يمنح هذا GitHound جسرًا غير مرتبط بالموفر من مخطط SCIM المشترك إلى نموذج هوية المؤسسة والفريق الأصلي لـ GitHub.

عندما يحدد GH_SamlIdentityProvider الذي تم جمعه موفر الهوية العلوي، يمكن لـ GitHound أيضًا إضافة حواف ارتباط SCIM الواعية بالموفر داخل مخرجات الـ sidecar لـ 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 في مخرجات sidecar الخاصة بها بحيث تظل هذه التعيينات مرئية دون خلط العُقد الأصلية لـ SCIM في الرسم البياني للمؤسسة الأصلي لـ GitHub:

• githound_<entId>.json يحتوي على بيانات المؤسسة الأصلية لـ GitHub
• githound_scim_<entId>.json يحتوي على عُقد SCIM الأصلية وحواف جسر SCIM
• githound_saml_<entId>.json يحتوي على بيانات SAML وهوية خارجية
• githound_hybrid_<entId>.json يحتوي على حواف عبر النماذج مثل SAML_Implements و SAML_HasAccount و GH_SyncedTo
• githound_saml_<entId>.json يحتوي أيضًا على طوبولوجيا SAML الموحدة لموفر خدمة GitHub، بما في ذلك SAML_TrustsIssuer و SAML_HasAssertionConsumerService

يبقى نموذج موفر الهوية الأصلي لـ GitHub سليمًا في مخرجات GitHub/SAML الأصلية:

• GH_ExternalIdentity
• GH_HasExternalIdentity
• GH_MapsToUser

طبقة SAML الموحدة في githound_hybrid_<entId>.json تضع الآن SAML_HasAccount مباشرة على GH_User، مع استخلاص match_values من خصائص GH_ExternalIdentity الموجهة لـ SAML مثل saml_identity_name_id و saml_identity_username.

تم وضع علامة collected = false على عُقد الغلاف GH_Organization التي يصدرها جمع المؤسسة عمدًا. إنها تمثل اكتشافًا هيكليًا من سياق المؤسسة ومن المقرر إثراؤها لاحقًا بواسطة جمع المنظمة العادي.

للتنسيق القائم على المؤسسة أولاً، سيقوم 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

تلميح: حدد تخطيط الجدول

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

أعضاء مديري المنظمة (ما يعادل مسؤول المجال)؟

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

ابحث عن كيانات GitHub التي يمكنها افتراض هويات Azure الموحدة (علاقات الثقة 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

أي المستودعات لديها حق الوصول إلى أسرار المنظمة؟

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

المستودعات التي تحتوي على تنبيهات فحص الأسرار

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

المساهمة

نرحب بمساهماتكم ونقدرها! لجعل العملية سلسة وفعالة، يرجى اتباع الخطوات التالية:

1. ناقش فكرتك

   • إذا وجدت خطأ أو تريد اقتراح ميزة جديدة، يرجى البدء بفتح مشكلة في هذا المستودع. صف المشكلة أو التحسين بوضوح حتى نتمكن من مناقشة أفضل نهج.

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 لهذا المستودع.

   • في وصف طلب السحب الخاص بك، يرجى تضمين:

     • ماذا قمت بتغييره ولماذا.
     • كيفية إعادة إنتاج/اختبار تغييراتك.

5. المراجعة والدمج

   • سأقوم بمراجعة طلب السحب الخاص بك، وأقدم ملاحظات إذا لزم الأمر، وأدمج بمجرد أن يكون كل شيء على ما يرام.
   • بالنسبة للتغييرات الأكبر أو الأكثر تعقيدًا، قد تستغرق المراجعة وقتًا أطول قليلاً - شكرًا مقدمًا على صبرك!

شكرًا لك على المساعدة في تحسين هذا الامتداد! 🎉

الترخيص

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.

ما لم يتم الإشارة إلى خلاف ذلك بواسطة ملف ترخيص ذي مستوى أدنى أو رأس ترخيص، يتم إصدار جميع الملفات في هذا المستودع بموجب ترخيص Apache-2.0. يمكن العثور على نسخة كاملة من الترخيص في ملف LICENSE ذي المستوى الأعلى.