تمكين فحص التعليمات البرمجية باستخدام أدوات الجهات الخارجية

مكتمل

بدلاً من تشغيل فحص التعليمات البرمجية في GitHub، يمكنك إجراء التحليل في مكان آخر ثم تحميل النتائج. يتم عرض التنبيهات الخاصة بفحص التعليمات البرمجية الذي تقوم بتشغيله خارجياً بنفس طريقة عرض التنبيهات التي تقوم بتشغيلها داخل GitHub. يمكنك تحميل ملفات تنسيق تبادل نتائج تحليل التعليمات البرمجية (SARIF) التي تم إنشاؤها خارج GitHub أو باستخدام GitHub Actions لمشاهدة تنبيهات فحص التعليمات البرمجية من أدوات الجهات الخارجية في المستودع.

في هذه الوحدة، ستتعلم كيفية تمكين مسح التعليمات البرمجية باستخدام أدوات الجهات الخارجية وكيفية استخدام ملفات SARIF وتحميلها.

حول تحميلات ملفات SARIF لفحص التعليمات البرمجية

ينشئ GitHub تنبيهات فحص التعليمات البرمجية في مستودع باستخدام معلومات من ملفات SARIF. يمكنك إنشاء ملفات SARIF باستخدام العديد من أدوات اختبار التحليل والأمان الثابت، بما في ذلك CodeQL. يجب أن تستخدم النتائج الإصدار 2.1.0 من SARIF.

يمكنك تحميل النتائج باستخدام واجهة برمجة التطبيقات لفحص التعليمات البرمجية أو CodeQL CLI أو إجراءات GitHub. يعتمد أسلوب التحميل الأفضل على كيفية إنشاء ملف SARIF.

واجهة برمجة تطبيقات مسح التعليمات البرمجية

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

يمكنك الوصول إلى واجهة برمجة تطبيقات GitHub عبر HTTPS من https://api.github.com. يتم إرسال جميع البيانات واستلامها كـ JSON. تستخدم واجهة برمجة التطبيقات أنواع وسائط مخصصة للسماح للمستهلكين باختيار تنسيق البيانات الذي يرغبون في استلامه. أنواع الوسائط خاصة بالموارد، ما يسمح لها بالتغيير بشكل مستقل ودعم التنسيقات التي لا تدعمها الموارد الأخرى.

هناك نوع وسائط مخصص واحد مدعوم لواجهة برمجة تطبيقات REST لفحص التعليمات البرمجية، application/sarif+json.

يمكنك استخدام هذا النوع من الوسائط مع طلبات GET المرسلة إلى نقطة النهاية /analyses/{analysis_id}. عند استخدام نوع الوسائط هذا مع هذه العملية، تتضمن الاستجابة مجموعة فرعية من البيانات الفعلية التي تم تحميلها للتحليل المحدد، بدلاً من ملخص التحليل الذي يتم إرجاعه عند استخدام نوع الوسائط الافتراضي. تتضمن الاستجابة أيضاً بيانات إضافية مثل خصائص github/alertNumber وgithub/alertUrl. يتم تنسيق البيانات على أنها إصدار 2.1.0 من SARIF.

فيما يلي مثال لأمر cURL باستخدام واجهة برمجة التطبيقات لسرد تنبيهات فحص التعليمات البرمجية لمؤسسة:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/code-scanning/alerts

راجع مستندات GitHub REST API لمزيد من المعلومات حول استخدام واجهة برمجة التطبيقات لفحص التعليمات البرمجية.

CodeQL CLI

يُعد CodeQL CLI منتجاً مستقلاً يمكنك استخدامه لتحليل التعليمات البرمجية. الغرض الرئيسي هو إنشاء تمثيل قاعدة بيانات للتعليمة البرمجية الأساسية، قاعدة بيانات CodeQL. بمجرد أن تصبح قاعدة البيانات جاهزة، يمكنك الاستعلام عنها بشكل تفاعلي، أو يمكنك تشغيل مجموعة من الاستعلامات لإنشاء مجموعة من النتائج بتنسيق SARIF وتحميل النتائج إلى GitHub.com. CodeQL CLI مجاني للاستخدام في المستودعات العامة التي يتم الاحتفاظ بها على GitHub.com، وهو متاح للاستخدام في المستودعات الخاصة المملوكة للعميل مع ترخيص الأمان المتقدم. تنزيل مجموعة CodeQL من https://github.com/github/codeql-action/releases.

