SEDATED

الغرض

مع العدد الهائل من تغييرات التعليمات البرمجية المطلوبة في بيئة CICD اليوم، يدفع المطورون باستمرار تعليمات برمجية قد تحتوي عن غير قصد على معلومات حساسة. ويمثل هذا الاحتمال لتعرض البيانات الحساسة خطرًا كبيرًا على المؤسسات (2017 OWASP Top Ten #3 - Sensitive Data Exposure). يعالج SEDATED® هذه المشكلة عبر مراجعة جميع تغييرات التعليمات البرمجية الواردة تلقائيًا وتقديم تغذية راجعة فورية للمطور. وإذا حدد بيانات حساسة، فسيمنع دفع الالتزام (الالتزامات) إلى خادم Git.

**ملاحظة: فقط الأسطر المُضافة أو المعدَّلة (التي تبدأ بـ + في ملف التصحيح) في عمليات دفع الالتزامات هي ما يفحصه SEDATED®. أما الأسطر التي تتم إزالتها (التي تبدأ بـ - في ملف التصحيح) في عمليات دفع الالتزامات، لا يفحصها SEDATED®.

الإعداد

1. استنساخ SEDATED® محليًا

git clone https://github.com/OWASP/SEDATED.git

cd SEDATED/

2. تحديث ملفات .example

cp /config/whitelists/commit_whitelist.txt.example /config/whitelists/commit_whitelist.txt

cp /config/whitelists/repo_whitelist.txt.example /config/whitelists/repo_whitelist.txt

cp /config/enforced_repos_list.txt.example /config/enforced_repos_list.txt

3. تخصيص متغيرات ودوال /config/custom_configs.sh (حسب الرغبة)

4. دفع SEDATED® مع تنفيذ خاص بالمؤسسة

ادفع التنفيذ الخاص بمؤسستك من SEDATED® إلى مستودع Git الذي تريده المؤسسة (GitHub أو GitLab أو Git أو غير ذلك...).

5. توجيه خطاف pre-receive إلى ملف pre-receive.sh الخاص بـ SEDATED®

يمكن العثور على إرشادات تنفيذ ذلك على مثيل GitHub Enterprise في GitHub_Enterprise_Setup.md.

الاختبار المحلي

• إعداد GitHub Docker - إرشادات عامة لإعداد حاوية GitHub docker لتعمل كخادم Git مع تمكين خطاف pre-receive لأغراض الاختبار المحلي.
  • سيلزم إجراء بعض التعديلات للسماح لـ SEDATED® بالعمل كما هو مصمم.
    • يجب استبدال always_reject.sh بنص pre-receive.sh البرمجي الخاص بـ SEDATED®.
    • يجب تضمين بنية الملفات/المجلدات المصاحبة لـ SEDATED® في نفس الدليل/أن تكون متاحة لنص pre-receive.sh البرمجي.
    • قد تكون هناك حاجة أيضًا إلى بعض التعديلات الإضافية، لكن الإرشادات المرتبطة أعلاه تُعد نقطة انطلاق جيدة للاختبار المحلي.

وصف الملفات

pre-receive.sh

• القلب والروح النابضة لـ SEDATED®.
• نص خطاف Git pre-receive الخاص بـ SEDATED®، والمستخدم بالاقتران مع التعبيرات النمطية الخاصة بـ SEDATED® (config/regexes.json)، يحدد أسطر التعليمات البرمجية المُضافة أو المعدَّلة التي تُدفع إلى مثيل Git والتي تحتوي على بيانات اعتماد/بيانات حساسة مُرمَّزة (كما هو محدد في config/regexes.json) ويمنع الدفع إذا تم العثور على أسطر تحتوي على بيانات اعتماد/بيانات حساسة مُرمَّزة.

/config/custom_configs.sh

• ملف الإعدادات المخصصة الخاص بـ SEDATED®، والمستخدم بالاقتران مع pre-receive.sh، يتيح للمؤسسات تخصيص تنفيذها لـ SEDATED® دون الحاجة إلى تعديل أي من الكود المصدري داخل ملف pre-receive.sh الخاص بـ SEDATED®، وذلك من خلال توفير متغيرات ودوال مخصصة مدمجة يتم استيرادها من pre-receive.sh.

/config/enforced_repos_list.txt

• يُستخدم عندما تكون علامة use_enforced_repo_check_custom الخاصة بـ SEDATED® (خطاف pre-receive) في config/custom_configs.sh مضبوطة على "True".
• يتيح "تمكين" SEDATED® عالميًا داخل المؤسسة، مع "فرضه" بشكل انتقائي فقط على المستودعات المدرجة في هذا الملف.
• يمكن فرض التطبيق على جميع المستودعات التابعة لمؤسسة أو اسم مستخدم معينين بإلحاق /* بنهاية المؤسسة أو اسم المستخدم المطلوب فرض التطبيق عليه.
• إذا كان SEDATED® مفعلاً عالميًا داخل مؤسسة ولم يظهر المستودع في ملف /config/enforced_repos_list.txt، فسيرى المستخدم الذي يقوم بالدفع (إذا كان يدفع من سطر الأوامر) رسالة قابلة للتخصيص (يمكن تخصيصها عبر ملف /config/custom_configs.sh) ولن يفحص SEDATED® أيًا من التعليمات البرمجية المضمنة في الدفع.
• يمكن العثور على علامة تمكين/تعطيل هذه الوظيفة في /config/custom_configs.sh وضبطها على "True" أو "False".
  • "False" - كل مستودع لديه SEDATED® "مفعلاً" سيكون SEDATED® "مفروضًا" عليه أيضًا.
  • "True" - فقط المستودعات التي لديها SEDATED® "مفعلاً" والمدرجة أيضًا في /config/enforced_repos_list.txt سيكون SEDATED® "مفروضًا" عليها. أما جميع المستودعات الأخرى التي لديها SEDATED® "مفعلاً" ولكنها غير مدرجة في ملف /config/enforced_repos_list.txt فستشاهد رسالة مخصصة معروضة فقط، ولن يتم فحص أي تعليمات برمجية لعمليات الدفع من تلك المستودعات.
• يمكن أن يكون هذا الملف فارغًا، وهو مطلوب للوجود فقط إذا كانت علامة use_enforced_repo_check_custom في config/custom_configs.sh مضبوطة على "True".

/config/regexes.json

• يحتوي على التعبيرات النمطية (regexes) المستخدمة لتحديد البيانات الحساسة/بيانات الاعتماد المُرمَّزة.
• تستهلك GNU grep هذه التعبيرات النمطية (في pre-receive.sh) مع علامة -P مما يجعلها تعبيرات نمطية متوافقة مع Perl (PCREs).
• يمكن إضافة التعبيرات النمطية أو إزالتها من هذا الملف حسب الحاجة، ومع ذلك، إذا كنت تستخدم نص /testing/regex_testing/regex_test_script.sh البرمجي، فسيلزم تحديث ملف /testing/regex_testing/test_cases.txt بإضافة أو إزالة حالات الاختبار المتعلقة بالتعبيرات النمطية المحدثة حتى تكون النتائج من /testing/regex_testing/regex_test_script.sh دقيقة.
• إذا كنت تضيف/تعدل تعبيرات نمطية في هذا الملف، فقد تحتاج إلى أحرف هروب إضافية \ اعتمادًا على التعبيرات النمطية المطلوبة، لأن هذا الملف بتنسيق JSON.

/config/whitelists/commit_whitelist.txt

• يُستخدم في حالة النتيجة الإيجابية الكاذبة، حيث يمكن استبعاد التزام واحد أو أكثر من عملية الفحص إذا كانت معرّفات الالتزامات الخاصة بها مدرجة في هذا الملف.
• يجب فصل معرّفات الالتزامات في هذا الملف بفواصل أسطر جديدة (carriage return) كما هو موضح في ملف /config/whitelists/commit_whitelist.txt.example.
• يمكن أن يكون هذا الملف فارغًا، لكن يجب أن يكون موجودًا.

اختياري: اطلب من المطورين تقديم طلبات سحب (pull requests) إلى هذا الملف (commit_whitelist.txt) عندما يواجهون نتائج إيجابية كاذبة حتى يمكن مراجعتها.

/config/whitelists/repo_whitelist.txt

• المستودعات بصيغة (organization/username)/repository المدرجة في هذا الملف ستُستبعد كليًا من الفحص عن البيانات الحساسة/بيانات الاعتماد المُرمَّزة حتى تتم إزالتها من هذه القائمة.
• يُستخدم في حالة الدفع الضخم (ترحيل مستودع على سبيل المثال) حيث لا يستطيع SEDATED® فحص التعليمات البرمجية الجديدة/المعدَّلة المضمنة في الدفع خلال نافذة الخمس ثوانٍ (نافذة الخمس ثوانٍ خاصة بـ GitHub وقد تكون مختلفة على مثيلات Git الأخرى).
• يجب فصل أسماء (organization/username)/repository في هذا الملف بفواصل أسطر جديدة (carriage return) كما هو موضح في ملف /config/whitelists/repo_whitelist.txt.example.
• يمكن أن يكون هذا الملف فارغًا، لكن يجب أن يكون موجودًا.

/testing/regex_testing/regex_test_script.sh

• نص اختبار التعبيرات النمطية الخاص بـ SEDATED®، والمستخدم بالاقتران مع testing/regex_testing/test_cases.txt، هو طريقة بسيطة وسريعة وبدون اتصال لاختبار/التحقق من أن التعبيرات النمطية داخل config/regexes.json صالحة وتطابق الأنماط المطلوبة، بالإضافة إلى استبعاد/عدم مطابقة ما هو مطلوب.
  • يختبر التعبيرات النمطية مقابل قائمة من حالات الاختبار (/testing/regex_testing/test_cases.txt) للتحقق من أن التعبيرات النمطية تعمل كما هو متوقع.
  • يشمل اختبار حالات الاختبار الإيجابية والسلبية معًا (/testing/regex_testing/test_cases.txt).
  • يجب استخدام GNU grep عند تشغيل النص البرمجي وإلا سيفشل النص (لا يمتلك BSD grep علامة -P).
  • حالات الاختبار المستخدمة في هذا النص البرمجي يتم جلبها من /testing/regex_testing/test_cases.txt.

/testing/regex_testing/test_cases.txt

• قائمة بحالات الاختبار التي سيتم تمريرها إلى /testing/regex_testing/regex_test_script.sh لاستهلاكها.
• كل حالة اختبار يلحق بها >>pass أو >>fail، وهذان يُعلمان نص /testing/regex_testing/regex_test_script.sh البرمجي بالتوقع المنشود من التعبيرات النمطية.
  • >>pass تعني أن دفعًا يحتوي على السلسلة السابقة سيتم قبوله بواسطة SEDATED® (أي أن التعبيرات النمطية لن تُحدد السلسلة السابقة).
  • >>fail تعني أن دفعًا يحتوي على السلسلة السابقة سيتم رفضه بواسطة SEDATED® (أي أن التعبيرات النمطية ستُحدد السلسلة السابقة).

التخصيص

صُممت المتغيرات والدوال المخصصة للسماح للمؤسسات بتخصيص تنفيذها الخاص لـ SEDATED® بسهولة دون تغيير ملف خطاف pre-receive الرئيسي الذي يقوم بكل العمل الشاق. يمكن العثور على جميع المتغيرات والدوال المخصصة في /config/custom_configs.sh، وفيما يلي شروح المتغيرات الواردة في هذا الملف.

المتغيرات المخصصة

• show_SEDATED_link_custom - "True" لعرض رابط مستودع OWASP/SEDATED على GitHub (حساس لحالة الأحرف)، وإلا فاضبطه على "False".
• documentation_link_custom - أضف رابطًا إلى الوثائق الخاصة بالمؤسسة حول كيفية رغبة المؤسسة في تعامل المطورين مع عمليات الدفع المرفوضة و/أو المعلومات العامة الخاصة بالمؤسسة فيما يتعلق بـ SEDATED®.
  • يُعرض للمطور عند رفض عملية الدفع.
  • يُعرض للمطور عندما يكون فحص المستودعات المفروض مضبوطًا على true ولم يكن المستودع مدرجًا في ملف enforced_repos_list.txt.
• use_enforced_repo_check_custom - "True" أو "False" (حساس لحالة الأحرف).
  • راجع وصف الملف أعلاه الخاص بـ /config/enforced_repos_list.txt لمزيد من التفاصيل حول معنى هذه العلامة.
• enforced_repo_check_true_message_custom مع رسالة مخصصة (ضروري فقط إذا كانت use_enforced_repo_check_custom مضبوطة على "True").
• obfuscate_output_custom - "True" أو "False" (حساس لحالة الأحرف). استخدم هذا الخيار لإخفاء البيانات الحساسة المعروضة في مخرجات SEDATED®.

الدوال المخصصة

• SET_USER_REPO_NAME_CUSTOM
  • يضبط اسم المستخدم/المؤسسة/المجموعة واسم المستودع.
  • يضبط اسم المستخدم/المؤسسة/المجموعة واسم المستودع باستخدام متغير GITHUB_REPO_NAME إذا كنت تستخدم GitHub.
  • إذا لم تكن تستخدم GitHub، يمكن ضبط متغيرات مخصصة للحصول على هذه الأسماء.
  • الأسماء غير الخاصة بـ GitHub المقدمة مضبوطة للحصول على الأسماء في Git الخام (vanilla Git) فقط، ولكن قد تحتاج إلى تعديل بناءً على التنفيذات المختلفة (أنظمة Git SCM).
• PRINT_ERROR_MESSAGE_CUSTOM
  • يتيح طباعة رسالة خطأ مخصصة عند مواجهة الأخطاء.
• EXIT_SEDATED_CUSTOM
  • اتخذ إجراءً مخصصًا إضافيًا عند الخروج من SEDATED® (مثل التسجيل، إرسال المقاييس، وما إلى ذلك...).
  • الافتراضي هو : "عدم القيام بأي شيء" كإجراء إضافي، وليس من الضروري تغييره.
• UNABLE_TO_ACCESS_REPO_WHITELIST_CUSTOM
  • اتخذ إجراءً مخصصًا إضافيًا عندما يتعذر على SEDATED® الوصول إلى ملف القائمة البيضاء للمستودعات (مثل طباعة رسالة خطأ، التسجيل، إرسال مقياس، وما إلى ذلك...).
  • الافتراضي هو : "عدم القيام بأي شيء" كإجراء إضافي، وليس من الضروري تغييره.
• PUSH_ACCEPTED_CUSTOM
  • اتخذ إجراءً مخصصًا إضافيًا عند قبول عملية دفع (مثل التسجيل، إرسال المقاييس، وما إلى ذلك...).
  • الافتراضي هو : "عدم القيام بأي شيء" كإجراء إضافي، وليس من الضروري تغييره.
• UNABLE_TO_ACCESS_REGEXES_CUSTOM
  • اتخذ إجراءً مخصصًا إضافيًا عندما يتعذر على SEDATED® الوصول إلى ملف regexes.json.
  • الافتراضي هو : "عدم القيام بأي شيء" كإجراء إضافي، وليس من الضروري تغييره.
  • سينفذ SEDATED® exit 1 ويطبع رسالة خطأ إذا تعذر الوصول إلى التعبيرات النمطية، ومع ذلك يمكن تنفيذ إجراء مخصص إضافي في هذه الحالات إذا رغبت (مثل طباعة رسالة خطأ إضافية، التسجيل، إرسال مقياس، وما إلى ذلك...).
• PUSH_REJECTED_WITH_VIOLATIONS_CUSTOM
  • اتخذ إجراءً مخصصًا إضافيًا عندما تُرفض عمليات الدفع لاحتوائها على مخالفات (مثل التسجيل، إرسال المقاييس، وما إلى ذلك...).
  • الافتراضي هو : "عدم القيام بأي شيء" كإجراء إضافي، وليس من الضروري تغييره.
• UNABLE_TO_ACCESS_COMMIT_WHITELIST_CUSTOM
  • اتخذ إجراءً مخصصًا إضافيًا عندما يتعذر على SEDATED® الوصول إلى ملف القائمة البيضاء للالتزامات (مثل التسجيل، إرسال المقاييس، وما إلى ذلك...).
  • الافتراضي هو : "عدم القيام بأي شيء" كإجراء إضافي، وليس من الضروري تغييره.

التوافق

متوافق فقط مع أدوات إدارة المصدر (SCM) التي تستخدم نظام التحكم في الإصدارات Git.

• GitHub
  • تم اختباره بالكامل (Enterprise v2.15.3).
  • إعداد SEDATED® لـ GitHub Enterprise.
• GitLab
  • تم اختباره مبدئيًا.
  • ستكون التعديلات على SET_USER_REPO_NAME_CUSTOM مطلوبة لضبط المستخدم/المؤسسة واسم المستودع.
• Git
  • تم اختباره مبدئيًا.
  • يجب وضع جميع ملفات/مجلدات SEDATED® في دليل .git/hooks/ (باستثناء مجلد/ملفات الوثائق).
  • أزل .sample من pre-receive.sample وانسخ الكود من ملف pre-receive.sh الخاص بـ SEDATED® إلى ملف pre-receive الذي أنشأناه للتو من ملف .sample.
  • اعتمادًا على التنفيذ، قد ترغب في استخدام git-template أو شيء مشابه.
• أي أداة Git SCM أخرى
  • غير مختبر.
  • من المرجح أن تكون التعديلات على SET_USER_REPO_NAME_CUSTOM مطلوبة لضبط المستخدم/المؤسسة واسم المستودع.
  • قد يتطلب تعديلات إضافية ليعمل.

المساهمة

المساهمات في هذا المشروع مرحّب بها!

يمكنك المساهمة بإحدى الطريقتين التاليتين:

• قدّم أفكارك للتحسين إلينا (أو إلى أي شخص في المجتمع قد يرغب في قبول تحدّي تحويل فكرتك إلى واقع داخل قاعدة الكود الخاصة بـ SEDATED®)؛ يرجى فتح issue مع شرح جيد لما تعتقد أنه يمكن أن يحسّن SEDATED® وكيف تعتقد أن ذلك يمكن أن يحدث عمليًا داخل قاعدة الكود.
• قدّم طلب سحب (pull request) مع تغييراتك البرمجية لجعل SEDATED® أفضل وسنقوم بالمراجعة والاختبار والدمج. :)

المؤلفون

• Dennis Kennedy
• Simeon Cloutier

الترخيص

SEDATED® مرخّص بموجب BSD 3-Clause "New" or "Revised" License.

**SEDATED® غير مضمون لتحديد كل حالة من حالات بيانات الاعتماد أو المفاتيح أو الأسرار المُرمَّزة، وما إلى ذلك... فهو يستخدم مطابقة الأنماط بالتعبيرات النمطية، ومع أنه أصبح جيدًا جدًا في التقاط معظم الحالات، إلا أنه ليس مثاليًا، لكننا دائمًا منفتحون على الأفكار و/أو طلبات السحب للمساعدة في جعل SEDATED® أفضل.