Sdílet prostřednictvím

Spuštění analýzy CodeQL v kódu ovladače systému Windows

CodeQL je výkonný statický analytický modul, který vývojářům pomáhá identifikovat ohrožení zabezpečení a porušení kódu ve zdrojovém kódu ovladače systému Windows. Tento článek vysvětluje, jak pomocí analýzy CodeQL vytvořit ověřovací soubor ovladače pro certifikaci programu WHCP (Windows Hardware Compatibility Program).

V tomto článku:

  • Nainstalujte odpovídající verzi CodeQL.
  • Nainstalujte potřebné balíčky CodeQL a sady dotazů.
  • Spuštěním CodeQL sestavte databázi a analyzujte kód.
  • Sestavte ověřovací soubor ovladače.

Vyberte odpovídající verzi CodeQL pro ovladač.

Note

Visual Studio (VS) 17.8 přerušilo kompatibilitu se staršími verzemi CodeQL používanými ve větvích WHCP_21H2 a WHCP_22H2. CodeQL CLI verze 2.15.4 se ověřuje pro použití s WHCP 21H2 a WHCP 22H2 při použití sady Visual Studio 17.8 nebo novější. Při použití sady Visual Studio 17.7 nebo starší použijte verzi 2.4.6 nebo 2.6.3. Pro program WHCP použijte verzi Rozhraní příkazového řádku CodeQL a verzi Windows, pro kterou certifikujete – verze 2.4.6, verze 2.6.3 nebo verze 2.15.4. Pro obecné použití s hlavní větví použijte CodeQL CLI verze 2.15.4.

Vyberte záložku pro váš scénář.

Tuto matici použijte k určení verzí, které se mají stáhnout.

Vydání Windows Verze rozhraní příkazového řádku CodeQL Microsoft/Windows-drivers CodeQL balíček verze Microsoft/cpp-queries CodeQL balíček verze Codeql/cpp-queries version Přidružená větev úložiště, která se má použít
Windows Server 2022 2.4.6 nebo 2.15.4 1.0.13 (Pokud používáte codeql 2.15.4) N/A 0.9.0 (Pokud používáte codeql 2.15.4) WHCP_21H2
Windows 11 2.4.6 nebo 2.15.4 1.0.13 (Pokud používáte codeql 2.15.4) N/A 0.9.0 (Pokud používáte codeql 2.15.4) WHCP_21H2
Windows 11, verze 22H2 2.6.3 nebo 2.15.4 1.0.13 (Pokud používáte codeql 2.15.4) N/A 0.9.0 (Pokud používáte codeql 2.15.4) WHCP_22H2
Windows 11, verze 23H2 2.6.3 nebo 2.15.4 1.0.13 (Pokud používáte codeql 2.15.4) N/A 0.9.0 (Pokud používáte codeql 2.15.4) WHCP_22H2
Windows 11 verze 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 verze 25H2 2.20.1 1.6.0 0.0.4 N/A WHCP_25H2

Note

Verze balíčku CodeQL není určena pro CodeQL CLI 2.4.6 a 2.6.3, protože pouze verze CodeQL novější než v2.7.0 podporují balíčky CodeQL.

Verze CodeQL ověřené pro použití s WHCP

Nejnovější informace o verzi, včetně testování nejnovějších ve vývoji, najdete v doplňkových nástrojích pro vývojáře ovladačů windows.

Verze rozhraní příkazového řádku CodeQL
2.21.4
2.21.2
2.20.1
2.15.4

Stažení a instalace codeQL

  1. Vytvořte adresář, který bude obsahovat CodeQL. Tento příklad používá C:\codeql-home\

    C:\> mkdir C:\codeql-home

  2. Projděte si předchozí tabulky a vyberte verzi rozhraní příkazového řádku CodeQL, která se má použít v souladu s požadovanou větví dotazů ovladače Microsoftu. Pokud provádíte analýzu jako součást programu WHCP, přečtěte si tabulku Použití programu Kompatibilita hardwaru systému Windows, jinak použijte hlavní větev a 2.15.4. Použití jiné verze může vést k tomu, že databáze není kompatibilní s knihovnami.

  3. Přejděte do verze binárních souborů rozhraní příkazového řádku CodeQL přidruženou k předchozím tabulkám a stáhněte soubor ZIP v souladu s architekturou vašeho projektu. Například pro 64bitovou verzi Systému Windows codeql-win64.zip.

  4. Extrahujte adresář CodeQL CLI do adresáře, který jste právě vytvořili, například C:\codeql-home\codeql\.

  5. Ověřte, že je CodeQL správně nainstalovaný, a to kontrolou verze:

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

