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

Välj fliken för ditt scenario:

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 hänvisar du till tabellen För användning av Windows maskinvarukompatibilitetsprogram, annars använder du Main-branch och versionen av CLI som anges i GitHub README eller i den föregående tabellen "för allmän användning". 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 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ö:

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

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

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

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"

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

Visa och tolka resultat

Det här avsnittet fokuserar på att generera och tolka resultat i SARIF-format. Andra resultatformat som CSV är tillgängliga, men stöds inte av Static Tools-logotyptestet.

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 visningsprogrammet är ett snabbt och enkelt sätt att se antalet överträdelser eller vilka frågor som har överträdelser, men ger bara begränsad information om var i källkoden överträdelsen inträffade. Sidan uppdateras inte 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 är egenskapsvärdet 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 (Static Tools Logo Hardware Lab Kit) och vägledning om var du ska placera DVL-filen finns i Köra test av statiska verktygslogotyp.

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. Den här uppgraderingen är enkelriktad och är inte 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.

För kontroller som portats från kodanalys respekteras befintliga kodanalysundertryckningar. 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ågan för C/C++-aviseringsundertryckning i stället för frågan om drivrutinsaviseringsundertryckning.

När en nedtryckning finns och identifieras innehåller den resulterande SARIF-filen data som visar att ett resultat har undertryckts. De flesta resultatvisningsprogram visar inte undertryckta resultat 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 heter RunCodeQLRebuildQuery.batbatchfilen . Ä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.

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

• Vanliga frågor och svar om CodeQL
• Översikt över CodeQL
• CodeQL-frågor och paket