Push Guard

Push Guard هو حارس pre-push محلي لـ Git للكشف عن تسريبات الأسرار المحتملة.

يقوم بفحص المحتوى الذي يتم دفعه، ويبلّغ عن أنماط الأسرار المحتملة، ويحجب جميع القيم المطابقة، ويخرج بقيمة غير صفرية حتى يمنع Git عملية الدفع.

تم بناؤه وصيانته بواسطة Dragon Lady - github.com/Dragon-Lady - X: @answerislove2

الترقية من 0.4.2: تغيير كاسر

تُزيل النسخة 0.4.3 استثناء # push-guard: ignore المضمّن. قد تبدأ الترقية في حجب عمليات الدفع والحزم التي كانت تنجح سابقًا. قبل ترقية الخطافات المشتركة أو تثبيتات CI، افحص كل مستودع مستهلك:

git grep -n -i 'push-guard:[[:space:]]*ignore'

راجع كل تطابق. أزل الأسرار والمواد الخاصة؛ لا يمكن استثناء أيٍّ منهما. بالنسبة لبيانات سير العمل/مؤشرات الاختراق (IOC) المشروعة، أضف فقط مسار المستودع الدقيق الذي تمت مراجعته ومعرّفات قواعد workflow.* الدقيقة إلى .push-guard-allow. العلامات المضمّنة أصبحت الآن نصًا عاديًا، بما في ذلك تلك الموجودة في الاختبارات أو التوثيق. لا تحوّل جميع أسطر العلامات إلى استثناءات تلقائيًا. راجع أي استثناء جديد باعتباره تغييرًا حساسًا أمنيًا.

يقرأ خطاف ما قبل الدفع (pre-push hook) الاستثناءات من commit الأساس المُعلن للوجهة، وليس من نسخة العمل أو الـ commits المرشحة. يجب مراجعة أي استثناء جديد أو موسّع وإقراره بشكل منفصل قبل أن يتمكن من استثناء عملية دفع لاحقة. بالنسبة لعملية دفع متعددة المراجع (multi-ref)، لا تنطبق سوى الاستثناءات المشتركة بين جميع قواعد الوجهة. المراجع الجديدة التي لا تحتوي على قاعدة مُعلنة لا تتلقى أي استثناءات.

وبالمثل، يقرأ scan السياسة من --base. عند تدقيق نطاق تاريخي أكبر مقابل لقطة سياسة تمت مراجعتها بشكل منفصل، مرّر صراحةً --allow-list-ref <reviewed-40-character-commit-SHA>. هذا قرار ثقة صريح من المتصل؛ لا تستبدل أبدًا سياسة المرشح غير المراجَع. يستمر scan-package في استخدام سياسة --repo التي يختارها المتصل، خارج الـ artifact. قدّم دليل سياسة تمت مراجعته عند فحص عمليات البناء غير الموثوقة.