Použití nápovědy 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.

Nápovědu ke konkrétnímu příkazu můžou získat spuštěním příkazu< codeql >--help. Například:

codeql create --help

Pokud chcete získat nápovědu pro dílčí příkazy, vypíšete je hierarchicky, například

codeql create language --help

Instalace balíčků CodeQL

Vyberte záložku pro vaše build prostředí

Tento postup použijte, pokud používáte Visual Studio 2022 17.8 nebo vyšší s WHCP_21H2 nebo WHCP_22H2 a CodeQL CLI verze 2.15.4.

Note

Pokud jste spustili testy CodeQL se starší verzí CodeQL, nezapomeňte původní dílčí modul CodeQL odebrat, pokud stále máte starou verzi klonovaného úložiště. CodeQL se může ve výchozím nastavení pokusit použít dotazy v dílčím modulu, což může způsobit chyby kvůli neshodě verzí.

Stažení balíčků dotazů CodeQL

CodeQL zavedl balíčky CodeQL (balíčky CodeQL nebo balíčky dotazů) ve verzi 2.7.0, což eliminuje nutnost klonovat úložiště Windows-Driver-Developer-Supplemental-Tools pro použití dotazů k certifikaci.

Note

Krok 1 je možné přeskočit, protože --download možnost stáhne všechny potřebné dotazy později při spuštění procesu analýzy.

  1. Stáhněte si správnou verzi sady microsoft/windows-drivers pack z tabulky Použití programu kompatibility hardwaru systému Windows . Zadejte @<version> v následujícím příkazu.
C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>

Pokud například používáte WHCP_24H2, spusťte následující příkaz, který stáhne balíček dotazů ovladače windows 1.1.0:

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

Tento příkaz použijte ke stažení verze 0.9.0 balíčku dotazů cpp-querys CodeQL.

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

CodeQL nainstaluje balíčky dotazů do výchozího adresáře:

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

Important

Neměňte instalační adresář ani nepřesouvejte nainstalovaný balíček dotazů.

Stažení sad dotazů ovladačů systému Windows

Microsoft poskytuje dvě sady dotazů pro zjednodušení kompletního pracovního postupu vývojáře ovladačů. Sada recommended.qls je nadmnožinou všech dotazů, které Microsoft považuje za cenné pro vývojáře ovladačů, a sada mustfix.qls obsahuje dotazy, které se považují za "Must-Fix" pro certifikaci WHCP. mustfix.qls musí být spuštěn a předán, aby bylo možné předat test loga Statických nástrojů.

Zkopírujte dva soubory sady dotazů z https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/src/windows-driver-suites místního počítače.

  • recommended.qls
  • mustfix.qls

Podrobnosti o obsahu sad dotazů najdete v tématu Dotazy a sady CodeQL.

Sestavení databáze CodeQL

Tyto příklady předpokládají použití vývojového prostředí Windows a že umístění instalace je C:\codeql-home, ale můžete použít nastavení, které vám vyhovuje. Seznam podporovaných kompilátorů najdete v podporovaných jazycích a architekturách CodeQL .

  1. Vytvořte adresář pro CodeQL pro umístění databází, které vytvoří. Příklad: C:\codeql-home\databases

    mkdir C:\codeql-home\databases

  2. Pomocí příkazu CodeQL vytvořte databázi s těmito parametry:

    • Prvním parametrem je odkaz na adresář databáze. Například C:\codeql-home\databases\MyDriverDatabase. (Tento příkaz selže, pokud adresář již existuje.)
    • --language nebo -l určuje jazyk nebo jazyky, ve které je váš zdrojový kód. Může to být čárkami oddělený seznam, například [cpp, javascript].
    • --source-root nebo -s určuje cestu ke zdrojovému kódu.
    • --command nebo -c určuje příkaz sestavení nebo cestu k souboru sestavení.
    codeql database create <path to new database> --language=<cpp> --source-root=<driver parent directory> --command=<build command or path to build file>

Examples

Příklad jednoho ovladače

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"

Příklad více ovladačů

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

Další informace nebo nápovědu database create k použití příkazu naleznete v tématu Vytváření databází CodeQL nebo Použití nápovědy CodeQL.

Provést analýzu

