Partilhar via

Executar a análise CodeQL no código do driver do Windows

O CodeQL é um poderoso mecanismo de análise estática que ajuda os desenvolvedores a identificar vulnerabilidades de segurança e violações de código no código-fonte do driver do Windows. Este artigo explica como usar a análise CodeQL para criar um arquivo de verificação de driver para a certificação do programa de compatibilidade de hardware do Windows (WHCP).

Neste artigo, você:

  • Instale a versão apropriada do CodeQL.
  • Instale os pacotes CodeQL necessários e os pacotes de consulta.
  • Execute o CodeQL para construir um banco de dados e analisar seu código.
  • Crie um ficheiro de verificação de controlador.

Selecione a versão apropriada do CodeQL para o seu driver

Note

O Visual Studio (VS) 17.8 quebrou a compatibilidade com versões mais antigas do CodeQL usadas nas ramificações WHCP_21H2 e WHCP_22H2. CodeQL CLI versão 2.15.4 é validado para uso com WHCP 21H2 e WHCP 22H2 ao usar o Visual Studio 17.8 ou superior. Ao usar o Visual Studio 17.7 ou anterior, use a versão 2.4.6 ou a versão 2.6.3. Para o Programa WHCP, utilize a versão do CLI CodeQL e a versão para Windows que está a certificar, de acordo com a tabela seguinte.

Selecione a guia para o seu cenário:

Use esta matriz para determinar as versões a serem baixadas.

Versão do Windows Versão da CLI do CodeQL microsoft/windows-drivers versão de pacote CodeQL microsoft/cpp-queries versão de pacote do CodeQL versão do codeql/cpp-queries Ramo associado
Windows Server 2022 2.4.6 ou 2.15.4 1.0.13 (Se estiver usando codeql 2.15.4) N/A 0.9.0 (Se estiver usando codeql 2.15.4) WHCP_21H2
Windows 11 2.4.6 ou 2.15.4 1.0.13 (Se estiver usando codeql 2.15.4) N/A 0.9.0 (Se estiver usando codeql 2.15.4) WHCP_21H2
Windows 11, versão 22H2 2.6.3 ou 2.15.4 1.0.13 (Se estiver usando codeql 2.15.4) N/A 0.9.0 (Se estiver usando codeql 2.15.4) WHCP_22H2
Windows 11, versão 23H2 2.6.3 ou 2.15.4 1.0.13 (Se estiver usando codeql 2.15.4) N/A 0.9.0 (Se estiver usando codeql 2.15.4) WHCP_22H2
Windows 11, versão 24H2 2.15.4 1.1.0 N/A 0.9.0 WHCP_24H2
Windows Server 2025 2.20.1 1.8.0 0.0.4 N/A WHCP_25H2
Windows 11, versão 25H2 2.20.1 1.8.0 0.0.4 N/A WHCP_25H2
Windows 11, versão 26H1 2.24.1 1.8.2 0.0.4 N/A WHCP_26H1

Note

Uma versão do pacote CodeQL não é especificada para o CodeQL CLI 2.4.6 e 2.6.3 porque apenas versões do CodeQL posteriores à v2.7.0 suportam pacotes CodeQL.

Versões do CodeQL validadas para uso com WHCP

Para obter as informações sobre a versão mais recente, incluindo o teste do desenvolvimento mais recente, consulte Ferramentas suplementares para desenvolvedores de drivers do Windows.

Versão da CLI do CodeQL
2.24.1
2.23.3
2.21.4
2.21.2
2.20.1
2.15.4

Baixe e instale o CodeQL

  1. Crie um diretório para conter CodeQL. Este exemplo usa C:\codeql-home\

    C:\> mkdir C:\codeql-home

  2. Consulte as tabelas anteriores para selecionar qual versão da CLI do CodeQL usar de acordo com a ramificação desejada das consultas de driver da Microsoft. Se estiver a realizar análises como parte do programa WHCP, consulte a tabela Para Uso de Programas de Compatibilidade de Hardware do Windows, caso contrário use o ramo principal e a versão da CLI listada no README do GitHub ou na tabela "para uso geral" anterior. Usar uma versão diferente pode resultar em um banco de dados incompatível com as bibliotecas.

  3. Navegue até a versão de binários da CLI do CodeQL associada às tabelas anteriores e baixe o arquivo zip de acordo com a arquitetura do seu projeto. Por exemplo, para Windows de 64 bits codeql-win64.zip.

  4. Extraia o diretório da CodeQL CLI para o diretório que criaste, por exemplo: *C:\codeql-home\codeql*.

  5. Verifique se o CodeQL está instalado corretamente, verificando a versão:

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

