CodeQL e o teste de logotipo de ferramentas estáticas

CodeQL e segurança do driver

A Microsoft está trabalhando para reduzir a superfície de ataques do sistema operacional Windows, e para isso é fundamental garantir que os drivers de terceiros atendam a critérios severos de segurança. Uma etapa nesse caminho é o requisito para o Programa de Compatibilidade de Hardware do Windows (WHCP), de acordo com o qual todos os envios de driver devem usar o mecanismo CodeQL no código-fonte do driver e corrigir quaisquer violações que sejam consideradas de solução obrigatória.

CodeQL, do GitHub, é um poderoso mecanismo de análise de código semântico e uma combinação de um vasto conjunto de consultas de segurança de alto valor com uma plataforma robusta, que o tornam uma ferramenta inestimável para proteger o código dos drivers.

O uso do CodeQL para fins de teste WHCP é aceitável de acordo com o Contrato de Licença de Usuário Final do Kit de laboratório de hardware. Para os participantes do WHCP, o EULA do HLK substitui os Termos e Condições do CodeQL do GitHub, declarando que o CodeQL pode ser usado durante a análise automatizada, CI ou CD, como parte dos processos normais de engenharia para fins de análise de drivers a serem enviados e certificados como parte do WHCP.

O requisito para analisar o código-fonte do driver e solucionar erros cuja correção é obrigatória será aplicado pelo Teste de logotipo de ferramentas estáticas.

Este tópico descreve como:

• Use o CodeQL para analisar o código-fonte do driver em busca de problemas de segurança de alto impacto.
• Verifique se o Teste de logotipo de ferramentas estáticas pode consumir os resultados da execução do CodeQL.
• Determine quais consultas "Must-Fix" devem ser executadas para a certificação WHCP.

EULA do HLK e CodeQL

O uso do CodeQL com a finalidade de certificação para o teste do Programa de compatibilidade de hardware do Windows é aceitável de acordo com o Contrato de Licença de Usuário Final do Kit de Laboratório de Hardware (HLK). Para participantes do WHCP, o EULA do HLK substitui os Termos e Condições do CodeQL do GitHub. O EULA do HLK afirma que o CodeQL pode ser usado durante a análise automatizada, CI ou CD, como parte dos processos normais de engenharia para fins de análise de drivers a serem enviados e certificados como parte do Programa de Compatibilidade de Hardware do Windows. Para aqueles que acompanham para uso geral, leia os Termos e Condições do CodeQL do GitHub e/ou entre em contato com a CodeQL.

Conceitos do CodeQL

CodeQL é um mecanismo de análise estática usado por desenvolvedores para executar análises de segurança em códigos em um ambiente de teste. O CodeQL ingere o código durante a compilação e cria um banco de dados a partir dele. O banco de dados se torna um diretório que contém dados consultáveis, uma referência de origem e arquivos de log. Uma vez que o banco de dados está pronto, é possível executar análises nele utilizando consultas CodeQL (também chamadas de verificações ou regras), que determinarão se o código-fonte contém violações ou vulnerabilidades de segurança. O CodeQL fornece uma biblioteca de consultas padrão que verificam a correção da linguagem, semântica e grande valor para os desenvolvedores que desejam ter códigos sem bugs e vulnerabilidades.

O CodeQL também oferece a opção de criar consultas personalizadas. Para mais informações sobre como escrever consultas personalizadas, consulte Como escrever consultas nos documentos do CodeQL.

O CodeQL também fornece uma ferramenta de linha de comando (CLI) do CodeQL para executar facilmente ações do CodeQL e/ou realizar análises em grande escala.

Para ler a documentação complementar da CLI do CodeQL, acesse CodeQL Getting Started.

1. Configuração do CodeQL

Para uso com o Programa de Compatibilidade de Hardware do Windows

Matriz da versão de lançamento do Programa de Compatibilidade de Hardware do Windows

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

Versão do Windows	Versão da CLI do CodeQL	microsoft/windows-drivers, versão do pacote QL	codeql/cpp-queries, versão do pacote QL	Ramificação a ser usada
Windows Server 2022	2.4.6 ou 2.15.4	1.0.13 (se estiver usando codeql 2.15.4)	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)	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)	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)	0.9.0 (se estiver usando codeql 2.15.4)	WHCP_22H2
Windows 11, versão 24H2	2.15.4	1.1.0	0.9.0	WHCP_24H2

Uma versão do pacote QL não é especificada para CodeQL CLI 2.4.6 e 2.6.3 porque apenas as versões mais recentes do CodeQL suportam pacotes QL.

Para uso geral

Para uso geral do CodeQL com outras versões do Windows fora do programa WHCP, ou para desenvolver e testar consultas, atualmente recomendamos a seguinte versão e ramificação:

