Bagikan melalui

Menjalankan Analisis CodeQL pada Kode Driver Windows

CodeQL adalah mesin analisis statis canggih yang membantu pengembang mengidentifikasi kerentanan keamanan dan pelanggaran kode dalam kode sumber driver Windows. Artikel ini menjelaskan cara menggunakan analisis CodeQL untuk membuat File Verifikasi Driver untuk sertifikasi Windows Hardware Compatibility Program (WHCP).

Dalam artikel ini, Anda:

  • Instal versi CodeQL yang sesuai.
  • Instal paket CodeQL dan suite kueri yang diperlukan.
  • Jalankan CodeQL untuk membangun database dan menganalisis kode Anda.
  • Buat File Verifikasi Driver.

Pilih versi CodeQL yang sesuai untuk driver Anda

Note

Visual Studio (VS) 17.8 memutuskan kompatibilitas dengan versi CodeQL yang lebih lama yang digunakan di cabang WHCP_21H2 dan WHCP_22H2. CodeQL CLI versi 2.15.4 divalidasi untuk digunakan dengan WHCP 21H2 dan WHCP 22H2 saat menggunakan Visual Studio 17.8 atau yang lebih tinggi. Saat menggunakan Visual Studio 17.7 atau yang lebih lama, gunakan versi 2.4.6 atau versi 2.6.3. Untuk Program WHCP, gunakan versi CodeQL CLI dan rilis Windows yang Anda sertifikasi, sesuai tabel berikut.

Pilih tab untuk skenario Anda:

Gunakan matriks ini untuk menentukan versi yang akan diunduh.

Rilis Windows Versi dari CodeQL CLI versi paket CodeQL microsoft/windows-drivers Versi paket CodeQL Microsoft/cpp-queries versi codeql/cpp-queries Cabang terkait
Windows Server 2022 2.4.6 atau 2.15.4 1.0.13 (Jika menggunakan codeql 2.15.4) N/A 0.9.0 (Jika menggunakan codeql 2.15.4) WHCP_21H2
Windows 11 2.4.6 atau 2.15.4 1.0.13 (Jika menggunakan codeql 2.15.4) N/A 0.9.0 (Jika menggunakan codeql 2.15.4) WHCP_21H2
Windows 11, versi 22H2 2.6.3 atau 2.15.4 1.0.13 (Jika menggunakan codeql 2.15.4) N/A 0.9.0 (Jika menggunakan codeql 2.15.4) WHCP_22H2
Windows 11, versi 23H2 2.6.3 atau 2.15.4 1.0.13 (Jika menggunakan codeql 2.15.4) N/A 0.9.0 (Jika menggunakan codeql 2.15.4) WHCP_22H2
Windows 11, versi 24H2 2.15.4 1.1.0 N/A 0.9.0 WHCP_24H2
Windows Server 2025 2.20.1 1.8.0 0.0.4 N/A WHCP_25H2
Windows 11, versi 25H2 2.20.1 1.8.0 0.0.4 N/A WHCP_25H2
Windows 11, versi 26H1 2.24.1 1.8.2 0.0.4 N/A WHCP_26H1

Note

Versi paket CodeQL tidak ditentukan untuk CodeQL CLI 2.4.6 dan 2.6.3 karena hanya versi CodeQL yang lebih baru dari v2.7.0 yang mendukung paket CodeQL.

Versi CodeQL divalidasi untuk digunakan dengan WHCP

Untuk informasi versi terbaru, termasuk menguji pengembangan terbaru, lihat Alat tambahan pengembang driver Windows.

Versi dari CodeQL CLI
2.24.1
2.23.3
2.21.4
2.21.2
2.20.1
2.15.4

