detect-secrets

عن

detect-secrets هي وحدة مسماة بشكل مناسب لـ (مفاجأة، مفاجأة) كشف الأسرار داخل قاعدة الشيفرات البرمجية.

ومع ذلك، على عكس الحزم الأخرى المشابهة التي تركز فقط على إيجاد الأسرار، تم تصميم هذه الحزمة مع وضع العميل المؤسسي في الاعتبار: توفير وسيلة متوافقة مع الإصدارات السابقة ومنهجية لـ:

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

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

يقوم بذلك عن طريق تشغيل مخرجات الفروقات الدورية مقابل تعبيرات regex المصممة بشكل استكشافي، لتحديد ما إذا كان أي سر جديد قد تم ارتكابه. بهذه الطريقة، يتجنب العبء الناجم عن التنقيب في كل تاريخ git، وكذلك الحاجة إلى مسح المستودع بأكمله في كل مرة.

للاطلاع على التغييرات الأخيرة، يرجى مراجعة CHANGELOG.md.

إذا كنت تتطلع إلى المساهمة، يرجى مراجعة CONTRIBUTING.md.

للحصول على وثائق أكثر تفصيلاً، تحقق من الوثائق الأخرى لدينا.

أمثلة

بداية سريعة:

قم بإنشاء خط أساس للأسرار المحتملة الموجودة حاليًا في مستودع git الخاص بك.```bash $ detect-secrets scan > .secrets.baseline

أو، لتشغيله من مجلد مختلف:```bash
$ detect-secrets -C /path/to/directory scan > /path/to/directory/.secrets.baseline

فحص الملفات غير المتتبعة بواسطة git:```bash $ detect-secrets scan test_data/ --all-files > .secrets.baseline

### إضافة أسرار جديدة إلى خط الأساس:

سيؤدي ذلك إلى إعادة مسح قاعدة الشيفرات الخاصة بك، و:

1. تحديث/ترقية خط الأساس الخاص بك ليكون متوافقًا مع أحدث إصدار،
2. إضافة أي أسرار جديدة يجدها إلى خط الأساس الخاص بك،
3. إزالة أي أسرار لم تعد موجودة في قاعدة الشيفرات الخاصة بك

سيؤدي ذلك أيضًا إلى الحفاظ على أي أسرار قمت بتوصيفها.```bash
$ detect-secrets scan --baseline .secrets.baseline

بالنسبة للخطوط الأساسية الأقدم من الإصدار 0.9، قم فقط بإعادة إنشائها.

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

مسح الملفات المرحّلة فقط:```bash $ git diff --staged --name-only -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline

**مسح جميع الملفات المتعقبة:**```bash
$ git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline

عرض جميع الإضافات المُمكّنة:```bash

$ detect-secrets scan --list-all-plugins ArtifactoryDetector AWSKeyDetector AzureStorageKeyDetector BasicAuthDetector CloudantDetector DiscordBotTokenDetector GitHubTokenDetector GitLabTokenDetector Base64HighEntropyString HexHighEntropyString IbmCloudIamDetector IbmCosHmacDetector IPPublicDetector JwtTokenDetector KeywordDetector MailchimpDetector NpmDetector OpenAIDetector PrivateKeyDetector PypiTokenDetector SendGridDetector SlackDetector SoftlayerDetector SquareOAuthDetector StripeDetector TelegramBotTokenDetector TwilioKeyDetector

### تعطيل الإضافات:```bash
$ detect-secrets scan --disable-plugin KeywordDetector --disable-plugin AWSKeyDetector

إذا كنت تريد تشغيل إضافة معينة فقط، يمكنك القيام بما يلي:```bash $ detect-secrets scan --list-all-plugins |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs detect-secrets scan test_data

### تدقيق خط الأساس:

هذه خطوة اختيارية لتسمية النتائج في خط الأساس الخاص بك. يمكن استخدامها لتضييق قائمة الأسرار التي يجب ترحيلها، أو لتكوين الإضافات بشكل أفضل لتحسين نسبة الإشارة إلى الضوضاء.```bash
$ detect-secrets audit .secrets.baseline

الاستخدام في نصوص بايثون الأخرى

الاستخدام الأساسي:```python from detect_secrets import SecretsCollection from detect_secrets.settings import default_settings

secrets = SecretsCollection() with default_settings(): secrets.scan_file('test_data/config.ini')

import json print(json.dumps(secrets.json(), indent=2))

**تكوين أكثر تقدماً:**```python
from detect_secrets import SecretsCollection
from detect_secrets.settings import transient_settings