Usando a ajuda do 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.

Para obter ajuda sobre um comando específico, execute o comando< codeql >--help. Por exemplo:

codeql create --help

Para obter ajuda para subcomandos, liste-os hierarquicamente, por exemplo

codeql create language --help

Instale os pacotes CodeQL

Selecione o separador para o seu ambiente de compilação:

Use este procedimento se estiver a usar o Visual Studio 2022 17.8 ou superior para certificação WHCP para 21H2 ou posterior e CodeQL CLI versão 2.15.4 ou posterior.

Note

Se você executou testes do CodeQL com uma versão anterior do CodeQL, certifique-se de remover o submódulo CodeQL antigo se você ainda tiver uma versão antiga do repositório clonado. CodeQL pode tentar usar as consultas no submódulo por padrão, o que pode causar erros devido a versões incompatíveis.

Faça o download dos pacotes de consulta CodeQL

O CodeQL introduziu os pacotes CodeQL (pacotes CodeQL ou pacotes de consulta) na versão 2.7.0, eliminando a necessidade de clonar o repositório Windows-Driver-Developer-Supplemental-Tools para usar as consultas para certificação.

  1. Transfira a versão correta do pacote microsoft/windows-drivers a partir da tabela Utilização do Programa de Compatibilidade de Hardware do Windows . Especifique o @<version> no comando a seguir.
C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>

Por exemplo, se estiver a certificar para WHCP 26H1, execute o seguinte comando para descarregar o query pack 1.8.2 windows-drivers:

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

Use este comando para descarregar a versão 0.0.4 do pacote de consulta Microsoft cpp-queries.

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

CodeQL instala os pacotes de consulta no diretório padrão:

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

Important

Não mudes o diretório de instalação nem movas o query pack instalado.

A Microsoft disponibiliza três conjuntos de consultas para simplificar o fluxo de trabalho dos programadores de drivers de ponta a ponta. Estas suites estão incluídas no pacote CodeQL microsoft/windows-drivers.

  • recommended.qls contém um conjunto amplo de verificações para bugs comuns de drivers e C/C++. Recomendamos executar esta suíte por padrão e rever os resultados.
  • mustrun.qls contém verificações que devem ser executadas para passar a certificação do Windows Hardware Compatibility Program (WHCP). Como estas consultas podem produzir falsos positivos em alguns casos, falhar estas verificações não falhará o teste do Logótipo de Ferramentas Estáticas, mas os programadores devem rever os resultados e corrigir erros reais. Um DVL gerado sem resultados para estas verificações falha no teste do Logótipo de Ferramentas Estáticas. Para o 26H1, mustrun.qls e recommended.qls são idênticos.
  • O mustfix.qls serve como um subconjunto das consultas must-run e contém verificações que reportam problemas que devem ser corrigidos para passar a certificação WHCP. Um DVL gerado com falhas nestas regras não passa no teste do Logótipo de Ferramentas Estáticas.

Para obter detalhes do conteúdo das suítes de consultas, consulte Consultas e suítes CodeQL.

Criar o banco de dados CodeQL

Estes exemplos pressupõem o uso de um ambiente de desenvolvimento do Windows e que o local de instalação é C:\codeql-home, mas você pode usar a configuração que mais lhe convier. Consulte Linguagens e estruturas suportadas pelo CodeQL para obter uma lista de quais compiladores são suportados.

  1. Crie um diretório para o CodeQL para colocar os bancos de dados que ele cria. Por exemplo: C:\codeql-home\databases

    mkdir C:\codeql-home\databases

  2. Use o comando CodeQL para criar um banco de dados com estes parâmetros:

    • O primeiro parâmetro é um link para o diretório do banco de dados. Por exemplo, C:\codeql-home\databases\MyDriverDatabase. (Este comando falhará se o diretório já existir.)
    • --language ou -l especifica o idioma ou idiomas em que o código-fonte está. Este parâmetro pode ser uma lista separada por vírgulas, como [cpp, javascript].
    • --source-root ou -s especifica o caminho para o código-fonte.
    • --command ou -c especifica o comando build ou o caminho para o arquivo build.
    codeql database create <path to new database> --language=<cpp> --source-root=<driver parent directory> --command=<build command or path to build file>

Examples

Exemplo de condutor único.

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"

Exemplo de vários drivers.

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

