Dela via

Kör CodeQL-analys på Windows-drivrutinskoden

CodeQL är en kraftfull statisk analysmotor som hjälper utvecklare att identifiera säkerhetsrisker och kodöverträdelser i Windows-drivrutins källkod. Den här artikeln beskriver hur du använder CodeQL-analys för att skapa en drivrutinsverifieringsfil för WHCP-certifiering (Windows Hardware Compatibility Program).

I den här artikeln kommer du att:

  • Installera lämplig CodeQL-version.
  • Installera nödvändiga CodeQL-paket och frågepaket.
  • Kör CodeQL för att skapa en databas och analysera koden.
  • Skapa en drivrutinsverifieringsfil.

Välj lämplig CodeQL-version för drivrutinen

Note

Visual Studio (VS) 17.8 bröt kompatibiliteten med äldre versioner av CodeQL som används i grenarna WHCP_21H2 och WHCP_22H2. CodeQL CLI version 2.15.4 verifieras för användning med WHCP 21H2 och WHCP 22H2 när du använder Visual Studio 17.8 eller senare. När du använder Visual Studio 17.7 eller tidigare använder du version 2.4.6 eller version 2.6.3. För WHCP-programmet använder du den CodeQL CLI-version och Windows-version som du certifierar för – version 2.4.6, version 2.6.3 eller version 2.15.4. Använd CodeQL CLI version 2.15.4 för allmän användning med huvudgrenen.

Välj fliken för ditt scenario:

Använd den här matrisen för att fastställa vilka versioner som ska laddas ned.

Windows-utgåva CodeQL CLI-version microsoft/windows-drivers CodeQL-paketversion microsoft/cpp-queries CodeQL-paketversion codeql/cpp-queries version Associerad lagringsplatsgren att använda
Windows Server 2022 2.4.6 eller 2.15.4 1.0.13 (Om du använder codeql 2.15.4) N/A 0.9.0 (Om du använder codeql 2.15.4) WHCP_21H2
Windows 11 2.4.6 eller 2.15.4 1.0.13 (Om du använder codeql 2.15.4) N/A 0.9.0 (Om du använder codeql 2.15.4) WHCP_21H2
Windows 11, version 22H2 2.6.3 eller 2.15.4 1.0.13 (Om du använder codeql 2.15.4) N/A 0.9.0 (Om du använder codeql 2.15.4) WHCP_22H2
Windows 11, version 23H2 2.6.3 eller 2.15.4 1.0.13 (Om du använder codeql 2.15.4) N/A 0.9.0 (Om du använder codeql 2.15.4) WHCP_22H2
Windows 11, version 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, version 25H2 2.20.1 1.6.0 0.0.4 N/A WHCP_25H2

Note

En version av CodeQL-paketet har inte angetts för CodeQL CLI 2.4.6 och 2.6.3 eftersom endast versioner av CodeQL senare än v2.7.0 stöder CodeQL-paket.

CodeQL-versioner som verifierats för användning med WHCP

Den senaste versionsinformationen, inklusive testning av det senaste under utveckling, finns i Tilläggsverktyg för Windows-drivrutinsutvecklare.

CodeQL CLI-version
2.21.4
2.21.2
2.20.1
2.15.4

Ladda ned och installera CodeQL

  1. Skapa en katalog som ska innehålla CodeQL. I det här exemplet används C:\codeql-home\

    C:\> mkdir C:\codeql-home

  2. Se föregående tabeller för att välja vilken version av CodeQL CLI som ska användas i enlighet med den önskade grenen av Microsofts drivrutinsfrågor. Om du utför analys som en del av WHCP-programmet läser du tabellen För användning av Windows maskinvarukompatibilitetsprogram, annars använder du Main-grenen och 2.15.4. Om du använder en annan version kan det leda till att en databas är inkompatibel med biblioteken.

  3. Gå till CodeQL CLI-binärversion som är associerad med de tidigare tabellerna och ladda ned zip-filen i enlighet med projektets arkitektur. Till exempel för 64-bitars Windows codeql-win64.zip.

  4. Extrahera Codeql CLI-katalogen till den du nyss skapade, till exempel : C:\codeql-home\codeql\.

  5. Kontrollera att CodeQL är korrekt installerat genom att kontrollera versionen:

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

