Executar a Análise de 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 do CodeQL para criar um arquivo de verificação de driver para a certificação WHCP (Programa de Compatibilidade de Hardware do Windows).

Neste artigo você:

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

Selecione a versão apropriada do CodeQL para o driver

Selecione a aba para o seu cenário.

Baixar e instalar 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 qualquer versão da CLI do CodeQL para usar de acordo com a ramificação desejada das consultas de driver da Microsoft. Se você estiver executando a análise como parte do programa WHCP, consulte a tabela Para Uso do Programa de Compatibilidade de Hardware do Windows. Caso contrário, use o ramo Principal e 2.15.4. O uso de uma versão diferente pode resultar em um banco de dados incompatível com as bibliotecas.

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

4. Extraia o diretório da CLI do Codeql para aquele que você acabou de criar, 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 em 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

Instalar os pacotes CodeQL

Selecione a guia para o ambiente de build:

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

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

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

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

Exibir e interpretar resultados

Vamos nos concentrar no formato SARIF desta seção, pois é o que é necessário para as etapas a seguir, embora você seja bem-vindo a usar o formato CSV se ele atender melhor às suas necessidades.

O SARIF (Formato de Intercâmbio de Resultados de Análise Estática) é um formato de tipo JSON usado para compartilhar resultados de análise estática. Leia mais sobre o padrão no SARIF (Formato de Intercâmbio de Resultados de Análise Estática) do OASIS, como o CodeQL usa a Saída SARIF e o json de esquema.

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

• O Visualizador do Microsoft Sarif (Web) tem funcionalidade que permite arrastar e soltar o arquivo SARIF no visualizador e, em seguida, exibe os resultados categorizados por regra. Essa é uma maneira muito rápida e fácil de ver a contagem de violações ou quais consultas têm violações, mas menos fácil de encontrar informações de código-fonte além do número de linha. Observe que a página não será atualizada se não houver violações.

• O Visualizador do Microsoft SARIF para Visual Studio é ótimo para exibir os resultados no Visual Studio para a transição perfeita de resultados para o código-fonte.

• A extensão SARIF para Visual Studio Code abre um painel de visualização e exibe 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 terá uma propriedade Resultados com detalhes sobre as violações detectadas e onde ela ocorreu. Se nenhuma violação for encontrada, o valor da propriedade estará 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 de qualquer consulta no pacote Must-Fixnão passará no Teste de Logotipo de Ferramentas Estáticas e não será certificado, independentemente da classificação de consulta no arquivo de consulta bruto (por exemplo, aviso).

Converter o SARIF em DVL (Formato de Log de Verificação de Driver)

O Teste de Logotipo de Ferramentas Estáticas analisa um DVL (Log de Verificação de Driver), que é o resultado compilado da análise estática codeQL executada no código-fonte do driver. Há três maneiras de converter o arquivo SARIF em formato DVL: Visual Studio, MSBuild ou da linha de comando usando a ferramenta dvl.exe . Para obter as etapas completas, consulte Criando um log de verificação de driver.

Mais instruções para o teste HLK do logotipo de ferramentas estáticas e orientações sobre onde colocar o arquivo DVL podem ser encontradas na execução do teste de logotipo 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, o branch associado no repositório ferramentas complementares do desenvolvedor do Windows Driver e a versão subsequente da CLI do CodeQL. Para a matriz de compatibilidade de versão do HLK/Windows, consulte o Kit do Windows Hardware Lab e para o branch de repositório de Ferramentas Complementares do Desenvolvedor do Windows/Windows Driver/versão da CLI do CodeQL, consulte a tabela WHCP na seção Selecionar a versão do CodeQL .

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 de versão codeql 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 do banco de dados atualizará um banco de dados. Lembre-se de que essa é uma atualização unidirecional e não é reversível. Para obter mais informações, consulte a atualização do banco de dados.

Procedimentos opcionais

Opcionalmente, você pode suprimir os resultados do CodeQL ou executar os procedimentos de build e análise como um evento pós-build no Visual Studio.

Suprimindo resultados do CodeQL

O CodeQL para drivers dá suporte à supressão de resultados. Atualmente, as supressões são 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 de correção de obrigação . Eles não têm nenhum impacto na geração de um Log de Verificação de Driver ou na aprovação do teste de Logotipo de Ferramentas Estáticas no momento. Para usar supressões, você deve executar a consulta DriverAlertSuppression.ql ao mesmo tempo que as outras consultas ou pacotes que deseja executar. Por padrão, essa consulta é habilitada ao executar nossos pacotes do nosso branch de desenvolvimento/principal do githubs.

Para verificações que foram portadas da Análise de Código, as supressões de Análise de Código existentes serão respeitadas. Para obter mais informações, consulte o pragma de aviso do C++.

• Known limitation: Não é possível combinar um #pragma(desabilitar) e #pragma(suprimir) na mesma linha no momento.

Para verificações novas no CodeQL, suprime-as fazendo uma de duas coisas:

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

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

Depois que uma supressão estiver presente e reconhecida, o arquivo SARIF resultante incluirá dados que um resultado foi suprimido e a maioria dos visualizadores de resultados não mostrará o resultado por padrão.

Evento pós-build 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-build.

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

1. Crie um pequeno arquivo em lote que recria o banco de dados CodeQL e execute as consultas desejadas nele. Neste exemplo, o arquivo em lote será nomeado RunCodeQLRebuildQuery.bat. Modifique os caminhos mostrados no arquivo de lote de exemplo para coincidir com os locais do diretório.

   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/Editar é usada no arquivo em lote para abrir o arquivo de resultados SARIF na instância existente do Visual Studio. Para exibir os resultados do SARIF, instale o Visualizador do Microsoft SARIF para Visual Studio e consulte as instruções para obter mais informações.

3. No projeto de driver, navegue até as propriedades do projeto. No menu suspenso de Configuração, selecione a configuração de build que você deseja verificar com o CodeQL – recomendamos Liberação. 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 Eventos de Build e Evento pós-build nas propriedades do projeto do driver.

5. Forneça um caminho para o arquivo em lote e uma descrição do evento pós-compilação.

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

   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

• Perguntas frequentes sobre CodeQL
• Visão geral do CodeQL
• Consultas e Conjuntos CodeQL