Mengunduh dan Menginstal CodeQL

  1. Buat direktori untuk berisi CodeQL. Contoh ini menggunakan C:\codeql-home\

    C:\> mkdir C:\codeql-home

  2. Lihat tabel sebelumnya untuk memilih versi CodeQL CLI mana yang akan digunakan sesuai dengan cabang kueri driver Microsoft yang diinginkan. Jika Anda melakukan analisis sebagai bagian dari program WHCP, lihat tabel Untuk Penggunaan Program Kompatibilitas Perangkat Keras Windows, jika tidak, gunakan cabang Utama dan versi CLI yang tercantum dalam GitHub README atau tabel "untuk penggunaan umum" sebelumnya. Menggunakan versi yang berbeda dapat mengakibatkan database tidak kompatibel dengan pustaka.

  3. Navigasikan ke rilis biner CodeQL CLI yang terkait dengan tabel sebelumnya, dan unduh file zip sesuai dengan arsitektur proyek Anda. Misalnya, untuk Windows 64 bit codeql-win64.zip.

  4. Ekstrak direktori Codeql CLI ke direktori yang Anda buat, misalnya: *C:\codeql-home\codeql*.

  5. Pastikan CodeQL diinstal dengan benar dengan memeriksa versi:

     C:\codeql-home\codeql>codeql --version
 CodeQL command-line toolchain release 2.15.4.
 Copyright (C) 2019-2023 GitHub, Inc.
 Unpacked in: C:\codeql-home\codeql
     Analysis results depend critically on separately distributed query and
     extractor modules. To list modules that are visible to the toolchain,
     use 'codeql resolve qlpacks' and 'codeql resolve languages'.

Menggunakan bantuan CodeQL

C:\codeql-home\codeql\>codeql --help
Usage: codeql <command> <argument>...
Create and query CodeQL databases, or work with the QL language.

GitHub makes this program freely available for the analysis of open-source software and certain other uses, but it is
not itself free software. Type codeql --license to see the license terms.

      --license              Show the license terms for the CodeQL toolchain.
Common options:
  -h, --help                 Show this help text.
  -v, --verbose              Incrementally increase the number of progress messages printed.
  -q, --quiet                Incrementally decrease the number of progress messages printed.
Some advanced options have been hidden; try --help -v for a fuller view.
Commands:
  query     Compile and execute QL code.
  bqrs      Get information from .bqrs files.
  database  Create, analyze and process CodeQL databases.
  dataset   [Plumbing] Work with raw QL datasets.
  test      Execute QL unit tests.
  resolve   [Deep plumbing] Helper commands to resolve disk locations etc.
  execute   [Deep plumbing] Low-level commands that need special JVM options.
  version   Show the version of the CodeQL toolchain.
  generate  Generate formatted QL documentation.

Untuk bantuan pada perintah tertentu, jalankan perintah< codeql >--help. Contohnya:

codeql create --help

Untuk mendapatkan bantuan untuk sub-perintah, cantumkan secara hierarkis, misalnya

codeql create language --help

Menginstal Paket CodeQL

Pilih tab untuk lingkungan build Anda:

Gunakan prosedur ini jika Anda menggunakan Visual Studio 2022 17.8 atau lebih tinggi untuk sertifikasi WHCP untuk 21H2 atau yang lebih baru dan CodeQL CLI versi 2.15.4 atau yang lebih baru.

Note

Jika Anda menjalankan pengujian CodeQL dengan versi CodeQL yang lebih lama, pastikan untuk menghapus submodul CodeQL lama jika Anda masih memiliki versi lama dari repositori kloning. CodeQL mungkin mencoba menggunakan kueri di submodul secara default, yang dapat menyebabkan kesalahan karena versi yang tidak cocok.

Mengunduh paket kueri CodeQL

CodeQL memperkenalkan Paket CodeQL (paket CodeQL atau paket kueri) dalam versi 2.7.0, menghilangkan kebutuhan untuk mengkloning repositori Windows-Driver-Developer-Supplemental-Tools untuk menggunakan kueri untuk sertifikasi.

  1. Unduh versi paket microsoft/windows-drivers yang benar dari tabel Penggunaan Program Kompatibilitas Perangkat Keras Windows . Tentukan @<version> pada perintah berikut.
C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>