Använda CodeQL-hjälp

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.

Om du vill ha hjälp med ett specifikt kommando kör du codeql-kommandot <> --help. Till exempel:

codeql create --help

Om du vill få hjälp med underkommandon listar du dem hierarkiskt, till exempel

codeql create language --help

Installera CodeQL-paketen

Välj fliken för din byggmiljö:

Använd den här proceduren om du använder Visual Studio 2022 17.8 eller senare med WHCP_21H2 eller WHCP_22H2 och CodeQL CLI version 2.15.4.

Note

Om du körde CodeQL-tester med en tidigare version av CodeQL ska du ta bort den gamla CodeQL-undermodulen om du fortfarande har en gammal version av den klonade lagringsplatsen. CodeQL kan försöka använda frågorna i undermodulen som standard, vilket kan orsaka fel på grund av felaktiga versioner.

Ladda ned CodeQL-frågepaketen

CodeQL introducerade CodeQL-paket (CodeQL-paket eller frågepaket) i version 2.7.0, vilket eliminerar behovet av att klona lagringsplatsen Windows-Driver-Developer-Supplemental-Tools för att använda frågorna för certifiering.

Note

Du kan hoppa över steg 1 eftersom --download alternativet laddar ned alla nödvändiga frågor senare när du kör analysprocessen.

  1. Ladda ned rätt version av microsoft/windows-drivers-paketet från tabellen Windows Hardware Compatibility Program Use . Specificera @<version> i följande kommando.
C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>

Om du till exempel använder WHCP_24H2 kör du följande kommando för att ladda ned frågepaketet 1.1.0 windows-drivers:

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

Använd det här kommandot för att ladda ned version 0.9.0 av frågepaketet CodeQL cpp-querys.

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

CodeQL installerar frågepaketen i standardkatalogen:

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

Important

Ändra inte installationskatalogen eller flytta det installerade frågepaketet.

Ladda ned Windows-drivrutinsfrågepaketen

Microsoft tillhandahåller två frågepaket för att förenkla arbetsflödet för utvecklare från slutpunkt till slutpunkt. Den rekommenderade.qls-sviten är en superuppsättning av alla frågor som Microsoft anser vara värdefulla för drivrutinsutvecklare, och mustfix.qls-sviten innehåller frågor som anses vara "Must-Fix" för WHCP-certifiering . mustfix.qls måste köras och skickas för att klara logotestet för statiska verktyg.

Kopiera de två frågesvitfilerna från https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/src/windows-driver-suites till din lokala dator.

  • recommended.qls
  • mustfix.qls

Mer information om innehållet i frågesviterna finns i CodeQL-frågor och sviter.

Skapa CodeQL-databasen

De här exemplen förutsätter användning av en Windows-utvecklingsmiljö och att installationsplatsen är C:\codeql-home, men du kan använda den konfiguration som passar dig. En lista över vilka kompilatorer som stöds finns i Språk och ramverk som stöds av CodeQL .

  1. Skapa en katalog för CodeQL för att placera de databaser som skapas. Exempel: C:\codeql-home\databases

    mkdir C:\codeql-home\databases

  2. Använd CodeQL-kommandot för att skapa en databas med följande parametrar:

    • Den första parametern är en länk till din databaskatalog. Till exempel C:\codeql-home\databases\MyDriverDatabase. (Det här kommandot misslyckas om katalogen redan finns.)
    • --language eller -l anger det språk eller språk som källkoden finns i. Det kan vara en kommaavgränsad lista, till exempel [cpp, javascript].
    • --source-root eller -s anger sökvägen till källkoden.
    • --command eller -c anger byggkommandot eller sökvägen till byggfilen.
    codeql database create <path to new database> --language=<cpp> --source-root=<driver parent directory> --command=<build command or path to build file>

Examples

Exempel på enskild förare.

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"

Exempel på flera drivrutiner.

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

Mer information eller hjälp med att använda kommandot finns i database createSkapa CodeQL-databaser eller Använda CodeQL-hjälp.

Utföra analys

