Credactor

اعثر على السر. أصلحه. التزم بالنظافة.

أدوات فحص الأسرار جيدة في إطلاق الإنذار، لكنها ليست ذات فائدة كبيرة في إخماده. فهي تسلّمك قائمة بالبيانات الاعتمادية المسرّبة وتترك التنظيف لك. Credactor يُغلق الحلقة: فهو يعثر على السر المكتوب في الكود ويعيد كتابته في مكانه، بحيث ينتقل التسريب من الاكتشاف إلى الإصلاح بأمر واحد.

إبقاء البيانات الاعتمادية خارج الكود المصدري ممارسة أمنية أساسية، وليست خيارية. Credactor يجعل هذه الأساسيات رخيصة الثمن، على جهازك قبل الالتزام أو في CI قبل الدمج. شغّله بمفرده، أو إلى جانب أدوات الفحص التي تثق بها بالفعل.

# Credactor يعثر على هذا:
db_password = "h8Tq2vKp9mRz4Wd"

# افتراضيًا يعيد كتابة السر كقيمة حارسة تفشل بصوت عالٍ وقت التشغيل:
db_password = "REDACTED_BY_CREDACTOR"

# مع --replace-with env، يكتب مرجعًا يقرأ من متغيرات البيئة:
db_password = os.environ["DB_PASSWORD"]

إعادة الكتابة تعيد كتابة الملفات في شجرة العمل لديك. إذا كان السر قد تم التزامه بالفعل، فقم بتدوير المفتاح وتنظيف السجل أيضًا (على سبيل المثال، باستخدام git filter-repo). إعادة كتابة ملف ليست بديلاً عن إبطال بيانات اعتمادية مسرّبة.

لماذا Credactor

• إعادة كتابة، وليس مجرد اكتشاف. معظم أدوات الفحص تتوقف عند النتيجة. Credactor يستبدل السر في مكانه: قيمة حارسة صاخبة REDACTED_BY_CREDACTOR تفشل وقت التشغيل افتراضيًا، أو مرجع متغير بيئة مدرك للغة (Python، JavaScript/TypeScript، Go، Java/Kotlin، Ruby، PHP، وshell) مثل os.environ["KEY"]. الاستبدال كود صالح. إذا كان الملف لا يتضمن بالفعل الاستيراد المطابق (مثل import os)، قم بإضافته.
• آمن افتراضيًا. كتابات ذرية، نسخ احتياطية تلقائية .bak، حماية لحدود الروابط الرمزية وأذونات الملفات، وإخفاء كامل للسر في كل المخرجات. إذا تعذرت كتابة نسخة احتياطية آمنة، يتخطى Credactor الملف بدلاً من إعادة كتابته بشكل أعمى، وأي تعطل في منتصف الكتابة يترك الأصل سليمًا.
• صفر تبعيات وقت التشغيل. مكتبة Python 3.11+ القياسية النقية، بالإضافة إلى إضافة اختيارية للترميزات غير UTF-8.
• مصمم لخط الإنتاج. مخرجات SARIF لفحص كود GitHub، وبوابة --ci للقراءة فقط مع رموز خروج دقيقة، وخطاف pre-commit (نسخة تجريبية)، واستيعاب تقارير Gitleaks أو TruffleHog. اكتشف باستخدام Gitleaks أو TruffleHog، وعالج باستخدام Credactor.

التثبيت

pip install credactor

يتطلب Python 3.11+. لا توجد تبعيات أخرى. يعمل على Linux وmacOS وWindows (مُختبَر على CI على Linux وWindows).

من المصدر:

git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .

يعمل credactor بعد ذلك من أي دليل.

بدء سريع

شغّل --dry-run أولاً وراجع النتائج قبل إعادة الكتابة. النتائج الإيجابية الخاطئة ممكنة، وتحت --fix-all قد تُعاد كتابة نتيجة إيجابية خاطئة. اكتم القيم المعروفة بأنها آمنة باستخدام # credactor:ignore أو إدخال في .credactorignore.

credactor --dry-run .                 # فحص، دون تغيير أي شيء
credactor .                           # فحص، ثم إعادة كتابة تفاعلية (نعم/لا لكل نتيجة)
credactor --fix-all .                 # إعادة كتابة كل شيء بعد تأكيد واحد
credactor --fix-all --yes .           # إعادة كتابة غير تفاعلية (CI / سكربتات)
credactor --ci .                      # بوابة قراءة فقط: خروج 1 عند وجود نتائج
credactor --replace-with env .        # إعادة كتابة إلى مراجع متغيرات بيئة بدلاً من القيمة الحارسة

خطاف pre-commit (نسخة تجريبية)

تكامل الخطاف في مرحلة تجريبية. شغّل credactor --dry-run . يدويًا قبل الاعتماد عليه وحده.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.6.0   # ثبّت على أحدث وسم إصدار
    hooks:
      - id: credactor

الاكتشاف

يكتشف Credactor أنواع البيانات الاعتمادية التي تتسرب غالبًا، ويخصص لكل منها مستوى خطورة لتتمكن من الفرز في لمحة.