Versão da CLI do CodeQL	microsoft/Windows-drivers, versão qlpack	versão codeql/cpp-queries	Ramificação a ser usada
2.15.4	mais recente	mais recente	main

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 acima para selecionar qual versão da CLI do CodeQL 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 com o Programa de Compatibilidade de Hardware do Windows, caso contrário, use a ramificação principal e 2.15.4. Se você usar uma versão diferente, o banco de dados pode acabar sendo incompatível com as bibliotecas.

3. Navegue até a versão de binários da CLI do CodeQL associada às tabelas acima 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 CLI do Codeql naquele que você acabou de criar, por exemplo: C:\codeql-home\codeql.

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

6. O comando help exibe informações de uso da linha de comando.

   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.
   

Instalar pacotes do CodeQL

Para as filiais WHCP_21H2 e WHCP_22H2

Se estiver usando o Visual Studio 2022 17.8 ou superior com WHCP_21H2 ou WHCP_22H2 e CodeQL CLI versão 2.15.4:

• Siga as etapas para "TODAS AS OUTRAS RAMIFICAÇÕES".
• Remova o submódulo CodeQL se você ainda tiver uma versão antiga do repositório clonado. O CodeQL pode tentar usar as consultas no submódulo por padrão, o que causará erros devido a versões incompatíveis.

Se estiver usando o Visual Studio versão 17.7 ou inferior E WHCP_21H2 ou WHCP_22H2 E CodeQL CLI versão 2.4.6 ou 2.6.3:

• Siga as instruções especiais para WHCP_21H2 e WHCP_22H2 usando o VS17.7 ou anterior abaixo.

TODAS OS OUTRAS RAMIFICAÇÕES

Baixe os pacotes de pesquisa do CodeQL

Não é mais necessário clonar o repositório Windows-Driver-Developer-Supplemental-Tools para usar as consultas para certificação. Os pacotes CodeQL ("pacotes QL" ou "pacotes de consulta") agora são usados.

1. Baixe a versão correta do pacote microsoft/windows-drivers da Matriz da versão de lançamento do Programa de Compatibilidade de Hardware do Windows. Especifique o @<version> no comando abaixo.

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

Por exemplo, se estiver usando WHCP_24H2, execute o seguinte comando para baixar o pacote de consulta de drivers do Windows 1.1.0:

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

Use este comando para baixar a versão 0.9.0 do pacote de consulta CodeQL cpp-queries.

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

(É possível pular a etapa acima, pois a --download opção baixará as consultas necessárias posteriormente no processo de análise.)

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

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

Não altere esse diretório nem mova o pacote instalado.

Baixar os conjuntos de consultas de driver do Windows

Localize e copie para o PC local os dois arquivos do conjunto de consultas principais.

• windows-driver-recommended.qls
• windows-driver-mustfix.qls

Seu conteúdo é mostrado abaixo em Consultas e pacotes; os dois arquivos estão localizados em https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/suites.

2. Compile o banco de dados CodeQL

Esses 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 quiser. Consulte Linguagens e estruturas suportadas pelo CodeQL para obter uma lista de quais compiladores são suportados.

1. Crie um diretório para 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 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 (esse comando falhará se o diretório já existir).
   • --language ou -l é o idioma ou idiomas em que seu código-fonte está (pode ser uma lista separada por vírgula; por exemplo: [cpp, javascript]).
   • -- source ou -s é o caminho para o seu código-fonte.
   • --command ou -c é o comando build ou o caminho para o arquivo build.

   codeql database create <database directory> --language=<language> --source=<path to source code> --command=<build command or path to build file>
   

Exemplos

Exemplo de driver simples.

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 mais informações ou ajuda para usar o database create comando, acesse Como criar bancos de dados CodeQL ou use o seguinte comando:

C:\codeql-home\codeql> codeql database create --help

3. Realizar análise

Aqui, a configuração termina e o próximo passo é analisar o 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. (Esse comando falhará se o diretório não existir.)
   • --download flag diz ao CodeQL para baixar dependências antes de executar as consultas.
   • --format é o tipo do arquivo do arquivo de saída. As opções incluem SARIF e CSV. (Para usuários WHCP, use o formato SARIF.)
   • --output é o caminho para onde você deseja o arquivo de saída, certifique-se de incluir o formato no nome do arquivo. (Esse comando falhará se o diretório não existir.)
   • o parâmetro query specifiers é uma lista separada por espaço de argumentos 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 arquivo de conjunto de consultas
     • o nome de um pacote de consulta CodeQL

   codeql database analyze --download <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif
   

   Exemplo:

   codeql database analyze --download D:\DriverDatabase suites/windows-driver-recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif 
   

   Para mais informações ou ajuda para usar o database analyze comando, acesse Como analisar bancos de dados com a CLI do CodeQL e Como usar um pacote do CodeQL para analisar um banco de dados CodeQL.

   Para ajuda sobre a linha de comando, use o seguinte comando:

   C:\codeql-home\codeql> codeql database analyze --help
   