Nu är det klart att skapa databasen och nästa steg är att utföra den faktiska analysen av drivrutins källkoden.

  1. Använd CodeQL-kommandot för att analysera databasen med hjälp av följande parametrar:

    • den första parametern är en länk till din databaskatalog. Till exempel C:\codeql-home\databases\MyDriverDatabase. (Obs! Det här kommandot misslyckas om katalogen inte finns.)
    • --format är filtypen för utdatafilen. Alternativen är: SARIF och CSV. (För WHCP-användare använder du SARIF-format.)
    • --output är sökvägen till den plats där du vill ha utdatafilen, se till att inkludera formatet i filnamnet. (Det här kommandot misslyckas om katalogen inte redan finns.)
    • parametern query specifiers är en blankstegsavgränsad lista med argument som kan innehålla:
      • en sökväg till en frågefil
      • en sökväg till en katalog som innehåller frågefiler
      • en sökväg till en frågesvitfil
      • namnet på ett CodeQL-frågepaket
    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

    Mer information eller hjälp med att använda database analyze kommandot finns i Analysera databaser med CodeQL CLI, Använda ett CodeQL-paket för att analysera en CodeQL-databas eller Använda CodeQL-hjälp.

Visa och tolka resultat

Vi kommer att fokusera på SARIF-format för det här avsnittet eftersom det är vad som krävs för följande steg, även om du är välkommen att använda CSV-format om det passar dina behov bättre.

SARIF (Static Analysis Results Interchange Format) är ett JSON-typformat som används för att dela statiska analysresultat. Läs mer om standarden på OASIS Static Analysis Results Interchange Format (SARIF), hur CodeQL använder SARIF-utdata och schema-json.

Det finns flera metoder för att tolka analysresultaten, inklusive manuellt sortering genom objekten. Här är några som vi använder:

  • Microsoft Sarif Viewer (Web) har funktioner som gör att du kan dra och släppa din SARIF-fil i visningsprogrammet och sedan visa resultat kategoriserade efter regel. Det här är ett mycket snabbt och enkelt sätt att se antalet överträdelser eller vilka frågor som har överträdelser, men mindre enkelt att hitta källkodsinformation förutom radnumret. Observera att sidan inte uppdateras om det inte finns några överträdelser.

  • Microsoft SARIF Viewer för Visual Studio är perfekt för att visa resultaten i Visual Studio för sömlös övergång från resultat till källkod.

  • SARIF-tillägget för Visual Studio Code öppnar en förhandsgranskningsruta och visar eventuella fel, varningar eller problem som rapporterats av CodeQL. Om du vill visa Sarif-filen i ett läsbart format öppnar du filen i Visual Studio Code och väljer Skift-Alt-F.

Det viktigaste avsnittet i SARIF-filen är Results egenskapen i Run objektet. Varje fråga har en results-egenskap med information om eventuella identifierade överträdelser och var den inträffade. Om inga överträdelser hittas kommer egenskapsvärdet att vara tomt.

Frågor klassificeras med hjälp av statusar som fel, varning och problem. Den här klassificeringen skiljer sig dock från hur Windows Maskinvarukompatibilitetsprogram och Static Tools Logo Test betygsätter resultaten. Alla drivrutiner med defekter från en fråga i Must-Fix-paketetklarar inte logotestet för statiska verktyg och kommer inte att certifieras, oavsett frågeklassificeringen i den råa frågefilen (till exempel varning).

Konvertera SARIF till drivrutinsverifieringsloggformat (DVL)

Logotestet för statiska verktyg parsar en drivrutinsverifieringslogg (DVL), som är det kompilerade resultatet av den statiska CodeQL-analys som du kör på drivrutins källkoden. Det finns tre sätt att konvertera SARIF-filen till DVL-format: Visual Studio, MSBuild eller från kommandoraden med hjälp av verktygetdvl.exe . Fullständiga steg finns i Skapa en drivrutinsverifieringslogg.

Ytterligare instruktioner för HLK-test för statiska verktygslogotyp och vägledning om var du ska placera DVL-filen finns i Köra test av static tools-logotypen.

Troubleshooting

Om du certifierar med WHCP kontrollerar du först att du använder den HLK-version som är associerad med Windows-versionen som du riktar in dig på, den associerade grenen i lagringsplatsen tilläggsverktyg för Windows-drivrutinen och den efterföljande CodeQL CLI-versionen. Information om HLK/Windows Release-kompatibilitetsmatris finns i Windows Hardware Lab Kit och för Windows Release/Windows Driver Developer Supplemental Tools repo branch/CodeQL CLI-versionen. Mer information finns i WHCP-tabellen i avsnittet Välj CodeQL-version .