Misalnya, jika Anda mensertifikasi untuk WHCP 26H1, jalankan perintah berikut untuk mengunduh paket kueri driver windows 1.8.2:

C:\codeql-home\> codeql pack download microsoft/windows-drivers@1.8.2

Gunakan perintah ini untuk mengunduh paket kueri Kueri cpp Microsoft versi 0.0.4.

C:\codeql-home\> codeql pack download microsoft/cpp-queries@0.0.4

CodeQL menginstal paket kueri ke direktori default:

C:\Users\<current user>\.codeql\packages\microsoft\windows-drivers\<downloaded version>\

Important

Jangan ubah direktori penginstalan atau pindahkan paket kueri yang diinstal.

Microsoft menyediakan tiga suite kueri untuk menyederhanakan alur kerja pengembang driver end-to-end. Suite ini disertakan dalam paket CodeQL microsoft/windows-drivers.

  • recommended.qls berisi rangkaian pemeriksaan menyeluruh terhadap bug driver umum dan C/C++. Sebaiknya jalankan suite ini secara default dan meninjau hasil.
  • mustrun.qls berisi pemeriksaan yang harus dijalankan untuk melewati sertifikasi Windows Hardware Compatibility Program (WHCP). Karena kueri ini dapat menghasilkan positif palsu dalam beberapa kasus, kegagalan dalam pemeriksaan ini tidak akan menyebabkan kegagalan dalam pengujian Logo Alat Statis, tetapi pengembang harus meninjau hasil dan memperbaiki bug yang nyata. DVL yang dihasilkan tanpa hasil dari pemeriksaan ini gagal dalam uji Logo Alat Statis. Untuk 26H1, mustrun.qls dan recommended.qls identik.
  • mustfix.qls berfungsi sebagai subset dari kueri yang harus dijalankan dan berisi pemeriksaan untuk melaporkan masalah yang harus diperbaiki agar lulus sertifikasi WHCP. DVL yang dihasilkan dengan kegagalan dalam aturan ini tidak lulus uji Logo Alat Statis.

Untuk detail konten suite kueri, lihat Kueri dan Suite CodeQL.

Membangun Database CodeQL

Contoh-contoh ini mengasumsikan penggunaan lingkungan pengembangan Windows dan bahwa lokasi penginstalan adalah C:\codeql-home, tetapi Anda dapat menggunakan pengaturan yang sesuai dengan Anda. Lihat Bahasa dan kerangka kerja yang didukung CodeQL untuk daftar pengkompilasi mana yang didukung.

  1. Buat direktori untuk CodeQL untuk menempatkan database yang dibuatnya. Misalnya: C:\codeql-home\databases

    mkdir C:\codeql-home\databases

  2. Gunakan perintah CodeQL untuk membuat database dengan parameter ini:

    • Parameter pertama adalah tautan ke direktori database Anda. Misalnya, C:\codeql-home\databases\MyDriverDatabase. (Perintah ini gagal jika direktori sudah ada.)
    • --language atau -l menentukan bahasa atau bahasa tempat kode sumber Anda berada. Parameter ini dapat menjadi daftar yang dipisahkan koma, seperti [cpp, javascript].
    • --source-root atau -s menentukan jalur ke kode sumber Anda.
    • --command atau -c menentukan perintah build atau jalur ke file build Anda.
    codeql database create <path to new database> --language=<cpp> --source-root=<driver parent directory> --command=<build command or path to build file>

Examples

Contoh driver tunggal.

C:\codeql-home\codeql> codeql database create D:\DriverDatabase --language=cpp --source-root=D:\Drivers\SingleDriver --command="msbuild /t:rebuild D:\Drivers\SingleDriver\SingleDriver.sln"

Contoh beberapa driver.

C:\codeql-home\codeql> codeql database create D:\SampleDriversDatabase --language=cpp --source-root=D:\AllMyDrivers\SampleDrivers --command=D:\AllMyDrivers\SampleDrivers\BuildAllSampleDrivers.cmd

Untuk informasi selengkapnya atau bantuan menggunakan database create perintah, lihat Membuat Database CodeQL atau Menggunakan bantuan CodeQL.