Instruções especiais para WHCP_21H2 e WHCP_22H2 usando o VS17.7 ou anterior

Essas instruções só se aplicam ao usar o Visual Studio 17.7 ou anterior com CodeQL 2.6.3 ou 2.4.6

1. Instale a versão do CodeQL conforme indicado nas etapas acima.

2. Clone e instale o repositório de Ferramentas Suplementares do Desenvolvedor de Drivers do Windows que contém as consultas CodeQL específicas para drivers:

   git clone https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools.git --recurse-submodules

3. Consulte a Matriz de versão de lançamento Programa de Compatibilidade de Hardware do Windows para identificar a ramificação correta para a versão do Windows que você deseja certificar.

4. Use o comando git checkout para fazer check-out da ramificação identificada.

5. Confirme se os submódulos estão presentes no diretório codeql-home.

    D:/codeql-home
        |--- codeql
        |--- Windows-Driver-Developer-Supplemental-Tools
   

6. Analise o banco de dados CodeQL.

   Atualize este comando de exemplo conforme seu ambiente. Defina os parâmetros, o caminho para o novo banco de dados, o formato, o arquivo sarif de saída, o caminho para a consulta CodeQL ou pacote de consultas para usar na análise.

   codeql database analyze <path to database> --format=sarifv2.1.0 --output=<"path to output file".sarif> <path to query/suite to run>

   Exemplo:

   codeql database analyze D:\DriverDatabase --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif D:\codeql-home\Windows-driver-developer-supplemental-tools\src\suites\windows_driver_mustfix.qls

   Verifique o caminho para o pacote ou consulta que você deseja executar, já que nem todas as ramificações têm a mesma estrutura de arquivos.

7. Consulte outras orientações neste documento para saber quais são as próximas etapas, por exemplo, como revisar e enviar resultados de teste.

4. Ver e interpretar resultados

Vamos focar o formato SARIF para esta seção, pois é o necessário para as etapas a seguir, embora você possa usar o formato CSV se for melhor para o que você precisa.

O formato Static Analysis Results Interchange Format (SARIF) é um formato do tipo JSON usado para compartilhar os resultados da 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 dos objetos. Aqui estão alguns que usamos:

• O Microsoft Sarif Viewer (Web) tem uma funcionalidade que permite arrastar e soltar o arquivo SARIF no visualizador e, em seguida, exibe 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 do código-fonte além do número da linha. A página não será atualizada se não houver violações.

• O Microsoft SARIF Viewer para Visual Studio é ótimo para mostrar 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

A seção mais importante do arquivo SARIF é a propriedade "Results" no objeto "Run". Cada consulta terá uma propriedade Results com detalhes sobre quaisquer violações detectadas 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", mas essa classificação é separada de como o Programa de Compatibilidade de Hardware do Windows e, especificamente, o Teste de Logotipo de Ferramentas Estáticas classificarão os resultados. Qualquer driver com defeitos de qualquer consulta dentro do pacote de resolução obrigatória não passará no Teste de Logotipo de Ferramentas Estáticas e não será certificado, independentemente da classificação da consulta no arquivo de consulta bruto (por exemplo, "aviso").

5. Como suprimir resultados do CodeQL (opcional)

O CodeQL para drivers suporta a 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 ruídos, e não como uma maneira de ignorar as verificações obrigatórias. Elas não afetam a geração de um Log de Verificação de Driver ou a aprovação no teste do Logotipo de Ferramentas Estáticas. 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 quando você executa 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 respeitadas. Para mais informações, consulte pragma de aviso C++.

• Known limitation:Por enquanto não é possível combinar um #pragma(disable) e um #pragma(supress) na mesma linha.

Para verificações que são novas no CodeQL, você pode suprimi-las fazendo uma de duas coisas:

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

• Escreva um comentário na linha acima composto 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 de driver.

Depois que 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.

6. Converter SARIF para o Formato de Log de Verificação de Driver (DVL)

O Teste de logotipo de ferramentas estáticas analisa um Driver Verification Log (DVL), que são os resultados compilados de vários mecanismos de análise estática que foram executados no código-fonte do driver. Há três maneiras de converter seu arquivo SARIF para o formato DVL; selecione a que melhor se adapta à sua configuração.

Como usar o Visual Studio (WDK Preview Build 20190 e posterior)

1. Coloque o arquivo de resultados SARIF no mesmo diretório que o arquivo .vcxproj.
2. No menu Extensão do driver, selecione Criar log de verificação do driver.
3. Verifique se a interface do usuário do DVL detecta o arquivo SARIF.
   • Observação: se você moveu o arquivo SARIF para o diretório .vcxproj usando a interface do usuário do Visual Studio, é possível que o Visual Studio tenha criado uma referência ao arquivo SARIF em vez de realmente movê-lo. Abra o diretório fora do Visual Studio para ter certeza que ele realmente esteja lá.
4. Selecione Criar.

