Eseguire l'analisi codeQL nel codice del driver Windows

CodeQL è un potente motore di analisi statico che consente agli sviluppatori di identificare le vulnerabilità di sicurezza e le violazioni del codice nel codice sorgente del driver Windows. Questo articolo illustra come usare l'analisi CodeQL per creare un file di verifica driver per la certificazione WHCP (Windows Hardware Compatibility Program).

In questo articolo si apprenderà come:

• Installare la versione codeQL appropriata.
• Installare i pacchetti CodeQL necessari e i gruppi di query.
• Eseguire CodeQL per compilare un database e analizzare il codice.
• Compilare un file di verifica del driver.

Selezionare la versione di CodeQL appropriata per il driver

Seleziona la scheda per scenario:

Scaricare e installare CodeQL

1. Creare una directory per contenere CodeQL. Questo esempio usa C:\codeql-home\

   C:\> mkdir C:\codeql-home
   

2. Fare riferimento alle tabelle precedenti per selezionare la versione dell'interfaccia della riga di comando codeQL da usare in base al ramo desiderato delle query del driver di Microsoft. Se si esegue l'analisi come parte del programma WHCP, consultare la tabella Per l'uso del programma compatibilità hardware di Windows. In caso contrario, utilizzare il ramo principale e 2.15.4. L'uso di una versione diversa può comportare un database incompatibile con le librerie.

3. Passare alla versione dei file binari dell'interfaccia della riga di comando codeQL associata alle tabelle precedenti e scaricare il file ZIP in base all'architettura del progetto. Ad esempio, per Windows a 64 bit codeql-win64.zip.

4. Estrarre la directory dell'interfaccia della riga di comando CodeQL nella directory appena creata, ad esempio *C:\codeql-home\codeql*.

5. Verificare che CodeQL sia installato correttamente controllando la versione:

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

Utilizzo dell'Aiuto di 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.

Per informazioni su un comando specifico, eseguire il comando< codeql >--help. Per esempio:

codeql create --help

Per ottenere assistenza per i sottocomandi, elencarli gerarchicamente, ad esempio

codeql create language --help

Installare i pacchetti CodeQL

Seleziona la scheda per l'ambiente di compilazione:

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

C:\codeql-home\> codeql pack download microsoft/[email protected]

C:\codeql-home\> codeql pack download codeql/[email protected]

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

Visualizzare e interpretare i risultati

Ci concentreremo sul formato SARIF per questa sezione perché è ciò che è necessario per i passaggi seguenti, anche se si è benvenuti a usare il formato CSV se si adatta meglio alle proprie esigenze.

Static Analysis Results Interchange Format (SARIF) è un formato di tipo JSON usato per la condivisione dei risultati dell'analisi statica. Altre informazioni sullo standard in OASIS Static Analysis Results Interchange Format (SARIF), sul modo in cui CodeQL usa l'output SARIF e il codice JSON dello schema.

Esistono diversi metodi per interpretare i risultati dell'analisi, tra cui l'ordinamento manuale degli oggetti. Ecco alcuni esempi usati:

• Microsoft Sarif Viewer (Web) include funzionalità che consentono di trascinare e rilasciare il file SARIF nel visualizzatore, quindi visualizzare i risultati classificati per regola. Si tratta di un modo molto rapido e semplice per vedere il numero di violazioni o quali query hanno violazioni, ma meno facile trovare informazioni sul codice sorgente a parte il numero di riga. Si noti che la pagina non verrà aggiornata se non sono presenti violazioni.

• Microsoft SARIF Viewer per Visual Studio è ideale per visualizzare i risultati all'interno di Visual Studio per passare facilmente dai risultati al codice sorgente.

• L'estensione SARIF per Visual Studio Code apre un riquadro di anteprima e visualizza eventuali errori, avvisi o problemi segnalati da CodeQL. Per visualizzare il file Sarif in un formato leggibile, aprire il file in Visual Studio Code e selezionare MAIUSC-ALT-F.

La sezione più importante del file SARIF è la Results proprietà all'interno dell'oggetto Run . Ogni query avrà una proprietà Results con informazioni dettagliate sulle violazioni rilevate e sulla posizione in cui si è verificata. Se non vengono trovate violazioni, il valore della proprietà sarà vuoto.

Le query vengono classificate usando stati, ad esempio errori, avvisi e problemi. Tuttavia, questa classificazione è separata dal modo in cui il programma di compatibilità hardware di Windows e il Test del logo degli strumenti statici valutano i risultati. Qualsiasi driver con difetti da qualsiasi query all'interno della suite Must-Fixnon supererà il test del logo degli strumenti statici e non verrà certificato, indipendentemente dalla classificazione delle query nel file di query non elaborato (ad esempio, avviso).

Convertire SARIF in formato DVL (Driver Verification Log Format)

Il test del logo degli strumenti statici analizza un log di verifica del driver (DVL), ovvero il risultato compilato dell'analisi statica CodeQL eseguita sul codice sorgente del driver. Esistono tre modi per convertire il file SARIF in formato DVL: Visual Studio, MSBuild o dalla riga di comando usando lo strumento dvl.exe . Per i passaggi dettagliati, vedere Creazione di un log di verifica del driver.

