Análisis del código con consultas de CodeQL

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

Para analizar un código base, puedes ejecutar consultas en una base de datos de CodeQL extraída de código. Los análisis de CodeQL generan resultados que se pueden cargar en GitHub para generar alertas de análisis de código.

Requisitos previos

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

Configurar la CodeQL CLI para ejecutar comandos localmente.
Crear una base de datos de CodeQL para el código fuente que quieres analizar.

La manera más sencilla de ejecutar codeql database analyze es usar las consultas estándar incluidas en el paquete de la CodeQL CLI.

En ejecución `codeql database analyze`

Cuando se ejecuta database analyze, hace lo siguiente:

Opcionalmente, descarga los paquetes de CodeQL a los que se hace referencia que no están disponibles localmente.
Ejecuta uno o varios archivos de consulta mediante una base de datos de CodeQL.
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.
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>...

Nota: Si analiza más de una base de datos de CodeQL para una sola confirmación, debe especificar una categoría SARIF para cada conjunto de resultados generados por este comando. Cuando cargas los resultados en GitHub, el code scanning utiliza esta categoría para almacenar los resultados para cada lenguaje por separado. Si olvida hacerlo, cada carga sobrescribe los resultados anteriores.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

Debes especificar <database>, --format y --output. Puedes especificar opciones adicionales en función del análisis que quieras hacer.

Opción	Obligatorio	Uso
`<database>`		Especifica la ruta del directorio que contiene la base de datos de CodeQL a analizar.
`<packs,queries>`		Especifica los paquetes o consultas de CodeQL a ejecutar. Para ejecutar las consultas estándar que se utilizan para el code scanning, omite este parámetro. Para ver los demás conjuntos de consultas incluidos en el conjunto de la CodeQL CLI, busque en `/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites`. Para obtener información sobre cómo crear un conjunto de consultas propio, consulta Creación de conjuntos de consultas de CodeQL en la documentación de la CodeQL CLI.
`--format`		Especifica el formato del archivo de resultados generado durante el análisis. Se admiten varios formatos diferentes, incluidos CSV, SARIF y grafo. Para cargarlo en GitHub, debe ser: `sarif-latest`. Para obtener más información, vea «Soporte de SARIF para escaneo de código».
`--output`		Especifica la ubicación en la que deseas guardar el archivo de resultados SARIF, incluido el nombre de archivo deseado con la extensión `.sarif`.
`--sarif-category`		Opcional para el análisis de base de datos única. Necesario para definir el lenguaje al analizar varias bases de datos para una sola confirmación en un repositorio. Especifique una categoría que se incluirá en el archivo de resultados de SARIF para este análisis. Una categoría se usa para distinguir varios análisis de la misma herramienta y confirmación, pero se ejecuta en distintos lenguajes o partes del código.
`--sarif-add-baseline-file-info`		Opción recomendada. Se usa para enviar información de cobertura de archivos a la página de estado de la herramienta. Para obtener más información, vea «Acerca de la página de estado de la herramienta para el examen de código».
`--sarif-include-query-help`		Especifica si se debe incluir la ayuda de consulta en la salida de SARIF. Uno entre: `always`: incluir la ayuda de consulta para todas las consultas. `custom_queries_only` (valor predeterminado): incluir la ayuda de consulta solo para consultas personalizadas, es decir, las de los paquetes de consultas que no tienen el formato `codeql/<lang>-queries`. `never`: no incluir la ayuda de consulta para ninguna consulta. Cualquier ayuda de consulta para consultas personalizadas incluidas en la salida de SARIF se mostrará en cualquier alerta de examen de código para la consulta. Para obtener más información, vea «Uso de consultas personalizadas con la CLI de CodeQL».
`<packs>`		Úsalo si deseas incluir los paquetes de consulta de CodeQL en el análisis. Para obtener más información, consulta "Descarga y uso de paquetes de CodeQL".
`--download`		Úselo si algunos de los paquetes de consulta de CodeQL aún no están en el disco y deben descargarse antes de ejecutar consultas.
`--threads`		Se usa si se quiere usar más de un subproceso para ejecutar consultas. El valor predeterminado es `1`. Puede especificar más subprocesos para acelerar la ejecución de consultas. Para establecer el número de subprocesos en el número de procesadores lógicos, especifique `0`.
`--verbose`		Se usa para obtener información más detallada sobre el proceso de análisis y datos de diagnóstico del proceso de creación de la base de datos.
`--threat-model`		(versión preliminar pública) Se usa para añadir modelos de riesgos para configurar orígenes adicionales en el análisis de CodeQL. Durante la versión preliminar pública, los modelos de riesgos solo son compatibles con el análisis de Java. Para obtener más información, vea «database analyze».

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

Ejemplo básico del análisis de una base de datos de CodeQL

En este ejemplo se analiza una base de datos de CodeQL almacenada en /codeql-dbs/example-repo y se guardan los resultados como un archivo SARIF: /temp/example-repo-js.sarif. Usa --sarif-category para incluir información adicional en el archivo SARIF que identifica los resultados como JavaScript. Esto es esencial cuando tienes más de una base de datos de CodeQL que analizar para una confirmación única en un repositorio.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Adición de información de cobertura de archivos a los resultados para la supervisión

