Skip to main content
Publicamos actualizaciones para la documentación con frecuencia y es posible que aún se esté traduciendo esta página. Para obtener la información más reciente, consulta la documentación en inglés.

Esta versión de GitHub Enterprise se discontinuó el 2023-03-15. No se realizarán lanzamientos de patch, ni siquiera para problemas de seguridad críticos. Para obtener rendimiento mejorado, seguridad mejorada y nuevas características, actualice a la versión más reciente de GitHub Enterprise. Para obtener ayuda con la actualización, póngase en contacto con el soporte técnico de GitHub Enterprise.

Analizar las bases de datos con la CLI de CodeQL

Puedes ejecutar consultas en una base de datos de CodeQL extraída de un código base.

Las licencias de GitHub CodeQL se otorgan por usuario tras la instalación. Puedes usar CodeQL solo para determinadas tareas según las restricciones de las licencias. Para obtener más información, vea «Acerca de la CLI de CodeQL».

Si tienes una licencia de GitHub Advanced Security, puedes usar CodeQL para el análisis automatizado, la integración continua y la entrega continua. Para obtener más información, vea «Acerca de GitHub Advanced Security».

Nota: Este artículo se migró desde el sitio web de documentación de CodeQL en enero de 2023.

Acerca del análisis de bases de datos con la CodeQL CLI

Nota: En este artículo se describen las características disponibles con el paquete CodeQL CLI 2.7.6 que se incluye en la versión inicial de GitHub Enterprise Server 3.4.

Si el administrador del sitio ha actualizado tu versión de la CodeQL CLI a una versión más reciente, consulta la versión de GitHub Enterprise Cloud de este artículo para obtener información sobre las características más recientes.

Para analizar un código base, debes ejecutar consultas en una base de datos de CodeQL extraída del código.

Los análisis de CodeQL generan resultados interpretados que se pueden mostrar como alertas o rutas de acceso en el código fuente. Para obtener información sobre cómo escribir consultas para que se ejecuten con database analyze, consulta Uso de consultas personalizadas con la CodeQL CLI.

Otros comandos de ejecución de consultas

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 database analyze para generar directamente resultados interpretados.

Antes de iniciar un análisis, debes hacer lo siguiente:

La manera más sencilla de ejecutar codeql database analyze consiste en usar paquetes de CodeQL. También puedes ejecutar el comando mediante consultas desde una restauración local del repositorio de CodeQL. Esto podría interesarte si quieres personalizar las consultas principales de CodeQL.

En ejecución codeql database analyze

Cuando se ejecuta database analyze, hace lo siguiente:

  1. Opcionalmente, descarga los paquetes de CodeQL a los que se hace referencia que no están disponibles localmente.
  2. Ejecuta uno o varios archivos de consulta mediante una base de datos de CodeQL.
  3. Interpreta los resultados en función de determinados metadatos de consulta, de modo que las alertas se puedan mostrar en la ubicación correcta del código fuente.
  4. Notifica los resultados de las consultas de diagnóstico y resumen a la salida estándar.

Para analizar una base de datos, ejecuta el comando siguiente:

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

Debe especificar:

  • <database>: ruta de acceso a la base de datos de CodeQL que quieres analizar.
  • --format: formato del archivo de resultados generado durante el análisis. Se admiten varios formatos diferentes, incluidos CSV, SARIF y grafo. Para obtener más información sobre CSV y SARIF, consulta Resultados. Para averiguar qué otros formatos de resultados se admiten, consulta "database analyze".
  • --output: ruta de acceso de salida del archivo de resultados generado durante el análisis.