Altre istruzioni per il test HLK del logo degli strumenti statici e indicazioni su dove posizionare il file DVL sono disponibili in Esecuzione del test del logo degli strumenti statici.

Risoluzione dei problemi

Se si esegue la certificazione con WHCP, assicurarsi prima di tutto di usare la versione HLK associata alla versione di Windows di destinazione, il ramo associato nel repository degli strumenti aggiuntivi per sviluppatori di Driver Windows e la versione successiva dell'interfaccia della riga di comando di CodeQL. Per la matrice di compatibilità di HLK/Windows Release, vedi Windows Hardware Lab Kit e per Windows Release/Windows Driver Developer Supplemental Tools repo branch/versione della CLI CodeQL, vedere la tabella WHCP nella sezione Selezionare la versione CodeQL.

Errori e soluzioni alternative

Per i problemi di mancata corrispondenza della versione del database , gli strumenti seguenti possono risultare utili.

Usare il comando codeql version per visualizzare la versione dell'exe codeql.

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

Il comando di aggiornamento del database aggiornerà un database. Tenere presente che si tratta di un aggiornamento unidirezionale e non è reversibile. Per altre informazioni, vedere Aggiornamento del database.

Procedure facoltative

Facoltativamente, è possibile eliminare i risultati di CodeQL o eseguire le procedure di compilazione e analisi come evento di post-compilazione in Visual Studio.

Eliminazione dei risultati di CodeQL

CodeQL per i driver supporta la soppressione dei risultati. Le soppressioni sono attualmente disponibili per comodità per aiutare gli sviluppatori a gestire i problemi e ridurre il rumore, non come un modo per ignorare i controlli Must-Fix. Al momento non hanno alcun impatto sulla generazione di un log di verifica del driver o sul superamento del test del logo degli strumenti di analisi statica. Per usare le soppressioni, è necessario eseguire la query DriverAlertSuppression.ql contemporaneamente alle altre query o suite da eseguire. Per impostazione predefinita, questa query è abilitata quando si eseguono le suite dal ramo principale/sviluppo di GitHubs.

Per i controlli che sono stati trasferiti dall'Analisi del Codice, verranno rispettate le soppressioni esistenti dell'Analisi del Codice. Per altre informazioni, vedere Pragma di avviso C++.

• Known limitation: Non è possibile combinare una #pragma(disable) e #pragma(suppress) nella stessa riga al momento.

Per i controlli nuovi di CodeQL, eliminarli eseguendo una delle due operazioni seguenti:

• Scrivere un'annotazione #pragma(suppress:the-rule-id-here) (senza virgolette) nella riga sopra la violazione, come si fa per l'analisi del codice. Sostituire "the-rule-id-here" con il @id valore nei metadati della query, visualizzabili nella parte superiore del file.

• Scrivere un commento sulla riga precedente costituita dal testo "lgtm[the-rule-id-here]" (virgolette meno). È necessario eseguire la query di eliminazione degli avvisi C/C++ standard anziché la query di eliminazione degli avvisi del driver.

Una volta presente e riconosciuta un'eliminazione, il file SARIF risultante includerà i dati che un risultato è stato eliminato e la maggior parte dei visualizzatori dei risultati non mostrerà il risultato per impostazione predefinita.

Evento post-compilazione di Visual Studio

Se si compila il driver usando Visual Studio, è possibile configurare query CodeQL da eseguire come evento di post-compilazione.

In questo esempio viene creato un piccolo file batch nel percorso di destinazione e viene chiamato come evento di post-compilazione. Per altre informazioni sugli eventi di compilazione di Visual Studio C++, vedere Specifica degli eventi di compilazione.

1. Creare un piccolo file batch che ricrea il database CodeQL e quindi esegue le query desiderate. In questo esempio il file batch verrà denominato RunCodeQLRebuildQuery.bat. Modificare i percorsi visualizzati nel file batch di esempio in modo che corrispondano ai percorsi della directory.

   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. L'opzione devenv.exe/Modifica viene usata nel file batch per aprire il file dei risultati SARIF nell'istanza esistente di Visual Studio. Per visualizzare i risultati SARIF, installare Microsoft SARIF Viewer per Visual Studio e fare riferimento alle istruzioni disponibili per altre informazioni.

3. Nel progetto driver, passare alle proprietà del progetto. Nell'elenco a discesa Configurazione, selezionare la configurazione di build che si desidera controllare con CodeQL: si consiglia Release. La creazione del database CodeQL e l'esecuzione delle query richiede alcuni minuti, pertanto non è consigliabile eseguire CodeQL nella configurazione di debug del progetto.

4. Selezionare Eventi di compilazione e evento post-compilazione nelle proprietà del progetto driver.

5. Specificare un percorso del file batch e una descrizione dell'evento di post-compilazione.

1. I risultati del file batch vengono visualizzati alla fine dell'output di compilazione.

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

Contenuti correlati

• Domande frequenti su CodeQL
• Panoramica di CodeQL
• Query e suite CodeQL