V tomto okamžiku je vytvoření databáze dokončeno a dalším krokem je provést skutečnou analýzu zdrojového kódu ovladače.

  1. Pomocí příkazu CodeQL analyzujte databázi pomocí následujících parametrů:

    • Prvním parametrem je odkaz na adresář databáze. Například C:\codeql-home\databases\MyDriverDatabase. (Poznámka: Tento příkaz selže, pokud adresář neexistuje.)
    • --format je typ souboru výstupního souboru. Mezi možnosti patří: SARIF a CSV. (Pro uživatele WHCP se používá formát SARIF.)
    • --output je cesta k umístění, kam chcete výstupní soubor, nezapomeňte do názvu souboru zahrnout formát. (Tento příkaz selže, pokud adresář ještě neexistuje.)
    • Parametr specifikátorů dotazu je seznam argumentů oddělených mezerami, mezi které patří:
      • cesta k souboru dotazu
      • cesta k adresáři obsahujícímu soubory dotazů
      • cesta k souboru sady dotazů
      • název balíčku dotazů 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

    Další informace nebo nápovědu database analyze k použití příkazu najdete v tématu Analýza databází pomocí rozhraní příkazového řádku CodeQL, použití balíčku CodeQL k analýze databáze CodeQL nebo použití nápovědy CodeQL.

Zobrazení a interpretace výsledků

Zaměříme se na formát SARIF pro tuto část, protože je to, co je potřeba pro následující kroky, i když vítáte použití formátu CSV, pokud vyhovuje vašim potřebám lépe.

Formát SARIF (Static Analysis Results Interchange Format) je formát typu JSON používaný ke sdílení výsledků statické analýzy. Přečtěte si další informace o standardu ve formátu SARIF (Static Analysis Results Interchange Format), jak CodeQL používá výstup SARIF a json schématu.

Existuje několik metod interpretace výsledků analýzy, včetně ručního řazení objektů. Tady je několik, které používáme:

  • Microsoft Sarif Viewer (Web) má funkce, které umožňují přetáhnout soubor SARIF do prohlížeče a pak zobrazí výsledky zařazené podle pravidla. Jedná se o velmi rychlý a snadný způsob, jak zobrazit počet porušení nebo které dotazy mají porušení, ale méně snadné najít informace o zdrojovém kódu kromě čísla řádku. Pokud nedojde k narušení, stránka se neaktualizuje.

  • Microsoft SARIF Viewer pro Visual Studio je skvělý pro zobrazení výsledků v sadě Visual Studio pro bezproblémový přechod z výsledků na zdrojový kód.

  • Rozšíření SARIF pro Visual Studio Code otevře podokno náhledu a zobrazí všechny chyby, upozornění nebo problémy hlášené CodeQL. Pokud chcete soubor Sarif zobrazit ve čitelném formátu, otevřete ho v editoru Visual Studio Code a vyberte Shift-Alt-F.

Nejdůležitější částí souboru SARIF je Results vlastnost uvnitř objektu Run . Každý dotaz bude mít vlastnost Výsledky s podrobnostmi o případných detekovaných porušeních a o tom, kde k němu došlo. Pokud nenajdeme žádná porušení, hodnota vlastnosti bude prázdná.

Dotazy se klasifikují pomocí stavů, jako je chyba, upozornění a problém. Tato klasifikace je však oddělená od toho, jak program kompatibility hardwaru systému Windows a Logo test statických nástrojů hodnotí výsledky. Jakýkoli ovladač s vadami z jakéhokoli dotazu v sadě Must-Fixneprojde testem loga Statických nástrojů a nebude certifikovaný bez ohledu na klasifikaci dotazu v nezpracovaného souboru dotazu (například upozornění).

Převod SARIF na formát protokolu ověření ovladače (DVL)

Test loga Statických nástrojů analyzuje protokol ověření ovladače (DVL), což je zkompilovaný výsledek statické analýzy CodeQL, kterou spustíte ve zdrojovém kódu ovladače. Existují tři způsoby, jak převést soubor SARIF do formátu DVL: Visual Studio, MSBuild nebo z příkazového řádku pomocí nástrojedvl.exe . Úplný postup najdete v tématu Vytvoření protokolu ověření ovladače.

Další pokyny pro test loga Statické nástroje HLK a pokyny k umístění souboru DVL najdete v Spuštění testu loga statických nástrojů.

Troubleshooting

Pokud certifikujete s WHCP, nejprve se ujistěte, že používáte verzi HLK přidruženou k verzi Windows, na kterou cílíte, přidruženou větev v úložišti Windows Driver Developer Supplemental Tools a další verzi rozhraní příkazového řádku CodeQL. Informace o matici kompatibility HLK/Windows Release naleznete v tématu Windows Hardware Lab Kit a pro úložiště Windows Release/Windows Driver Developer Supplemental Tools, branch/CodeQL CLI verzi, viz tabulka WHCP v části Vyberte verzi CodeQL.