Usando o MSBuild

1. Coloque o arquivo de resultados SARIF no mesmo diretório que o arquivo .vcxproj.

2. Abra o prompt de comando do Visual Studio, o prompt de comando das ferramentas nativas do Visual Studio ou o Enterprise Windows Driver Kit (EWDK).

3. Use o comando msbuild com os parâmetros a seguir:

   • caminho para o arquivo de projeto vcx
   • /target:dvl
   • /p:Configuration="Release"
   • /P:Platform=<platform> (Use apenas uma das seguintes cadeias de caracteres: x86, x64, arm, arm64)

   msbuild.exe <vcxprojectfile> /target:dvl /p:Configuration="Release" /P:Platform=<platform>

Usando CMD

1. Localize o dvl.exe do WDK ou de um eWDK montado.

2. Use o exe com os seguintes parâmetros:

   • /manualCreate
   • driver name (Não inclua o formato de arquivo .sys)
   • driver architecture (Use apenas uma das seguintes cadeias de caracteres: x86, x64, arm, arm64)

   "C:\Program Files (x86)\Windows Kits\10\Tools\dvl\dvl.exe" /manualCreate <driver name> <driver architecture>

Mais instruções para o teste HLK de logotipo de ferramentas estáticas e orientações sobre onde colocar o arquivo DVL podem ser encontradas em Como executar o teste.

7. Evento pós-compilação do Visual Studio (opcional)

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

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

1. Crie um pequeno arquivo em lote que recria o banco de dados CodeQL e, em seguida, executa as consultas desejadas nele. Neste exemplo, o arquivo em lotes será nomeado para RunCodeQLRebuildQuery.bat. Modifique os caminhos mostrados no arquivo em lotes de exemplo para corresponder aos 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" "C:\codeql-home\Windows-Driver-Developer-Supplemental-Tools\codeql\codeql-queries\cpp\ql\src\Likely Bugs\Underspecified Functions" --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 do Visual Studio. Para exibir os resultados SARIF, instale o Microsoft SARIF Viewer para Visual Studio e consulte as instruções para saber mais informações.

3. No projeto do driver, acesse as propriedades do projeto. Na lista suspensa Configuração, selecione a configuração de compilação que você deseja verificar com o CodeQL (recomendamos "Release"). 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 Debug do seu projeto.

4. Selecione Eventos de compilação e Evento pós-compilação nas propriedades do projeto de driver.

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

1. Os resultados da execução do arquivo em lotes serão exibidos no fim 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 <<<"
   

Solução de problemas

Se você estiver certificando com WHCP, verifique primeiro se você está usando a versão HLK associada à versão do Windows com que você quer trabalhar, a ramificação associada no repositório de Ferramentas Suplementares do Desenvolvedor de Driver do Windows e a versão subsequente da CLI do CodeQL. Para a matriz de compatibilidade HLK/Windows Release, consulte Windows Hardware Lab Kit; para Windows Release/repositório de Ferramentas Suplementares do Desenvolvedor de Drivers do Windows versão ramificação/CLI do CodeQL, consulte a tabela WHCP na seção Configuração do CodeQL.

Erros e soluções alternativas

Para incompatibilidades da 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 do banco de dados atualizará um banco de dados. Esteja ciente de que esta é uma atualização unidirecional e não é reversível. Para mais informações, consulte atualização do banco de dados.

Consultas e pacotes

Como parte do repositório GitHub do Microsoft CodeQL, fornecemos dois pacotes de consulta para simplificar o fluxo de trabalho completo do desenvolvedor de drivers. O pacote de pesquisas windows_driver_recommended.qls é um superconjunto de todas as consultas que a Microsoft considerou valiosas para desenvolvedores de drivers. O conjunto de consultas windows_driver_mustfix.qls contém consultas consideradas "solução obrigatória" para certificação WHCP, que devem ser executadas e aprovadas para passar no Teste de Logotipo de Ferramentas Estáticas. Os pacotes de consultas recomendados e de solução obrigatória são atualizados regularmente.

Consultas do tipo de solução obrigatória

O subconjunto de consultas abaixo é de solução obrigatória para certificação WHCP e também está incluído no pacote de solução recomendada.

Esse conjunto de regras está incluído no windows_driver_mustfix.qls.

ID	Localidade	Common Weakness Enumeration
cpp/bad-addition-overflow-check	codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql	CWE-190, CWE-192
cpp/pointer-overflow-check	codeql/cpp-queries/<Version>/Likely Bugs/Memory Management/PointerOverflow.ql	N/D
cpp/too-few-arguments	codeql/cpp-queries/<Version>/Likely Bugs/Underspecified Functions/TooFewArguments.ql	N/D
cpp/comparison-with-wider-type	codeql/cpp-queries/<Version>/Security/CWE/CWE-190/ComparisonWithWiderType.ql	CWE-190, CWE-197, CWE-835
cpp/hresult-boolean-conversion	codeql/cpp-queries/<Version>/Security/CWE/CWE-253/HResultBooleanConversion.ql	CWE-253