شغّل push-guard scan --base <trusted-base> --head HEAD الخاص بالإصدار الجديد و push-guard scan-package dist/* مقابل التغييرات الصادرة الفعلية والـ artifacts المبنية قبل ترقية الخطاف المثبّت. قد تختلف مسارات أعضاء الأرشيف عن مسارات المصدر؛ راجع تلك المسارات الدقيقة بشكل منفصل. أبقِ الإصدار المثبّت الحالي حتى تُكمل المستودعات المتأثرة هذا الترحيل.

الموقع الإلكتروني

صفحة الهبوط العامة: push-guard.netlify.app

توجد صفحة الهبوط الثابتة للمشروع في docs/ ولا تحتوي على أي تبعيات وقت تشغيل، أو سكربتات خارجية، أو تحليلات، أو أصول بعيدة. يمكن تقديمها عبر GitHub Pages من دليل docs/ أو نشرها على Netlify باستخدام netlify.toml المضمّن (بدون أمر بناء؛ دليل النشر docs).

يستخدم مشروع Netlify الحالي عمليات النشر اليدوية. لا تؤدي عملية Git push وحدها إلى تحديث الصفحة العامة: انشر محتويات docs/ بعد كل إصدار وتحقق من الإصدار المباشر، والصورة الاجتماعية، وترويسات الاستجابة. يحافظ ملف docs/_headers على ترويسات الأمان عند نشر ذلك الدليل مباشرةً.

الوضعية

• فحص محلي للقراءة فقط للأهداف. لا تتبّع (telemetry).
• لا شبكة افتراضيًا. فقط خيار --send الصريح في Sweep يفعّل تنبيهات مجمّعة إلى وجهات مُهيّأة؛ يبقى حارس Git دون اتصال.
• لا تثبيت حزم أو تعديل ملفات الهدف أثناء الفحوصات.
• لا تُطبع أو تُسجّل أو تُحفظ قيم الأسرار المطابقة أو أسطر المصدر.
• يستخدم وضع Git عملية git الفرعية فقط لقراءة فروق الـ commits، والأشجار المدفوعة، ومسارات الخطافات المُهيّأة، وبيانات التعريف الخاصة بالتجاهل. يُحافظ على نقطة دخول الخطاف الحالية، مع تقوية فحص المحتوى الخام والتاريخ الصادر.
• يقرأ Sweep ملفات مختارة خارج Git، داخل $HOME، ولا ينفّذ أي عمليات فرعية، بما في ذلك Git.
• لا تُكتب نتائج الفحص افتراضيًا. ينشئ Sweep مفتاح HMAC عشوائيًا واحدًا بحجم 32 بايت في $XDG_STATE_HOME/push-guard-sweep/fp.key (افتراضيًا ~/.local/state/push-guard-sweep/fp.key) لبصمات مستقرة غير قابلة للتخمين. هذا المفتاح هو الاستثناء الصريح لقاعدة "لا تُخزّن بيانات افتراضيًا". لا يحتوي على أي بيانات مفحوصة. دليل الحالة بصلاحيات 0700 والملفات تُنشأ بصلاحيات 0600.
• ملفات --baseline و--output الصريحة في Sweep تحتوي على بيانات تعريف محلية محجوبة؛ يخزّن --send إيصالات إزالة التكرار المفتاحية، ولا يخزّن أبدًا بيانات اعتماد التنبيهات أو الأسرار.
• لا ادعاء بأن مستودعًا أو جهازًا نظيف. المطابقات هي خيوط مراجعة، وليست دليلًا على أن بيانات الاعتماد لا تزال صالحة.

حظر عملية الدفع هو استجابة Git للتوصية. يبقى Push Guard للقراءة فقط ولا يعدّل الملفات. التجاوز متاح عبر git push --no-verify عندما تكون القيمة المطابقة معروفة بأنها ليست سرًا.

Sweep: الأسرار على القرص

يوفّر الأمر push-guard sweep والاسم المستعار push-guard-sweep الفحص المحلي نفسه. ويتطلبان Python 3.11 أو أحدث الخاص بالحزمة الحالية، ولا يضيفان أي تبعيات وقت تشغيل إضافية. تستخدم اختبارات التطوير الإضافة الاختيارية test (python -m pip install ".[test]"، ثم PYTHONPATH=src python -m pytest -q من جذر المستودع). يضيف إصدار 0.4.0 ميزة Sweep. تقوم CI بتثبيت إضافة التطوير تلك وتشغّل مجموعة اختبارات pytest بأكملها، بما في ذلك حالات unittest القديمة. تُشغَّل اختبارات الإصدار في مهمة منفصلة؛ ولا توفّر تلك المهمة أبدًا مخرجات التوزيع للنشر. ولا تثبّت مهمة بناء المخرجات تبعيات الاختبار. ولا تقوم Sweep بتثبيت أو تمكين أي مجدول.

push-guard sweep --list-targets
push-guard sweep --roots ~/projects --class stray
push-guard-sweep --format json --output ~/sweep-report.json
push-guard-sweep --baseline ~/sweep-baseline.json
push-guard-sweep report --format html --output ~/sweep-report.html
push-guard-sweep print-timer --interval 7d

كل عملية فحص تراعي أيضًا مواقع السجل الافتراضية وملفات النقطة (dotfiles) وملفات التهيئة والسجلات المذكورة أدناه. يغيّر --roots جذور البحث الخاصة بـ .env* والتضمين المخصص؛ استخدم --exclude لتضييق مجموعات الافتراضيات الأخرى. يضيف --include GLOB المتكرر ملفات ضمن عمليات البحث المحدودة القائمة، ويزيل --exclude GLOB المتكرر المسارات. تطابق أنماط Glob أسماء الملفات الأساسية، أو المسارات النسبية إلى HOME، أو المسارات المطلقة. الاستثناءات لها الأولوية؛ لا يمكن للتضمينات تجاوز استثناءات الأمان أو حدود العمق. يتم توسيع ~ في وسائط المسار على سطر الأوامر. يجب أن تبقى المسارات المفحوصة داخل $HOME.

• السجل: سجل أوامر Bash وZsh وPython وNode وPostgreSQL وMySQL وSQLite و.lesshst. نص سجل أوامر SQLite منفصل عن ملفات قواعد البيانات.
• ملفات النقطة: .bashrc و.zshrc و.profile و.bash_profile و.npmrc و.docker/config.json؛ وملفات JSON وTOML وYAML وINI وCONF محددة تحت .config بعمق لا يتجاوز أربعة مستويات من الدلائل تحته.
• ملفات .env*: تحت الجذور المحددة (الافتراضي HOME)، بعمق لا يتجاوز ستة مستويات من الدلائل. تُستثنى أشجار التبعيات والبيئات الافتراضية وبيانات Git الوصفية وذاكرات التخزين المؤقت من هذا البحث.
• السجلات: ملفات .log والملفات داخل logs/، بعمق لا يتجاوز أربعة مستويات من الدلائل تحت .local/state و.cache و.codex و.config/Cursor/logs وlog_dirs المهيأة.

مخازن بيانات الاعتماد المعروفة (.git-credentials و.aws/credentials و.netrc و.pypirc و.config/gh/hosts.yml و.config/rclone/rclone.conf و.codex/auth.json) هي فحوصات للبيانات الوصفية فقط. لا يتم فتح محتوياتها أبدًا. يُبلَّغ عن كل منها كـ expected-store، بخطورة info للأوضاع الخاصة أو خطورة warn لأذونات التنفيذ/المجموعة/الآخرين. تكون line فارغة (null) ويحدد fp_kind=path صراحةً بصمة مسار مُفتاحية، وليس بصمة رمز. يتولى Reach Ward جرد بيانات الاعتماد في هذه المخازن. يتجنب ذلك اختلاق قيمة سرية أو رقم سطر لفحص وضع. تُصنَّف جميع المطابقات الأخرى كـ stray وتحذر عادةً؛ رموز وصول Google منخفضة الخطورة ومُعلَّمة كقصيرة العمر، ومن المحتمل أنها منتهية الصلاحية. لا يتم التحقق من أي رمز مقابل مزوّد.