Chyby a alternativní řešení

V případě problémů s neshodou verzí databáze můžou být užitečné následující nástroje.

Pomocí příkazu codeql version zobrazte verzi souboru 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'.

Příkaz pro upgrade databáze aktualizuje databázi. Mějte na paměti, že se jedná o jednosměrný upgrade a není nevratný. Další informace najdete v tématu Upgrade databáze.

Volitelné procedury

Volitelně můžete potlačit výsledky CodeQL nebo spustit procedury sestavení a analýzy jako událost po sestavení v sadě Visual Studio.

Potlačení výsledků funkcí CodeQL

CodeQL pro ovladače podporuje potlačení výsledků. Potlačení jsou v současné době poskytována jako užitečný nástroj, který pomáhá vývojářům nastavovat priority problémů a snižovat zbytečný šum, ne jako způsob, jak obejít povinné kontroly Must-Fix. V současnosti nemají žádný vliv na generování protokolu ověření ovladače ani na test loga statických nástrojů. Pokud chcete použít potlačení, musíte spustit dotaz DriverAlertSuppression.ql současně s ostatními dotazy nebo sadami, které chcete spustit. Ve výchozím nastavení je tento dotaz povolený při spouštění našich sad z hlavní/vývojové větve GitHubs.

U kontrol přenesených z Analýzy kódu budou zachována stávající potlačení. Další informace viz pragma upozornění v C++.

  • Known limitation: Momentálně nelze kombinovat #pragma(disable) a #pragma(suppress) na stejném řádku.

Pokud jde o kontroly, které jsou nové pro CodeQL, můžete je potlačit jedním ze dvou způsobů:

  • Na řádku nad porušením napište poznámku #pragma(suppress:the-rule-id-here) (bez uvozovek), stejně jako v případě analýzy kódu. Nahraďte "the-rule-id-here" @id hodnotou v metadatech dotazu, která se dá zobrazit v horní části souboru.

  • Napište komentář na řádek výše složený z textu "lgtm[the-rule-id-here]" (minus uvozovky). Místo dotazu na potlačení upozornění ovladače budete muset spustit standardní dotaz potlačení upozornění C/C++ .

Jakmile je potlačení přítomno a rozpoznáno, výsledný soubor SARIF bude obsahovat data o tom, že výsledek byl potlačen, a většina prohlížečů výsledků ve výchozím nastavení nezobrazí výsledek.

Událost po sestavení sady Visual Studio

Pokud vytváříte ovladač pomocí sady Visual Studio, můžete nakonfigurovat dotazy CodeQL tak, aby se spouštěly jako událost po sestavení.

V tomto příkladu se v cílovém umístění vytvoří malý dávkový soubor a použije se k volání jako událost po sestavení. Další informace o událostech sestavení v sadě Visual Studio C++ naleznete v tématu Určení událostí sestavení.

  1. Vytvořte malý dávkový soubor, který znovu vytvoří databázi CodeQL a potom na ní spustí požadované dotazy. V tomto příkladu bude dávkový soubor pojmenován RunCodeQLRebuildQuery.bat. Upravte cesty zobrazené v ukázkovém dávkovém souboru tak, aby odpovídaly umístění adresářů.

    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. Možnost devenv.exe / Upravit se používá v dávkovém souboru k otevření souboru výsledků SARIF v existující instanci sady Visual Studio. Pokud chcete zobrazit výsledky SARIF, nainstalujte prohlížeč Microsoft SARIF pro Visual Studio a další informace najdete v pokynech.

  3. V projektu ovladače přejděte na vlastnosti projektu. V rozevírací nabídce Konfigurace vyberte konfiguraci sestavení, kterou chcete zkontrolovat pomocí CodeQL – doporučujeme Release. Vytvoření databáze CodeQL a spuštění dotazů trvá několik minut, takže nedoporučujeme spouštět CodeQL v konfiguraci ladění projektu.

  4. Ve vlastnostech projektu ovladače vyberte Události sestavení a Událost po sestavení .

  5. Zadejte cestu k dávkovému souboru a popis události po sestavení.

Konfigurace události po sestavení sady Visual Studio zobrazující dávkový soubor nakonfigurovaný jako možnost příkazového řádku

  1. Výsledky dávkového souboru se zobrazí na konci výstupu sestavení.

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

Související obsah

  • Last updated on