Ejecutar análisis de CodeQL en código de controlador de Windows

CodeQL es un potente motor de análisis estático que ayuda a los desarrolladores a identificar vulnerabilidades de seguridad y infracciones de código en el código fuente del controlador de Windows. En este artículo se explica cómo usar el análisis de CodeQL para crear un archivo de comprobación de controladores para la certificación del Programa de compatibilidad de hardware de Windows (WHCP).

En este artículo, usted:

• Instale la versión de CodeQL adecuada.
• Instale los paquetes y conjuntos de consultas de CodeQL necesarios.
• Ejecute CodeQL para compilar una base de datos y analizar el código.
• Cree un archivo de comprobación del controlador.

Seleccione la versión de CodeQL adecuada para el controlador.

Seleccione la pestaña para tu escenario:

Descargar e instalar CodeQL

1. Cree un directorio para que contenga CodeQL. En este ejemplo se usa C:\codeql-home\

   C:\> mkdir C:\codeql-home
   

2. Consulte las tablas anteriores para seleccionar la versión de la CLI de CodeQL que se usará de acuerdo con la rama deseada de las consultas de controladores de Microsoft. Si va a realizar análisis como parte del programa WHCP, consulte la tabla Para uso del Programa de Compatibilidad de Hardware de Windows, de lo contrario, use la rama Main y 2.15.4. El uso de una versión diferente puede dar lugar a que una base de datos no sea compatible con las bibliotecas.

3. Vaya a la versión de archivos binarios de la CLI de CodeQL asociada a las tablas anteriores y descargue el archivo ZIP de acuerdo con la arquitectura del proyecto. Por ejemplo, para Windows de 64 bits codeql-win64.zip.

4. Extraiga el directorio de la CLI de Codeql al que acaba de crear, por ejemplo: C:\codeql-home\codeql\.

5. Compruebe que CodeQL está instalado correctamente comprobando la versión:

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

Uso de la ayuda de 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 obtener ayuda sobre un comando específico, ejecute el comando< codeql >--help. Por ejemplo:

codeql create --help

Para obtener ayuda para los subcomandos, enumere jerárquicamente, por ejemplo,

codeql create language --help

Instalación de los paquetes de CodeQL

Seleccione la pestaña del entorno de compilación:

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

Nos centraremos en el formato SARIF para esta sección, ya que es lo que es necesario para los pasos siguientes, aunque le damos la bienvenida a usar el formato CSV si se adapta mejor a sus necesidades.

El formato de intercambio de resultados de análisis estáticos (SARIF) es un formato de tipo JSON que se usa para compartir resultados de análisis estáticos. Obtenga más información sobre el estándar en OASIS Static Analysis Results Interchange Format (SARIF), cómo utiliza CodeQL SARIF Output y el esquema json.

Hay varios métodos para interpretar los resultados del análisis, incluida la ordenación manual a través de los objetos . Estos son algunos de los que usamos:

• El Visor de Microsoft Sarif (Web) tiene funcionalidad que le permite arrastrar y colocar el archivo SARIF en el visor y, a continuación, muestra los resultados clasificados por regla. Esta es una manera muy rápida y sencilla de ver el recuento de infracciones o qué consultas tienen infracciones, pero menos fácil de encontrar información de código fuente aparte del número de línea. Tenga en cuenta que la página no se actualizará si no hay ninguna infracción.

• Microsoft SARIF Viewer para Visual Studio es excelente para mostrar los resultados en Visual Studio para realizar una transición sin problemas de los resultados al código fuente.

• La extensión SARIF para Visual Studio Code abre un panel de vista previa y muestra los errores, advertencias o problemas notificados por CodeQL. Para mostrar el archivo Sarif en un formato legible, abra el archivo en Visual Studio Code y seleccione Mayús-Alt-F.

La sección más importante del archivo SARIF es la Results propiedad dentro del Run objeto . Cada consulta tendrá una propiedad de Resultados con detalles sobre las infracciones detectadas y dónde ocurrieron. Si no se encuentra ninguna infracción, el valor de la propiedad estará vacío.

Las consultas se clasifican mediante estados como error, advertencia y problema. Sin embargo, esta clasificación es independiente de cómo el Programa de compatibilidad de hardware de Windows y la prueba de logotipo de herramientas estáticas califican los resultados. Cualquier controlador con defectos de cualquier consulta dentro del conjunto Must-Fixno pasará la prueba de logotipo de Static Tools y no se podrá certificar, independientemente de la clasificación de consultas en el archivo de consulta sin procesar (por ejemplo, advertencia).

Convertir SARIF al formato de registro de verificación del controlador (DVL)

La prueba del logotipo de herramientas estáticas analiza un registro de verificación de controladores (DVL), que es el resultado compilado del análisis estático de CodeQL que se ejecuta sobre el código fuente del controlador. Hay tres maneras de convertir el archivo SARIF al formato DVL: Visual Studio, MSBuild o desde la línea de comandos mediante la herramienta dvl.exe . Para ver los pasos completos, consulte Creación de un registro de comprobación de controladores.

Encontrará instrucciones adicionales para la prueba de HLK del logotipo de static Tools e instrucciones sobre dónde colocar el archivo DVL en Ejecución de la prueba de logotipo de Static Tools.

Troubleshooting

