Credactor

ابحث عن السر. أصلحه. ادفع نظيفًا.

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

الحفاظ على بيانات الاعتماد خارج الكود المصدري هو ممارسة أمنية أساسية، وليست اختيارية. Credactor يجعل هذه الأساسية رخيصة الثمن: على جهازك قبل الـ commit، أو في CI قبل الـ merge. استخدمه لوحده أو جنبًا إلى جنب مع أدوات الكشف التي تثق بها.

# Credactor finds this:
db_password = "h8Tq2vKp9mRz4Wd"

# By default it rewrites the secret as a sentinel that fails loudly at runtime:
db_password = "REDACTED_BY_CREDACTOR"

# With --replace-with env, it writes a reference that reads from the environment:
db_password = os.environ["DB_PASSWORD"]

عملية الاستبدال تعيد كتابة الملفات في شجرة العمل الخاصة بك. إذا تم بالفعل commit لسر ما، فقم بتدوير المفتاح وتنظيف التاريخ أيضًا (مثلاً باستخدام git filter-repo). إعادة كتابة ملف ليست بديلاً عن إلغاء صلاحية بيانات اعتماد مسربة.

لماذا Credactor

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

التثبيت

pip install credactor

يتطلب بايثون 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.5.0   # قم بتثبيت أحدث إصدار
    hooks:
      - id: credactor

الكشف

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

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

مجموعة قواعد Credactor الأصلية أضيق من مجموعة أداة كشف مخصصة، وبعض تنسيقات المزوّدين (مثل SendGrid و Twilio و webhooks 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) يتطلبان هدف دليل. راجع دليل تكامل CI.

المزيد من الميزات

• استبدال تفاعلي أو دفعة؛ سلسلة استبدال مخصصة عبر --replacement؛ --scan-history لمسح تاريخ commits
• نسخ احتياطية آمنة: --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 مثبتة)، لذا فإن تبعية معدلة تفشل البناء.
• فحص بايت القطع الأثرية مقابل المصدر. عند كل push وقبل كل نشر، يقوم scripts/audit_wheel.py بمقارنة wheel و sdist مع المصدر الملتزم بايت ببايت (sha256 مقابل git HEAD)؛ أي ملف مضاف أو مفقود أو معدل يفشل البوابة، لذا لا يمكن لخطوة بناء حقن كود دون أن يُلاحظ.
• CI مرتكز بال SHA وأقل صلاحية. GitHub Actions مثبتة على SHA commits، وتبقى رموز سير العمل ضيقة — contents: read افتراضيًا، id-token: write فقط لمهمة النشر.

الوثائق

الترخيص

Apache 2.0. راجع LICENSE.