رموز المزود الحتمية (البادئات أعلاه) يتم الإبلاغ عنها بغض النظر عن الإنتروبيا. الكواشف الاستدلالية (JWTs، سلاسل الاتصال، hex، Base64) يجب أن تتجاوز حد الإنتروبيا. يتم الإبلاغ عن hex أو Base64 المستقل فقط عند اقتباسه. القيمة عالية الإنتروبيا غير المقتبسة تُلتقط فقط على متغير باسم بيانات اعتمادية، مما يحفظ تجزئات git والمجاميع الاختبارية. للقواعد الكاملة للاكتشاف ومستويات الخطورة، راجع الدليل.

مجموعة القواعد الأصلية في Credactor أضيق من أداة فحص مخصصة، وبعض تنسيقات المزودين (مثل SendGrid وTwilio وخطافات Slack) لا يتم اكتشافها. قوتها في المعالجة: اقرنها بـ Gitleaks أو TruffleHog لأوسع اكتشاف، أو شغّلها بمفردها.

اقرنها بأداة فحص أخرى، وأعد كتابة الجميع

يقف Credactor بمفرده، ويصبح أقوى في الصحبة. هل تشغّل Gitleaks أو TruffleHog بالفعل؟ مرّر تقريرهما إلى Credactor وسيعيد كتابة المجموعة المدمجة، مع إزالة التكرار مقابل نتائجه الخاصة (عند التداخل، يفوز مستوى الخطورة الأعلى). تمريرة معالجة واحدة تغطي فحصك وفحصهما:

gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .

--from-gitleaks / --from-trufflehog (أو جدول [ingest] في .credactor.toml) يتطلبان هدف دليل — وجّه Credactor إلى نفس الجذر الذي شغّل عليه الفاحص. مسارات التقرير تُحلّ مقابل دليل العمل، والتقرير لقطة: أعد توليده بعد إعادة الكتابة أو تغيير الشجرة. راجع دليل تكامل CI.

ميزات إضافية

• إعادة كتابة تفاعلية أو دفعة؛ سلسلة استبدال مخصصة عبر --replacement؛ --scan-history لفحص سجل التزامات git
• نسخ احتياطية آمنة: --secure-delete (الكتابة فوق وإزالة .bak؛ يرفع الحاجز ضد الاسترداد العادي، وليس ضمانًا جنائيًا) أو --secure-backup-dir لتخزين النسخ الاحتياطية خارج المستودع
• قوائم السماح المضمّنة # credactor:ignore و.credactorignore (أنماط glob، file:line، قيم حرفية)
• إعداد لكل مستودع عبر .credactor.toml
• 29 نوع ملف مصدر/إعداد/ملاحظات جاهزة (بما في ذلك .txt)؛ --scan-json لتضمين JSON؛ --fail-on-error للفشل عند تعذر قراءة ملف

أنواع الملفات المفحوصة

.py .js .ts .jsx .tsx .sh .bash .env .cfg .ini .toml .yaml .yml .rb .go .java .php .cs .kt .tf .hcl .conf .config .properties .xml .pem .key .crt .txt

بالإضافة إلى متغيرات .env.* / .env-* (.env.local, .env.production) وملفات SSH / المفاتيح الخاصة (id_rsa, id_dsa, id_ecdsa, id_ed25519)، جميعها مطابقة بالاسم وليس بالامتداد. JSON مستبعد افتراضيًا لأن استجابات API تنتج معدل نتائج إيجابية خاطئة مرتفعًا؛ أضف --scan-json لتضمينه. الملف المذكور مباشرة في سطر الأوامر يُفحص حتى لو لم يكن امتداده في هذه القائمة.

رموز الخروج

تقوية سلسلة التوريد

يجب أن تكون الأداة الأمنية آمنة للتثبيت، وليس فقط آمنة للتشغيل. خط البناء والإصدار في Credactor مُقوّى من البداية إلى النهاية؛ التفاصيل الكاملة في وثيقة الأمان.

• صفر تبعيات وقت التشغيل. pip install credactor الافتراضي لا يسحب أي حزم طرف ثالث (فقط الإضافة الاختيارية [encoding])، فلا يوجد شيء لفحصه وقت التثبيت.
• سلسلة أدوات مثبتة بالتجزئة. البناء في CI والإصدارات تُثبّت من ملف قفل --require-hashes، بما في ذلك خلفية البناء (python -m build --no-isolation مقابل setuptools مثبت)، بحيث يفشل البناء عند أي تبعية معبثة.
• القطع الأثرية مُدققة بالبايت مقابل المصدر. عند كل دفع وقبل كل نشر، يقارن scripts/audit_wheel.py العجلة وsdist بالمصدر الملتزم بايتًا ببايت (sha256 مقابل git HEAD)؛ أي ملف مضاف أو مفقود أو معدل يفشل البوابة، فلا يمكن لخطوة بناء حقن كود دون أن يُلاحظ.
• CI مثبت بـ SHA وبأقل صلاحيات. GitHub Actions تثبّت على تجزئات SHA للالتزامات، ورموز سير العمل تبقى ضيقة — contents: read افتراضيًا، وid-token: write فقط لوظيفة النشر.

الوثائق

الترخيص

Apache 2.0. راجع LICENSE.