تصدير SARIF والتكامل مع GitHub code scanning

صدّر تدقيق vetkit مكتملًا عبر نقطة نهاية التقرير الخاصة به مع format=sarif، ثم ارفع ملف SARIF 2.1.0 من مسار عمل GitHub Actions الخاص بك. وطابق التدقيق مع المستودع والـ commit الجاري تحليله قبل الرفع. فتنزيل التقرير لا ينشر بحد ذاته تنبيهات على GitHub؛ والرفع خطوة منفصلة تُعدّها بنفسك.

1. تحقّق من المتطلبات المسبقة

• جهّز معرّف المؤسسة ومعرّف التدقيق ومفتاح API من vetkit يملك الصلاحية reports:read. ومسار العمل المؤتمت الذي يبدأ التدقيقات ويستطلع حالتها أيضًا يحتاج إلى audits:write وaudits:read.
• تأكّد من مستودع التدقيق ومن الـ commit SHA الخاص به. وفي CI، اطلب تدقيقًا للـ commit الدقيق الخاص بمسار العمل أو أعد استخدام تدقيق موجود له، وانتظر اكتماله قبل التصدير.
• افحص تقرير JSON بحثًا عن نتائج جزئية وعن نطاق الفحص الفعلي. فمستند SARIF الصالح قد يمثّل مع ذلك تحليلًا غير مكتمل.

يدعم GitHub ميزة code scanning للمستودعات العامة ولمستودعات المؤسسات المؤهَّلة التي فُعّلت فيها GitHub Code Security. تحقّق من أهلية مستودعك ومن صلاحية الكتابة في وثائق GitHub الخاصة برفع SARIF.

2. صدّر التدقيق

اضبط المتغيرات أدناه في الصدفة المحلية أو في بيئة CI. VETKIT_API_URL هو أصل (origin) واجهة vetkit البرمجية لديك دون /v1. احفظ المفتاح في مدير أسرار أو في أسرار CI، لا في ملف مسار العمل أو المستودع أو سكربت الصدفة. يتطلب هذا الأمر curl وjq:

$ set -euo pipefail$ : "${VETKIT_API_URL:?Set the API origin}"$ : "${VETKIT_ORG_ID:?Set the organization ID}"$ : "${VETKIT_AUDIT_ID:?Set the completed audit ID}"$ : "${VETKIT_API_KEY:?Set a reports:read key}" $ curl --fail-with-body --silent --show-error --max-time 30 \  "$VETKIT_API_URL/v1/orgs/$VETKIT_ORG_ID/audits/$VETKIT_AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif$ jq -e '.version == "2.1.0" and (.runs | type == "array")' vetkit.sarif >/dev/null

تُرجع نقطة النهاية application/sarif+json واسم ملف مرفق مبنيًا على الـ commit المدقَّق. ويحفظه الأمر عن قصد باسم vetkit.sarif لخطوة الرفع. وفحص jq مجرد فحص أساسي للصيغة، وليس تحققًا كاملًا من المخطط (schema) ولا تأكيدًا لاكتمال الفحص. تعامل مع التقرير المنزَّل على أنه معلومات عن المستودع وتحكّم في الوصول إليه.

3. ارفع التقرير من مسار العمل

في مسار عمل خاص بالمستودع المفحوص، اسحب الشيفرة المصدرية المطابقة، واحصل على التدقيق المكتمل، وشغّل أمر التنزيل أعلاه. واحفظ VETKIT_API_KEY في سرّ من أسرار Actions. يعرض المقتطف التالي الصلاحيات وخطوة الرفع النهائية؛ وهو ليس مسار عمل فحص قائمًا بذاته. أضف خطوة التنزيل بين السحب (checkout) والرفع:

permissions:  contents: read  actions: read  security-events: write # Inside the job's steps, after choosing the matching audit:steps:  - uses: actions/checkout@v6    with:      persist-credentials: false  # Insert the authenticated download step here.  - name: Upload vetkit results    uses: github/codeql-action/upload-sarif@v4    with:      sarif_file: vetkit.sarif      category: vetkit

