Consultas de CodeQL personalizadas

Las consultas personalizadas amplían el análisis de seguridad integrado de CodeQL para detectar vulnerabilidades y aplicar estándares de codificación específicos para su base de código.

¿Quién puede utilizar esta característica?

CodeQL está disponible para los siguientes tipos de repositorios:

En este artículo

¿Qué son las consultas personalizadas de CodeQL ?

Las consultas personalizadas amplían la funcionalidad de análisis de seguridad integrado de CodeQL para detectar vulnerabilidades, estándares de codificación y patrones específicos de tu base de código.

Nota:

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:

  • ejecución de consultas en la base de datos, 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 Descodificación de bqrs. 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.

Cuándo usar consultas personalizadas

Use consultas personalizadas para:

  • Detección de vulnerabilidades específicas de la arquitectura o marcos de la aplicación
  • Aplicar estándares de codificación específicos de la organización o procedimientos recomendados
  • Encuentra patrones no cubiertos por los paquetes de consultas estándar CodeQL
  • Analice las bases de datos de CodeQL con el comando database analyze usando la CodeQL CLI para generar resultados interpretados.

Estructura de la consulta

Las consultas personalizadas se escriben en archivos de consulta, que se guardan con la .ql extensión . Estos archivos también contienen metadatos importantes que proporcionan información sobre el propósito de la consulta e indican al CodeQL CLI cómo procesar los resultados. Entre las propiedades necesarias se incluyen:

  •         **Identificador de consulta (`@id`)**: letras minúsculas o dígitos, delimitados por `/` o `-`

  •         **Tipo de consulta (`@kind`)**: uno de los siguientes:
    * problem - Alerta simple * path-problem - Alerta con secuencia de localización de código * diagnostic - Solución de problemas del extractor * metric - Métrica de resumen (requiere @tags summary)

Nota:

Los requisitos de metadatos pueden variar si quiere usar su consulta con otras aplicaciones. Para obtener más información, consulte Metadatos para las consultas de CodeQL.

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

Documentación de consulta

La documentación de consulta ayuda a los usuarios a comprender qué detecta una consulta y cómo solucionar los problemas identificados. Puede incluir documentación para las consultas personalizadas en dos formatos:

  •           **Archivos Markdown**: guardados junto con la consulta, se pueden incluir en archivos SARIF y mostrarse en la interfaz de usuario de code scanning

  •           **              Archivos `.qhelp`**: coherentes con las consultas estándar de CodeQL pero deben convertirse a Markdown para usarlos con code scanning

Cuando los archivos SARIF que contienen ayuda de consulta se cargan en GitHub, la documentación aparece en la interfaz de usuario code scanning para las alertas generadas por la consulta.

Para obtener más información, consulte Consulta de archivos de ayuda.

Uso compartido de consultas personalizadas

Puede compartir consultas personalizadas con la comunidad publicando sus propios paquetes de consultas. Consulta Publicación y uso de paquetes de CodeQL.

Lectura adicional

  •         [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)

  •         [Consultas de CodeQL](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)