Gitleaks

قد ترفع مفتاح API أو كلمة مرور إلى Git دون أن تنتبه، ثم تحذف السطر وتظن أن المشكلة انتهت، بينما يبقى السر داخل تاريخ المستودع. Gitleaks يفحص تاريخ Git والملفات والنصوص بحثًا عن بيانات اعتماد مكتوبة داخلها، ويمكن تشغيله على جهازك قبل الالتزام أو داخل CI عند كل push وpull request. قيمته أنه يحوّل فحص الأسرار من تذكير يدوي إلى بوابة قابلة للتكرار، لكنه لا يثبت أن الكود خالٍ من كل الأسرار ولا يبطل المفتاح المسرب نيابة عنك.

🧭 ما Gitleaks وكيف يعمل؟

Gitleaks أداة سطر أوامر مفتوحة المصدر مكتوبة بلغة Go. تستخدم مجموعة قواعد للكشف عن أنماط مثل مفاتيح API والرموز وكلمات المرور، وتضيف سياقًا مثل الملف والسطر والقاعدة والبصمة لكل نتيجة. تستطيع فحص تاريخ Git عبر patches، أو فحص ملفات ومجلدات كما هي الآن، أو قراءة نص من stdin.

تشغّلها داخل المستودع، فتطابق المحتوى مع القواعد الافتراضية أو ملف إعداد مخصص. عند وجود نتيجة، تعيد عادة رمز خروج 1 كي تستطيع CI أو hook إيقاف المسار. لا ترسل CLI الأساسي المشروع إلى خدمة سحابية ليعمل؛ الفحص محلي. أما تشغيل GitHub Action فيجري داخل runner ويستخدم GITHUB_TOKEN للتعليقات، وقد يرفع تقرير SARIF بوصفه artifact بحسب إعداداته.

رسم توضيحي أصلي لمسار العمل، وليس لقطة من واجهة Gitleaks.

🎯 كيف سيفيد مطورًا أو فريقًا صغيرًا؟

يفيدك عندما تعمل على مستودع يحتوي مفاتيح خدمات، ملفات .env، إعدادات نشر أو أمثلة قد ينسخ أحدهم إليها قيمة حقيقية. بدل الاعتماد على أن يتذكر كل شخص البحث يدويًا قبل push، تستطيع وضع فحص محلي سريع ثم تكراره في CI. إذا كشف الفحص سرًا، تعرف الملف والسطر والقاعدة وتبدأ الاستجابة فورًا.

القيمة المضافة ليست «منع التسريب بنسبة 100%». القواعد قد تنتج إنذارات كاذبة، وقد لا تعرف سرًا بصيغة غير مغطاة. كذلك لا تبحث الأداة عن صلاحيات واسعة أو ثغرات الكود أو اعتماديات مصابة؛ هي متخصصة في أسرار مكتوبة داخل المحتوى. إذا كان مشروعك لا يحتوي Git ولا ملفات نصية حساسة، أو تحتاج منصة لإدارة الأسرار وتدويرها، فستحتاج أداة أخرى إلى جانبها.

🌟 الميزات والقدرات الرئيسية

1. ثلاثة أوضاع فحص واضحة: git وdir وstdin

استخدم gitleaks git عندما تريد فحص تاريخ مستودع Git؛ الأداة تستند تحت الغطاء إلى git log -p ويمكن تقييد النطاق بخيارات السجل. استخدم gitleaks dir لفحص ملفات أو مجلدات حالية، واستخدم gitleaks stdin عندما تريد تمرير نص من أداة أخرى.

• أين تجدها: أوامر CLI الأساسية.
• كيف تستخدمها: اختر git للتاريخ، وdir للنسخة الحالية أو artifact، وstdin لمسار أنابيب.
• مثال توضيحي: gitleaks git --redact . يفحص المستودع الحالي ويخفي قيمة السر من سجل الخرج.
• ما ينبغي الانتباه إليه: أوامرا detect وprotect قديمان منذ v8.19.0، رغم بقائهما مخفيين للتوافق. لا تبنِ تعليمات جديدة عليهما.

الرسم يلخص نطاقات الفحص الموثقة؛ لا يعني أن وضعًا واحدًا يغطي كل الحالات.

2. فحص قبل الالتزام ثم بوابة ثانية في CI

