Publicación y uso de paquetes de CodeQL

Configuración del archivo qlpack.yml antes de publicarlo

Puedes comprobar y modificar los detalles de configuración del paquete de CodeQL antes de la publicación. Abre el archivo qlpack.yml en su editor de texto preferido.

library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range

• name: debe seguir el formato <scope>/<pack>, donde <scope> es la organización de GitHub en la que vas a publicar y es el nombre del paquete.

• Se permite un máximo de un elemento default-suite o default-suite-file. Estas son dos maneras diferentes de definir un conjunto predeterminado de consultas que se va a ejecutar, la primera de ellas especificando las consultas directamente en el archivo qlpack.yml y la segunda especificando un conjunto de consultas en el paquete.

En ejecución codeql pack publish

Cuando estés a punto para publicar un paquete en GitHub Container registry, puedes ejecutar el comando siguiente en la raíz del directorio del paquete:

codeql pack publish

El paquete publicado se mostrará en la sección paquetes de la organización de GitHub que especifica el ámbito del archivo qlpack.yml.

En ejecución codeql pack download <scope>/<pack>

Para ejecutar un paquete que haya creado otra persona, primero debes descargarlo; para ello, ejecuta el comando siguiente:

codeql pack download <scope>/<pack>@x.x.x

• <scope>: el nombre de la organización de GitHub desde la que lo descargarás.
• <pack>: el nombre del paquete que quieres descargar.
• @x.x.x: un número de versión opcional. Si se omite, se descargará la versión más reciente.

Este comando acepta argumentos para varios paquetes.

Si escribes scripts que especifican un número de versión determinado de un paquete de consultas que se va a descargar, ten en cuenta que al actualizar la versión de CodeQL a una versión más reciente, es posible que también tengas que cambiar a una versión más reciente del paquete de consultas. Las versiones más recientes de CodeQL pueden proporcionar un rendimiento degradado cuando se usan con paquetes de consulta anclados a una versión muy antigua. Para obtener más información, consulta "Acerca de la compatibilidad con paquetes de CodeQL".

Uso de un paquete de CodeQL para analizar una base de datos de CodeQL

Para analizar una base de datos de CodeQL con un paquete de CodeQL, ejecuta el comando siguiente:

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

• <database>: la base de datos de CodeQL que se va a analizar.
• <scope>: el nombre de la organización de GitHub en la que se va a publicar el paquete.
• <pack>: el nombre del paquete que estás usando.
• @x.x.x: un número de versión opcional. Si se omite, se usará la versión más reciente.
• :<path>: una ruta de acceso opcional a una consulta, directorio o conjunto de consultas. Si se omite, se usará el conjunto de consultas predeterminado del paquete.

El comando analyze ejecutará el conjunto predeterminado de los paquetes de CodeQL especificados. Puedes especificar varios paquetes de CodeQL que se usarán para analizar una base de datos de CodeQL. Por ejemplo:

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>

Acerca de la compatibilidad con paquetes de CodeQL

Cuando se publica un paquete de consultas, incluye representaciones precompiladas de todas las consultas que contiene. La ejecución de estas consultas precompiladas suele ser mucho más rápida que compilar el origen de QL desde cero durante el análisis. Pero las consultas precompiladas también dependen de ciertos elementos internos del evaluador de QL, por lo que si la versión de CodeQL que realiza el análisis es muy diferente de la versión que ejecutó codeql pack publish, puede que sea necesario compilar las consultas desde el origen en lugar de durante el análisis. La recompilación se produce automáticamente y no afectará a los resultados del análisis, pero puede hacer que el análisis sea considerablemente más lento.

Por lo general, se puede suponer que si un paquete se publica con una versión de CodeQL, las consultas precompiladas que contiene se pueden usar directamente mediante versiones posteriores de CodeQL, siempre y cuando no hayan transcurrido más de 6 meses entre las fechas de lanzamiento. Nos esforzaremos de forma razonable para mantener nuevas versiones compatibles durante más tiempo que el indicado anteriormente, pero no podemos garantizarlo.

También se puede suponer que un paquete que ha publicado la versión pública más reciente de CodeQL la podrá utilizar la versión de CodeQL que usa code scanning y GitHub Actions, aunque a menudo sea una versión un poco más antigua.

Como excepción a lo anterior, los paquetes publicados con versiones de CodeQL anteriores a la versión 2.12.0 no son compatibles con ninguna versión, ya sea anterior o posterior. Estas versiones anteriores no escribieron consultas precompiladas en un formato que admita la compatibilidad entre versiones. Los paquetes que han publicado estas versiones pueden seguirlos usando versiones más recientes, pero el análisis será más lento porque las consultas deben volver a compilarse primero.

Como usuario de un paquete de consultas publicado, puedes comprobar que CodeQL usa las consultas precompiladas que contiene inspeccionando la salida del terminal de una ejecución de análisis que usa el paquete de consultas. Si contiene líneas con un aspecto similar a las siguientes, significa que las consultas precompiladas se usaron correctamente:

[42/108] Loaded /long/path/to/query/Filename.qlx.

Pero si en su lugar tienen un aspecto similar al siguiente, significa que se produjo un error en el uso de las consultas precompiladas:

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

Los resultados del análisis seguirán siendo buenos en este caso, pero para obtener un rendimiento óptimo, es posible que tengas que actualizar a una versión más reciente de la CLI de CodeQL o del paquete de consultas.

Si publicas paquetes de consulta en el Container registry en el GitHub.com para que otros usuarios los usen, se recomienda usar una versión reciente de CodeQL para ejecutar codeql pack publish y publicar una versión nueva del paquete con una versión actualizada de CodeQL antes de que la versión que usaste alcance los 6 meses de antigüedad. De este modo, puedes asegurarte de que los usuarios del paquete que mantienen sus CodeQL actualizados se van a beneficiar de las consultas precompiladas del paquete.

Si publicas paquetes de consultas con la intención de usarlos en una instalación de GitHub Enterprise Server que usa sus archivos binarios de CodeQL agrupados, usa la misma versión de CodeQL para ejecutar codeql pack publish. Es posible que las versiones más recientes generen consultas compiladas previamente que la de GitHub Enterprise Server no reconozca. El administrador de GitHub Enterprise Server puede optar por actualizar a una versión más reciente de CodeQL con frecuencia. Si es así, sigue su ejemplo.

Autenticación en Container registries de GitHub

Puedes publicar paquetes y descargar paquetes privados autenticándote en el Container registry de GitHub adecuado.

Puedes autenticarte en el Container registry en el GitHub.com de dos maneras:

1. Pasa la opción --github-auth-stdin a la CodeQL CLI y, después, proporciona un token de GitHub Apps o personal access token mediante la entrada estándar.
2. Establece la variable de entorno GITHUB_TOKEN en un token de GitHub Apps o personal access token.