También puede especificar:

  • <query-specifiers>...: lista separada por espacios con las consultas que se van a ejecutar en la base de datos. Se trata de una lista de argumentos, donde cada uno de ellos puede ser:

    • Una ruta de acceso a un archivo de consulta
    • Una ruta de acceso a un directorio que contiene archivos de consulta
    • Una ruta de acceso a un archivo de conjunto de consultas
    • El nombre de un paquete de consultas de CodeQL
      • Con un intervalo de versiones opcional
      • Con una ruta de acceso opcional a una consulta, directorio o conjunto de consultas dentro del paquete

    Si se omite, se usará el conjunto de consultas predeterminado para el lenguaje de la base de datos analizada. Para obtener la sintaxis completa de los especificadores de consulta, lee el artículo titulado "Especificación de las consultas que se van a ejecutar en un paquete de CodeQL".

  • --sarif-category: categoría de identificación de los resultados. Se usa cuando se quiere cargar más de un conjunto de resultados para una confirmación. Por ejemplo, cuando se usa github upload-results a fin de enviar resultados para más de un lenguaje a la API de examen de código de GitHub. Para obtener más información sobre este caso de uso, consulta Configuración de la CodeQL CLI en el sistema de integración continua.

  • --sarif-add-query-help (compatible con la versión 2.7.1 y versiones posteriores): agrega la ayuda de consulta personalizada escrita en Markdown a los archivos SARIF (v2.1.0 o versiones posterior) generados por el análisis. La ayuda de consulta almacenada en archivos .qhelp debe convertirse a .md antes de ejecutar el análisis. Para obtener más información, lee "Inclusión de ayuda de consulta para consultas personalizadas de CodeQL en archivos SARIF".

  • --download: marca booleana que permitirá a la CLI descargar los paquetes de CodeQL a los que se hace referencia y que no están disponibles localmente. Si falta esta marca y un paquete de CodeQL no está disponible localmente, se producirá un error en el comando.

Actualizar bases de datos

En el caso de las bases de datos creadas con la CodeQL CLI v2.3.3 o versiones anteriores, deberás actualizar explícitamente la base de datos para poder ejecutar un análisis con una versión más reciente de la CodeQL CLI. Si este paso es necesario, verás un mensaje que te indicará que la base de datos debe actualizarse al ejecutar database analyze.

En el caso de las bases de datos creadas con la CodeQL CLI v2.3.4 o versiones posteriores, la CLI ejecutará implícitamente las actualizaciones necesarias. No es necesario ejecutar explícitamente el comando de actualización.

Para obtener información detallada sobre todas las opciones que se pueden usar al analizar bases de datos, consulta "database analyze".

Especificación de las consultas que se deben a ejecutar en un paquete de CodeQL

Los especificadores de consulta se usan en codeql database analyze y en otros comandos que operan en un conjunto de consultas. La forma completa de un especificador de consulta es scope/name@range:path, donde:

  • scope/name es el nombre completo de un paquete de CodeQL.

  • range es un intervalo de SemVer.

  • path es una ruta de acceso del sistema de archivos a una sola consulta, un directorio que contiene consultas o un archivo de conjunto de consultas.

Cuando se especifica scope/name, range y path son opcionales. Si range se omite, se usa la versión más reciente del paquete especificado. Si path se omite, se usa el conjunto de consultas predeterminado del paquete especificado.

path puede ser un archivo de consulta .ql, un directorio que contiene una o varias consultas o un archivo de conjunto de consultas .qls. Si se omite el nombre de paquete, debes proporcionar path, que se interpretará en relación con el directorio de trabajo del proceso actual. No se admiten patrones globales.

Si se especifica scope/name y path, el valor de path no puede ser absoluto. Se interpreta en relación con la raíz del paquete de CodeQL.

Especificadores de consulta de ejemplo

  • codeql/python-queries: todas las consultas del conjunto de consultas predeterminado de la versión más reciente del paquete codeql/python-queries.

  • codeql/python-queries@1.2.3: todas las consultas del conjunto de consultas predeterminado de la versión 1.2.3 del paquete codeql/python-queries.

  • codeql/python-queries@~1.2.3: todas las consultas del conjunto de consultas predeterminado de la versión más reciente del paquete codeql/python-queries que es >= 1.2.3 y < 1.3.0.

  • codeql/python-queries:Functions: todas las consultas del directorio Functions en la versión más reciente del paquete codeql/python-queries.

  • codeql/python-queries@1.2.3:Functions: todas las consultas del directorio Functions de la versión 1.2.3 del paquete codeql/python-queries.

  • codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls: todas las consultas del directorio codeql-suites/python-code-scanning.qls de la versión 1.2.3 del paquete codeql/python-queries.

  • suites/my-suite.qls: todas las consultas del archivo suites/my-suite.qls en relación con el directorio de trabajo actual.

