42crunch/api-security-audit-actionيؤتمت التدقيق الأمني الثابت لعقود OpenAPI في بيئات CI/CD، عبر تنفيذ أكثر من 300 فحص للمصادقة والتفويض وقيود البيانات، مع بوابات حد أدنى للدرجات ومخرجات بصيغة SARIF.
يبحث إجراء اختبار الأمان الثابت لواجهات REST API عن عقود REST API التي تتبع مواصفة OpenAPI (OAS، المعروفة سابقًا باسم Swagger) ويجري فحوصات أمان شاملة عليها. يتم دعم كل من OAS v2 و v3.0.x، بتنسيقي JSON و YAML.
يمكنك استخدام هذا الإجراء في السيناريوهات التالية:
يعمل هذا الإجراء بواسطة تدقيق أمان API من 42Crunch. يجري تدقيق الأمان تحليلًا ثابتًا لتعريف API يتضمن أكثر من 300 فحص لأفضل الممارسات والثغرات المحتملة المتعلقة بالمصادقة والتفويض بالإضافة إلى قيود البيانات.
بشكل افتراضي، سيقوم هذا الإجراء بما يلي:
.json و .yaml في المستودع.بهذه الطريقة، يمكنك تحديد أي عقود API جديدة أو معدّلة في المستودع.
يمكنك ضبط سلوك الإجراء بدقة عبر تحديد أجزاء معينة من المستودع أو أقنعة أسماء الملفات ليتم تضمينها أو استبعادها في اكتشاف واجهات API. يمكنك حتى تعطيل الاكتشاف تمامًا وبدلاً من ذلك سرد ملفات API محددة فقط لفحصها وربطها بواجهات API الموجودة لديك في منصة 42Crunch لأمان API. يمكنك تكوين كل هذه الإعدادات في ملف الإعدادات 42c-conf.yaml. للحصول على أمثلة متقدمة، انظر هنا.
يتم رفع جميع واجهات API المكتشفة إلى مجموعة API في منصة 42Crunch. بشكل افتراضي، يستخدم الإجراء متغيري البيئة GITHUB_REPOSITORY و GITHUB_REF لتسمية المستودع واسم الفرع/الوسم/طلب السحب (PR) الذي نشأت منه مجموعة API. يمكنك تجاوز هذا الاسم باستخدام معلمة الإجراء default-collection-name. خلال عمليات التشغيل اللاحقة، تبقى واجهات API في المجموعة متزامنة مع التغييرات في مستودعك.
أضف هذا الإجراء إلى سير عمل CI/CD في GitHub واجعله يفشل عند وجود تعريفات API تحتوي على مشكلات أمنية.
يمنح تدقيق الأمان كل عقد API درجة تدقيق من 0 إلى 100 تعكس السطح الأمني لواجهات API لديك. يمكنك استخدام معلمة min-score في إجراء GitHub لتعيين عتبة درجة التدقيق التي يفشل عندها الإجراء (الافتراضي هو 75، إذا لم يتم تحديد قيمة أخرى). يساعد هذا في اكتشاف تعريفات API ذات الجودة الرديئة ومعالجة المشكلات في أقرب وقت ممكن، أي أثناء مرحلة التصميم.
يمكن تعيين شروط فشل أكثر تقدمًا في ملف الإعدادات 42c-conf.yaml، مثل درجة التدقيق حسب الفئة (الأمان أو التحقق من البيانات)، أو مستوى خطورة المشكلات، أو حتى مشكلات محددة يتم تحديدها بواسطة معرف المشكلة الخاص بها. للحصول على أمثلة متقدمة، انظر هنا.
بالإضافة إلى ذلك، تفرض الإضافة بوابات جودة الأمان المعرّفة على مستوى المنصة (الافتراضية أو المدفوعة بالوسوم). تفرض بوابات جودة الأمان متطلبات أمان التطبيقات المحددة داخل المؤسسة.
في كل مرة يتم فيها تشغيل الإجراء، يتضمن رابطًا إلى التقرير التفصيلي ذي الأولويات والقابل للتنفيذ لكل ملف من ملفات OpenAPI لديك:
اتبع الروابط لقراءة التقرير التفصيلي في منصة 42Crunch:
يمكنك أيضًا تتبع المشكلات التي عثر عليها تدقيق 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يكتب تقرير تنفيذ التدقيق بتنسيق JSON إلى الملف المحدد. يوضح تقرير التنفيذ قائمة واجهات API التي تم إنشاؤها وتحديثها وحذفها. يكون هذا مفيدًا إذا أردت استهلاك نتائج تنفيذ التدقيق تلقائيًا في خطوة لاحقة من خط الأنابيب. بشكل افتراضي، لا يتم كتابة أي تقرير.
api-tagsيمكن لمهمة CI/CD تعيين وسوم تلقائيًا لواجهات API المنشأة حديثًا. يتم تحديد الوسوم بالتنسيق التالي: category1:name1 category2:name2. هذه العلامة اختيارية.
sarif-reportيحول تنسيق JSON الخام للتدقيق إلى SARIF ويحفظ النتائج في الملف المحدد. بشكل افتراضي، لا يتم كتابة أي تقرير.
audit-timeoutيحدد الحد الأقصى لمهلة الانتظار (بالثواني) لتقرير التدقيق. ستفشل المهمة إذا لم تكن النتيجة جاهزة خلال هذه الفترة. الافتراضي: 600
أنشئ رمز API على منصة 42Crunch وانسخ قيمته في سر مستودع باسم API_TOKEN.
ستبدو الخطوة الجديدة النموذجية في سير عمل قائم كما يلي:
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
سيبدو سير العمل النموذجي الذي يفحص محتويات المستودع، ويجري تدقيق الأمان على كل ملف من ملفات OpenAPI الموجودة في المشروع، ويحفظ ملف التنفيذ كقطعة أثرية (artifact) كما يلي:
name: "42crunch-audit-workflow"
# follow standard Code Scanning triggers
on:
push:
branches: [ "main" ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ "main" ]
schedule:
- cron: '19 9 * * 6'
env:
PLATFORM_URL: https://us.42crunch.cloud
jobs:
run_42c_audit:
environment: QA
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
platform-url: ${{ env.PLATFORM_URL}}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
# Upload results to Github code scanning
upload-to-code-scanning: false
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
- name: save-audit-report
if: always()
uses: actions/upload-artifact@v3
with:
name: auditaction-report-${{ github.run_id }}
path: audit-action-report-${{ github.run_id }}.json
if-no-files-found: error
تتم صيانة هذا الإجراء بواسطة فريق النظم البيئية في 42Crunch. إذا واجهت مشكلة، أو كان لديك سؤال لم تتم الإجابة عنه هنا، يمكنك إنشاء تذكرة دعم على support.42crunch.com.
عند الإبلاغ عن مشكلة، تأكد من تضمين ما يلي: