detect secrets
v1.5.0
detect-secrets عبارة عن وحدة نمطية مسماة بشكل مناسب لكشف الأسرار (المفاجأة، المفاجأة) داخل قاعدة التعليمات البرمجية.
ومع ذلك، على عكس الحزم المماثلة الأخرى التي تركز فقط على العثور على الأسرار، فقد تم تصميم هذه الحزمة مع وضع عميل المؤسسة في الاعتبار: توفير وسيلة منهجية ومتوافقة مع الإصدارات السابقة من أجل:
منع الأسرار الجديدة من الدخول إلى قاعدة التعليمات البرمجية،
اكتشاف ما إذا تم تجاوز هذه الموانع بشكل صريح، و
توفير قائمة مرجعية بالأسرار التي يجب تدوينها والانتقال إلى مساحة تخزين أكثر أمانًا.
بهذه الطريقة، يمكنك إنشاء فصل بين الاهتمامات: قبول أنه قد تكون هناك حاليًا أسرار مختبئة في مستودعك الكبير (وهذا ما نشير إليه بخط الأساس )، ولكن منع هذه المشكلة من التفاقم، دون التعامل مع الجهد الهائل المحتمل لنقل الأسرار الموجودة بعيدا.
يقوم بذلك عن طريق تشغيل مخرجات فرق دورية مقابل عبارات التعبير العادي المصممة بشكل إرشادي، لتحديد ما إذا كان قد تم ارتكاب أي سر جديد . وبهذه الطريقة، يتم تجنب عبء البحث في سجل git بأكمله، بالإضافة إلى الحاجة إلى فحص المستودع بأكمله في كل مرة.
لإلقاء نظرة على التغييرات الأخيرة، يرجى مراجعة CHANGELOG.md.
إذا كنت تتطلع إلى المساهمة، يرجى الاطلاع على CONTRIBUTING.md.
لمزيد من الوثائق التفصيلية، راجع وثائقنا الأخرى.
أنشئ خطًا أساسيًا للأسرار المحتملة الموجودة حاليًا في مستودع git الخاص بك.
$ كشف الأسرار المسح > .secrets.baseline
أو لتشغيله من دليل مختلف:
$ كشف الأسرار -C /path/to/directory scan> /path/to/directory/.secrets.baseline
فحص الملفات المتعقبة غير التابعة لـ git:
$ كشف الأسرار مسح test_data/ --all-files> .secrets.baseline
سيؤدي هذا إلى إعادة فحص قاعدة التعليمات البرمجية الخاصة بك، و:
قم بتحديث/ترقية خط الأساس الخاص بك ليكون متوافقًا مع الإصدار الأحدث،
أضف أي أسرار جديدة تجدها إلى خط الأساس الخاص بك،
قم بإزالة أي أسرار لم تعد موجودة في قاعدة التعليمات البرمجية الخاصة بك
سيؤدي هذا أيضًا إلى الحفاظ على أي أسرار مصنفة لديك.
$ كشف الأسرار المسح الضوئي --baseline .secrets.baseline
بالنسبة للخطوط الأساسية الأقدم من الإصدار 0.9، ما عليك سوى إعادة إنشائها.
فحص الملفات المرحلية فقط:
$ git diff --staged --name-only -z | xargs -0 خطاف كشف الأسرار --baseline .secrets.baseline
فحص جميع الملفات المتعقبة:
$ git ls-files -z | xargs -0 خطاف كشف الأسرار --baseline .secrets.baseline
$ كشف الأسرار - قائمة جميع الإضافات 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
$ كشف الأسرار - تعطيل البرنامج المساعد KeywordDetector - تعطيل البرنامج المساعد AWSKeyDetector
إذا كنت تريد تشغيل مكون إضافي محدد فقط ، فيمكنك القيام بما يلي:
$ كشف الأسرار - قائمة جميع الإضافات |
grep -v 'BasicAuthDetector' |
sed "s#^#--disable-plugin #g" |
xargs يكشف عن أسرار المسح test_dataهذه خطوة اختيارية لتسمية النتائج في خط الأساس الخاص بك. ويمكن استخدامه لتضييق نطاق قائمة الأسرار التي تريد ترحيلها، أو لتكوين مكوناتك الإضافية بشكل أفضل لتحسين نسبة الإشارة إلى الضوضاء.
$ كشف الأسرار التدقيق .secrets.baseline
الاستخدام الأساسي:
من كشف_الأسرار استيراد SecretsCollectionمن كشف_secrets.settings import default_settingssecrets = SecretsCollection()with default_settings():secrets.scan_file('test_data/config.ini')import jsonprint(json.dumps(secrets.json(), indent=2))المزيد من التكوين المتقدم:
من Detect_secrets import SecretsCollectionfrom Detect_secrets.settings import transient_settingssecrets = SecretsCollection() with transient_settings({# تشغيل عمليات الفحص فقط مع هذه المكونات الإضافية فقط.# هذا التنسيق هو نفس التنسيق الذي تم حفظه في خط الأساس الذي تم إنشاؤه.'plugins_used': [# مثال لتكوين مكون إضافي مضمن {'name': "Base64HighEntropyString"، "الحد": 5.0،
},# مثال على استخدام مكون إضافي مخصص{'name': 'HippoDetector','path': 'file:///Users/aaronloo/Documents/github/detect-secrets/testing/plugins.py',
},
],# يمكننا أيضًا تحديد المرشحات الإضافية التي نريدها.# هذا مثال على استخدام الوظيفة `is_identified_by_ML_model` داخل الملف المحلي # `./private-filters/example.py`.'filters_used': [
{'المسار': 'ملف://private-filters/example.py::is_identified_by_ML_model'،
},
]
}) كإعدادات:# إذا أردنا إجراء أي تعديلات إضافية على كائن الإعدادات الذي تم إنشاؤه (على سبيل المثال# تعطيل المرشحات الافتراضية)، فيمكننا القيام بذلك على النحو التالي: 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')$ نقطة تثبيت كشف الأسرار ؟
التثبيت عبر الشراب:
$ تثبيت المشروب وكشف الأسرار
يأتي 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
نوصي بإعداد هذا كخطاف ما قبل الالتزام. إحدى الطرق للقيام بذلك هي استخدام إطار الالتزام المسبق:
# .ما قبل الالتزام-config.yamlrepos:
- الريبو: https://github.com/Yelp/detect-secretsrev: v1.5.0hooks:
- المعرف: كشف الأسرار: ['--baseline'، '.secrets.baseline'] استبعاد: package.lock.jsonهناك أوقات نريد فيها استبعاد نتيجة إيجابية خاطئة من حظر الالتزام، دون إنشاء خط أساس للقيام بذلك. يمكنك القيام بذلك عن طريق إضافة تعليق على هذا النحو:
Secret = "hunter2" # pragma: سر القائمة المسموح بها
أو
// pragma: القائمة المسموح بها للسطر التالي Secretconst Secret = "hunter2";
تدقيق الكشف عن الأسرار $ --help
الاستخدام: تدقيق كشف الأسرار [-h] [--diff] [--stats]
[--تقرير] [--حقيقي فقط | --فقط-خطأ]
[--json]
اسم الملف [اسم الملف ...]
يسمح تدقيق خط الأساس للمحللين بتسمية النتائج وتحسين المكونات الإضافية للحصول على أعلى نسبة إشارة إلى ضوضاء لبيئتهم.
الحجج الموضعية:
filename قم بتدقيق ملف أساسي محدد لتمييز الفرق
بين الإيجابية الكاذبة والحقيقية.
الحجج الاختيارية:
-h, --help في إظهار رسالة المساعدة هذه والخروج
--diff يسمح بمقارنة ملفين أساسيين
التمييز بشكل فعال الفرق بين البرنامج المساعد المختلفة
التكوينات.
--stats يعرض نتائج جلسة التدقيق التفاعلية التي
تم حفظها في ملف أساسي.
--report يعرض تقريرًا بالأسرار المكتشفة
التقارير:
عرض ملخص بجميع النتائج والقرارات المتخذة. ليتم استخدامه مع وضع التقرير (--التقرير).
--only-real يتضمن فقط الأسرار الحقيقية في التقرير
--only-false يتضمن فقط النتائج الإيجابية الخاطئة في التقرير
التحليلات:
قم بقياس مدى نجاح المكونات الإضافية الخاصة بك بناءً على النتائج المصنفة في ملفك
خط الأساس. لاستخدامها مع وضع الإحصائيات (--الإحصائيات).
- تنتج مخرجات json تنسيقًا يمكن قراءته آليًا.تعمل هذه الأداة من خلال نظام من المكونات الإضافية والمرشحات .
تجد المكونات الإضافية أسرارًا في الكود
تتجاهل المرشحات النتائج الإيجابية الخاطئة لزيادة دقة المسح
يمكنك ضبط كليهما ليناسب احتياجاتك في الدقة/الاستدعاء.
هناك ثلاث إستراتيجيات مختلفة نستخدمها لمحاولة العثور على أسرار في الكود:
القواعد المستندة إلى Regex
هذه هي الأنواع الأكثر شيوعًا من المكونات الإضافية، وتعمل بشكل جيد مع الأسرار جيدة التنظيم. ويمكن التحقق من هذه الأسرار بشكل اختياري، مما يزيد من دقة المسح. ومع ذلك، فإن الاعتماد على هذه العناصر فقط قد يؤثر سلبًا على استدعاء الفحص الخاص بك.
كاشف الانتروبيا
يبحث هذا عن سلاسل "ذات مظهر سري" من خلال مجموعة متنوعة من الأساليب الإرشادية. يعد هذا أمرًا رائعًا بالنسبة للأسرار غير المنظمة، ولكنه قد يتطلب ضبطًا لضبط دقة المسح.
كاشف الكلمات الرئيسية
يؤدي هذا إلى تجاهل القيمة السرية، والبحث عن أسماء المتغيرات التي ترتبط غالبًا بتعيين أسرار ذات قيم مشفرة. يعد هذا أمرًا رائعًا بالنسبة للسلاسل "غير السرية المظهر" (مثل كلمات مرور le3tc0de)، ولكنه قد يتطلب ضبط المرشحات لضبط دقة المسح.
هل تريد العثور على سر لا نكتشفه حاليًا؟ يمكنك أيضًا (بسهولة) تطوير المكون الإضافي الخاص بك واستخدامه مع المحرك! لمزيد من المعلومات، راجع وثائق البرنامج المساعد.
يأتي detect-secrets مع العديد من المرشحات المضمنة المختلفة التي قد تناسب احتياجاتك.
في بعض الأحيان، تريد أن تكون قادرًا على السماح لخطوط معينة عالميًا في المسح الضوئي الخاص بك، إذا كانت تتطابق مع نمط معين. يمكنك تحديد قاعدة regex على هذا النحو:
$ كشف الأسرار - استبعاد الأسطر 'كلمة المرور = (بلاه|وهمية)'
أو يمكنك تحديد قواعد regex متعددة على هذا النحو:
$ كشف الأسرار المسح الضوئي - استبعاد الخطوط "كلمة المرور = بلاه" - استبعاد الخطوط "كلمة المرور = وهمية"
في بعض الأحيان، تريد أن تكون قادرًا على تجاهل ملفات معينة في الفحص الخاص بك. يمكنك تحديد نمط regex للقيام بذلك، وإذا كان اسم الملف يتوافق مع نمط regex هذا، فلن يتم فحصه:
$ كشف الأسرار - استبعاد الملفات '.*.signature$'
أو يمكنك تحديد أنماط regex متعددة على هذا النحو:
$ فحص كشف الأسرار --exclude-files '.*.signature$' --exclude-files '.*/i18n/.*'
في بعض الأحيان، تريد أن تكون قادرًا على تجاهل بعض القيم السرية في الفحص الخاص بك. يمكنك تحديد قاعدة regex على هذا النحو:
$ فحص كشف الأسرار -- استبعاد الأسرار '(fakesecret|${.*})'أو يمكنك تحديد قواعد regex متعددة على هذا النحو:
$ فحص كشف الأسرار -- استبعاد الأسرار 'fakesecret' -- استبعاد الأسرار '${.*})'في بعض الأحيان، تريد تطبيق الاستثناء على سطر معين، بدلاً من استبعاده عالميًا. يمكنك القيام بذلك باستخدام القائمة المسموح بها المضمنة على هذا النحو:
API_KEY = 'سيتم اكتشاف هذا بشكل عادي بواسطة مكون إضافي' # pragma: سر القائمة المسموح بها
هذه التعليقات مدعومة بلغات متعددة. على سبيل المثال
const GoogleCredentialPassword = "شيء سري هنا"; // براغما: سر القائمة المسموح بها
يمكنك أيضًا استخدام:
# pragma: القائمة المسموح بها للسطر التالي SecretAPI_KEY = 'WillAlsoBeIgnored'
قد تكون هذه طريقة مناسبة لك لتجاهل الأسرار، دون الحاجة إلى إعادة إنشاء خط الأساس بالكامل مرة أخرى. إذا كنت بحاجة إلى البحث بشكل صريح عن هذه الأسرار المُدرجة في القائمة المسموح بها، يمكنك أيضًا إجراء ما يلي:
$ كشف الأسرار - القائمة المسموح بها فقط
هل تريد كتابة المزيد من المنطق المخصص لتصفية النتائج الإيجابية الخاطئة؟ تحقق من كيفية القيام بذلك في وثائق المرشحات الخاصة بنا.
تتيح لك علامة --exclude-secrets تحديد قواعد التعبير العادي لاستبعاد القيم السرية. ومع ذلك، إذا كنت تريد تحديد قائمة كبيرة من الكلمات بدلاً من ذلك، فيمكنك استخدام علامة --word-list .
لاستخدام هذه الميزة، تأكد من تثبيت حزمة pyahocorasick ، أو ببساطة استخدم:
تثبيت النقطة $ وكشف الأسرار[word_list]
وبعد ذلك، يمكنك استخدامه على هذا النحو:
$ cat wordlist.txt ليس سرا حقيقيا $ cat Sample.ini كلمة المرور = not-a-real-secret# سوف تظهر النتائج$ Detect-secrets scan Sample.ini# لم يتم العثور على نتائج$ Detect-secrets scan --word-list wordlist.txt
كاشف الثرثرة هو نموذج بسيط لتعلم الآلة، يحاول تحديد ما إذا كانت القيمة السرية هي في الواقع هراء، مع افتراض أن القيم السرية الحقيقية ليست مثل الكلمات.
لاستخدام هذه الميزة، تأكد من تثبيت حزمة gibberish-detector ، أو استخدم:
تثبيت النقطة $ وكشف الأسرار[رطانة]
تحقق من حزمة كاشف الهراء لمزيد من المعلومات حول كيفية تدريب النموذج. سيتم تضمين نموذج تم تدريبه مسبقًا (تم إنشاؤه عن طريق معالجة طلبات RFC) لسهولة الاستخدام.
يمكنك أيضًا تحديد النموذج الخاص بك على هذا النحو:
$ كشف الأسرار المسح الضوئي --نموذج رطانة custom.model
هذا ليس مكونًا إضافيًا افتراضيًا، نظرًا لأنه سيتجاهل الأسرار مثل password .
ليس المقصود من هذا أن يكون حلاً مؤكدًا لمنع الأسرار من دخول قاعدة التعليمات البرمجية. فقط التعليم المناسب للمطورين يمكنه فعل ذلك حقًا. ينفذ خطاف ما قبل الالتزام هذا العديد من الاستدلالات لمحاولة منع الحالات الواضحة لارتكاب الأسرار.
الأشياء التي لا يمكن منعها:
أسرار متعددة الخطوط
كلمات المرور الافتراضية التي لا تؤدي إلى تشغيل KeywordDetector (على سبيل المثال login = "hunter2" )
"لم يتم اكتشاف مستودع git." تمت مواجهة تحذير، على الرغم من أنني في git repo.
تحقق لمعرفة ما إذا كان إصدار git الخاص بك هو >= 1.8.5. إذا لم يكن الأمر كذلك، يرجى ترقيته ثم حاول مرة أخرى. مزيد من التفاصيل هنا.
يعرض detect-secrets audit "ليس ملفًا أساسيًا صالحًا!" بعد إنشاء خط الأساس.
تأكد من أن ترميز الملف الأساسي الخاص بك هو UTF-8. مزيد من التفاصيل هنا.