Melakukan Analisis

Pada titik ini, pembuatan database selesai dan langkah selanjutnya adalah melakukan analisis aktual pada kode sumber driver.

  1. Gunakan perintah CodeQL untuk menganalisis database Anda menggunakan parameter berikut:

    • parameter pertama adalah tautan ke direktori database Anda. Misalnya, C:\codeql-home\databases\MyDriverDatabase. (Catatan: perintah ini gagal jika direktori tidak ada.)
    • --format adalah jenis file dari file output. Opsinya meliputi: SARIF dan CSV. (Untuk Pengguna WHCP , gunakan format SARIF.)
    • --output adalah jalur ke tempat Anda menginginkan file output, pastikan untuk menyertakan format dalam nama file. (Perintah ini gagal jika direktori belum ada.)
    • parameter penentu kueri adalah daftar argumen yang dipisahkan spasi yang dapat mencakup:
      • jalur ke file kueri
      • jalur ke direktori yang berisi file kueri
      • jalur ke file rangkaian kueri
      • nama paket kueri CodeQL
    codeql database analyze <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif

    Example:

    codeql database analyze D:\DriverDatabase microsoft/windows-drivers:windows-driver-suites/recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif

    Untuk informasi selengkapnya atau bantuan menggunakan database analyze perintah, lihat Menganalisis Database dengan CodeQL CLI, Menggunakan paket CodeQL untuk menganalisis database CodeQL, atau Menggunakan bantuan CodeQL.

Menampilkan dan Menginterpretasikan Hasil

Bagian ini berfokus pada pembuatan dan interpretasi hasil dalam format SARIF. Format hasil lain seperti CSV tersedia, tetapi tidak didukung oleh pengujian Logo Alat Statis.

Format Pertukaran Hasil Analisis Statis (SARIF) adalah format jenis JSON yang digunakan untuk berbagi hasil analisis statis. Baca selengkapnya tentang standar di OASIS Static Analysis Results Interchange Format (SARIF), cara CodeQL menggunakan Output SARIF, dan json skema.

Ada beberapa metode untuk menginterpretasikan hasil analisis, termasuk mengurutkan objek secara manual. Berikut adalah beberapa yang kami gunakan:

  • Penampil Microsoft Sarif (Web) memiliki fungsionalitas yang memungkinkan Anda menyeret dan meletakkan file SARIF Anda ke penampil, lalu menampilkan hasil yang dikategorikan menurut aturan. Penampil ini adalah cara cepat dan mudah untuk melihat jumlah pelanggaran atau kueri mana yang memiliki pelanggaran, tetapi hanya memberikan informasi terbatas di mana dalam kode sumber terjadi pelanggaran. Halaman tidak diperbarui jika tidak ada pelanggaran.

  • Penampil Microsoft SARIF untuk Visual Studio sangat bagus untuk menampilkan hasil dalam Visual Studio untuk transisi yang mulus dari hasil ke kode sumber.

  • Ekstensi SARIF untuk Visual Studio Code membuka panel pratinjau dan menampilkan kesalahan, peringatan, atau masalah yang dilaporkan oleh CodeQL. Untuk menampilkan file Sarif dalam format yang dapat dibaca, buka file di Visual Studio Code dan pilih Shift-Alt-F.

Bagian terpenting dari file SARIF adalah properti Results dalam objek Run. Setiap kueri memiliki properti Hasil dengan detail tentang setiap pelanggaran yang terdeteksi dan tempatnya terjadi. Jika tidak ada pelanggaran yang ditemukan, properti tersebut tidak memiliki nilai.

Kueri diklasifikasikan menggunakan status seperti kesalahan, peringatan, dan masalah. Namun, klasifikasi ini terpisah dari bagaimana Program Kompatibilitas Perangkat Keras Windows dan Uji Logo Alat Statis menilai hasilnya. Setiap driver yang cacat dari kueri apa pun dalam rangkaian Must-Fixtidak akan lulus Uji Logo Alat Statis dan akan gagal disertifikasi, terlepas dari klasifikasi kueri dalam file kueri mentah (misalnya, peringatan).