O arquivo windows_driver_mustfix.qls contém essas consultas de código de correção obrigatórias.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Security queries required to fix when certifying Windows Drivers
- queries: . 
  from: codeql/cpp-queries
  version: 0.9.0
- include:
    query path: 
      - Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql
      - Likely Bugs/Memory Management/PointerOverflow.ql
      - Likely Bugs/Underspecified Functions/TooFewArguments.ql
      - Security/CWE/CWE-190/ComparisonWithWiderType.ql
      - Security/CWE/CWE-253/HResultBooleanConversion.ql
- import: windows-driver-suites/windows_mustfix_partial.qls
  from: microsoft/windows-drivers

Esse conjunto de regras está incluído em windows-driver-suites/windows_mustfix_partial.qls.

ID	Localidade	Common Weakness Enumeration
cpp/windows/wdk/deprecated-api	/microsoft/windows-drivers/<Version>/drivers/general/queries/WdkDeprecatedApis/wdk-deprecated-api.ql	N/D
microsoft/Security/CWE/CWE-704/WcharCharConversionLimited	/microsoft/windows-drivers/<Version>/microsoft/Security/CWE/CWE-704/WcharCharConversionLimited.ql	CWE-704

O arquivo windows_mustfix_partial.qls contém essas consultas de código de correção obrigatórias.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Security queries required to fix when certifying Windows Drivers
- queries: .
  from: microsoft/windows-drivers
- include:
    query path: 
      - drivers/general/queries/WdkDeprecatedApis/wdk-deprecated-api.ql
      - microsoft/Security/CWE/CWE-704/WcharCharConversionLimited.ql

Consultas de correção recomendadas

Essas consultas fazem parte do pacote de consultas windows_driver_recommended.qls no repositório Microsoft GitHub CodeQL. A coluna "Common Weakness Enumeration" (CWE) especifica quais tipos de problemas de segurança a consulta determinada procura. Consulte a página da Mitre no CWE para conhecer mais detalhes sobre CWEs.

Práticas Recomendadas

ID	Localidade	Common Weakness Enumeration
cpp/offset-use-before-range-check	codeql/cpp-queries/<Version>/Best Practices/Likely Errors/OffsetUseBeforeRangeCheck.ql	N/D

Bugs prováveis

ID	Localidade	Common Weakness Enumeration
cpp/bad-addition-overflow-check	codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql	CWE-190, CWE-192
cpp/integer-multiplication-cast-to-long	codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/IntMultToLong.ql	CWE-190, CWE-192, CWE-197, CWE-681
cpp/signed-overflow-check	codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/SignedOverflowCheck.ql	N/D
cpp/upcast-array-pointer-arithmetic	codeql/cpp-queries/<Version>/Likely Bugs/Conversion/CastArrayPointerArithmetic.ql	CWE-119, CWE-843
cpp/pointer-overflow-check	codeql/cpp-queries/<Version>/Likely Bugs/Memory Management/PointerOverflow.ql	N/D
cpp/too-few-arguments	codeql/cpp-queries/<Version>/Likely Bugs/Underspecified Functions/TooFewArguments.ql	N/D
cpp/incorrect-not-operator-usage	codeql/cpp-queries/<Version>/Likely Bugs/Likely Typos/IncorrectNotOperatorUsage.ql	CWE-480
cpp/suspicious-add-sizeof	codeql/cpp-queries/<Version>/Likely Bugs/Memory Management/SuspiciousSizeof.ql	CWE-468
cpp/uninitialized-local	codeql/cpp-queries/<Version>/Likely Bugs/Memory Management/UninitializedLocal.ql	CWE-457, CWE-665

Segurança

ID	Localidade	Common Weakness Enumeration
cpp/conditionally-uninitialized-variable	codeql/cpp-queries/<Version>/Security/CWE/CWE-457/ConditionallyUninitializedVariable.ql.	CWE-457
cpp/unterminated-variadic-call	codeql/cpp-queries/<Version>/Security/CWE/CWE-121/UnterminatedVarargsCall.ql	CWE-121
cpp/suspicious-pointer-scaling	codeql/cpp-queries/<Version>/Security/CWE/CWE-468/IncorrectPointerScaling.ql	CWE-468
cpp/suspicious-pointer-scaling-void	codeql/cpp-queries/<Version>/Security/CWE/CWE-468/IncorrectPointerScalingVoid.ql	CWE-468
cpp/potentially-dangerous-function	codeql/cpp-queries/<Version>/Security/CWE/CWE-676/PotentiallyDangerousFunction.ql	CWE-676
cpp/incorrect-string-type-conversion	codeql/cpp-queries/<Version>/Security/CWE/CWE-704/WcharCharConversion.ql	CWE-704
cpp/comparison-with-wider-type	codeql/cpp-queries/<Version>/Security/CWE/CWE-190/ComparisonWithWiderType.ql	CWE-190, CWE-197, CWE-835
cpp/hresult-boolean-conversion	codeql/cpp-queries/<Version>/Security/CWE/CWE-253/HResultBooleanConversion.ql	CWE-253
cpp/suspicious-add-sizeof	codeql/cpp-queries/<Version>/Security/CWE/CWE-468/CWE-468/SuspiciousAddWithSizeof.ql	CWE-468