Si está certificando con WHCP, primero asegúrese de que está usando la versión de HLK asociada a la versión de Windows a la que quiere dirigirse, la rama asociada en el repositorio Herramientas Complementarias para Desarrolladores de Controladores de Windows, y la versión correspondiente de la CLI de CodeQL. Para obtener la matriz de compatibilidad de HLK/Windows Release, consulte Windows Hardware Lab Kit y para la compatibilidad del lanzamiento de Windows y las herramientas complementarias para desarrolladores de controladores de Windows, la versión del controlador CLI de CodeQL, consulte la tabla WHCP en la sección Seleccionar la versión de CodeQL.

Errores y soluciones alternativas

Para los problemas de desajuste de la versión de la base de datos, las siguientes herramientas pueden resultar útiles.

Utilice el comando codeql version para mostrar la versión del ejecutable codeql.

C:\codeql-home\codeql\>codeql version
CodeQL command-line toolchain release 2.4.0.
Copyright (C) 2019-2020 GitHub, Inc.
Unpacked in: C:\codeql-home\codeql\
   Analysis results depend critically on separately distributed query and
   extractor modules. To list modules that are visible to the toolchain,
   use 'codeql resolve qlpacks' and 'codeql resolve languages'.

El comando de actualización de la base de datos actualizará una base de datos. Tenga en cuenta que se trata de una actualización unidireccional y no es reversible. Para obtener más información, consulte Actualización de la base de datos.

Procedimientos opcionales

Opcionalmente, puede suprimir los resultados de CodeQL o ejecutar los procedimientos de compilación y análisis como un evento posterior a la compilación en Visual Studio.

Suprimir los resultados de CodeQL

CodeQL para controladores admite la supresión de resultados. Las supresiones se proporcionan actualmente como una comodidad para ayudar a los desarrolladores a evaluar los problemas y reducir el ruido, no como una manera de omitir las comprobaciones must-fix . No tienen ningún impacto en la generación de un registro de comprobación del controlador ni en pasar la prueba de logotipo de Static Tools en este momento. Para usar supresiones, debe ejecutar la consulta DriverAlertSuppression.ql al mismo tiempo que las demás consultas o conjuntos que desea ejecutar. De forma predeterminada, esta consulta se habilita al ejecutar nuestros conjuntos desde nuestra rama principal o de desarrollo de GitHubs.

En el caso de las comprobaciones migradas desde el análisis de código, se respetarán las supresiones de análisis de código existentes. Para obtener más información, vea Pragma de advertencia de C++.

• Known limitation: No puedes combinar #pragma(disable) y #pragma(suppress) en la misma línea por ahora.

Para las comprobaciones que son nuevas en CodeQL, suprimalas haciendo una de estas dos cosas:

• Escriba una #pragma(suppress:the-rule-id-here) anotación (sin comillas) en la línea anterior a la infracción, como lo hace para el análisis de código. Reemplace "the-rule-id-here" por el valor @id de los metadatos de la consulta, visible en la parte superior del archivo.

• Escriba un comentario en la línea anterior compuesta por el texto "lgtm[the-rule-id-here]" (comillas menos). Deberá ejecutar la consulta de supresión de alertas estándar de C/C++ en lugar de la consulta de supresión de alertas del controlador.

Una vez que una supresión está presente y reconocida, el archivo SARIF resultante incluirá los datos que se suprimen y la mayoría de los visores de resultados no mostrarán el resultado de forma predeterminada.

Evento posterior a la compilación de Visual Studio

Si va a compilar el controlador mediante Visual Studio, puede configurar consultas codeQL para que se ejecuten como un evento posterior a la compilación.

En este ejemplo, se crea un pequeño archivo por lotes en la ubicación de destino y se ejecuta como un evento posterior a la compilación. Para obtener más información sobre los eventos de compilación de Visual Studio C++, vea Especificar eventos de compilación.

1. Cree un pequeño archivo por lotes que vuelva a crear la base de datos CodeQL y, a continuación, ejecute las consultas deseadas en él. En este ejemplo, el archivo por lotes se denominará RunCodeQLRebuildQuery.bat. Modifique las rutas de acceso que se muestran en el archivo batch de ejemplo para que coincidan con las ubicaciones de tus directorios.

   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. La opción devenv.exe / Editar se usa en el archivo por lotes para abrir el archivo de resultados SARIF en la instancia existente de Visual Studio. Para ver los resultados de SARIF, instale microsoft SARIF Viewer para Visual Studio y consulte las instrucciones que encontrará para obtener más información.

3. En el proyecto de controlador, acceda a las propiedades del proyecto. En la lista desplegable Configuración , seleccione la configuración de compilación que desea comprobar con CodeQL: se recomienda liberar. La creación de la base de datos CodeQL y la ejecución de las consultas tarda unos minutos, por lo que no se recomienda ejecutar CodeQL en la configuración de depuración del proyecto.

4. Seleccione Eventos de compilación y Evento posterior a la compilación en las propiedades del proyecto de controlador.

5. Proporcione una ruta de acceso al archivo por lotes y una descripción del evento posterior a la compilación.

1. Los resultados del archivo por lotes se muestran al final de la salida de la compilación.

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

Contenido relacionado

• Preguntas más frecuentes sobre CodeQL
• Introducción a CodeQL
• Consultas y paquetes de CodeQL