يدعم المستودع تشغيل Gitleaks عبر pre-commit كي يفشل الالتزام عندما يجد نتيجة. ويمكن استخدام Gitleaks-Action في GitHub Actions لفحص push وpull request أو تشغيله عند الطلب. الطبقتان مهمتان: الفحص المحلي يعطي تنبيهًا مبكرًا، وCI يغطي من لم يثبت hook أو عطّله.

• أين تجدها: ملف .pre-commit-config.yaml محليًا، وملف workflow داخل .github/workflows/ في GitHub.
• كيف تستخدمها: ثبّت إصدارًا محددًا، شغّل الاختبار على مستودع تجريبي، ثم فعّل CI مع fetch-depth: 0 عندما تريد التاريخ الكامل.
• مثال توضيحي: التزام يحوي مفتاحًا تجريبيًا يفشل محليًا؛ وإذا تجاوز المطور hook، يفشل طلب السحب في CI.
• القيد: يمكن تجاوز hook المحلي، وGitHub Action الرسمي يحتاج مفتاح ترخيص مجاني لمستودعات حسابات المؤسسات؛ الحساب الشخصي لا يحتاجه. الإصدار الحالي للعمل هو gitleaks/gitleaks-action@v3، بينما v2 توقف على GitHub-hosted runners بعد إزالة Node 20 في 16 سبتمبر 2026.

رسم لدفاع متعدد الطبقات؛ لا يعني أن CI يعالج السر أو يمنع كل طرق التسريب.

3. قواعد قابلة للتخصيص ونتائج قابلة للتتبع

إذا لم تمرر إعدادًا، يستخدم Gitleaks قواعده الافتراضية. تستطيع إنشاء .gitleaks.toml يمدد القواعد الافتراضية عبر [extend] useDefault = true، أو تحميل ملف محدد بخيار --config. ويمكن تعطيل قواعد بعينها أو إضافة قواعد خاصة بنظامك.

لكل نتيجة بصمة يمكن وضعها في .gitleaksignore لاستبعاد نتيجة محددة، كما يمكن استخدام تعليق gitleaks:allow لحالة اختبار معروفة. استخدم الاستثناء بأضيق نطاق ووثّق سببه؛ فالاستثناء الواسع يحول الأداة إلى ضوء أخضر مضلل. ميزة .gitleaksignore موصوفة في README بأنها تجريبية وقابلة للتغيير.

يدعم التقرير صيغ json وcsv وjunit وsarif، إضافة إلى قالب مخصص. استخدم --redact لإخفاء قيم الأسرار من stdout والسجلات. ومع ذلك، عامل ملفات التقارير بوصفها حساسة: قد تحتوي سطر المطابقة أو الحقول التي تكشف جزءًا من الاعتماد.

4. Baseline للانتقال التدريجي في المستودعات القديمة

قد يحتوي مستودع قديم عشرات النتائج المعروفة، فلا يكون من العملي إصلاحها جميعًا قبل إضافة البوابة. تستطيع حفظ تقرير سابق وتمريره عبر --baseline-path؛ عندها يحتوي التقرير الجديد على النتائج التي لم تكن في baseline.

• أين تجدها: الخياران --report-path و--baseline-path.
• كيف تستخدمها: أنشئ التقرير، راجع كل نتيجة، أبطِل الأسرار الحقيقية أولًا، ثم استخدم baseline مؤقتًا لمنع نتائج جديدة.
• مثال توضيحي: تبقي ثلاث نتائج قديمة قيد المعالجة، بينما يمنع CI ظهور نتيجة رابعة جديدة.
• القيد المهم: baseline لا يحذف السر ولا يبطله ولا يجعله آمنًا؛ هو آلية مقارنة فقط. لا تجعل تقريرًا يحتوي أسرارًا ملفًا عامًا.

الرسم يوضح أثر baseline على التقرير، لا على صلاحية بيانات الاعتماد.

🪜 مثال عملي: إضافة فحص أسرار لمستودع صغير

مثال إرشادي لم أنفذه على مستودع فعلي. بعد تثبيت Gitleaks، انتقل إلى نسخة عمل غير إنتاجية ثم:

