Escritura de consultas personalizadas para la CLI de CodeQL

Este artículo trata específicamente de escribir consultas para usarlas con el comando análisis de base de datos para generar resultados interpretados. Para obtener información conceptual sobre las consultas personalizadas, consulte Consultas de CodeQL personalizadas.

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, consulte Consultas de CodeQL.

Inclusión de metadatos de 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 metric y @tags summary).

Para obtener más información sobre estas propiedades de metadatos, consulte Metadatos para las consultas de CodeQL y la Guía de estilo de los metadatos de consulta.

Inclusión de ayuda de consulta para consultas personalizadas de CodeQL en archivos SARIF

Para obtener información sobre los formatos de ayuda de consulta y documentación, consulte Consultas de CodeQL personalizadas.

Para incluir asistencia para consultas en archivos SARIF al ejecutar análisis de código:

1. Escriba la ayuda de consulta en uno de los siguientes formatos: * Archivo Markdown: guarde un archivo Markdown junto con la consulta con el mismo nombre (por ejemplo, my-query.md para my-query.ql) * ** .qhelp file**: escriba la ayuda de consulta en .qhelp formato y, a continuación, conviértela en Markdown antes de ejecutar el análisis. Para obtener más información, vea Consulta de archivos de ayuda y Prueba de archivos de ayuda de consulta.

2. Ejecute codeql database analyze con la --sarif-add-query-help opción :

   codeql database analyze <database> --format=sarif-latest --output=results.sarif --sarif-add-query-help
   

   Nota:

   La opción --sarif-add-query-help está disponible a partir de CodeQL CLI v2.7.1 y versiones posteriores.

3. Cargue el archivo SARIF en GitHub.

Pasos siguientes

Para compartir y usar las consultas personalizadas, consulte Publicación y uso de paquetes de CodeQL.