Sugerencia

El conjunto de consultas predeterminado de los paquetes de consultas estándar de CodeQL es codeql-suites/<lang>-code-scanning.qls. También se pueden encontrar otros conjuntos de consultas útiles en el directorio codeql-suites de cada paquete. Por ejemplo, el paquete codeql/cpp-queries contiene los siguientes conjuntos de consultas:

  • cpp-code-scanning.qls: consultas de examen de código estándar para C++. Es el conjunto de consultas predeterminado para este paquete.

  • cpp-security-extended.qls: consultas del conjunto cpp-code-scanning.qls predeterminado para C++, además de consultas de gravedad y precisión más bajas.

  • cpp-security-and-quality.qls: consultas de cpp-security-extended.qls, además de consultas de mantenimiento y confiabilidad.

Puedes ver los orígenes de estos conjuntos de consultas en el repositorio de CodeQL. Los conjuntos de consultas de otros lenguajes son similares.

Ejemplos de análisis de bases de datos en ejecución

En los ejemplos siguientes se muestra cómo se ejecuta database analyze con paquetes de CodeQL y cómo se usa una restauración local del repositorio de CodeQL. En estos ejemplos se da por supuesto que las bases de datos de CodeQL se han creado en un directorio del mismo nivel que las copias locales del repositorio de CodeQL.

Ejecución de una sola consulta

Para ejecutar una sola consulta en una base de datos de CodeQL para un código base de JavaScript, puedes usar el comando siguiente desde el directorio que contiene la base de datos:

codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

Este comando ejecuta una sola consulta que encuentra posibles errores relacionados con variables no utilizadas, importaciones, funciones o clases; es una de las consultas de JavaScript incluidas en el repositorio de CodeQL. Puedes ejecutar más de una consulta si especificas una lista separada por espacios con rutas de acceso similares.

El análisis genera un archivo CSV (js-results.csv) en un directorio nuevo (js-analysis).

Como alternativa, si tienes desprotegido el repositorio de CodeQL, puedes ejecutar las mismas consultas si especificas la ruta de acceso directamente a la consulta:

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

También puede ejecutar tus propias consultas personalizadas con el comando database analyze. Para obtener más información sobre cómo preparar las consultas para usarlas con CodeQL CLI, lee el artículo titulado "Uso de consultas personalizadas con la CodeQL CLI".

Ejecución de todas las consultas en un directorio

Puedes ejecutar todas las consultas ubicadas en un directorio si proporcionas la ruta de acceso del directorio, en lugar de enumerar todos los archivos de consulta individuales. Las rutas de acceso se buscan de forma recursiva, por lo que también se ejecutarán las consultas contenidas en las subcarpetas.

Importante

Debes evitar especificar la raíz de un paquete de consultas principal de CodeQL al ejecutar database analyze, ya que podría contener algunas consultas especiales que no están diseñadas para usarse con el comando. En su lugar, ejecuta el paquete de consultas para incluir las consultas predeterminadas del paquete en el análisis, o bien ejecuta uno de los conjuntos de consultas de examen de código.

Por ejemplo, para ejecutar todas las consultas de Python incluidas en el directorio Functions del paquete de consultas codeql/python-queries, ejecutarías lo siguiente:

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

Como alternativa, si tienes desprotegido el repositorio de CodeQL, puedes ejecutar las mismas consultas si especificas la ruta de acceso directamente al directorio:

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

Cuando el análisis finalice, se generará un archivo de resultados SARIF. Al especificar --format=sarif-latest, se garantiza que se aplica a los resultados un formato conforme a la especificación SARIF más reciente admitida por CodeQL.

Ejecución de conjuntos de consultas

Para ejecutar un conjunto de consultas en una base de datos de CodeQL para un código base de C/C++, puedes usar el comando siguiente desde el directorio que contiene la base de datos:

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

