git secrets --scan [-r|--recursive] [--cached] [--no-index] [--untracked] [<files>...]
git secrets --scan-history
git secrets --install [-f|--force] [<target-directory>]
git secrets --list [--global]
git secrets --add [-a|--allowed] [-l|--literal] [--global] <pattern>
git secrets --add-provider [--global] <command> [arguments...]
git secrets --register-aws [--global]
git secrets --aws-provider [<credentials-file>]

يمكنك استخدام هدف ``install`` من ملف Makefile المقدم لتثبيت ``git secrets`` وصفحة الدليل. يمكنك تخصيص مسار التثبيت باستخدام متغيرات PREFIX و MANPREFIX.

::

    make install

ويندوز
~~~~~~~

قم بتشغيل سكريبت PowerShell المقدم ``install.ps1``. سيقوم هذا بنسخ الملفات اللازمة إلى دليل التثبيت (``%USERPROFILE%/.git-secrets`` بشكل افتراضي) وإضافة الدليل إلى متغير PATH الخاص بالمستخدم الحالي.

::

    PS > ./install.ps1

Homebrew (لمستخدمي macOS)

brew install git-secrets

**لم تنته بعد! يجب عليك تثبيت خطافات git لكل مستودع ترغب في استخدامه مع** ``git secrets --install``.

cd /path/to/my/repo
git secrets --install
git secrets --register-aws

git secrets --register-aws --global

git secrets --install ~/.git-templates/git-secrets
git config --global init.templateDir ~/.git-templates/git-secrets

git secrets --add-provider -- cat /path/to/secret/file/patterns

git secrets --scan-history

يجب أن يظهر كل خيار من هذه الخيارات أولاً في سطر الأوامر.

``--install``
    يقوم بتثبيت خطافات git لمستودع. بمجرد تثبيت الخطافات لمستودع git، سيتم منع الالتزامات وعمليات الدمج غير السريعة لهذا المستودع من ارتكاب الأسرار.

``--scan``
    يقوم بفحص ملف واحد أو أكثر بحثًا عن الأسرار. عندما يحتوي ملف على سر، سيتم كتابة النص المتطابق من الملف المفحوص إلى stdout وسيخرج السكريبت بحالة غير صفرية. سيتم كتابة كل سطر متطابق مع اسم الملف الذي تطابق، ونقطتين، ورقم السطر المتطابق، ونقطتين، ثم سطر النص المتطابق. إذا لم يتم توفير أي ملفات، فسيتم فحص جميع الملفات التي يتم إرجاعها بواسطة ``git ls-files``.

``--scan-history``
    يقوم بفحص المستودع بما في ذلك جميع المراجعات. عندما يحتوي ملف على سر، سيتم كتابة النص المتطابق من الملف المفحوص إلى stdout وسيخرج السكريبت بحالة غير صفرية. سيتم كتابة كل سطر متطابق مع اسم الملف الذي تطابق، ونقطتين، ورقم السطر المتطابق، ونقطتين، ثم سطر النص المتطابق.

``--list``
    يسرد تكوين ``git-secrets`` للمستودع الحالي أو في تكوين git العام.

``--add``
    يضيف نمطًا محظورًا أو مسموحًا به.

``--add-provider``
    يسجل موفر أسرار. موفرات الأسرار هي ملفات قابلة للتنفيذ عند استدعائها تخرج أنماطًا محظورة يجب على ``git-secrets`` معاملتها كمحظورة.

