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

Selecione a guia para o seu cenário:

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 executar a análise como parte do programa WHCP, consulte a tabela Para uso do programa de compatibilidade de hardware do Windows; caso contrário, utilize o ramo principal e 2.15.4. 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 Codeql CLI para o 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 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:

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

Ver e interpretar resultados

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

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 funcionalidade que permite arrastar e soltar seu arquivo SARIF no visualizador e, em seguida, exibe os resultados categorizados por regra. Esta é 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 da linha. Observe que a página não será atualizada 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 terá uma propriedade Resultados com detalhes sobre quaisquer violações detetadas e onde ocorreram. 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 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.

Mais instruções para o Static Tools Logo HLK Test e orientação sobre onde colocar o arquivo DVL podem ser encontradas em Running the Static Tools Logo test.

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 database upgrade atualizará um banco de dados. Esteja ciente de que esta é uma 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. Por padrão, essa consulta é ativada ao executar nossos pacotes a partir de nossa ramificação principal/de desenvolvimento do githubs.

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

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

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). Você precisará executar a consulta de supressão de alerta C/C++ padrão em vez da consulta de supressão de alerta do condutor.

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

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 arquivo em lote que recria o banco de dados CodeQL e executa as consultas desejadas nele. Neste exemplo, o arquivo em lotes será chamado 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 exibir os resultados do SARIF, instale o Microsoft SARIF Viewer para Visual Studio e consulte as instruções para obter 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.

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

• CodeQL FAQ
• Visão geral do CodeQL
• Consultas e suítes do CodeQL