تحتوي المجموعة على:

• منتج CodeQL CLI
• إصدار متوافق من الاستعلامات والمكتبات من https://github.com/github/codeql
• إصدارات مسبقة التحويل من جميع الاستعلامات المضمنة في المجموعة

يجب عليك دائما استخدام حزمة CodeQL، لأن هذا يضمن التوافق ويعطي أيضا أداء أفضل بكثير من تنزيل منفصل من CodeQL CLI وتحقق من استعلامات CodeQL.

تحليل مسح التعليمات البرمجية باستخدام GitHub Actions

لاستخدام GitHub Actions لتحميل ملف SARIF تابع لجهة خارجية إلى المستودع، ستحتاج إلى سير عمل GitHub Actions. يُعد سير عمل GitHub Actions عملية تلقائية، تتكون من مهمة واحدة أو أكثر، تم تكوينها كملف .yml. يتم تخزين مهام سير العمل في الدليل .github/workflows الخاص بالمستودع.

يستخدم سير العمل الإجراء upload-sarif، والذي يُعد جزءاً من المستودع github/codeql-action. يتضمن سير العمل هذا معلمات الإدخال التي يمكنك استخدامها لتكوين التحميل.

معلمة الإدخال الرئيسية هي sarif-file، التي تقوم بتكوين ملف أو دليل ملفات SARIF المراد تحميلها. يكون الدليل أو مسار الملف نسبة إلى جذر المستودع.

يمكن تكوين الإجراء upload-sarif للتشغيل عند وقوع الحدث push وscheduled.

يوضح هذا المثال عناصر upload-sarif ملف yml للإجراء:

name: 'Code Scanning : Upload SARIF'
description: 'Upload the analysis results'
author: 'GitHub'
inputs:
  sarif_file:
    description: |
      The SARIF file or directory of SARIF files to be uploaded to GitHub code scanning.
      See https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/
      uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions
      for information on the maximum number of results and maximum file size supported by code scanning.
    required: false
    default: '../results'
  checkout_path:
    description: "The path at which the analyzed repository was checked out. 
    Used to relativize any absolute paths in the uploaded SARIF file."
    required: false
    default: ${{ github.workspace }}
  token:
    default: ${{ github.token }}
  matrix:
    default: ${{ toJson(matrix) }}
  category:
    description: String used by Code Scanning for matching the analyses
    required: false
  wait-for-processing:
    description: If true, the Action will wait for the uploaded SARIF to be processed before completing.
    required: true
    default: "false"
runs:
  using: 'node12'
  main: '../lib/upload-sarif-action.js' 

في كل مرة يتم فيها تحميل نتائج فحص تعليمة برمجية جديد، تتم معالجة النتائج وإضافة التنبيهات إلى المستودع. يستخدم GitHub الخصائص في ملف SARIF لعرض التنبيهات. على سبيل المثال، لمنع تكرار التنبيهات لنفس المشكلة، يستخدم مسح التعليمات البرمجية البصمات لمطابقة النتائج عبر عمليات التشغيل المختلفة بحيث تظهر مرة واحدة فقط في آخر تشغيل للفرع المحدد. تتضمن ملفات SARIF التي تم إنشاؤها بواسطة سير عمل تحليل CodeQL بيانات هذه البصمة في الحقل partialFingerprints. إذا قمت بتحميل ملف SARIF باستخدام الإجراء upload-sarif وكانت هذه البيانات مفقودة، يحاول GitHub ملء الحقل partialFingerprints من الملفات المصدر.

إذا لم يحتوِ ملف SARIF الخاص بك على partialFingerprints، فسيحسب الإجراء upload-sarif الحقل partialFingerprints نيابة عنك ويحاول منع تكرار التنبيهات. يمكن لـ GitHub إنشاء partialFingerprints فقط عندما يحتوي المستودع على كل من ملف SARIF والتعليمة البرمجية المصدر المستخدمين في التحليل الثابت.