``--register-aws``
    يضيف أنماط AWS الشائعة إلى تكوين git ويضمن عدم العثور على مفاتيح موجودة في ``~/.aws/credentials`` في أي التزام. تتم إضافة الفحوصات التالية:

    - معرفات مفتاح الوصول AWS عبر ``(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}``
    - مفاتيح API لـ Amazon Bedrock. طويلة العمر عبر ``ABSK[A-Za-z0-9+/]{109,}=*`` وقصيرة العمر عبر ``bedrock-api-key-YmVkcm9jay5hbWF6b25hd3MuY29t``
    - تعيينات مفتاح الوصول السري AWS عبر ":" أو "=" محاطة بعلامات اقتباس اختيارية
    - تعيينات معرف حساب AWS عبر ":" أو "=" محاطة بعلامات اقتباس اختيارية
    - أنماط مسموح بها لمفاتيح AWS سبيل المثال (``AKIAIOSFODNN7EXAMPLE`` و ``wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY``)
    - بيانات اعتماد معروفة من ``~/.aws/credentials``

    .. note::

        على الرغم من أن الأنماط المسجلة بواسطة هذا الأمر يجب أن تلتقط معظم حالات بيانات اعتماد AWS، إلا أن هذه الأنماط **ليست** مضمونة لالتقاطها **جميعًا**. يجب استخدام ``git-secrets`` كوسيلة إضافية للتأمين - ما زلت بحاجة إلى بذل العناية الواجبة لضمان عدم ارتكاب بيانات الاعتماد في مستودع.

``--aws-provider``
    موفر أسرار يخرج بيانات الاعتماد الموجودة في ملف INI. يمكنك اختياريًا توفير المسار إلى ملف INI.


خيارات ``--install``

إذا كان ``<target-directory>`` المقدم ليس في مستودع git، فسيتم إنشاء الدليل ووضع الخطافات في ``<target-directory>/hooks``. يمكن أن يكون هذا مفيدًا لإنشاء أدلة قوالب git لاستخدامها مع ``git init --template <target-directory>``.

يمكنك تشغيل ``git init`` على مستودع تمت تهيئته بالفعل. من `وثائق git init <https://git-scm.com/docs/git-init>`_:

    من وثائق git: تشغيل ``git init`` في مستودع موجود آمن. لن يقوم بالكتابة فوق الأشياء الموجودة بالفعل. السبب الرئيسي لإعادة تشغيل ``git init`` هو لاستلام القوالب المضافة حديثًا (أو لنقل المستودع إلى مكان آخر إذا تم توفير ``--separate-git-dir``).

يتم تثبيت خطافات git التالية:

1. ``pre-commit``: يستخدم للتحقق مما إذا كانت أي من الملفات التي تم تغييرها في الالتزام تستخدم أنماطًا محظورة.
2. ``commit-msg``: يستخدم لتحديد ما إذا كانت رسالة الالتزام تحتوي على أنماط محظورة.
3. ``prepare-commit-msg``: يستخدم لتحديد ما إذا كان التزام الدمج سيقدم تاريخًا يحتوي على نمط محظور في أي نقطة. يرجى ملاحظة أن هذا الخطاف يتم استدعاؤه فقط لعمليات الدمج غير السريعة.

.. note::

    يسمح git فقط بتنفيذ سكريبت واحد لكل خطاف. إذا كان المستودع يحتوي على أدلة فرعية على غرار Debian مثل ``pre-commit.d`` و ``commit-msg.d``، فسيتم تثبيت خطافات git في هذه الأدلة، مما يفترض أنك قمت بتكوين الخطافات المقابلة لتنفيذ جميع السكريبتات الموجودة في هذه الأدلة. إذا لم تكن هذه الأدلة الفرعية git موجودة، فسيتم تثبيت خطافات git إلى دليل ``.git/hooks`` الخاص بمستودع git.

cd /path/to/my/repository
git secrets --install

git secrets --install /path/to/my/repository

git secrets --install ~/.git-templates/git-secrets
git init --template ~/.git-templates/git-secrets

git secrets --install -f

``-r, --recursive``
    يقوم بفحص الملفات المحددة بشكل متكرر. إذا تمت مصادفة دليل، فسيتم فحص الدليل. إذا لم يتم توفير ``-r``، فسيتم تجاهل الأدلة.

    لا يمكن استخدام ``-r`` جنبًا إلى جنب مع ``--cached``، أو ``--no-index``، أو ``--untracked``.

