استخدم CodeQL CLI

مكتمل

بالإضافة إلى واجهة المستخدم الرسومية على GitHub.com، يمكنك أيضا الوصول إلى العديد من ميزات CodeQL الأساسية نفسها من خلال واجهة سطر الأوامر.

ستغطي هذه الوحدة استخدام CodeQL CLI لإنشاء قواعد البيانات وتحليل قواعد البيانات وتحميل النتائج إلى GitHub.

أوامر CodeQL CLI

بمجرد جعل CodeQL CLI متاحا للخوادم في نظام CI الخاص بك وتأكد من أنه يمكنهم المصادقة باستخدام GitHub، فأنت مستعد لإنشاء البيانات.

يمكنك استخدام ثلاثة أوامر مختلفة لإنشاء نتائج وتحميلها إلى GitHub:

• database create لإنشاء قاعدة بيانات CodeQL لتمثيل البنية الهرمية لكل لغة برمجة معتمدة في المستودع.
• database analyze لتشغيل الاستعلامات لتحليل كل قاعدة بيانات CodeQL وتلخيص النتائج في ملف SARIF.
• github upload-resultsلتحميل ملفات SARIF الناتجة إلى GitHub حيث تتم مطابقة النتائج مع فرع أو طلب سحب وعرضها كتنبيهات مسح التعليمات البرمجية.

يمكنك عرض تعليمات سطر الأوامر لأي أمر باستخدام --help option.

يتم دعم تحميل بيانات SARIF لعرضها كنتائج مسح التعليمات البرمجية في GitHub للمستودعات المملوكة للمؤسسة مع تمكين GitHub Advanced Security والمستودعات العامة على GitHub.com.

إنشاء قواعد بيانات CodeQL لتحليل

اتبع هذه الخطوات لإنشاء قواعد بيانات CodeQL لتحليلها.

1. تحقق من التعليمات البرمجية التي تريد تحليلها:
   • بالنسبة للفرع، تحقق من رئيس الفرع الذي تريد تحليله.
   • للحصول على طلب سحب، تحقق من إما الالتزام الرئيسي بطلب السحب، أو تحقق من التزام الدمج الذي تم إنشاؤه بواسطة GitHub لطلب السحب.
2. قم بإعداد البيئة ل codebase، مع التأكد من توفر أي تبعيات.
3. ابحث عن أمر الإنشاء، إن وجد، لقاعدة التعليمات البرمجية. يتوفر هذا عادةً في ملف تكوين في نظام CI.
4. تشغيل codeql database create من جذر السداد مع الخروج من المستودع الخاص بك وإنشاء قاعدة التعليمات البرمجية:

   • لإنشاء قاعدة بيانات CodeQL واحدة للغة واحدة مدعومة، استخدم الأمر التالي:

     codeql database create <database> --command <build> --language=<language-identifier>
     

   • لإنشاء قاعدة بيانات CodeQL واحدة لكل لغة للغات متعددة مدعومة، استخدم الأمر التالي:

     codeql database create <database> --command <build> \
       --db-cluster --language=<language-identifier>,<language-identifier>
     

إشعار

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

تظهر القائمة الكاملة للمعلمات للأمر database create في الجدول التالي:

خيار	الاستخدام المطلوب
<database>	حدد اسم وموقع دليل لإنشاء قاعدة بيانات CodeQL. سيفشل الأمر إذا حاولت الكتابة فوق دليل موجود. إذا قمت أيضا بتحديد --db-cluster، فهذا هو الدليل الأصل، ويتم إنشاء دليل فرعي لكل لغة تم تحليلها.
--language	حدد معرف اللغة لإنشاء قاعدة بيانات لأحد cppو csharpgojavajavascriptpythonruby(استخدم JavaScript لتحليل التعليمات البرمجية ل TypeScript). عند استخدامه مع --db-cluster، يقبل الخيار قائمة مفصولة بفاصلة، أو يمكن تحديده أكثر من مرة.
--command	الطريقة المستحسنة. تُستخدم لتحديد أمر الإنشاء أو البرنامج النصي الذي يستدعي عملية الإنشاء لقاعدة التعليمات البرمجية. يتم تشغيل الأوامر من المجلد الحالي أو، حيث يتم تعريفه، من --source-root. لا حاجة لتحليل Python و JavaScript / TypeScript.
--db-cluster	اختياري. استخدم في قواعد برمجية متعددة اللغات لإنشاء قاعدة بيانات واحدة لكل لغة محددة بواسطة --language.
--no-run-unnecessary-builds	الطريقة المستحسنة. استخدم لمنع أمر الإنشاء للغات حيث لا يحتاج CodeQL CLI إلى مراقبة البنية (على سبيل المثال، Python وJavaScript/TypeScript).
--source-root	اختياري. استخدمه إذا قمت بتشغيل CLI خارج جذر السداد للمستودع. بشكل افتراضي، يفترض الأمر إنشاء قاعدة البيانات أن الدليل الحالي هو الدليل الجذر للملفات المصدر؛ استخدم هذا الخيار لتحديد موقع مختلف.