يدعم تحميل SARIF 5000 نتيجة كحد أقصى لكل تحميل. يتم تجاهل أية نتائج فوق هذا الحد. إذا قامت أداة بإنشاء عدد كبير جداً من النتائج، فيجب عليك تحديث التكوين للتركيز على نتائج القواعد أو الاستعلامات الأكثر أهمية.

لكل عملية تحميل، يدعم تحميل SARIF حجماً أقصى يبلغ 10 ميجا بايت لملف SARIF المضغوط بتنسيق gzip. سيتم رفض أي تحميلات فوق هذا الحد. إذا كان ملف SARIF كبيراً جداً لأنه يحتوي على نتائج كثيرة جداً، فيجب عليك تحديث التكوين للتركيز على نتائج القواعد أو الاستعلامات الأكثر أهمية.

تحميل ملفات SARIF التي تم إنشاؤها خارج المستودع الخاص بك

يمكنك أيضاً إنشاء سير عمل جديد يقوم بتحميل ملفات SARIF بعد تثبيتها في المستودع. يكون هذا مفيداً عندما يتم إنشاء ملف SARIF كأداة خارج المستودع الخاص بك.

في المثال التالي، يتم تشغيل سير العمل في أي وقت يتم دفع التثبيتات إلى المستودع. يستخدم الإجراء الخاصية partialFingerprints لتحديد ما إذا كانت التغييرات قد حدثت أم لا.

بالإضافة إلى التشغيل عند دفع التثبيتات، تتم جدولة سير العمل للتشغيل مرة واحدة في الأسبوع. يقوم سير العمل هذا بتحميل الملف results.sarif الموجود في جذر المستودع. يمكنك أيضاً تعديل سير العمل هذا لتحميل دليل ملفات SARIF. على سبيل المثال، يمكنك وضع جميع ملفات SARIF في دليل في جذر المستودع الخاص بك المسمى sarif-output وتعيين معلمة إدخال الإجراء sarif_file على sarif-output.

name: "Upload SARIF"

// Run workflow each time code is pushed to your repository and on a schedule. 
//The scheduled workflow runs every Thursday at 15:45 UTC.

on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
  steps:
    # This step checks out a copy of your repository.
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Upload SARIF file
      uses: github/codeql-action/upload-sarif@v1
      with:
        # Path to SARIF file relative to the root of the repository
        sarif_file: results.sarif 

تحميل ملفات SARIF التي تم إنشاؤها كجزء من سير عمل CI

إذا أنشأت ملف SARIF التابع لجهة خارجية كجزء من سير عمل التكامل المستمر (CI)، فيمكنك إضافة الإجراء upload-sarif كخطوة بعد تشغيل اختبارات CI. إذا لم يكن لديك سير عمل CI بالفعل، فيمكنك إنشاء واحد باستخدام سير عمل بادئ في المستودع https://github.com/actions/starter-workflows.

في هذا المثال، يتم تشغيل سير العمل في أي وقت يتم دفع التثبيتات إلى المستودع. يستخدم الإجراء الخاصية partialFingerprints لتحديد ما إذا كانت التغييرات قد حدثت أم لا. بالإضافة إلى التشغيل عند دفع التثبيتات، تتم جدولة سير العمل للتشغيل مرة واحدة في الأسبوع.

يوضح هذا المثال أداة تحليل التعليمات البرمجية ESLint كخطوة في سير العمل. تقوم الخطوة Run ESLint بتشغيل أداة ESLint وإخراج الملف results.sarif. ثم يقوم سير العمل بتحميل ملف results.sarif إلى GitHub باستخدام الإجراء upload-sarif.

  ```
  name: "ESLint analysis"

// Run workflow each time code is pushed to your repository and on a schedule.
// The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v2
      - name: Run npm install
        run: npm install
      // Runs the ESlint code analysis
      - name: Run ESLint
        // eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      // Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v1
        with:
          // Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
  ```