secrets = SecretsCollection()
with transient_settings({
    # Only run scans with only these plugins.
    # This format is the same as the one that is saved in the generated baseline.
    'plugins_used': [
        # Example of configuring a built-in plugin
        {
            'name': 'Base64HighEntropyString',
            'limit': 5.0,
        },

        # Example of using a custom plugin
        {
            'name': 'HippoDetector',
            'path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
        },
    ],

    # We can also specify whichever additional filters we want.
    # This is an example of using the function `is_identified_by_ML_model` within the
    # local file `./private-filters/example.py`.
    'filters_used': [
        {
            'path': 'file://private-filters/example.py::is_identified_by_ML_model',
        },
    ]
}) as settings:
    # If we want to make any further adjustments to the created settings object (e.g.
    # disabling default filters), we can do so as such.
    settings.disable_filters(
        'detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign',
        'detect_secrets.filters.heuristic.is_likely_id_string',
    )

    secrets.scan_file('test_data/config.ini')

التثبيت```bash

$ pip install detect-secrets ✨🍰✨

قم بالتثبيت عبر [brew](https://brew.sh/):```bash
$ brew install detect-secrets

الاستخدام

يأتي detect-secrets مع ثلاث أدوات مختلفة، وغالبًا ما يكون هناك ارتباك حول أي منها يجب استخدامه. استخدم قائمة المراجعة المفيدة هذه لمساعدتك في اتخاذ القرار:

هل تريد إضافة أسرار إلى خط الأساس الخاص بك؟ إذا كان الأمر كذلك، استخدم detect-secrets scan.
هل تريد التنبيه إلى أسرار جديدة غير موجودة في خط الأساس؟ إذا كان الأمر كذلك، استخدم detect-secrets-hook.
هل تقوم بتحليل خط الأساس نفسه؟ إذا كان الأمر كذلك، استخدم detect-secrets audit.

إضافة الأسرار إلى خط الأساس```

$ detect-secrets scan --help usage: detect-secrets scan [-h] [--string [STRING]] [--only-allowlisted] [--all-files] [--baseline FILENAME] [--force-use-all-plugins] [--slim] [--list-all-plugins] [-p PLUGIN] [--base64-limit [BASE64_LIMIT]] [--hex-limit [HEX_LIMIT]] [--disable-plugin DISABLE_PLUGIN] [-n | --only-verified] [--exclude-lines EXCLUDE_LINES] [--exclude-files EXCLUDE_FILES] [--exclude-secrets EXCLUDE_SECRETS] [--word-list WORD_LIST_FILE] [-f FILTER] [--disable-filter DISABLE_FILTER] [path [path ...]]

Scans a repository for secrets in code. The generated output is compatible with detect-secrets-hook --baseline.

positional arguments: path Scans the entire codebase and outputs a snapshot of currently identified secrets.

optional arguments: -h, --help show this help message and exit --string [STRING] Scans an individual string, and displays configured plugins' verdict. --only-allowlisted Only scans the lines that are flagged with allowlist secret. This helps verify that individual exceptions are indeed non-secrets.

scan options: --all-files Scan all files recursively (as compared to only scanning git tracked files). --baseline FILENAME If provided, will update existing baseline by importing settings from it. --force-use-all-plugins If a baseline is provided, detect-secrets will default to loading the plugins specified by that baseline. However, this may also mean it doesn't perform the scan with the latest plugins. If this flag is provided, it will always use the latest plugins --slim Slim baselines are created with the intention of minimizing differences between commits. However, they are not compatible with the audit functionality, and slim baselines will need to be remade to be audited.

plugin options: Configure settings for each secret scanning ruleset. By default, all plugins are enabled unless explicitly disabled.

--list-all-plugins Lists all plugins that will be used for the scan. -p PLUGIN, --plugin PLUGIN Specify path to custom secret detector plugin. --base64-limit [BASE64_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 4.5. --hex-limit [HEX_LIMIT] Sets the entropy limit for high entropy strings. Value must be between 0.0 and 8.0, defaults to 3.0. --disable-plugin DISABLE_PLUGIN Plugin class names to disable. e.g. Base64HighEntropyString

filter options: Configure settings for filtering out secrets after they are flagged by the engine.

-n, --no-verify Disables additional verification of secrets via network call. --only-verified Only flags secrets that can be verified. --exclude-lines EXCLUDE_LINES If lines match this regex, it will be ignored. --exclude-files EXCLUDE_FILES If filenames match this regex, it will be ignored. --exclude-secrets EXCLUDE_SECRETS If secrets match this regex, it will be ignored. --word-list WORD_LIST_FILE Text file with a list of words, if a secret contains a word in the list we ignore it. -f FILTER, --filter FILTER Specify path to custom filter. May be a python module path (e.g. detect_secrets.filters.common.is_invalid_file) or a local file path (e.g. file://path/to/file.py::function_name). --disable-filter DISABLE_FILTER Specify filter to disable. e.g. detect_secrets.filters.common.is_invalid_file

### حجب الأسرار غير الموجودة في خط الأساس```
$ detect-secrets-hook --help
usage: detect-secrets-hook [-h] [-v] [--version] [--baseline FILENAME]
                           [--list-all-plugins] [-p PLUGIN]
                           [--base64-limit [BASE64_LIMIT]]
                           [--hex-limit [HEX_LIMIT]]
                           [--disable-plugin DISABLE_PLUGIN]
                           [-n | --only-verified]
                           [--exclude-lines EXCLUDE_LINES]
                           [--exclude-files EXCLUDE_FILES]
                           [--exclude-secrets EXCLUDE_SECRETS]
                           [--word-list WORD_LIST_FILE] [-f FILTER]
                           [--disable-filter DISABLE_FILTER]
                           [filenames [filenames ...]]