1. تأكد من الإصدار: gitleaks version.
2. افحص تاريخ المستودع محليًا مع إخفاء القيم: gitleaks git --redact ..
3. إذا ظهرت نتيجة حقيقية، لا تحذف السطر فقط. أبطِل المفتاح لدى مزود الخدمة وأنشئ بديلًا، ثم انقل القيمة إلى Secret Manager أو متغير بيئة مناسب.
4. افحص ما إذا بقيت القيمة في تاريخ Git وحدد إن كانت سياسة المشروع تتطلب إعادة كتابة التاريخ. إعادة الكتابة قد تؤثر في بقية المطورين؛ لا تنفذها دون تنسيق.
5. أعد الفحص. الرمز 0 يعني عدم العثور على نتائج، بينما الرمز 1 يعني نتيجة أو خطأ؛ راجع الخرج بدل الاعتماد على الرقم وحده.
6. أضف hook محليًا ثم CI، وثبّت الإصدارات بدل الاعتماد على latest في مسار حساس.
7. راجع الاستثناءات في كل طلب سحب. إذا أضفت baseline، ضع خطة لإغلاق النتائج القديمة بدل إبقائها دائمًا.

حذف السطر لا يبطل بيانات الاعتماد الموجودة لدى المزود ولا يزيلها تلقائيًا من تاريخ Git.

⚖️ ماذا يغيّر مقارنة بالفحص اليدوي؟

الأداة تقلل الاعتماد على الذاكرة البشرية، لكنها لا تستبدل مراجعة سرية المستودع أو إدارة الأسرار أو تدوير المفاتيح.

⚙️ الإعدادات التي تحتاجها فعلًا

ابدأ بالقواعد الافتراضية. أضف .gitleaks.toml فقط إذا احتجت قاعدة داخلية أو استثناءً دقيقًا، ويفضل تمديد الافتراضي بدل استبداله من غير قصد. يمكن تحميل الإعداد بالترتيب: --config، ثم GITLEAKS_CONFIG، ثم GITLEAKS_CONFIG_TOML، ثم ملف .gitleaks.toml داخل الهدف.

المسح داخل archives وفك ترميز النصوص المعماة جزئيًا متوقفان افتراضيًا؛ يتحكمان بهما --max-archive-depth و--max-decode-depth. تفعيل أعماق كبيرة يوسّع العمل والموارد، لذلك اضبطهما بناءً على ملفاتك. استخدم --max-target-megabytes للحد من الملفات الكبيرة و--timeout لمسار CI المتوقع أن ينتهي.

🚀 التثبيت والتوافق

على macOS عبر Homebrew، الأمر الرسمي:

brew install gitleaks
gitleaks version

يوفر المشروع صور Docker رسمية على Docker Hub وGHCR، وبناءً من المصدر لمن لديه Go، وملفات ثنائية جاهزة لأنظمة ومعماريات متعددة. الإصدار المستقر الذي تحققت منه هو v8.30.1 المنشور في 21 مارس 2026. تعرض أصول الإصدار ملفات macOS وLinux وWindows لمعمارية x64 وARM بحسب النظام.

🔗 التكاملات والمنصات

يعمل CLI محليًا على أنظمة متعددة، ويتكامل مع Git وpre-commit وDocker. التكامل الرسمي مع GitHub هو Gitleaks-Action. يمكن أن تستهلك أدوات CI الأخرى رمز الخروج أو تقارير JUnit/SARIF/JSON، لكن ذلك لا يعني وجود إضافة رسمية لكل منصة.

في GitHub Action v3، يستخدم الإجراء GITHUB_TOKEN لاستدعاء GitHub API والتعليق على طلبات السحب. رفع SARIF artifact مفعّل افتراضيًا وفق README ويمكن تعطيله عبر GITLEAKS_ENABLE_UPLOAD_ARTIFACT=false. راجع محتوى التقرير وسياسة الاحتفاظ قبل رفعه.

💰 التكلفة والتشغيل المحلي

CLI الأساسي مفتوح المصدر برخصة MIT ولا يحتاج حسابًا أو API مدفوعًا؛ يمكن تشغيل الفحص محليًا. تكلفة CI تعتمد على runner وخطة GitHub. Gitleaks-Action منفصل في الترخيص منذ v2.0.0: لا يحتاج الحساب الشخصي إلى مفتاح، أما مستودعات حساب المؤسسات فتحتاج مفتاح ترخيص مجاني يُطلب من موقع Gitleaks مع الاسم والبريد والشركة. لا تخلط رخصة CLI مع شروط Action.