مثال لغة واحدة

ينشئ هذا المثال قاعدة بيانات CodeQL للمستودع الذي تم سحبه في /checkouts/example-repo. يستخدم مستخرج JavaScript لإنشاء تمثيل هرمي لرمز JavaScript و TypeScript في المستودع. يتم تخزين قاعدة البيانات الناتجة في /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

مثال لغات متعددة

ينشئ هذا المثال قاعدة بيانات CodeQL للمستودع الذي تم سحبه في /checkouts/example-repo-multi. يستخدم:

• --db-cluster لطلب تحليل أكثر من لغة واحدة.
• --language لتحديد اللغات التي يجب إنشاء قواعد بيانات لها.
• --command لإخبار الأداة الأمر إنشاء قاعدة التعليمات البرمجية، هنا جعل.
• --no-run-unnecessary-builds لإخبار الأداة بتخطي أمر الإنشاء للغات التي لا تكون هناك حاجة إليها (مثل Python).

يتم تخزين قواعد البيانات الناتجة في python و cpp الدلائل الفرعية من /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

تحليل قاعدة بيانات CodeQL

بعد إنشاء قاعدة بيانات CodeQL، اتبع الخطوات التالية لتحليلها:

1. قم بتشغيله codeql pack download <packs> اختيارياً لتنزيل أي حزم CodeQL (تجريبية) تريد تشغيلها أثناء التحليل.
2. قم بتشغيل codeql database analyze على قاعدة البيانات، وحدد الحزم و/أو الاستعلامات التي يجب استخدامها.

codeql database analyze <database> --format=<format> \
    --output=<output>  <packs,queries>

إشعار

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

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

تظهر القائمة الكاملة للمعلمات للأمر database analyze في الجدول التالي:

خيار	الاستخدام المطلوب
<database>	حدد مسار الدليل الذي يحتوي على قاعدة بيانات CodeQL لتحليلها.
<packs,queries>	حدد حزم CodeQL أو الاستعلامات المراد تشغيلها. لتشغيل الاستعلامات القياسية المستخدمة لمسح الرمز، قم بحذف هذه المعلمة. يمكنك العثور على مجموعات الاستعلام الأخرى المضمنة في مجموعة CodeQL CLI في /<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites. للحصول على معلومات حول إنشاء مجموعة الاستعلام الخاصة بك، راجع إنشاء مجموعات استعلام CodeQL[5] في وثائق CodeQL CLI.
--format	حدد تنسيق ملف النتائج الذي تم إنشاؤه بواسطة الأمر. للتحميل إلى GitHub، يجب أن يكون هذا: sarif-latest.
--output	حدد مكان حفظ ملف نتائج SARIF.
--sarif-category	اختياري لتحليل قاعدة بيانات واحدة. مطلوب لتعريف اللغة عند تحليل قواعد بيانات متعددة لعملية تنفيذ واحدة في المستودع. حدد فئة لتضمينها في ملف نتائج SARIF لهذا التحليل. تُستخدم الفئة للتمييز بين التحليلات المتعددة لنفس الأداة والالتزام، ولكن يتم إجراؤها على لغات مختلفة أو أجزاء مختلفة من الكود.
--sarif-add-query-help	اختياري. استخدمه إذا كنت تريد تضمين أي تعليمات استعلام متاحة ذات علامة التخفيض المنخفضة للاستعلامات المخصصة المستخدمة في تحليلك. سيتم عرض أي استعلام مساعدة للاستعلامات المخصصة المضمنة في إخراج SARIF في واجهة مستخدم مسح الكود إذا كان الاستعلام ذي الصلة يولد تنبيهاً.
<packs>	اختياري. استخدمه إذا قمت بتنزيل حزم استعلام CodeQL وأردت تشغيل الاستعلامات الافتراضية أو مجموعات الاستعلام المحددة في الحزم.
--threads	اختياري. استخدم إذا كنت تريد استخدام أكثر من مؤشر ترابط لتشغيل الاستعلامات. القيمة الافتراضية هي 1. يمكنك تحديد المزيد من مؤشرات الترابط لتسريع تنفيذ الاستعلام. لتعيين عدد مؤشرات الترابط إلى عدد المعالجات المنطقية، حدد 0.
--verbose	اختياري. تُستخدم للحصول على معلومات أكثر تفصيلاً حول عملية التحليل وبيانات التشخيص من عملية إنشاء قاعدة البيانات.