O arquivo windows_driver_recommended.qls contém essas consultas de código recomendadas.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Recommended and required queries for Windows Drivers.
- import: windows-driver-suites/windows_mustfix_partial.qls
  from: microsoft/windows-drivers
- import: windows-driver-suites/windows_recommended_partial.qls
  from: microsoft/windows-drivers
- queries: . 
  from: codeql/cpp-queries
  version: 0.9.0
- include:
    query path: 
      - Best Practices/Likely Errors/OffsetUseBeforeRangeCheck.ql
      - Likely Bugs/Arithmetic/IntMultToLong.ql
      - Likely Bugs/Arithmetic/SignedOverflowCheck.ql
      - Likely Bugs/Conversion/CastArrayPointerArithmetic.ql
      - Likely Bugs/Likely Typos/IncorrectNotOperatorUsage.ql
      - Likely Bugs/Memory Management/SuspiciousSizeof.ql
      - Likely Bugs/Memory Management/UninitializedLocal.ql
      - Security/CWE/CWE-121/UnterminatedVarargsCall.ql
      - Security/CWE/CWE-457/ConditionallyUninitializedVariable.ql
      - Security/CWE/CWE-468/IncorrectPointerScaling.ql
      - Security/CWE/CWE-468/IncorrectPointerScalingVoid.ql
      - Security/CWE/CWE-468/SuspiciousAddWithSizeof.ql
      - Security/CWE/CWE-676/PotentiallyDangerousFunction.ql
      - Security/CWE/CWE-704/WcharCharConversion.ql
      - Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql
      - Likely Bugs/Memory Management/PointerOverflow.ql
      - Likely Bugs/Underspecified Functions/TooFewArguments.ql
      - Security/CWE/CWE-190/ComparisonWithWiderType.ql
      - Security/CWE/CWE-253/HResultBooleanConversion.ql

Essas consultas fazem parte do windows_recommended_partial.qls.

Bugs prováveis - windows_recommended_partial.qls

ID	Localidade	Common Weakness Enumeration
cpp/paddingbyteinformationdisclosure	microsoft/windows-drivers/<Version>/microsoft/Likely Bugs/Boundary Violations/PaddingByteInformationDisclosure.ql	N/D
cpp/badoverflowguard	microsoft/windows-drivers/<Version>/microsoft/Likely Bugs/Conversion/BadOverflowGuard.ql	N/D
cpp/infiniteloop	microsoft/windows-drivers/<Version>/microsoft/Likely Bugs/Conversion/InfiniteLoop.ql	N/D
cpp/uninitializedptrfield	microsoft/windows-drivers/<Version>/microsoft/Likely Bugs/UninitializedPtrField.ql	N/D
cpp/use-after-free	microsoft/windows-drivers/<Version>/microsoft/Likely Bugs/Memory Management/UseAfterFree/UseAfterFree.ql	N/D

Security - windows_recommended_partial.qls

ID	Localidade	Code Analysis Warning
cpp/weak-crypto/cng/hardcoded-iv	/microsoft/windows-drivers/<Version>/microsoft/Security/Crytpography/HardcodedIVCNG.ql	N/D

Drivers - Geral

ID	Localidade	Code Analysis Warning
cpp/drivers/ke-set-event-pageable	/microsoft/windows-drivers/<Version>/drivers/general/queries/KeSetEventPageable/KeSetEventPageable.ql	Nenhuma verificação de CA associada
cpp/drivers/role-type-correctly-used	/microsoft/windows-drivers/<Version>/drivers/general/queries/RoleTypeCorrectlyUsed/RoleTypeCorrectlyUsed.ql	Nenhuma verificação de CA associada
cpp/drivers/extended-deprecated-apis	/microsoft/windows-drivers/<Version>/drivers/general/queries/ExtendedDeprecatedApis.ql	Aviso C28719, aviso C28726, aviso C28735, aviso C28750
cpp/drivers/irql-not-saved	/microsoft/windows-drivers/<Version>/drivers/general/queries/IrqlNotSaved/IrqlNotSaved.ql	Aviso C28158
cpp/drivers/irql-not-used	/microsoft/windows-drivers/<Version>/drivers/general/queries/IrqlNotUsed/IrqlNotUsed.ql	Aviso C28157
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers/<Version>/drivers/general/queries/IrqlTooHigh/IrqlTooHigh.ql	Aviso C28150
cpp/drivers/irql-too-low	/microsoft/windows-drivers/<Version>/drivers/general/queries/IrqlTooLow/IrqlTooLow.ql	Aviso C28120
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers/<Version>/drivers/general/queries/IrqlSetTooHigh/IrqlTooHigh.ql	Aviso C28121
cpp/drivers/irql-set-too-low	/microsoft/windows-drivers/<Version>/drivers/general/queries/IrqlSetTooLow/IrqlSetTooLow.ql	Aviso C28124
cpp/drivers/pool-tag-integral	/microsoft/windows-drivers/<Version>/drivers/general/queries/PoolTagIntegral/PoolTagIntegral.ql	Aviso C28134
cpp/drivers/str-safe	/microsoft/windows-drivers/<Version>/drivers/general/queries/StrSafe/StrSafe.ql	Aviso C28146

