Consultas personalizadas y la CodeQL CLI
Puedes personalizar los análisis de CodeQL escribiendo tus propias consultas para destacar vulnerabilidades o errores específicos.
Este tema trata específicamente cómo escribir consultas para usarlas con el comando database analyze con el fin de generar resultados interpretados.
Note
Las consultas que se ejecutan con database analyze tienen estrictos requisitos de metadatos. También puedes ejecutar consultas con los siguientes subcomandos de nivel de asociación:
- database run-queries, que genera resultados no interpretados en un formato binario intermedio denominado BQRS.
- query run, que genera archivos BQRS o imprime tablas de resultados directamente en la línea de comandos. La visualización de los resultados directamente en la línea de comandos puede ser útil para el desarrollo de consultas iterativas mediante la CLI.
Las consultas que se ejecutan con estos comandos no tienen los mismos requisitos de metadatos. Aun así, para guardar datos legibles para el usuario, debes procesar cada archivo de resultados BQRS mediante el subcomando de asociación bqrs decode. Por lo tanto, en la mayoría de los casos de uso, es más fácil usar el comando database analyze para generar directamente resultados interpretados.
Escritura de una consulta válida
Antes de ejecutar un análisis personalizado, debes escribir una consulta válida y guardarla en un archivo con una extensión .ql. Hay mucha documentación disponible para ayudarte a escribir consultas. Para obtener más información, consulta Consultas de CodeQL.
Inclusión de metadatos de consulta
Los metadatos de consulta se incluyen en la parte superior de cada archivo de consulta. Proporcionan a los usuarios información sobre la consulta e indican a la CodeQL CLI cómo procesar los resultados de la consulta.
Al ejecutar consultas con el comando database analyze, debes incluir las dos propiedades siguientes para asegurarte de que los resultados se interpretan correctamente:
-
Identificador de la consulta (
@id): una secuencia de palabras compuestas de letras minúsculas o dígitos, delimitados por/o-, que identifican y clasifican la consulta. -
Tipo de consulta (
@kind): identifica la consulta como una alerta simple (@kind problem), una alerta documentada por una secuencia de ubicaciones de código (@kind path-problem), para la solución de problemas del extractor (@kind diagnostic) o como una métrica de resumen (@kind metricy@tags summary).
Para obtener más información sobre estas propiedades de metadatos, consulta Metadatos para las consultas de CodeQL y la guía de estilo de los metadatos de consulta.
Note
Los requisitos de metadatos pueden variar si quieres usar tu consulta con otras aplicaciones. Para obtener más información, consulta Metadatos para las consultas de CodeQL.
Empaquetado de consultas de QL personalizadas
Al escribir tus propias consultas con la intención de compartirlas con otros usuarios, debes guardarlas en un paquete personalizado de CodeQL. Puedes publicar el paquete como un paquete de CodeQL en GitHub Packages, el Container registry de GitHub. Para más información, consulta Personalización del análisis con paquetes de CodeQL.
Los paquetes de CodeQL organizan los archivos usados en análisis de CodeQL y pueden almacenar consultas, archivos de biblioteca, conjuntos de consultas y metadatos importantes. Su directorio raíz debe contener un archivo denominado qlpack.yml. Debes guardar las consultas personalizadas en la raíz del paquete de CodeQL o en sus subdirectorios.
Para cada paquete de CodeQL, el archivo qlpack.yml incluye información que indica a la CodeQL CLI cómo compilar las consultas, de qué otros paquetes y bibliotecas de CodeQL depende el paquete y dónde encontrar las definiciones del conjunto de consultas. Para obtener más información sobre qué incluir en este archivo, consulta Personalización del análisis con paquetes de CodeQL.
Inclusión de ayuda de consulta para consultas personalizadas de CodeQL en archivos SARIF
Si usas la CodeQL CLI para ejecutar análisis que examinen código en sistemas de CI/CD de terceros, puedes incluir ayuda de consulta para las consultas personalizadas de los archivos SARIF generados durante un análisis. Después de cargar el archivo SARIF en GitHub, la ayuda de consulta se muestra en la interfaz de usuario de examen de código para las alertas generadas por las consultas personalizadas.
A partir de la CodeQL CLI v2.7.1 y versiones posteriores, puedes incluir ayuda de consulta representada con Markdown en archivos SARIF. Para ello, proporciona la opción --sarif-add-query-help al ejecutar codeql database analyze.
Puedes escribir ayuda de consulta para las consultas personalizadas directamente en un archivo Markdown y guardarla con la consulta correspondiente. Como alternativa, para garantizar la coherencia con las consultas estándar de CodeQL, puedes escribir ayuda de consulta en el formato .qhelp. La ayuda de consulta escrita en archivos .qhelp no se puede incluir en archivos SARIF y estos no se pueden procesar en un examen de código, por lo que debe convertirse a Markdown antes de ejecutar el análisis. Para obtener más información, lee Consulta de archivos de ayuda y Prueba de archivos de ayuda de consulta.
Contribución al repositorio de CodeQL
Si quieres compartir tu consulta con otros usuarios de CodeQL, puedes abrir una solicitud de incorporación de cambios en el repositorio de CodeQL. Para obtener más información, consulta "Contribución a CodeQL".