المستوى: مبتدئ. المقال ده مكتوب لحد لسه بادئ في Git وأمن الكود. لو محترف، انزل على قسم الـ trade-offs والإعداد على طول.

امنع تسريب مفتاح API في Git تلقائياً بـ Gitleaks

بعد ما تخلّص المقال ده هيكون عندك حارس تلقائي بيوقف أي مفتاح سري قبل ما يدخل تاريخ المشروع. السطر اللي بيحطّك في مصيبة بيتمسك في أقل من ثانية، على جهازك، قبل ما يوصل GitHub.

المشكلة باختصار

تخيّل إنك نسخت مفتاح بيت في ورقة، والورقة دي اتصوّرت ووُزّعت على 20 شخص. تمزّق الأصل دلوقتي مش هيرجّع النسخ. ده بالظبط اللي بيحصل في Git.

لو كتبت مفتاح AWS في ملف، وعملت commit، ثم مسحته في commit تاني، المفتاح لسه موجود في تاريخ المشروع. أي حد يعمل git clone يقدر يطلّعه. الافتراض إنك "مسحته" غلط؛ Git بيحفظ كل نسخة.

والمشكلة دي مش نظرية. حسب تقرير GitGuardian لسنة 2024، اتسرّب أكتر من 12.8 مليون سر جديد علناً على GitHub في سنة واحدة. مفتاح واحد بيكفي إن حد يشغّل سيرفرات على حسابك ويسيبلك فاتورة بآلاف الدولارات.

يعني إيه "سر" وليه الفحص اليدوي بيفشل

السر (Secret) هو أي قيمة بتثبت هويتك لخدمة: مفتاح API، كلمة مرور قاعدة بيانات، توكن. ليها أنماط معروفة. مثلاً مفتاح AWS بيبدأ بـ AKIA وطوله 20 حرف. توكن GitHub بيبدأ بـ ghp_.

الفحص بالعين بيفشل لأنك بشري. ممكن تنسى ملف .env مرة واحدة في 200 commit، والمرة دي كفاية. الحل إنك تخلّي برنامج يفحص بدالك في كل مرة، أوتوماتيك، من غير ما تفتكر.

الأداة اللي هنستخدمها اسمها Gitleaks. هي أداة مفتوحة المصدر بتفحص ملفاتك بقواعد جاهزة (regex) لأنماط الأسرار، وبتقولك: الملف ده، السطر ده، فيه سر.

الحل: حارس من طبقتين

هنبني خطّين دفاع، مش خط واحد. ركز في الفرق:

1. الطبقة الأولى (pre-commit): فحص على جهازك قبل ما يتسجّل الـ commit أصلاً. لو فيه سر، الـ commit بيتوقف. السر ما خرجش من جهازك.
2. الطبقة الثانية (CI): فحص على GitHub Actions بعد الـ push. شبكة أمان تمسك أي حاجة فاتت، مثلاً لو زميل مفعّلش الطبقة الأولى.

الخطوة 1: التثبيت

# على Mac
brew install gitleaks

# على Linux (تنزيل النسخة الجاهزة)
# راجع صفحة الإصدارات لاختيار معمارية جهازك
gitleaks version

الخطوة 2: جرّب الفحص بإيدك مرة

الأمر الحديث للفحص المحلي على التغييرات اللي عملتلها git add هو:

# يفحص الملفات المُجهّزة (staged) بس — مناسب للـ pre-commit
gitleaks git --staged --verbose

# لفحص تاريخ المشروع كله من أوله
gitleaks git --verbose

ملحوظة: الأمرين القديمين gitleaks protect وgitleaks detect اتـ deprecated من نسخة v8.19، لكن لسه بيشتغلوا. استخدم gitleaks git الجديد.

الخطوة 3: ركّب الطبقة الأولى (pre-commit) تلقائياً

هنستخدم إطار pre-commit عشان يشغّل Gitleaks لوحده قبل كل commit. اعمل ملف اسمه .pre-commit-config.yaml في جذر المشروع:

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks

pip install pre-commit
pre-commit install

من دلوقتي، أي git commit فيه سر هيتوقف برسالة بتحدد الملف والسطر. النتيجة المتوقعة: السر مايخرجش من جهازك أبداً.

الخطوة 4: ركّب الطبقة الثانية (GitHub Actions)

اعمل ملف .github/workflows/gitleaks.yml فيه خطوة checkout بعمق كامل (fetch-depth صفر) عشان يفحص التاريخ كله، ثم خطوة gitleaks-action الرسمية مع تمرير GITHUB_TOKEN.

دلوقتي أي push أو pull request بيتفحص على السيرفر. لو السر فات الطبقة الأولى، الـ build بيفشل وبيظهر تنبيه قبل ما يتدمج الكود.

الأرقام والـ trade-offs

الفحص سريع. على مشروع متوسط (آلاف الملفات)، فحص الملفات المُجهّزة في الـ pre-commit بياخد تقديرياً 150 إلى 400 ميلي ثانية لكل commit. ده ثمن بسيط مقابل المكسب.

• بتكسب: حماية تلقائية لا تعتمد على ذاكرتك، وطبقتين بدل واحدة.
• بتخسر: أجزاء من الثانية في كل commit، + احتمال إيجابي كاذب (false positive): الأداة تحسب نص عادي إنه سر. الحل: تضيفه لملف استثناءات .gitleaks.toml أو تعلّم السطر بتعليق allow.

الافتراض هنا إن مشروعك على Git وبتستخدم GitHub. لو على GitLab أو Bitbucket، نفس فكرة الطبقتين تنفع، بس إعداد الـ CI بيختلف.

متى لا تستخدم هذه الطريقة

لو السر اتسرّب فعلاً ووصل GitHub، Gitleaks مش هيكفي. الفحص بيمنع التسريب، مش بيعالجه بعد وقوعه. في الحالة دي لازم: تلغي المفتاح (revoke) فوراً من لوحة الخدمة، تطلّع واحد جديد، وبعدين تنظّف التاريخ بأداة زي git filter-repo. اعتبر أي سر وصل مستودع عام إنه محروق.

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

الخطوة التالية

افتح أي مشروع شغّال عندك ونفّذ سطر واحد دلوقتي: gitleaks git --verbose. لو طلّعلك أي سر في التاريخ، ده معناه إن عندك مفتاح مكشوف لازم تلغيه النهاردة قبل أي حاجة تانية. بعدها ركّب الطبقتين فوق.

المصادر

• التوثيق الرسمي وأوامر git الحديثة: gitleaks/gitleaks (GitHub)
• أكشن الـ CI الرسمي: gitleaks/gitleaks-action
• إطار الـ pre-commit: pre-commit.com
• إحصاءات تسريب الأسرار على GitHub: GitGuardian — State of Secrets Sprawl 2024
• صيغة مفاتيح AWS: AWS IAM — Identifiers