Este comando descarga el paquete de consultas de CodeQL codeql/cpp-queries, ejecuta el análisis y genera un archivo en el formato SARIF versión 2.1.0 compatible con todas las versiones de GitHub. Este archivo se puede cargar en GitHub mediante la ejecución de codeql github upload-results o de la API de examen de código. Para más información, consulta "Configurar el CLI de CodeQL en tu sistema de IC" o "Examen del código".

Los conjuntos de consultas de CodeQL son archivos .qls que usan directivas para seleccionar las consultas que se ejecutarán en función de determinadas propiedades de metadatos. Los paquetes estándar de CodeQL contienen metadatos que especifican la ubicación de los conjuntos de consultas que usa el examen de código, para que la CodeQL CLI sepa dónde encontrar los archivos de los conjunto automáticamente, y no es necesario especificar la ruta de acceso completa en la línea de comandos. Para obtener más información, lee el artículo titulado "Creación de conjuntos de consultas de CodeQL".

Para más información sobre cómo crear conjuntos de consultas personalizados, consulta "Creación de conjuntos de consultas de CodeQL".

Información de diagnóstico y resumen

Al crear una base de datos de CodeQL, el extractor almacena los datos de diagnóstico en la base de datos. Los conjuntos de consultas de examen de código incluyen consultas adicionales para informar sobre estos datos de diagnóstico y calcular las métricas de resumen. Cuando el comando database analyze se completa, la CLI genera el archivo de resultados y notifica los datos de diagnóstico y resumen a la salida estándar. Si decides generar la salida de SARIF, los datos adicionales también se incluyen en el archivo SARIF.

Si el análisis encontró menos resultados de lo esperado para las consultas estándar, revisa los resultados de las consultas de diagnóstico y resumen para comprobar si es probable que la base de datos de CodeQL sea una representación adecuada del código base que quieres analizar.

Integración de un paquete de CodeQL en un flujo de trabajo de examen de código en GitHub

Puedes usar los paquetes de consultas de CodeQL en la configuración del examen de código. Esto te permite seleccionar paquetes de consulta publicados por varios orígenes y usarlos para analizar el código. Para obtener más información, lee el artículo titulado "Uso de paquetes de consultas de CodeQL en la acción de CodeQL o "Descarga y uso de paquetes de consultas de CodeQL en el sistema de integración continua".

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. Para obtener más información, consulta "Configuración de la CodeQL CLI en el sistema de integración continua".

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

Results

Puedes guardar los resultados del análisis en varios formatos diferentes, incluidos SARIF y CSV.

El formato SARIF está diseñado para representar la salida de una amplia gama de herramientas de análisis estático. Para obtener más información, consulta Salida de SARIF.

Si decides generar los resultados en formato CSV, cada línea del archivo de salida se corresponde con una alerta. Cada línea es una lista separada por comas con la información siguiente.

PropiedadDescripciónEjemplo
NombreNombre de la consulta que identificó el resultado.Inefficient regular expression
DescripciónDescripción de la consulta.A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.
severityGravedad de la consulta.error
MessageMensaje de alerta.This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
Ruta de accesoRuta de acceso del archivo que contiene la alerta./vendor/codemirror/markdown.js
Línea de inicioLínea del archivo donde comienza el código que desencadenó la alerta.617
Columna de inicioColumna de la línea de inicio que marca el inicio del código de alerta. No se incluye cuando es igual a 1.32
Línea de finalizaciónLínea del archivo donde finaliza el código que desencadenó la alerta. No se incluye cuando tiene el mismo valor que la línea de inicio.64
Columna de finalizaciónCuando está disponible, es la columna de la línea de finalización que marca el final del código de alerta. En caso contrario, se repite la línea de finalización.617

Puedes integrar los archivos de resultados en tu propia infraestructura de depuración o de revisión de código. Por ejemplo, la salida del archivo SARIF se puede usar para resaltar las alertas en la ubicación correcta del código fuente mediante un complemento del visor de SARIF para el IDE.

Información adicional