``--cached``
    يبحث في كائنات blob المسجلة في ملف الفهرس.

``--no-index``
    يبحث في الملفات الموجودة في الدليل الحالي التي لا يديرها git.

``--untracked``
    بالإضافة إلى البحث في الملفات المتعقبة في شجرة العمل، يقوم ``--scan`` أيضًا في الملفات غير المتعقبة.

``<files>...``
    المسار إلى ملف واحد أو أكثر على القرص لفحصها بحثًا عن الأسرار.

    إذا لم يتم توفير أي ملفات، فسيتم فحص جميع الملفات التي يتم إرجاعها بواسطة ``git ls-files``.


أمثلة
^^^^^^^^

فحص جميع الملفات في المستودع::

    git secrets --scan

فحص ملف واحد بحثًا عن الأسرار::

    git secrets --scan /path/to/file

فحص دليل بشكل متكرر بحثًا عن الأسرار::

    git secrets --scan -r /path/to/directory

فحص ملفات متعددة بحثًا عن الأسرار::

    git secrets --scan /path/to/file /path/to/other/file

يمكنك الفحص باستخدام علامات البدل::

    git secrets --scan /path/to/directory/*

فحص من stdin::

    echo 'hello!' | git secrets --scan -


خيارات ``--list``

``--global``
    يضيف أنماطًا إلى تكوين git العام

``-l, --literal``
    يهرب أحرف التعبير العادية الخاصة في النمط المقدم بحيث يتم البحث عن النمط حرفيًا.

``-a, --allowed``
    يحدد النمط على أنه مسموح به بدلاً من محظور. تستخدم الأنماط المسموح بها لتصفية النتائج الإيجابية الكاذبة.

``<pattern>``
    نمط التعبير العادي للبحث.


أمثلة
^^^^^^^^

يضيف نمطًا محظورًا إلى المستودع الحالي::

    git secrets --add '[A-Z0-9]{20}'

يضيف نمطًا محظورًا إلى تكوين git العام::

    git secrets --add --global '[A-Z0-9]{20}'

يضيف سلسلة يتم البحث عنها حرفيًا (يتم هروب ``+``)::

    git secrets --add --literal 'foo+bar'

يضيف نمطًا مسموحًا به::

    git secrets --add -a 'allowed pattern'


خيارات ``--register-aws``

``[<credentials-file>]``
    إذا تم توفيره، يحدد المسار المخصص لملف INI لفحصه. إذا لم يتم توفيره، يتم افتراض ``~/.aws/credentials``.


خيارات ``--add-provider``

git secrets --add-provider -- git secrets --aws-provider

git secrets --add-provider -- cat /path/to/secret/file/patterns

git secrets --add --allowed 'my regex pattern'

كما أنه من الممارسات السيئة إضافة أنماط محظورة جشعة جدًا، فمن الممارسات السيئة أيضًا إضافة أنماط مسموح بها متسامحة جدًا. تأكد من اختبار أنماطك باستخدام استدعاءات مخصصة لـ ``git secrets --scan $filename`` لضمان عملها كما هو مقصود.

git secrets --add-provider -- git secrets --aws-provider

This is a test!
password=ex@mplepassword
password=******
More test...

git secrets --add 'password\s*=\s*.+'
git secrets --add --allowed --literal 'ex@mplepassword'

/tmp/example:3:password=******

[ERROR] Matched prohibited pattern

Possible mitigations:
- Mark false positives as allowed using: git config --add secrets.allowed ...
- List your configured patterns: git config --get-all secrets.patterns
- List your configured allowed patterns: git config --get-all secrets.allowed
- Use --no-verify if this is a one-time false positive

/tmp/example:2:password=ex@mplepassword
/tmp/example:3:password=******

git secrets --add --allowed '/tmp/example:.*'
git secrets --scan /tmp/example && echo $?
# Outputs: 0

git secrets --add --allowed '/tmp/example:3:.*'
git secrets --scan /tmp/example && echo $?
# Outputs: 0