مثال أساسي

يحلل هذا المثال قاعدة بيانات CodeQL المخزنة في /codeql-dbs/example-repo ويحفظ النتائج كملف SARIF: /temp/example-repo-js.sarif. يستخدم --sarif-category لتضمين معلومات إضافية في ملف SARIF الذي يعرف النتائج باسم JavaScript. يعد هذا ضرورياً عندما يكون لديك أكثر من قاعدة بيانات CodeQL لتحليل التزام واحد في المستودع.

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=javascript
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
    codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

تحميل النتائج إلى GitHub

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

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

قبل أن تتمكن من تحميل النتائج إلى GitHub، يجب تحديد أفضل طريقة لتمرير التطبيق GitHub أو رمز الوصول الشخصي الذي أنشأته سابقاً إلى CodeQL CLI. نوصي بمراجعة إرشادات نظام CI الخاص بك حول الاستخدام الآمن لمتجر سري. يدعم CodeQL CLI:

• التفاعل مع مخزن سري باستخدام خيار --github-auth-stdin. هذه هي الطريقة الموصى بها للمصادقة.
• حفظ السر في متغير البيئة GITHUB_TOKEN وتشغيل CLI دون تضمين --github-auth-stdin الخيار.
• مرر خيار سطر الأوامر --github-auth-stdin وقم بتوفير رمز مميز مؤقت عبر الإدخال القياسي. يوصى بذلك لأغراض الاختبار.

عندما تقرر الأسلوب الأكثر أمانا وموثوقية لخادم CI الخاص بك، قم بتشغيل codeql github upload-results على كل ملف نتائج SARIF وقم بتضمين --github-auth-stdin ما لم يكن الرمز المميز متوفرا في متغير GITHUB_TOKENالبيئة .

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> 

يتم عرض القائمة الكاملة للمعلمات للأمر github upload-results في الجدول كما يلي.

خيار	الاستخدام المطلوب
--repository	حدد OWNER/NAME للمستودع الذي سيتم تحميل البيانات إليه. يجب أن يكون المالك مؤسسة داخل مؤسسة لديها ترخيص ل GitHub Advanced Security، ويجب تمكين GitHub Advanced Security للمستودع ما لم يكن المستودع عاما.
--ref	حدد اسم المرجع الذي قمت بسحبه وتحليله بحيث يمكن مطابقة النتائج مع الكود الصحيح. بالنسبة للفرع، استخدم refs/heads/BRANCH-NAME؛ للالتزام الرئيسي لطلب سحب، استخدم refs/pulls/NUMBER/head؛ أو لتثبيت دمج تم إنشاؤه بواسطة GitHub لطلب سحب، استخدم refs/pulls/NUMBER/merge.
--commit	حدد SHA الكامل للالتزام الذي حللته.
--sarif	حدد ملف SARIF لتحميله.
--github-auth-stdin	اختياري. استخدم لتمرير CLI التطبيق GitHub أو رمز الوصول الشخصي الذي تم إنشاؤه للمصادقة مع واجهة برمجة تطبيقات REST الخاصة GitHub عبر الإدخال القياسي. هذا غير مطلوب إذا كان الأمر لديه حق الوصول إلى GITHUB_TOKEN متغير بيئة تم تعيينه باستخدام هذا الرمز المميز.