GitHub Action: اختبار الأمان الثابت لواجهات REST API من 42Crunch

يبحث إجراء اختبار الأمان الثابت لواجهات REST API عن عقود REST API التي تتبع مواصفة OpenAPI (OAS، المعروفة سابقًا باسم Swagger) ويجري فحوصات أمان شاملة عليها. يتم دعم كل من OAS v2 و v3.0.x، بتنسيقي JSON و YAML.

يمكنك استخدام هذا الإجراء في السيناريوهات التالية:

• إضافة مهمة اختبار أمان ثابت تلقائي للواجهات البرمجية (SAST) إلى سير عمل CI/CD لديك.
• إجراء هذه الفحوصات عند مراجعات طلبات السحب و/أو عمليات دمج التعليمات البرمجية.
• الإبلاغ عن المشكلات المكتشفة في تنبيهات الأمان / فحص التعليمات البرمجية في GitHub.

يعمل هذا الإجراء بواسطة تدقيق أمان API من 42Crunch. يجري تدقيق الأمان تحليلًا ثابتًا لتعريف API يتضمن أكثر من 300 فحص لأفضل الممارسات والثغرات المحتملة المتعلقة بالمصادقة والتفويض بالإضافة إلى قيود البيانات.

اكتشاف واجهات API في مستودعاتك

بشكل افتراضي، سيقوم هذا الإجراء بما يلي:

1. البحث عن أي ملفات .json و .yaml في المستودع.
2. اختيار الملفات التي تستخدم مخطط OpenAPI.
3. إجراء تدقيق أمان على تعريفات OpenAPI.

بهذه الطريقة، يمكنك تحديد أي عقود API جديدة أو معدّلة في المستودع.

يمكنك ضبط سلوك الإجراء بدقة عبر تحديد أجزاء معينة من المستودع أو أقنعة أسماء الملفات ليتم تضمينها أو استبعادها في اكتشاف واجهات API. يمكنك حتى تعطيل الاكتشاف تمامًا وبدلاً من ذلك سرد ملفات API محددة فقط لفحصها وربطها بواجهات API الموجودة لديك في منصة 42Crunch لأمان API. يمكنك تكوين كل هذه الإعدادات في ملف الإعدادات 42c-conf.yaml. للحصول على أمثلة متقدمة، انظر هنا.

يتم رفع جميع واجهات API المكتشفة إلى مجموعة API في منصة 42Crunch. بشكل افتراضي، يستخدم الإجراء متغيري البيئة GITHUB_REPOSITORY و GITHUB_REF لتسمية المستودع واسم الفرع/الوسم/طلب السحب (PR) الذي نشأت منه مجموعة API. يمكنك تجاوز هذا الاسم باستخدام معلمة الإجراء default-collection-name. خلال عمليات التشغيل اللاحقة، تبقى واجهات API في المجموعة متزامنة مع التغييرات في مستودعك.

استخدام هذا الإجراء لمنع نشر واجهات API المعرضة للخطر

أضف هذا الإجراء إلى سير عمل CI/CD في GitHub واجعله يفشل عند وجود تعريفات API تحتوي على مشكلات أمنية.

يمنح تدقيق الأمان كل عقد API درجة تدقيق من 0 إلى 100 تعكس السطح الأمني لواجهات API لديك. يمكنك استخدام معلمة min-score في إجراء GitHub لتعيين عتبة درجة التدقيق التي يفشل عندها الإجراء (الافتراضي هو 75، إذا لم يتم تحديد قيمة أخرى). يساعد هذا في اكتشاف تعريفات API ذات الجودة الرديئة ومعالجة المشكلات في أقرب وقت ممكن، أي أثناء مرحلة التصميم.

يمكن تعيين شروط فشل أكثر تقدمًا في ملف الإعدادات 42c-conf.yaml، مثل درجة التدقيق حسب الفئة (الأمان أو التحقق من البيانات)، أو مستوى خطورة المشكلات، أو حتى مشكلات محددة يتم تحديدها بواسطة معرف المشكلة الخاص بها. للحصول على أمثلة متقدمة، انظر هنا.