Konversi SARIF ke Format Log Verifikasi Driver (DVL)

Uji Logo Alat Statis mengurai Log Verifikasi Driver (DVL), yang merupakan hasil yang dikompilasi dari analisis statis CodeQL yang Anda jalankan pada kode sumber driver. Ada tiga cara untuk mengonversi file SARIF Anda ke format DVL: Visual Studio, MSBuild, atau dari baris perintah menggunakan alat dvl.exe . Untuk langkah-langkah lengkap, lihat Membuat Log Verifikasi Driver.

Instruksi lebih lanjut untuk Uji Static Tools Logo Hardware Lab Kit (HLK) dan panduan untuk lokasi penempatan file DVL dapat ditemukan dalam Menjalankan Uji Static Tools Logo.

Troubleshooting

Jika Anda mensertifikasi dengan WHCP, pertama-tama pastikan Anda menggunakan versi HLK yang terkait dengan rilis Windows yang Anda targetkan, cabang terkait di repositori Alat Tambahan Pengembang Driver Windows, dan versi CodeQL CLI berikutnya. Untuk matriks kompatibilitas Rilis HLK/Windows, lihat Windows Hardware Lab Kit dan untuk Windows Release/Windows Driver Developer Supplemental Tools cabang repositori/versi CLI CodeQL, lihat tabel WHCP di bagian Pilih versi CodeQL.

Kesalahan dan Solusi

Untuk masalah ketidakcocokan versi database , alat berikut mungkin berguna.

Gunakan perintah versi codeql untuk menampilkan versi codeql exe.

C:\codeql-home\codeql\>codeql version
CodeQL command-line toolchain release 2.4.0.
Copyright (C) 2019-2020 GitHub, Inc.
Unpacked in: C:\codeql-home\codeql\
   Analysis results depend critically on separately distributed query and
   extractor modules. To list modules that are visible to the toolchain,
   use 'codeql resolve qlpacks' and 'codeql resolve languages'.

Perintah peningkatan database memperbarui database. Peningkatan ini adalah salah satu cara dan tidak dapat dibalik. Untuk informasi selengkapnya, lihat peningkatan database.

Prosedur opsional

Secara opsional, Anda dapat menyembunyikan hasil CodeQL atau menjalankan prosedur pembentukan dan analisis sebagai peristiwa pasca build di Visual Studio.

Menyembunyikan Hasil CodeQL

CodeQL untuk pengendali mendukung penyembunyian hasil. Supresi saat ini disediakan sebagai kenyamanan untuk membantu pengembang melakukan triase masalah dan mengurangi kebisingan, bukan sebagai cara untuk melewati pemeriksaan Must-Fix . Mereka tidak berdampak pada pembuatan Log Verifikasi Driver atau lulus tes Logo Alat Statis saat ini. Untuk menggunakan supresi, Anda harus menjalankan kueri DriverAlertSuppression.ql secara bersamaan dengan kueri atau suite lain yang ingin Anda jalankan.

Untuk pemeriksaan yang di-port dari Analisis Kode, supresi Analisis Kode yang ada dihormati. Untuk informasi selengkapnya, lihat pragma peringatan C++.

  • Known limitation: Anda tidak dapat menggabungkan #pragma(nonaktifkan) dan #pragma(menekan) di baris yang sama saat ini.

Untuk pemeriksaan yang baru di CodeQL, nonaktifkan mereka dengan melakukan salah satu dari dua hal:

  • Tulis anotasi #pragma(suppress:the-rule-id-here) (tanpa tanda kutip) pada baris di atas pelanggaran, seperti yang Anda lakukan untuk Analisis Kode. Ganti "the-rule-id-here" dengan nilai @id dalam metadata kueri, yang dapat dilihat di bagian atas file.

  • Tulis komentar pada baris di atas yang terdiri dari teks "lgtm[the-rule-id-here]" (tanda kutip minus). Anda perlu menjalankan kueri supresi peringatan C/C++ standar alih-alih kueri supresi peringatan driver.

