Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
CodeQL, geliştiricilerin Windows sürücü kaynak kodundaki güvenlik açıklarını ve kod ihlallerini tanımlamalarına yardımcı olan güçlü bir statik analiz altyapısıdır. Bu makalede, Windows Donanım Uyumluluk Programı (WHCP) sertifikası için Sürücü Doğrulama Dosyası oluşturmak üzere CodeQL analizinin nasıl kullanılacağı açıklanmaktadır.
Bu makalede şunları yapacaksınız:
- Uygun CodeQL sürümünü yükleyin.
- Gerekli CodeQL paketlerini ve sorgu paketlerini yükleyin.
- Veritabanı oluşturmak ve kodunuzu analiz etmek için CodeQL'i çalıştırın.
- Sürücü Doğrulama Dosyası oluşturun.
Sürücünüz için uygun CodeQL sürümünü seçin
Uyarı
Visual Studio (VS) 17.8, WHCP_21H2 ve WHCP_22H2 dallarında kullanılan CodeQL'in eski sürümleriyle uyumluluğu bozar. CodeQL CLI sürüm 2.15.4, Visual Studio 17.8 veya üzerini kullanırken WHCP 21H2 ve WHCP 22H2 ile kullanılmak üzere doğrulanır. Visual Studio 17.7 veya önceki sürümleri kullanırken, sürüm 2.4.6 veya sürüm 2.6.3 kullanın. WHCP Programı için, sertifikaladığınız CodeQL CLI sürümünü ve Windows sürümünü kullanın: sürüm 2.4.6, sürüm 2.6.3 veya sürüm 2.15.4. Ana dal ile genel kullanım için CodeQL CLI sürüm 2.15.4'i kullanın.
Senaryonuz için sekmeyi seçin:
İndirilecek sürümleri belirlemek için bu matrisi kullanın.
Windows Sürümü | CodeQL CLI sürümü | microsoft/windows-drivers CodeQL paketi sürümü | codeql/cpp-queries CodeQL paketi sürümü | Kullanılacak dal |
---|---|---|---|---|
Windows Server 2022 | 2.4.6 veya 2.15.4 | 1.0.13 (codeql 2.15.4 kullanılıyorsa) | 0.9.0 (codeql 2.15.4 kullanılıyorsa) | WHCP_21H2 |
Windows 11 | 2.4.6 veya 2.15.4 | 1.0.13 (codeql 2.15.4 kullanılıyorsa) | 0.9.0 (codeql 2.15.4 kullanılıyorsa) | WHCP_21H2 |
Windows 11, sürüm 22H2 | 2.6.3 veya 2.15.4 | 1.0.13 (codeql 2.15.4 kullanılıyorsa) | 0.9.0 (codeql 2.15.4 kullanılıyorsa) | WHCP_22H2 |
Windows 11, sürüm 23H2 | 2.6.3 veya 2.15.4 | 1.0.13 (codeql 2.15.4 kullanılıyorsa) | 0.9.0 (codeql 2.15.4 kullanılıyorsa) | WHCP_22H2 |
Windows 11, sürüm 24H2 | 2.15.4 | 1.1.0 | 0.9.0 | WHCP_24H2 |
Uyarı
CodeQL'in v2.7.0'dan sonraki sürümleri CodeQL paketlerini desteklediğinden CodeQL CLI 2.4.6 ve 2.6.3 için CodeQL paketinin sürümü belirtilmedi.
CodeQL'i İndirme ve Yükleme
CodeQL içeren bir dizin oluşturun. Bu örnekte
C:\codeql-home\
C:\> mkdir C:\codeql-home
Microsoft'un sürücü sorgularının istenen dalına uygun olarak hangi CodeQL CLI sürümünün kullanılacağını seçmek için önceki tablolara bakın. WHCP programının bir parçası olarak analiz gerçekleştiriyorsanız , Windows Donanım Uyumluluk Programı Kullanımı tablosuna bakın, aksi takdirde Main dalı ve 2.15.4 kullanın. Farklı bir sürüm kullanmak, veritabanının kitaplıklarla uyumsuz olmasına neden olabilir.
Önceki tablolarla ilişkilendirilmiş CodeQL CLI ikili dosyaları sürümüne gidin ve projenizin mimarisine uygun zip dosyasını indirin. Örneğin, 64 bit Windows codeql-win64.zip için.
Codeql CLI dizinini yeni oluşturduğunuz dizine ayıklayın; örneğin: *C:\codeql-home\codeql*.
Sürümü denetleyerek CodeQL'in doğru yüklendiğini doğrulayın:
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'.
CodeQL yardımı kullanma
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.
Belirli bir komutla ilgili yardım için codeql <command> --help komutunu çalıştırın. Örneğin:
codeql create --help
Alt komutlar için yardım almak için bunları hiyerarşik olarak listeleyin, örneğin
codeql create language --help
CodeQL Paketlerini Yükleme
Derleme ortamınız için sekmeyi seçin:
Visual Studio 2022 17.8 veya üzerini WHCP_21H2 veya WHCP_22H2 ve CodeQL CLI sürüm 2.15.4 ile kullanıyorsanız bu yordamı kullanın.
Uyarı
CodeQL testlerini CodeQL'in önceki bir sürümüyle çalıştırdıysanız, kopyalanan deponun eski bir sürümüne sahipseniz eski CodeQL alt modülünün kaldırdığınızdan emin olun. CodeQL, varsayılan olarak alt modüldeki sorguları kullanmayı deneyebilir ve bu da eşleşmeyen sürümler nedeniyle hatalara neden olabilir.
CodeQL sorgu paketlerini indirme
CodeQL, 2.7.0 sürümünde CodeQL Paketlerini (CodeQL paketleri veya sorgu paketleri) kullanıma seçerek sertifika sorgularını kullanmak için Windows-Driver-Developer-Supplemental-Tools deposunu kopyalama gereksinimini ortadan kaldırmıştı.
Uyarı
1. adımı atlamak mümkündür, bu --download
seçenek daha sonra analiz işlemini çalıştırırken gerekli sorguları indirir.
-
Windows Donanım Uyumluluk Programı Kullanım tablosundan microsoft/windows-drivers paketinin doğru sürümünü indirin. Aşağıdaki komutta
@<version>
öğesini belirtin.
C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>
Örneğin, WHCP_24H2 kullanıyorsanız aşağıdaki komutu çalıştırarak 1.1.0 windows-drivers sorgu paketini indirin:
C:\codeql-home\> codeql pack download microsoft/windows-drivers@1.1.0
CodeQL cpp-queries sorgu paketinin 0.9.0 sürümünü indirmek için bu komutu kullanın.
C:\codeql-home\> codeql pack download codeql/cpp-queries@0.9.0
CodeQL, sorgu paketlerini varsayılan dizine yükler:
C:\Users\<current user>\.codeql\packages\microsoft\windows-drivers\<downloaded version>\
Önemli
Yükleme dizinini değiştirmeyin veya yüklü sorgu paketini taşımayın.
Windows sürücü sorgu paketlerini indirme
Microsoft, uçtan uca sürücü geliştirici iş akışını basitleştirmek için iki sorgu paketi sağlar. windows_driver_recommended.qls paketi, Microsoft'un sürücü geliştiricileri için değerli bulduğu tüm sorguların üst kümesidir ve windows_driver_mustfix.qls paketi WHCP sertifikası için "Düzeltilmesi Gereken" olarak kabul edilen sorgular içerir. Statik Araçlar Logo Testi'ni geçirmek için windows_driver_mustfix.qls çalıştırılmalı ve geçirilmelidir.
İki sorgu paketi dosyasını https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/suites'den yerel bilgisayarınıza kopyalayın.
- windows_driver_recommended.qls
- windows_driver_mustfix.qls
Sorgu paketlerinin içeriğinin ayrıntıları için bkz. CodeQL Sorguları ve Paketleri.
CodeQL Veritabanı Oluşturma
Bu örneklerde Windows geliştirme ortamının kullanıldığı ve yükleme konumunun C:\codeql-home olduğu varsayılır, ancak size uygun kurulumu kullanabilirsiniz. Hangi derleyicilerin desteklendiğine ilişkin bir liste için bkz. CodeQL tarafından desteklenen diller ve çerçeveler .
Oluşturduğu veritabanlarını yerleştirmek için CodeQL için bir dizin oluşturun. Örneğin: C:\codeql-home\databases
mkdir C:\codeql-home\databases
Şu parametrelere sahip bir veritabanı oluşturmak için CodeQL komutunu kullanın:
- İlk parametre, veritabanı dizininize bir bağlantıdır. Örneğin, C:\codeql-home\databases\MyDriverDatabase. (Dizin zaten varsa bu komut başarısız olur.)
-
--language
veya-l
kaynak kodunuzun içinde olduğu dili veya dilleri belirtir. Bu, [cpp, javascript] gibi virgülle ayrılmış bir liste olabilir. -
--source
veya-s
kaynak kodunuzun yolunu belirtir. -
--command
veya-c
derleme komutunuzu veya derleme dosyanızın yolunu belirtir.
codeql database create <database directory> --language=<language> --source=<path to source code> --command=<build command or path to build file>
Örnekler
Tek sürücü örneği.
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"
Birden çok sürücü örneği.
C:\codeql-home\codeql> codeql database create D:\SampleDriversDatabase --language=cpp --source-root=D:\AllMyDrivers\SampleDrivers --command=D:\AllMyDrivers\SampleDrivers\BuildAllSampleDrivers.cmd
Komutunu kullanma database create
hakkında daha fazla bilgi veya yardım için bkz. CodeQL Veritabanları Oluşturma veya CodeQL Kullanma yardımı.
Analiz Gerçekleştirme
Bu noktada veritabanı oluşturma işlemi tamamlanır ve sonraki adım sürücü kaynak kodu üzerinde gerçek analizi gerçekleştirmektir.
Aşağıdaki parametreleri kullanarak veritabanınızı analiz etmek için CodeQL komutunu kullanın:
- İlk parametre, veritabanı dizininize bir bağlantıdır. Örneğin, C:\codeql-home\databases\MyDriverDatabase. (Not: Dizin yoksa bu komut başarısız olur.)
-
--download
flag, Sorguları çalıştırmadan önce CodeQL'e bağımlılıkları indirmesini söyler. -
--format
çıkış dosyasının dosya türüdür. Seçenekler şunlardır: SARIF ve CSV. (WHCP Kullanıcıları için SARIF biçimini kullanır.) -
--output
, çıkış dosyasını istediğiniz yerin yoludur, dosya adına biçimi eklediğinizden emin olun. (Dizin zaten yoksa bu komut başarısız olur.) - sorgu tanımlayıcıları parametresi, aşağıdakileri içerebilen bağımsız değişkenlerin boşlukla ayrılmış bir listesidir:
- sorgu dosyasına giden yol
- sorgu dosyalarını içeren bir dizinin yolu
- sorgu paketi dosyasının yolu
- CodeQL sorgu paketinin adı
codeql database analyze --download <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif
Örnek:
codeql database analyze --download D:\DriverDatabase suites/windows\_driver_recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif
Komutu kullanma
database analyze
hakkında daha fazla bilgi veya yardım için bkz. CodeQL CLI ile Veritabanlarını Çözümleme, CodeQL veritabanını analiz etmek için CodeQL paketi kullanma veya CodeQL kullanma yardımı.
Sonuçları Görüntüleme ve Yorumlama
Aşağıdaki adımlar için gerekli olduğu için bu bölüm için SARIF biçimine odaklanacağız, ancak ihtiyaçlarınıza daha uygunsa CSV biçimini kullanabilirsiniz.
Statik Çözümleme Sonuçları Değişim Biçimi (SARIF), statik analiz sonuçlarını paylaşmak için kullanılan bir JSON türü biçimidir. OASIS Statik Çözümleme Sonuçları Değişim Biçimi (SARIF), CodeQL'in SARIF Çıkışını nasıl kullandığı ve şema json'ı kullanarak standart hakkında daha fazla bilgi edinin.
Çözümleme sonuçlarını yorumlamak için nesneler arasında el ile sıralama da dahil olmak üzere çeşitli yöntemler vardır. Kullandığımız birkaç şey şunlardır:
Microsoft Sarif Viewer (Web), SARIF dosyanızı görüntüleyiciye sürükleyip bırakmanızı ve ardından kurala göre kategorilere ayrılmış sonuçları görüntülemenizi sağlayan işlevlere sahiptir. Bu, ihlal sayısını veya ihlalleri olan sorguları görmenin çok hızlı ve kolay bir yoludur, ancak satır numarası dışında kaynak kodu bilgilerini bulmak daha kolaydır. Herhangi bir ihlal yoksa sayfanın güncelleştirilmediğini unutmayın.
Visual Studio için Microsoft SARIF Görüntüleyicisi, sonuçlardan kaynak koda sorunsuz geçiş için sonuçları Visual Studio'da görüntülemek için mükemmeldir.
Visual Studio Code için SARIF uzantısı bir önizleme bölmesi açar ve CodeQL tarafından bildirilen hataları, uyarıları veya sorunları görüntüler. Sarif dosyasını okunabilir bir biçimde görüntülemek için dosyayı Visual Studio Code'da açın ve Shift-Alt-F'yi seçin.
SARIF dosyasının en önemli bölümü nesnenin Results
Run
içindeki özelliğidir. Her sorgu, algılanan ihlallerle ve nerede oluştuğuyla ilgili ayrıntıları içeren bir Results özelliğine sahip olur. İhlal bulunmazsa özellik değeri boş olur.
Sorgular hata, uyarı ve sorun gibi durumlar kullanılarak sınıflandırılır. Ancak bu sınıflandırma, Windows Donanım Uyumluluk Programı ve Statik Araçlar Logo Testi'nin sonuçları nasıl derecelediresinden ayrıdır. Must-Fix paketindeki herhangi bir sorgudan hata alan herhangi bir sürücü Statik Araçlar Logo Testi'ni geçmeyecek ve ham sorgu dosyasındaki sorgu sınıflandırmasına bakılmaksızın sertifikalanamaz (örneğin, uyarı).
SARIF'i Sürücü Doğrulama Günlüğü Biçimine (DVL) Dönüştürme
Statik Araçlar Logo Testi, sürücü kaynak kodunda çalıştırdığınız CodeQL statik analizinin derlenmiş sonucu olan bir Sürücü Doğrulama Günlüğünü (DVL) ayrıştırır. SARIF dosyanızı DVL biçimine dönüştürmenin üç yolu vardır: Visual Studio, MSBuild veya dvl.exe aracını kullanarak komut satırından. Tam adımlar için bkz . Sürücü Doğrulama Günlüğü Oluşturma.
Statik Araçlar Logo HLK Testi için diğer yönergeler ve DVL dosyasının nereye yerleştirileceğine ilişkin yönergeler Statik Araçlar Logo testini çalıştırma bölümünde bulunabilir.
Sorun giderme
WHCP sertifikası kullanıyorsanız öncelikle hedeflediğiniz Windows sürümüyle ilişkili HLK sürümünü, Windows Sürücü Geliştirici Ek Araçları deposundaki ilişkili dalı ve sonraki CodeQL CLI sürümünü kullandığınızdan emin olun. HLK/Windows Release uyumluluk matrisi için bkz. Windows Hardware Lab Kit ve Windows Release/Windows Driver Developer Supplemental Tools deposu dal/CodeQL CLI sürümü için CodeQL sürümünü seçme bölümündeki WHCP tablosuna bakın.
Hatalar ve Geçici Çözümler
Veritabanı sürümü uyuşmazlıkları sorunları için aşağıdaki araçlar yararlı olabilir.
codeql exe sürümünü görüntülemek için codeql version komutunu kullanın.
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'.
Veritabanı yükseltme komutu bir veritabanını güncelleştirir. Bunun tek yönlü bir yükseltme olduğunu ve geri alınamadığını unutmayın. Daha fazla bilgi için bkz. veritabanı yükseltmesi.
İsteğe bağlı prosedürler
İsteğe bağlı olarak, CodeQL sonuçlarını gizleyebilir veya derleme ve analiz yordamlarını Visual Studio'da derleme sonrası olay olarak çalıştırabilirsiniz.
CodeQL Sonuçlarını Gizleme
Sürücüler için CodeQL, sonuçları gizlemeyi destekler. Engellemeler şu anda geliştiricilerin sorunları önceliklendirmesine ve gürültüyü azaltmasına yardımcı olmak için bir kolaylık olarak sunulmaktadır; Bu, Düzeltilmesi Gereken denetimleri atlamanın bir yolu olarak değildir. Şu anda Sürücü Doğrulama Günlüğü oluşturma veya Statik Araçlar Logo testini geçirme üzerinde hiçbir etkisi yoktur. Gizlemeleri kullanmak için DriverAlertSuppression.ql sorgusunu çalıştırmak istediğiniz diğer sorgularla veya paketlerle aynı anda çalıştırmanız gerekir. Bu sorgu, githubs ana/geliştirme dalımızdan paketlerimizi çalıştırırken varsayılan olarak etkinleştirilir.
Kod Analizi'nden geçirilen denetimler için mevcut Kod Analizi engellemeleri kabul edilir. Daha fazla bilgi için bkz. C++ uyarı pragması.
-
Known limitation:
Şu anda bir #pragma (devre dışı bırakma) ve #pragma (gizleme) aynı satırda birleştiremezsiniz.
CodeQL'de yeni olan denetimler için iki işlemden birini yaparak bunları gizleyin:
Kod Analizi için yaptığınız gibi ihlalin üzerindeki satıra bir
#pragma(suppress:the-rule-id-here)
ek açıklama (tırnak işareti olmadan) yazın. "The-rule-id-here" değerini, dosyanın üst kısmında görüntülenebilen sorgunun@id
meta verilerindeki değerle değiştirin.Yukarıdaki satıra "lgtm[the-rule-id-here]" (eksi tırnak işareti) metninden oluşan bir açıklama yazın. Sürücü uyarısı gizleme sorgusu yerine standart C/C++ uyarı gizleme sorgusunu çalıştırmanız gerekir.
Bir gizleme mevcut ve tanındıktan sonra, sonuçta elde edilen SARIF dosyası bir sonucun gizlendiği verileri içerir ve sonuç görüntüleyicilerinin çoğu varsayılan olarak sonucu göstermez.
Visual Studio Derleme Sonrası Olay
Visual Studio kullanarak sürücüyü oluşturuyorsanız CodeQL sorgularını derleme sonrası olay olarak çalışacak şekilde yapılandırabilirsiniz.
Bu örnekte, hedef konumda küçük bir toplu iş dosyası oluşturulur ve derleme sonrası olay olarak çağrılır. Visual Studio C++ derleme olayları hakkında daha fazla bilgi için bkz. Derleme olaylarını belirtme.
CodeQL veritabanını yeniden oluşturan ve ardından üzerinde istenen sorguları çalıştıran küçük bir toplu iş dosyası oluşturun. Bu örnekte, toplu iş dosyası olarak adlandırılacaktır
RunCodeQLRebuildQuery.bat
. Örnek toplu iş dosyasında gösterilen yolları dizin konumlarınızla eşleşecek şekilde değiştirin.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
devenv.exe / Düzenle seçeneği, SARIF sonuç dosyasını mevcut Visual Studio örneğinde açmak için toplu iş dosyasında kullanılır. SARIF sonuçlarını görüntülemek için Visual Studio için Microsoft SARIF Görüntüleyicisi'ni yükleyin ve daha fazla bilgi için buradaki yönergelere bakın.
Sürücü projesinde proje özellikleri'ne gidin. Yapılandırma açılır menüsünde CodeQL ile denetlemek istediğiniz derleme yapılandırmasını seçin. Yayın yapmanızı öneririz. CodeQL veritabanının oluşturulması ve sorguların çalıştırılması birkaç dakika sürer, bu nedenle Projenizin Hata Ayıklama yapılandırmasında CodeQL çalıştırmanızı önermeyiz.
Sürücü projesi özelliklerinde Derleme Olayları ve Derleme Sonrası Olay'ı seçin.
Toplu iş dosyasının yolunu ve derleme sonrası olayının açıklamasını sağlayın.
Toplu iş dosyası sonuçları, derleme çıkışının sonunda görüntülenir.
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 <<<"