Opcionalmente, puedes enviar información de cobertura de archivos a GitHub para su presentación en la página de estado de la herramienta para code scanning. Para más información sobre la página de cobertura de seguridad, consulta "Acerca de la página de estado de la herramienta para el examen de código".

Para incluir información de cobertura de archivos con los resultados de code scanning, agrega la marca --sarif-add-baseline-file-info a la invocación codeql database analyze en el sistema de CI, por ejemplo:

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --sarif-add-baseline-file-info \ --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

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 un paquete de consultas de CodeQL

Para ejecutar un paquete de consultas de CodeQL existente desde el Container registry de GitHub, puedes especificar uno o varios nombres de paquete:

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

Este comando ejecuta el conjunto de consultas predeterminado de dos paquetes de consultas de CodeQL: microsoft/coding-standards versión 1.0.0 y la versión más reciente de github/security-queries en la base de datos especificada. Para obtener más información sobre los conjuntos predeterminados, consulta "Publicación y uso de paquetes de CodeQL".

La marca --download es opcional. Al usarla, se garantiza la descarga del paquete de consultas si aún no está disponible localmente.

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 tus consultas para usarlas con la CodeQL CLI, consulta "Uso de consultas personalizadas con la CLI de CodeQL".

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 un subconjunto de consultas en un paquete de CodeQL

Si usas la CodeQL CLI v2.8.1 o una versión posterior, puedes incluir una ruta de acceso al final de una especificación del paquete para ejecutar un subconjunto de consultas dentro del paquete. Esto se aplica a cualquier comando que busque o ejecute consultas dentro de un paquete.

La manera completa de especificar un conjunto de consultas tiene el formato 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.

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.

Para analizar una base de datos mediante todas las consultas de la carpeta experimental/Security dentro del paquete codeql/cpp-queries de CodeQL, puedes usar lo siguiente:

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

Para ejecutar la consulta RedundantNullCheckParam.ql en el paquete de CodeQL codeql/cpp-queries, usa lo siguiente:

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

Para analizar la base de datos mediante el conjunto de consultas cpp-security-and-quality.qls desde una versión del paquete de CodeQL codeql/cpp-queries que es >= 0.0.3 y < 0.1.0 (se elegirá la versión compatible más alta), puedes usar lo siguiente:

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

Si necesitas hacer referencia a un archivo de consulta, directorio o conjunto cuya ruta de acceso contiene un elemento @ o : literal, puedes anteponer a la especificación de consulta el prefijo path:, como se indica a continuación:

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

Para obtener más información sobre los paquetes de CodeQL, consulta Personalización del análisis con paquetes de 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 "Carga de los resultados del análisis de CodeQL en GitHub" o "Puntos de conexión de la API de REST para el análisis de 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, vea «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".

Incluir paquetes de modelos para añadir posibles fuentes de datos contaminados

Nota: Los modelos de riesgos están actualmente en versión preliminar pública y está sujeta a cambios. Durante la versión preliminar pública, los modelos de riesgos solo son compatibles con el análisis de Java/Kotlin y C#.

Puede configurar modelos de riesgos en un análisis de code scanning. Para obtener más información, consulte “Modelos de riesgos para Java y Kotlin” y “Modelos de riesgos para C#” en la documentación de CodeQL.

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --threat-model=local \
  --output=/temp/my-company.sarif codeql/java-queries

En este ejemplo, las consultas pertinentes del paquete de consultas estándar codeql/java-queries usarán el modelo de riesgos local, así como el modelo de riesgos predeterminado para los orígenes de flujo de datos remote. Debe usar el modelo de riesgos local si considera que los datos de los orígenes locales (por ejemplo: sistemas de archivos, argumentos de la línea de comandos, bases de datos y variables de entorno) son posibles orígenes de datos con contenido dañado para el código base.

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, vea «Salida SARIF de la CLI de CodeQL».

Para obtener más información sobre qué aspecto tendrán los resultados en formato CSV, consulta «Salida CSV de la CLI de CodeQL».

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.

Visualizar la información diangóstica y de la bitácora

Cuando analices una base de datos de CodeQL utilizando un conjunto de consultas del code scanning adicionalmente a generar información detallada sobre las alertas, el CLI reporta datos de diagnóstico desde el paso de generación de base de datos y las métricas de resumen. Si decides generar la salida de SARIF, los datos adicionales también se incluyen en el archivo SARIF. En el caso de los repositorios con pocas alertas, puede que esta información te sea útil para determinar si genuinamente hay pocos problemas en el código o si hubieron errores que se generaron en la base datos de CodeQL. Para obtener un resultado más detallado de codeql database analyze, utilice la opción --verbose.

Para más información sobre el tipo de información de diagnóstico disponible, consulta "Visualizar las bitácoras del escaneo de código".

Puedes optar por exportar y cargar información de diagnóstico en GitHub, incluso si se produce un error en un análisis de CodeQL. Para obtener más información, vea «Carga de los resultados del análisis de CodeQL en GitHub».

Pasos siguientes

Para obtener información sobre cómo cargar los resultados de análisis de CodeQL en GitHub, consulta «Carga de los resultados del análisis de CodeQL en GitHub».