Drivers - WDM

ID	Localidade	Code Analysis Warning
cpp/drivers/illegal-field-access	/microsoft/windows-drivers/<Version>/drivers/wdm/queries/IllegalFieldAccess/IllegalFieldAccess.ql	Aviso C28128
cpp/drivers/illegal-field-access2	/microsoft/windows-drivers/<Version>/drivers/wdm/queries/IllegalFieldAccess2/IllegalFieldAccess2.ql	Aviso C28175
cpp/drivers/illegal-field-write	/microsoft/windows-drivers/<Version>/drivers/wdm/queries/IllegalFieldWrite/IllegalFieldWrite.ql	Aviso C28176
cpp/drivers/opaque-mdl-use	/microsoft/windows-drivers/<Version>/drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlUse.ql	(Nenhuma verificação de CA associada)
cpp/drivers/opaque-mdl-write	/microsoft/windows-drivers/<Version>/drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlWrite.ql	Aviso C28145
cpp/drivers/pending-status-error	/microsoft/windows-drivers/<Version>/drivers/wdm/queries/PendingStatusError/PendingStatusError.ql	Aviso C28143
cpp/drivers/wrong-dispatch-table-assignment	/microsoft/windows-drivers/<Version>/drivers/wdm/queries/WrongDispatchTableAssignment/WrongDispatchTableAssignment.ql	Aviso C28169

O arquivo windows-driver-suites/windows_recommended_partial.qls contém essas consultas de código recomendadas.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Recommended and required queries for Windows Drivers.
- import: windows-driver-suites/windows_mustfix_partial.qls
- queries: .
  from: microsoft/windows-drivers
- include:
    query path: 
      - microsoft/Likely Bugs/Boundary Violations/PaddingByteInformationDisclosure.ql
      - microsoft/Likely Bugs/Conversion/BadOverflowGuard.ql
      - microsoft/Likely Bugs/Conversion/InfiniteLoop.ql
      - microsoft/Likely Bugs/Memory Management/UseAfterFree/UseAfterFree.ql
      - microsoft/Likely Bugs/UninitializedPtrField.ql
      - microsoft/Security/Crytpography/HardcodedIVCNG.ql
      - drivers/general/queries/KeSetEventPageable/KeSetEventPageable.ql
      - drivers/general/queries/RoleTypeCorrectlyUsed/RoleTypeCorrectlyUsed.ql
      - drivers/general/queries/DefaultPoolTag/DefaultPoolTag.ql
      - drivers/general/queries/ExaminedValue/ExaminedValue.ql
      - drivers/general/queries/ExtendedDeprecatedApis/ExtendedDeprecatedApis.ql
      - drivers/general/queries/IrqlNotSaved/IrqlNotSaved.ql
      - drivers/general/queries/IrqlNotUsed/IrqlNotUsed.ql
      - drivers/general/queries/IrqlTooHigh/IrqlTooHigh.ql
      - drivers/general/queries/IrqlTooLow/IrqlTooLow.ql
      - drivers/general/queries/IrqlSetTooHigh/IrqlTooHigh.ql
      - drivers/general/queries/IrqlSetTooLow/IrqlSetTooLow.ql
      - drivers/general/queries/PoolTagIntegral/PoolTagIntegral.ql
      - drivers/general/queries/StrSafe/StrSafe.ql
      - drivers/wdm/queries/IllegalFieldAccess/IllegalFieldAccess.ql
      - drivers/wdm/queries/IllegalFieldAccess2/IllegalFieldAccess2.ql
      - drivers/wdm/queries/IllegalFieldWrite/IllegalFieldWrite.ql
      - drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlUse.ql
      - drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlWrite.ql
      - drivers/wdm/queries/PendingStatusError/PendingStatusError.ql
      - drivers/wdm/queries/WrongDispatchTableAssignment/WrongDispatchTableAssignment.ql

Perguntas frequentes (FAQ)

Quando isso será necessário para a certificação do dispositivo?

Consulte o Processo de Certificação do Programa de Compatibilidade de Hardware do Windows para saber mais sobre os requisitos.