Para obter mais informações ou ajuda sobre como usar o database create comando, consulte Criando bancos de dados CodeQL ou Usando a ajuda do CodeQL.

Realizar análises

Neste ponto, a criação do banco de dados está concluída e a próxima etapa é executar a análise real no código-fonte do driver.

  1. Use o comando CodeQL para analisar seu banco de dados usando os seguintes parâmetros:

    • O primeiro parâmetro é um link para o diretório do banco de dados. Por exemplo, C:\codeql-home\databases\MyDriverDatabase. (Nota: este comando falha se o diretório não existir.)
    • --format é o tipo de arquivo do arquivo de saída. As opções incluem: SARIF e CSV. (Para utilizadores WHCP, utilize o formato SARIF.)
    • --output é o caminho para onde você deseja que o arquivo de saída, certifique-se de incluir o formato no nome do arquivo. (Este comando falhará se o diretório ainda não existir.)
    • O parâmetro Query Specifiers é uma lista de argumentos separada por espaços que pode incluir:
      • Um caminho para um arquivo de consulta
      • Um caminho para um diretório que contém arquivos de consulta
      • Um caminho para um ficheiro de suite de consultas
      • o nome de um pacote de consultas 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 microsoft/windows-drivers:windows-driver-suites/recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif

    Para obter mais informações ou ajuda sobre como usar o database analyze comando, consulte Analisando bancos de dados com a CLI do CodeQL, Usando um pacote do CodeQL para analisar um banco de dados do CodeQL ou Usando a ajuda do CodeQL.

Ver e interpretar resultados

Esta secção foca-se na geração e interpretação de resultados em formato SARIF. Outros formatos de resultados, como CSV, estão disponíveis, mas não são suportados pelo teste do Logótipo de Ferramentas Estáticas.

O SARIF (Static Analysis Results Interchange Format) é um formato do tipo JSON usado para compartilhar resultados de análise estática. Leia mais sobre o padrão em OASIS Static Analysis Results Interchange Format (SARIF), como o CodeQL usa a saída SARIF e o esquema json.

Existem vários métodos para interpretar os resultados da análise, incluindo a classificação manual através dos objetos. Aqui estão alguns que usamos:

  • O Microsoft Sarif Viewer (Web) tem funcionalidades que permitem arrastar e largar o seu ficheiro SARIF no visualizador, exibindo depois os resultados categorizados por regra. Este visualizador é uma forma rápida e fácil de ver a contagem de violações ou quais as consultas que têm violações, mas fornece apenas informação limitada sobre onde ocorreu no código-fonte a violação. A página não atualiza se não houver violações.

  • O Microsoft SARIF Viewer para Visual Studio é ótimo para exibir os resultados no Visual Studio para uma transição perfeita dos resultados para o código-fonte.

  • A extensão SARIF para Visual Studio Code abre um painel de visualização e exibe quaisquer erros, avisos ou problemas relatados pelo CodeQL. Para exibir o arquivo Sarif em um formato legível, abra o arquivo no Visual Studio Code e selecione Shift-Alt-F.

A seção mais importante do arquivo SARIF é a Results propriedade dentro do Run objeto. Cada consulta tem uma propriedade Resultados com detalhes sobre quaisquer violações detetadas e onde ocorreram. Se não forem encontradas infrações, o valor da propriedade fica vazio.

As consultas são classificadas usando status como erro, aviso e problema. No entanto, essa classificação é separada de como o Programa de Compatibilidade de Hardware do Windows e o Teste de Logotipo de Ferramentas Estáticas classificam os resultados. Qualquer driver com defeitos resultantes de qualquer consulta da suite Must-Fix não passará no Teste de Validação de Ferramentas Estáticas e não será certificado, independentemente da classificação da consulta no arquivo bruto de consultas (por exemplo, aviso).

Converter SARIF para formato de Log de Verificação de Driver (DVL)

O teste do logótipo das Ferramentas Estáticas analisa um log de verificação de driver (DVL), que é o resultado compilado da análise estática do CodeQL que corre no código-fonte do driver. Há três maneiras de converter seu arquivo SARIF para o formato DVL: Visual Studio, MSBuild ou a partir da linha de comando usando a ferramenta dvl.exe . Para obter as etapas completas, consulte Criar um registo de verificação de controlador.

Instruções adicionais para o Teste do Kit de Laboratório de Hardware do Static Tools Logo (HLK) e orientações sobre onde colocar o ficheiro DVL podem ser encontradas em Execução do Teste do Logo de Ferramentas Estáticas.

Troubleshooting

