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 untuk - versi 2.4.6, versi 2.6.3, atau versi 2.15.4. Untuk penggunaan umum dengan cabang utama, gunakan CodeQL CLI versi 2.15.4.

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 repositori terkait yang akan digunakan
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.6.0 0.0.4 N/A WHCP_25H2
Windows 11, versi 25H2 2.20.1 1.6.0 0.0.4 N/A WHCP_25H2

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.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 2.15.4. 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 baru saja 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 dengan WHCP_21H2 atau WHCP_22H2 dan CodeQL CLI versi 2.15.4.

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.

Note

Dimungkinkan untuk melewati langkah 1, karena opsi --download mengunduh kueri yang diperlukan kemudian saat menjalankan proses analisis.

  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 menggunakan WHCP_24H2, jalankan perintah berikut untuk mengunduh paket kueri windows-driver 1.1.0:

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

Gunakan perintah ini untuk mengunduh paket kueri CodeQL cpp-queries versi 0.9.0.

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

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 terinstal.

Mengunduh suite kueri driver Windows

Microsoft menyediakan dua suite kueri untuk menyederhanakan alur kerja pengembang driver end-to-end. Suite recommended.qls adalah superset dari semua kueri yang dianggap berharga oleh Microsoft untuk pengembang driver, dan suite mustfix.qls mengandung kueri yang dianggap "Harus Diperbaiki" untuk WHCP sertifikasi. mustfix.qls harus dijalankan dan lulus agar dapat melewati Tes Logo Alat Statis.

Salin dua file rangkaian kueri dari https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/src/windows-driver-suites ke PC lokal Anda.

  • recommended.qls
  • mustfix.qls

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. Ini bisa 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 suites/windows\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

Kami akan berfokus pada format SARIF untuk bagian ini karena inilah yang diperlukan untuk langkah-langkah berikut, meskipun Anda dipersilakan untuk menggunakan format CSV jika sesuai dengan kebutuhan Anda dengan lebih baik.

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. Ini adalah cara yang sangat cepat dan mudah untuk melihat jumlah pelanggaran atau kueri mana yang memiliki pelanggaran, tetapi kurang mudah untuk menemukan informasi kode sumber selain dari nomor baris. Perhatikan bahwa halaman tidak akan 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 akan memiliki properti Hasil dengan detail tentang setiap pelanggaran yang terdeteksi dan tempatnya terjadi. Jika tidak ada pelanggaran yang ditemukan, nilai properti akan kosong.

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 Logo Alat Statis HLK dan panduan tentang tempat menempatkan file DVL tersebut dapat ditemukan di dalam Menjalankan pengujian Logo Alat Statis.

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 akan memperbarui database. Ketahuilah bahwa ini adalah peningkatan satu arah dan tidak dapat dibatalkan. 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. Secara default, kueri ini diaktifkan saat menjalankan suite kami dari cabang utama/pengembangan githubs kami.

Untuk pemeriksaan yang telah di-port dari Analisis Kode, pembatalan Analisis Kode yang ada akan dipatuhi. Untuk informasi selengkapnya, lihat pragma peringatan C++.

  • Known limitation: Anda tidak dapat menggabungkan #pragma(disable) dan #pragma(suppress) 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 harus menjalankan kueri penekanan peringatan standar C/C++ daripada kueri penekanan peringatan driver.

Setelah penyembunyian ada dan dikenali, file SARIF yang dihasilkan akan menyertakan data bahwa hasil telah disembunyikan, dan sebagian besar peninjau hasil secara default tidak akan menunjukkan hasilnya.

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 akan 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