Por que é exigido que o CodeQL seja executado no código-fonte do driver?

Por dois motivos principais:

1. A segurança do Windows é primordial, e exigir que o CodeQL seja executado no código-fonte do driver é um passo para ajudar a melhorar a segurança dos componentes que são certificados pela Microsoft.
2. As consultas do CodeQL são desenvolvidas ativamente por engenheiros de segurança da Microsoft, pois a Microsoft está comprometida em garantir que seu ecossistema de hardware se beneficie das mesmas ferramentas de alta qualidade usadas na Microsoft.

A que tipos de drivers o CodeQL e o teste do logotipo de ferramentas estáticas se aplicam?

No momento, o teste do logotipo de ferramentas estáticas requer que o CodeQL seja executado e o conjunto de consultas "Must-Fix" seja aprovado para todos os drivers em modo kernel, exceto drivers gráficos. Observe que a execução do CodeQL em drivers gráficos é altamente recomendada, mesmo que não seja obrigatória no momento. Algumas consultas também podem encontrar defeitos úteis em componentes de modo de usuário.

No futuro, pretendemos estender o teste e suas consultas para exigir resultados para drivers gráficos, drivers de modo de usuário e componentes de driver e outros componentes do pacote de drivers. Se você encontrar um comportamento inesperado ou falsos positivos executando o CodeQL em drivers gráficos ou drivers de modo de usuário, registre um problema no repositório Windows-Driver-Developer-Supplemental-Tools.

Qual licença rege o uso do CodeQL para desenvolvedores de drivers?

O uso do CodeQL para fins de teste WHCP é aceitável de acordo com o Contrato de Licença de Usuário Final do Kit de laboratório de hardware. Para participantes do WHCP, o EULA do HLK substitui os Termos e Condições do CodeQL do GitHub. O EULA do HLK afirma que o CodeQL pode ser usado durante análises automatizadas, CI ou CD, como parte dos processos normais de engenharia para fins de análise de drivers a serem submetidos e certificados como parte do WHCP.

Preciso usar o Visual Studio ou msbuild para executar o CodeQL?

o CodeQL não requer MSBuild ou Visual Studio para ser usado. Acesse linguagens e estruturas suportadas para conferir uma lista de quais compiladores são suportados.

Como o HLK verifica se meu driver foi escaneado pelo CodeQL?

O Teste de logotipo de ferramentas estáticas no HLK impõe esse requisito. Detalhes sobre o Teste de logotipo de ferramentas estáticas podem ser encontrados na página do MS Docs.

Todos os defeitos relatados pelo CodeQL são verdadeiros?

Cada consulta CodeQL tem níveis variados de precisão. Nosso objetivo é minimizar os falsos positivos, mas ocasionalmente eles ocorrerão. Nosso conjunto de consultas "Must-Fix" foi desenvolvido e escolhido a dedo para uso com o programa WHCP porque nossos testes extensivos resultam em quase zero falsos positivos. Se você estiver vendo falsos positivos de uma consulta nesse conjunto de consultas, envie um e-mail stlogohelp@microsoft.com imediatamente ou registre um problema no repositório Windows-Driver-Developer-Supplemental-Tools e trabalharemos para resolver a situação o mais rápido possível.

A classificação de "aviso" ou "erro" de uma consulta é importante para o Teste de logotipo de ferramentas estáticas?

As consultas são classificadas usando status como "erro", "aviso" e "problema" no CodeQL, mas essa classificação é separada de como o Programa de Compatibilidade de Hardware do Windows e, especificamente, o Teste de logotipo de ferramentas estáticas classificarão os resultados. Qualquer driver com defeitos de qualquer consulta dentro do pacote de resolução obrigatória não passará no Teste de Logotipo de Ferramentas Estáticas e não será certificado, independentemente da classificação da consulta no arquivo de consulta bruto (por exemplo, "aviso").

Posso gerar um DVL em soluções do Visual Studio?

Não, a geração DVL deve ser executada no nível do projeto e não pode ser executada em soluções do Visual Studio. Instruções sobre como gerar um DVL podem ser encontradas em: Como criar um log de verificação de driver.

Posso gerar um Driver Verification Log (DVL) fora do contexto do msbuild ou Visual Studio?

Como parte do Windows Driver Kit (WDK) e Enterprise WDK (eWDK), a Microsoft envia um componente chamado dvl.exe, que pode ser usado para gerar os Driver Verification Logs (DVLs). A partir das versões WDK/eWDK 21342 preview e superiores, é possível gerar um DVL a partir da linha de comando fora do contexto do msbuild ou do Visual Studio passando um nome e uma arquitetura de driver. Consulte Como criar um Driver Verification Log para saber mais detalhes.

Tenho comentários ou perguntas sobre como usar o CodeQL no meu driver. Para onde envio feedback?

Envie comentários e perguntas para stlogohelp@microsoft.com.