Se você estiver certificando com o WHCP, primeiro verifique se está usando a versão HLK associada à versão do Windows que você está direcionando, a ramificação associada no repositório de Ferramentas Suplementares do Windows Driver Developer e a versão subsequente da CLI do CodeQL. Para obter a matriz de compatibilidade HLK/Windows Release, consulte Windows Hardware Lab Kit e para Windows Release/Windows Driver Developer Supplemental Tools repo branch/CodeQL CLI version, consulte a tabela WHCP na seção Select the CodeQL version .

Erros e soluções alternativas

Para problemas de incompatibilidade de versão do banco de dados , as ferramentas a seguir podem ser úteis.

Use o comando codeql version para exibir a versão do 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'.

O comando de atualização da base de dados atualiza uma base de dados. Esta atualização é unidirecional e não é reversível. Para obter mais informações, consulte Atualização de banco de dados.

Procedimentos facultativos

Opcionalmente, você pode suprimir os resultados do CodeQL ou executar a compilação e analisar procedimentos como um evento pós-compilação no Visual Studio.

Suprimindo resultados do CodeQL

CodeQL para os drivers suporta a supressão de resultados. As supressões são atualmente fornecidas como uma conveniência para ajudar os desenvolvedores a fazer a triagem de problemas e reduzir o ruído, não como uma maneira de ignorar as verificações Must-Fix . Eles não têm impacto na geração de um Registo de Verificação de Controlador ou na aprovação no teste das Ferramentas Estáticas neste momento. Para usar supressões, você deve executar a consulta DriverAlertSuppression.ql ao mesmo tempo que as outras consultas ou pacotes que deseja executar.

Para verificações portadas a partir da Análise de Código, as supressões existentes da Análise de Código são respeitadas. Para obter mais informações, consulte C++ warning pragma.

  • Known limitation: Neste momento, não podes combinar um #pragma(desativar) e #pragma(suprimir) na mesma linha.

Para verificações que são novas no CodeQL, suprima-as fazendo uma das duas coisas:

  • Escreva uma #pragma(suppress:the-rule-id-here) anotação (sem aspas) na linha acima da violação, como faz para a Análise de Código. Substitua o "the-rule-id-here" pelo valor @id nos metadados da consulta, visível na parte superior do ficheiro.

  • Escreva um comentário na linha acima composta pelo texto "lgtm[the-rule-id-here]" (menos aspas). Tens de executar a consulta padrão de supressão de alertas em C/C++ em vez da consulta de supressão de alertas do driver.

Uma vez presente e reconhecida uma supressão, o ficheiro SARIF resultante inclui dados que indicam que um resultado é suprimido. A maioria dos visualizadores de resultados não mostra resultados suprimidos por defeito.

Evento pós-compilação do Visual Studio

Se você estiver criando o driver usando o Visual Studio, poderá configurar consultas CodeQL para serem executadas como um evento pós-compilação.

Neste exemplo, um pequeno ficheiro batch é criado no local de destino e invocado como um evento pós-compilação. Para obter mais informações sobre eventos de compilação do Visual Studio C++, consulte Especificando eventos de compilação.

  1. Crie um pequeno ficheiro batch que recrie a base de dados CodeQL e depois execute as consultas desejadas nele. Neste exemplo, o ficheiro batch chama-se RunCodeQLRebuildQuery.bat. Modifique os caminhos apresentados no ficheiro de lotes de exemplo para que correspondam aos locais dos seus diretórios.

    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. A opção devenv.exe / Edit é usada no arquivo em lotes para abrir o arquivo de resultados SARIF na instância existente do Visual Studio. Para visualizar os resultados do SARIF, instale o Microsoft SARIF Viewer para Visual Studio e consulte as instruções para mais informações.

  3. No projeto de driver, navegue até às propriedades do projeto. Na lista suspensa Configuração, selecione a configuração de compilação que pretende verificar com o CodeQL - recomendamos Versão Final. Criar o banco de dados CodeQL e executar as consultas leva alguns minutos, portanto, não recomendamos que você execute o CodeQL na configuração de depuração do seu projeto.

  4. Selecione Build Events e Post-Build Event nas propriedades do projeto de driver.

  5. Indique o caminho para o ficheiro batch e uma descrição do evento pós-compilação.

Configuração de evento pós-compilação do Visual Studio mostrando um arquivo em lotes configurado como uma opção de linha de comando.

  1. Os resultados do arquivo em lote são exibidos no final da saída da compilação.

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

Conteúdo relacionado

  • Last updated on