بالإضافة إلى ذلك، تفرض الإضافة بوابات جودة الأمان المعرّفة على مستوى المنصة (الافتراضية أو المدفوعة بالوسوم). تفرض بوابات جودة الأمان متطلبات أمان التطبيقات المحددة داخل المؤسسة.

قراءة التقارير التفصيلية القابلة للتنفيذ

في كل مرة يتم فيها تشغيل الإجراء، يتضمن رابطًا إلى التقرير التفصيلي ذي الأولويات والقابل للتنفيذ لكل ملف من ملفات OpenAPI لديك:

اتبع الروابط لقراءة التقرير التفصيلي في منصة 42Crunch:

رفع تنبيهات 42Crunch إلى فحص التعليمات البرمجية في GitHub

يمكنك أيضًا تتبع المشكلات التي عثر عليها تدقيق 42Crunch مباشرة في GitHub، في علامة التبويب الأمان ضمن تنبيهات فحص التعليمات البرمجية.

لتفعيل ذلك، ما عليك سوى تضمين upload-to-code-scanning:true في معلمات الإجراء في سير عمل GitHub لديك.

انقر على أي من التنبيهات لرؤية موقعه الدقيق في التعليمات البرمجية والحصول على تفاصيل الثغرة وخطوات المعالجة الموصى بها.

البدء

يستخدم هذا الإجراء خدمة تدقيق أمان API من 42Crunch. قبل استخدام الإجراء، ستحتاج إلى امتلاك حساب على منصة 42Crunch. إذا لم تكن عميلًا لدى 42Crunch، يمكنك طلب حساب مجاني من هذه الصفحة: https://42crunch.com/get-started/.

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

معلمات الإجراء

api-token

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

min-score

الحد الأدنى لدرجة التدقيق التي يجب أن تصل إليها ملفات OpenAPI، وإلا يفشل الإجراء. الافتراضي هو 75.

upload-to-code-scanning

رفع نتائج التدقيق إلى فحص التعليمات البرمجية في GitHub. الافتراضي هو false. لاحظ أنه يجب أن يمتلك سير العمل أذونات محددة حتى تنجح هذه الخطوة.

...
jobs:
  run_42c_audit:
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for results upload to Github Code Scanning
...

ignore-failures

إذا تم تعيينه على true، فإنه يُجبر التنفيذ على الاكتمال بنجاح حتى إذا تحققت شروط الفشل (مثل min-score أو معايير SQG) التي قمت بتعيينها. الافتراضي هو false.

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

ignore-network-errors

إذا تم تعيينه على true، فإنه يُجبر التنفيذ على الاكتمال بنجاح حتى في حالة حدوث خطأ في الشبكة (مثل فشل الاتصال بمنصة 42Crunch، وما إلى ذلك). الافتراضي هو false.

skip-local-checks

إذا تم تعيينه على true، فإنه يعطل جميع شروط الفشل (مثل الحد الأدنى للدرجة) المحددة في ملف 42c-conf.yaml ويُفشل التنفيذ فقط إذا لم يتم استيفاء المعايير المحددة في SQGs. الافتراضي هو false.

platform-url

عنوان URL الذي تصل من خلاله إلى منصة 42Crunch. الافتراضي هو https://us.42crunch.cloud.

إذا كنت عميلًا مؤسسيًا، أدخل عنوان URL الذي تستخدمه للوصول إلى منصة الإنتاج الخاصة بك.

root-directory

الدليل الجذر الذي يحتوي على ملف الإعدادات 42c-conf.yaml. إذا لم يتم تحديده، يتم استخدام دليل العمل الحالي للإضافة بدلاً من ذلك، وهو ما يتوافق عادةً مع جذر المستودع المسحوب.

default-collection-name

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

log-level

مستوى التفاصيل في السجلات، أحد القيم التالية: FATAL، ERROR، WARN، INFO، DEBUG. الافتراضي هو INFO.

share-everyone

يشارك تلقائيًا مجموعات API التي أنشأتها مهمة CI/CD مع الجميع في مؤسستك على منصة 42Crunch. القيم المقبولة هي: OFF، READ_ONLY، READ_WRITE. الافتراضي هو OFF. لاحظ أن الهوية التي يعمل الإجراء باسمها (مالك رمز API) يجب أن تمتلك إذن Share with Everyone، وإلا ستفشل المهمة بخطأ 403.

json-report