positional arguments:
  filenames             Filenames to check.

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Verbose mode.
  --version             Display version information.
  --json                Print detect-secrets-hook output as JSON
  --baseline FILENAME   Explicitly ignore secrets through a baseline generated
                        by `detect-secrets scan`

plugin options:
  Configure settings for each secret scanning ruleset. By default, all
  plugins are enabled unless explicitly disabled.

  --list-all-plugins    Lists all plugins that will be used for the scan.
  -p PLUGIN, --plugin PLUGIN
                        Specify path to custom secret detector plugin.
  --base64-limit [BASE64_LIMIT]
                        Sets the entropy limit for high entropy strings. Value
                        must be between 0.0 and 8.0, defaults to 4.5.
  --hex-limit [HEX_LIMIT]
                        Sets the entropy limit for high entropy strings. Value
                        must be between 0.0 and 8.0, defaults to 3.0.
  --disable-plugin DISABLE_PLUGIN
                        Plugin class names to disable. e.g.
                        Base64HighEntropyString

filter options:
  Configure settings for filtering out secrets after they are flagged by the
  engine.

  -n, --no-verify       Disables additional verification of secrets via
                        network call.
  --only-verified       Only flags secrets that can be verified.
  --exclude-lines EXCLUDE_LINES
                        If lines match this regex, it will be ignored.
  --exclude-files EXCLUDE_FILES
                        If filenames match this regex, it will be ignored.
  --exclude-secrets EXCLUDE_SECRETS
                        If secrets match this regex, it will be ignored.
  -f FILTER, --filter FILTER
                        Specify path to custom filter. May be a python module
                        path (e.g.
                        detect_secrets.filters.common.is_invalid_file) or a
                        local file path (e.g.
                        file://path/to/file.py::function_name).
  --disable-filter DISABLE_FILTER
                        Specify filter to disable. e.g.
                        detect_secrets.filters.common.is_invalid_file

نوصي بإعداد هذا كخطاف pre-commit. إحدى الطرق للقيام بذلك هي باستخدام إطار pre-commit:```yaml

.pre-commit-config.yaml

repos:

repo: https://github.com/Yelp/detect-secrets rev: v1.5.0 hooks:
- id: detect-secrets args: ['--baseline', '.secrets.baseline'] exclude: package.lock.json

#### القائمة البيضاء المضمنة

هناك أوقات نريد فيها استبعاد إيجابية كاذبة من منع الالتزام، دون إنشاء خط أساس للقيام بذلك. يمكنك القيام بذلك عن طريق إضافة تعليق كالتالي:```python
secret = "hunter2"      # pragma: allowlist secret

أو```javascript // pragma: allowlist nextline secret const secret = "hunter2";

### تدقيق الأسرار في خط الأساس```bash
$ detect-secrets audit --help
usage: detect-secrets audit [-h] [--diff] [--stats]
                      [--report] [--only-real | --only-false]
                      [--json]
                      filename [filename ...]

Auditing a baseline allows analysts to label results, and optimize plugins for
the highest signal-to-noise ratio for their environment.

positional arguments:
  filename      Audit a given baseline file to distinguish the difference
                between false and true positives.

optional arguments:
  -h, --help    show this help message and exit
  --diff        Allows the comparison of two baseline files, in order to
                effectively distinguish the difference between various plugin
                configurations.
  --stats       Displays the results of an interactive auditing session which
                have been saved to a baseline file.
  --report      Displays a report with the secrets detected

reporting:
  Display a summary with all the findings and the made decisions. To be used with the report mode (--report).

  --only-real   Only includes real secrets in the report
  --only-false  Only includes false positives in the report

analytics:
  Quantify the success of your plugins based on the labelled results in your
  baseline. To be used with the statistics mode (--stats).

  --json        Outputs results in a machine-readable format.

الإعدادات

تعمل هذه الأداة من خلال نظام من الإضافات والمرشحات.

الإضافات تكتشف الأسرار في الكود
المرشحات تتجاهل الإيجابيات الخاطئة لزيادة دقة المسح

يمكنك ضبط كليهما لتناسب احتياجاتك من الدقة والاستدعاء.

الإضافات

هناك ثلاث استراتيجيات مختلفة نستخدمها لمحاولة اكتشاف الأسرار في الكود:

القواعد المستندة إلى التعبيرات العادية

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

يبحث هذا عن السلاسل "التي تبدو كأسرار" عبر مجموعة متنوعة من الأساليب الاستدلالية. هذا رائع للأسرار غير المنظمة، ولكنه قد يتطلب ضبطًا لتعديل دقة المسح.
كاشف الكلمات المفتاحية

يتجاهل هذا قيمة السر، ويبحث عن أسماء المتغيرات التي غالبًا ما ترتبط بتعيين أسرار بقيم مُشفَّرة. هذا رائع للسلاسل "التي لا تبدو كأسرار" (مثل كلمات مرور le3tc0de)، ولكنه قد يتطلب ضبط المرشحات لتعديل دقة المسح.

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

المرشحات

يأتي detect-secrets مع عدة مرشحات مدمجة قد تناسب احتياجاتك.

--exclude-lines

أحيانًا، قد ترغب في القدرة على السماح عالميًا بأسطر معينة في المسح، إذا كانت تطابق نمطًا محددًا. يمكنك تحديد قاعدة تعبير عادي كالتالي:```bash $ detect-secrets scan --exclude-lines 'password = (blah|fake)'

أو يمكنك تحديد قواعد regex متعددة كما يلي:```bash
$ detect-secrets scan --exclude-lines 'password = blah' --exclude-lines 'password = fake'

--exclude-files

في بعض الأحيان، قد ترغب في تجاهل ملفات معينة أثناء المسح الضوئي. يمكنك تحديد نمط تعبير عادي (regex) للقيام بذلك، وإذا تطابق اسم الملف مع هذا النمط، فلن يتم مسحه ضوئيًا:```bash $ detect-secrets scan --exclude-files '.*.signature$'

أو يمكنك تحديد أنماط regex متعددة كما يلي:```bash
$ detect-secrets scan --exclude-files '.*\.signature$' --exclude-files '.*/i18n/.*'

--exclude-secrets

في بعض الأحيان، قد ترغب في تجاهل قيم سرية معينة في الفحص. يمكنك تحديد قاعدة تعبير منتظم على النحو التالي:```bash $ detect-secrets scan --exclude-secrets '(fakesecret|${.*})'

أو يمكنك تحديد قواعد regex متعددة كما يلي:```bash
$ detect-secrets scan --exclude-secrets 'fakesecret' --exclude-secrets '\${.*})'

التصريح المضمّن

أحيانًا، ترغب في تطبيق استثناء على سطر معين، بدلاً من استبعاده عالميًا. يمكنك القيام بذلك من خلال التصريح المضمّن على النحو التالي:```python API_KEY = 'this-will-ordinarily-be-detected-by-a-plugin' # pragma: allowlist secret

هذه التعليقات مدعومة بعدة لغات. مثلاً```java
const GoogleCredentialPassword = "something-secret-here";     //  pragma: allowlist secret

يمكنك أيضًا استخدام:```python

pragma: allowlist nextline secret

API_KEY = 'WillAlsoBeIgnored'

قد تكون هذه طريقة مناسبة لك لتجاهل secrets، دون الحاجة إلى إعادة إنشاء baseline بالكامل مرة أخرى. إذا كنت بحاجة إلى البحث بشكل صريح عن هذه allowlisted secrets، يمكنك أيضًا القيام بـ:```bash
$ detect-secrets scan --only-allowlisted

هل تريد كتابة منطق مخصص إضافي لتصفية النتائج الإيجابية الخاطئة؟ تحقق من كيفية القيام بذلك في وثائق الفلاتر.

الإضافات

قائمة الكلمات

العلامة --exclude-secrets تسمح لك بتحديد قواعد التعبير العادي لاستبعاد القيم السرية. ولكن، إذا كنت تريد تحديد قائمة كبيرة من الكلمات بدلاً من ذلك، يمكنك استخدام العلامة --word-list.

لاستخدام هذه الميزة، تأكد من تثبيت حزمة pyahocorasick، أو استخدم ببساطة:```bash $ pip install detect-secrets[word_list]

ثم، يمكنك استخدامه على النحو التالي:```bash
$ cat wordlist.txt
not-a-real-secret
$ cat sample.ini
password = not-a-real-secret

# Will show results
$ detect-secrets scan sample.ini

# No results found
$ detect-secrets scan --word-list wordlist.txt

كاشف الهراء

كاشف الهراء هو نموذج تعلم آلي بسيط، يحاول تحديد ما إذا كانت القيمة السرية هي في الواقع هراء، بافتراض أن القيم السرية الحقيقية ليست شبيهة بالكلمات.

لاستخدام هذه الميزة، تأكد من تثبيت الحزمة gibberish-detector، أو استخدم:

pip install -r requirements.txt
``````bash
$ pip install detect-secrets[gibberish]

تحقق من حزمة gibberish-detector للحصول على مزيد من المعلومات حول كيفية تدريب النموذج. سيتم تضمين نموذج مدرب مسبقًا (تم تغذيته بمعالجة RFCs) للاستخدام السهل.

يمكنك أيضًا تحديد النموذج الخاص بك على النحو التالي:```bash $ detect-secrets scan --gibberish-model custom.model

هذه ليست إضافة افتراضية، نظرًا لأنها ستتجاهل الأسرار مثل `password`.

## تحذيرات

هذه الأداة ليست حلاً مضمونًا لمنع الأسرار من دخول قاعدة التعليمات البرمجية. فقط توعية المطورين المناسبة يمكنها فعل ذلك حقًا. هذا الخطاف pre-commit يطبق عدة استدلالات لمحاولة منع الحالات الواضحة لالتزام الأسرار.

**الأشياء التي لن يتم منعها:**

- الأسرار متعددة الأسطر
- كلمات المرور الافتراضية التي لا تؤدي إلى تشغيل `KeywordDetector` (على سبيل المثال `login = "hunter2"`)

## الأسئلة الشائعة

### عام

- **تمت مواجهة تحذير "لم يتم الكشف عن مستودع git"، على الرغم من أنني في مستودع git.**

  تحقق مما إذا كان إصدار `git` الخاص بك >= 1.8.5. إذا لم يكن كذلك، فيرجى ترقيته ثم المحاولة مرة أخرى.
  [مزيد من التفاصيل هنا](https://github.com/Yelp/detect-secrets/issues/220).

### ويندوز

- **يعرض `detect-secrets audit` رسالة "ملف أساسي غير صالح!" بعد إنشاء الأساس.**

  تأكد من أن ترميز ملف الأساس الخاص بك هو UTF-8.
  [مزيد من التفاصيل هنا](https://github.com/Yelp/detect-secrets/issues/272#issuecomment-619187136).

detect-secrets

الأكثر شعبية

detect-secrets

عن

أمثلة

بداية سريعة:

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

عرض جميع الإضافات المُمكّنة:```bash

الاستخدام في نصوص بايثون الأخرى

التثبيت```bash

الاستخدام

إضافة الأسرار إلى خط الأساس```

.pre-commit-config.yaml

الإعدادات

الإضافات

المرشحات

--exclude-lines

--exclude-files

--exclude-secrets

التصريح المضمّن

pragma: allowlist nextline secret

الإضافات

قائمة الكلمات

كاشف الهراء