يستخدم إجراء الرفع في GitHub المعامل sarif_file لمسار التقرير وcategory للتمييز بين التحليلات. وإعادة استخدام الأداة/الفئة نفسها للـ commit نفسه قد تستبدل النتائج السابقة؛ فاستخدم فئات مختلفة للتحليلات المنفصلة. وتتبع الصلاحيات وإصدارات الإجراءات المذكورة أعلاه مثال GitHub.

يُبقي مثال التكامل مع المستودع في vetkit رفع SARIF اختياريًا خلف VETKIT_UPLOAD_SARIF=true. ويطلب مسار عمل الفحص الكامل فيه تدقيقًا للـ commit الدقيق، ويرفض النتائج الفاشلة أو الجزئية أو غير المقيَّمة بدرجة قبل الرفع الاختياري. ولا يفرض فحص الاكتمال هذا حدًّا أدنى لخطورة النتائج أو للدرجة: حدّد سياسة الإطلاق لديك بشكل منفصل. وفحوص GitHub App ورفع SARIF مساران منفصلان للتكامل.

4. فسّر النتائج المستوردة

يصدّر vetkit تشغيل SARIF واحدًا (run) يكون فيه vetkit هو المشغّل (driver). وتتضمن النتائج معرّفات القواعد، ومواقع الملفات حيث تتوفر، ونصوص المعالجة، وبصمات vetkit. وتُسجَّل إصدارات المحلّلات كامتدادات (extensions)، ويُضمَّن مصدر المستودع والـ commit. ويستخدم تعيين درجات الخطورة مستويات SARIF إلى جانب خصائص الخطورة في vetkit؛ وهذه التعيينات الرقمية ليست درجات CVSS محسوبة بشكل مستقل.

تستخدم النتائج على مستوى المستودع موقعًا اصطناعيًا هو (repository)، لذا قد لا تشير إلى سطر حقيقي في الشيفرة المصدرية. وتبقى النتائج المكتومة في الملف المصدَّر مع بيانات الكتم الوصفية الخاصة بـ SARIF. فلا تفترض أن عدد النتائج المصدَّرة يساوي عدد التنبيهات النشطة التي يعرضها GitHub. واحتفظ بتقرير vetkit الأصلي لمعرفة التغطية وسياق الدرجات وتفاصيل المراجعة.

استكشاف الأخطاء وإصلاحها

• فشل التنزيل: تحقّق من أصل الواجهة البرمجية، ومعرّفي المؤسسة والتدقيق، وصلاحية المفتاح، والصلاحية reports:read. ولا تطبع المفتاح أثناء تصحيح الأخطاء.
• مواقع خاطئة في الشيفرة المصدرية: قارن commit التدقيق بـ commit مسار العمل وبالنسخة المسحوبة. ولا ترفع تقريرًا أقدم كدليل على مراجعة أحدث.
• رُفض الرفع: تحقّق من أهلية GitHub وصلاحيات مسار العمل ومخرجات الخطأ من إجراء الرفع. إذ يطبّق GitHub خصائص SARIF التي يدعمها وحدود الحجم الخاصة به.
• لا تظهر أي تنبيهات: افحص نتائج الملف، وبيانات الكتم الوصفية، والتحليل المختار، وتغطية التدقيق الأصلي. فنجاح النقل لا يثبت أن الفحص نظيف.

المصادر والحدود

جرى التحقق في 1 نوفمبر 2026 مقابل وحدة التحكم/الخدمة الخاصة بالتقارير في vetkit، ومُسلسِل SARIF، ومثال التكامل مع GitHub Actions في المستودع. راجع مرجع API ومتطلبات الرفع في GitHub لطرفَي التكامل. وقد تتغيّر أهلية GitHub وسلوك الإجراءات. ينقل تصدير SARIF النتائج الموجودة؛ ولا يشغّل CodeQL، ولا يضيف فحوصًا إلى التدقيق الأصلي، ولا يضمن ظهور كل تفاصيل تقرير vetkit في واجهة GitHub.