Fel och lösningar

För problem med matchning av databasversioner kan följande verktyg vara till hjälp.

Använd kommandot codeql-version för att visa versionen av 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'.

Kommandot för databasuppgradering uppdaterar en databas. Tänk på att detta är en enkelriktad uppgradering och inte är reversibel. Mer information finns i databasuppgradering.

Valfria procedurer

Du kan också utelämna CodeQL-resultat eller köra bygg- och analysprocedurerna som en händelse efter bygget i Visual Studio.

Utelämna CodeQL-resultat

CodeQL för drivrutiner stöder undertryckning av resultat. Undertryckningar tillhandahålls för närvarande som ett hjälpmedel för att hjälpa utvecklare att sortera problem och minska bruset, och inte som ett sätt att kringgå Must-Fix-kontrollerna. De har ingen inverkan på att generera en drivrutinsverifieringslogg eller klara det statiska verktyg-logotestet för närvarande. Om du vill använda undertryckningar måste du köra frågan DriverAlertSuppression.ql samtidigt som de andra frågorna eller sviterna som du vill köra. Som standard är den här frågan aktiverad när du kör våra sviter från vår githubs main/development-gren.

För kontroller som har överförts från kodanalys kommer befintliga undantag för kodanalys att respekteras. Mer information finns i C++-varnings pragma.

  • Known limitation: Du kan inte kombinera en #pragma(inaktivera) och #pragma(utelämna) på samma rad just nu.

För kontroller som är nya för CodeQL undertrycker du dem genom att göra en av två saker:

  • Skriv en #pragma(suppress:the-rule-id-here) anteckning (utan citattecken) på raden ovanför överträdelsen, som du gör för kodanalys. Ersätt "regeln-id-här" med @id värdet i frågans metadata, som kan visas överst i filen.

  • Skriv en kommentar på raden ovan som består av texten "lgtm[the-rule-id-here]" (minus citattecken). Du måste köra standardfråga för undertryckning av C/C++-aviseringar i stället för frågan för undertryckning av drivrutinsaviseringar.

När en undertryckning finns och identifieras innehåller den resulterande SARIF-filen data som ett resultat har undertryckts, och de flesta resultatvisningsprogram visar inte resultatet som standard.

Visual Studio-händelse efter kompilering

Om du skapar drivrutinen med Visual Studio kan du konfigurera CodeQL-frågor så att de körs som en händelse efter bygget.

I det här exemplet skapas en liten batchfil i målkatalogen och körs som en händelse efter kompileringen. Mer information om Visual Studio C++-bygghändelser finns i Ange bygghändelser.

  1. Skapa en liten batchfil som återskapar CodeQL-databasen och kör sedan önskade frågor på den. I det här exemplet får batchfilen namnet RunCodeQLRebuildQuery.bat. Ändra sökvägarna som visas i batch-exempelfilen så att de matchar dina katalogplatser.

    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. Alternativet devenv.exe/redigera används i batchfilen för att öppna SARIF-resultatfilen i den befintliga instansen av Visual Studio. Om du vill visa SARIF-resultaten installerar du Microsoft SARIF Viewer för Visual Studio och läser anvisningarna där för mer information.

  3. I drivrutinsprojektet navigerar du till projektegenskaper. I rullgardinsmenyn Konfiguration, välj den konfiguration som du vill kontrollera med CodeQL – vi rekommenderar Release. Det tar några minuter att skapa CodeQL-databasen och köra frågorna, så vi rekommenderar inte att du kör CodeQL i felsökningskonfigurationen för projektet.

  4. Välj Skapa händelser och Händelse efter bygge i egenskaperna för drivrutinsprojektet.

  5. Ange en sökväg till batchfilen och en beskrivning av händelsen efter bygget.

Händelsekonfigurationen i Visual Studio efter bygget visar en batchfil som konfigurerats som ett kommandoradsalternativ.

  1. Batchfilens resultat visas i slutet av byggutdata.

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

Relaterat innehåll

  • Last updated on