⚠️ الحدود ومتى لا تستخدمه وحده

• الأداة تبحث عن أسرار وفق قواعد؛ قد تفوت سرًا غير معروف أو تنتج إنذارًا كاذبًا.
• رمز الخروج 1 يعني «نتيجة أو خطأ»، لذا اقرأ السجل ولا تفترض السبب.
• فحص Git يعتمد على patches، ويختلف عن فحص الملفات الحالية.
• المسح داخل archives وفك الترميز غير مفعّلين افتراضيًا.
• حذف السر من آخر commit لا يبطل الاعتماد ولا يمحوه من التاريخ.
• المشروع أعلن أنه feature complete، وأن الإصدارات المقبلة ستكون إصلاحات أمنية بينما ينتقل التركيز إلى Betterleaks. هذا لا يجعل الأداة متوقفة، لكنه قيد مهم إذا كنت تبحث عن ميزات جديدة سريعة.
• لا تستبدل Gitleaks بمدير أسرار، أو فحص اعتماديات، أو SAST عام، أو سياسات حماية الفروع.

🔐 الأمان والصلاحيات والخصوصية

CLI يحتاج قراءة الملفات وتاريخ Git الذي تطلب فحصه، وكتابة ملف إذا حددت --report-path. لا يحتاج سرًا ليعمل محليًا. لا تمرر مفاتيح حقيقية في أوامر قد تُحفظ داخل shell history، ولا تشارك التقرير قبل تنقيحه.

GitHub Action يحتاج GITHUB_TOKEN ويستطيع التعليق على PR، وقد يرفع artifact. عند حساب مؤسسة يحتاج أيضًا GITLEAKS_LICENSE مخزنًا كسر مشفر. امنح workflow أقل صلاحيات ممكنة، وثبّت إصدار Action أو commit موثوقًا، وراجع أي إعداد مخصص أو استثناء كما تراجع الكود.

عند العثور على اعتماد حقيقي: أبطله أولًا، ثم استبدله، ثم افحص نطاق الاستخدام والسجل وأعد الفحص. إعادة كتابة Git history خطوة مستقلة وقد تتطلب تنسيقًا ونسخًا احتياطية؛ لا تنفذها تلقائيًا لمجرد ظهور نتيجة.

🔎 لماذا اخترناه اليوم؟

قارنت Gitleaks من مجال الأمان ومنع تسرب الأسرار مع Lychee من مجال جودة التوثيق وفحص الروابط. Lychee أداة جيدة ومفتوحة المصدر وتخدم مواقع التوثيق، لكن Gitleaks يسد فجوة أمان أوضح بعد بطاقة goose الخاصة بوكلاء AI، ويضيف طبقة قابلة للتطبيق فورًا على مستودعات فرد أو فريق صغير. لم يكن عدد النجوم هو سبب الاختيار؛ بل وضوح المهمة، العمل المحلي، تكامل pre-commit وCI، ونضج الوثائق مع معرفة قيوده.

وقت الفحص أظهر GitHub لـGitleaks 30,309 نجمة و2,314 تفرعًا، وآخر push في 23 أكتوبر 2026. أظهر مستودع Lychee نحو 4.0 آلاف نجمة و240 تفرعًا، مع دعم فحص الروابط محليًا وعبر GitHub Action. هذه أرقام انتشار لحظية، لا تقييم جودة أو أمان.

📚 المصادر وتاريخ التحقق

تحققت في 25 أكتوبر 2026 من المستودع الأصلي وREADME، الإصدار v8.30.1، الرخصة، Gitleaks-Action v3 وشروطه، وموقع Gitleaks. للاكتشاف والمقارنة راجعت GitHub Topic: secret-scanning، ونتائج ذات صلة في Claude Skills وDSH Market، ثم تحققت من الحقائق في المصادر الأصلية. قارنت أيضًا Lychee ووثائقه.

لم أثبّت Gitleaks أو أشغّل المثال على مستودع حقيقي، ولم أجرِ تدقيقًا للكود أو اختبارًا مستقلًا للشبكة. الأرقام والإصدار والنشاط لقطة زمنية وقت التحقق.