Credactor

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

تتوقف معظم أدوات فحص الأسرار عند التنبيه: تحصل على قائمة ببيانات الاعتماد المسرّبة ويبقى عليك التنظيف. يكتشف Credactor الأسرار المضمّنة في الشيفرة ويعيد كتابتها في مكانها، بحيث تنتقل التسريبة في شجرة العمل لديك من "تم اكتشافها" إلى "تم إصلاحها" بأمر واحد. يعمل على جهازك، أو كخطاف pre-commit، أو كبوابة CI، ويمكنه أيضًا إصلاح ما تكتشفه Gitleaks أو TruffleHog أو Betterleaks.

# Before
db_password = "h8Tq2vKp9mRz4Wd"

# credactor --fix-all .   (default: a sentinel that fails loudly at runtime)
db_password = "REDACTED_BY_CREDACTOR"

# credactor --replace-with env --fix-all .   (read it from the environment)
db_password = os.environ["DB_PASSWORD"]

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

لماذا Credactor

• إنه يُصلح، لا يكتفي بالإبلاغ. يُستبدل كل اكتشاف في موضعه بعنصر حارس، أو بعلامتك الخاصة، أو ببحث عن متغيّر بيئة بلغة الملف نفسها.
• كتابات حذرة. تُخطَّط كل عملية تحرير في الذاكرة، ويُؤخذ نسخ احتياطي أولًا (الوضع 0600)، ثم تُكتب في ملف مؤقت وتُعاد تسميتها إلى موضعها. يُتخطّى أي ملف تغيّر أثناء التشغيل، أو مسار يخرج عن جذر الفحص، أو كتلة مفتاح خاص مع تحذير، ويبقى اكتشافه مُبلَّغًا عنه.
• يعمل مع الماسح الذي تشغّله بالفعل. زوّده بتقرير Gitleaks أو TruffleHog أو Betterleaks فيُصلح اكتشافاتها واكتشافاته في تمريرة واحدة منزوعة التكرار.
• مصمَّم لخطوط الأنابيب. بوابة --ci للقراءة فقط مع رموز خروج واضحة، وSARIF 2.1.0 مع مواقع الأسطر والأعمدة لـ GitHub Code Scanning، وإجراء GitHub وخطاف pre-commit. تُقنَّع الأسرار في كل صيغة تقرير، ويُنظَّف الإخراج النصي حتى لا يتمكن ملف مفحوص من حقن تسلسلات هروب أو أوامر سير عمل CI في طرفيتك أو سجلك.
• إصدارات مُتحقَّق منها مقابل مصدرها. مكتبة Python 3.11+ القياسية الخالصة دون أي تبعيات وقت التشغيل. قبل وصول إصدار إلى PyPI، يُقارَن كل ملف Credactor في حزمة wheel وsdist بايتًا ببايت مع المصدر الموسوم، ويجب أن تطابق بيانات تعريف الحزمة pyproject.toml (انظر تقوية سلسلة التوريد).

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

التثبيت

pip install credactor

باستخدام uv، ثبّته كأداة، أو شغّله مرة واحدة دون تثبيت:

uv tool install credactor
uvx credactor --dry-run .

أو باستخدام Homebrew على macOS وLinux:

brew install rxb06/tap/credactor

يتطلب Python 3.11 أو أحدث. تم اختباره في CI على Linux وWindows، من Python 3.11 إلى 3.13. بالنسبة للملفات بترميزات غير UTF-8 أو Latin-1 أو UTF-16 البسيط، أضف الخيار الإضافي الاختياري: pip install 'credactor[encoding]' أو uv tool install 'credactor[encoding]' (تتضمنه صيغة Homebrew).

البدء السريع

1. اطّلع على ما يجده. لا يتم تغيير أي شيء.

credactor --dry-run .

======================================================================
  CREDENTIAL SCAN REPORT  --  2 finding(s) in 1 file(s)
======================================================================

  FILE: config.py
  ────────────────────────────────────────────────────────────
  Line    3  [HIGH]  [variable:db_password]
           db_password = "h8Tq[REDACTED]"
  Line    4  [CRITICAL]  [pattern:AWS access key]
           aws_key = "AKIA[REDACTED]"