Setelah pembatalan ada dan dikenali, file SARIF yang dihasilkan menyertakan data bahwa hasil tersebut telah dibatalkan. Sebagian besar penampil hasil tidak menampilkan hasil yang disembunyikan secara default.

Peristiwa Pasca-Build Visual Studio

Jika Anda membangun driver menggunakan Visual Studio, Anda dapat mengonfigurasi kueri CodeQL untuk dijalankan sebagai peristiwa setelah pembangunan.

Dalam contoh ini, file batch kecil dibuat di lokasi target dan dipanggil sebagai peristiwa pasca-kompilasi. Untuk informasi selengkapnya tentang peristiwa build Visual Studio C++, lihat Menentukan peristiwa build.

  1. Buat file batch kecil yang membuat ulang database CodeQL lalu jalankan kueri yang diinginkan di dalamnya. Dalam contoh ini, file batch diberi nama RunCodeQLRebuildQuery.bat. Ubah jalur yang ditampilkan dalam contoh file batch agar sesuai dengan lokasi direktori Anda.

    ECHO ">>> Running CodeQL Security Rule V 1.0 <<<"
ECHO ">>> Removing previously created rules database <<<"
rmdir /s/q C:\codeql-home\databases\kmdf
CALL C:\codeql-home\codeql\codeql\codeql.cmd database create -l=cpp -s="C:\codeql-home\drivers\kmdf" -c "msbuild /p:Configuration=Release /p:Platform=x64 C:\codeql-home\drivers\kmdf\kmdfecho.sln /t:rebuild /p:PostBuildEventUseInBuild=false " "C:\codeql-home\databases\kmdf" -j 0
CALL C:\codeql-home\codeql\codeql\codeql database analyze "C:\codeql-home\databases\kmdf" "<path to query suite .qls file>" --format=sarifv2.1.0 --output=C:\codeql-home\databases\kmdf.sarif -j 0 --rerun
ECHO ">>> Loading SARIF Results in Visual Studio <<<"
CALL devenv /Edit C:\codeql-home\databases\kmdf.sarif
SET ERRORLEVEL = 0

  2. Opsi devenv.exe / Edit digunakan dalam file batch untuk membuka file hasil SARIF di instans Visual Studio yang ada. Untuk melihat hasil SARIF, instal Penampil Microsoft SARIF untuk Visual Studio dan lihat instruksi di sana untuk informasi selengkapnya.

  3. Dalam proyek driver, navigasikan ke properti proyek. Pada menu tarik-turun Konfigurasi, pilih konfigurasi build yang ingin Anda periksa dengan CodeQL - kami menyarankan untuk memilih Rilis. Membuat database CodeQL dan menjalankan kueri membutuhkan waktu beberapa menit, jadi kami tidak menyarankan Anda menjalankan CodeQL pada konfigurasi Debug proyek Anda.

  4. Pilih Build Events dan Peristiwa Setelah Build di properti proyek driver.

  5. Berikan jalur ke file batch dan deskripsi peristiwa setelah build.

Konfigurasi acara post build Visual Studio memperlihatkan file batch yang dikonfigurasi sebagai opsi baris perintah.

  1. Hasil file batch ditampilkan di akhir output build.

    1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\MistypedFunctionArguments.ql.
1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\TooManyArguments.ql.
1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\TooFewArguments.ql.
1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\ImplicitFunctionDeclaration.ql.
1>[1/4 eval 4.4s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\TooManyArguments.bqrs.
1>[2/4 eval 4.4s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\TooFewArguments.bqrs.
1>[3/4 eval 4.5s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\ImplicitFunctionDeclaration.bqrs.
1>[4/4 eval 5.2s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\MistypedFunctionArguments.bqrs.
1>Shutting down query evaluator.
1>Interpreting results.
1>">>> Loading SARIF Results in Visual Studio <<<"

Konten terkait

  • Last updated on