تُظهر التقارير أول أربعة أحرف فقط من كل سر.

2. أصلحها. راجع النتائج أولًا: --fix-all يعيد كتابة كل واحدة منها، بما في ذلك الإيجابيات الكاذبة. للإبقاء على واحدة، أضف # credactor:ignore إلى سطرها (انظر كتم الإيجابيات الكاذبة) أو أصلحها تفاعليًا وأجب بـ n. قبل تغيير كل ملف، تُكتب نسخة .bak بجانبه حتى تتمكن من التراجع.

credactor .                          # ask y/N for each finding (needs a terminal)
credactor --fix-all .                # fix all after one confirmation
credactor --fix-all --yes .          # fix all, no prompt (scripts)
credactor --replace-with env --fix-all .   # environment lookups instead of the sentinel

وضع Env يكتب البحث، وليس الاستيراد: أضف import os أو ما يعادله في لغتك إذا كان الملف يفتقر إليه. على Windows Git Bash، شغّل الوضع التفاعلي كـ winpty credactor ..

3. تحقّق، ثم نظّف النسخ الاحتياطية. كل ملف .bak لا يزال يحتوي على السر الأصلي، وCredactor لا يعدّل ملف .gitignore الخاص بك أبدًا، لذا فإن git add . العادي سيقوم بإضافته إلى منطقة التجهيز.

diff config.py.bak config.py         # check what changed
cp config.py.bak config.py           # undo

أضف *.bak و*.credactor.tmp إلى .gitignore واحذف النسخ الاحتياطية بمجرد أن ترضى عن النتيجة. لإبقاء النسخ الاحتياطية خارج شجرة المشروع منذ البداية، مرّر --secure-backup-dir DIR (دليل خارج المستودع) في تشغيل الإصلاح. أما --secure-delete فيمحو كل نسخة احتياطية بدلًا من ذلك، ما يجعل git خيارك الوحيد للتراجع.

الأوامر في لمحة

الأمر	ما يفعله	يغيّر الملفات
credactor --dry-run .	الإبلاغ عن النتائج	لا
credactor .	مراجعة وإصلاح نتيجة واحدة في كل مرة	نعم، عند y
credactor --fix-all .	إصلاح كل النتائج بعد تأكيد واحد	نعم
credactor --ci .	بوابة: الخروج بالرمز 1 عند وجود نتائج	أبدًا
credactor --staged --ci .	بوابة على ما هو مُجهّز للالتزام فقط	أبدًا
credactor --scan-history .	فحص آخر 100 التزام يغيّر الملفات	أبدًا
credactor --ci -f sarif . > results.sarif	SARIF 2.1.0 لـ Code Scanning	أبدًا
credactor --ci -f json . > findings.json	تقرير قابل للقراءة آليًا	أبدًا

كل علم وكل تركيبة موجودة في الدليل.

استخدمه في pre-commit وCI

خطاف pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.7.5
    hooks:
      - id: credactor

pre-commit install

كل git commit يقوم بعد ذلك بفحص المحتوى المُجهَّز ويُحظر إذا كان يحتوي على بيانات اعتماد. لا يقوم الخطاف أبدًا بإعادة كتابة الملفات. يتطلب pre-commit 3.2.0 أو أحدث؛ بدون إطار العمل، راجع الخطاف المستقل.

إجراء GitHub

steps:
  - uses: actions/checkout@v7
  - uses: rxb06/[email protected]

تعمل الـ Action دائمًا مع --ci، لذا لا تعيد كتابة الـ checkout أبدًا. تُفشل النتائج الخطوة، وكذلك أي خطأ. للإبلاغ إلى Code Scanning بدلًا من الإفشال:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v7
  - uses: rxb06/[email protected]
    with:
      format: sarif
      upload-sarif: true
      fail-on-findings: false

يُدرج دليل تكامل CI كل مُدخل ومُخرج من Action ويغطي GitLab CI وخطوات shell العادية.

أحضر ماسحك الخاص

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

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