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.

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>

Uso de paquetes de CodeQL en el GitHub Enterprise Server

De manera predeterminada, la CodeQL CLI espera descargar paquetes de CodeQL desde el Container registry y publicarlos en ese servicio en el GitHub.com. Pero también puedes trabajar con paquetes de CodeQL en un Container registry en el GitHub Enterprise Server creando un archivo qlconfig.yml a fin de indicar a la CLI qué Container registry usar para cada paquete.

Cree un archivo ~/.codeql/qlconfig.yml con tu editor de texto preferido y agrega entradas a fin de especificar qué registro se usará para uno o varios patrones de nombre de paquete. Por ejemplo, el archivo qlconfig.yml siguiente asocia todos los paquetes con el Container registry para el GitHub Enterprise Server en GHE_HOSTNAME, excepto los paquetes que coinciden con codeql/\*, que están asociados con el Container registry en el GitHub.com:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  url: https://ghcr.io/v2/
- packages: '*'
  url: https://containers.GHE_HOSTNAME/v2/

La CodeQL CLI determinará qué registro se usará para un nombre de paquete determinado al buscar el primer elemento de la lista registries con una propiedad packages que coincida con ese nombre de paquete. Esto significa que, por lo general, querrás definir primero los patrones de nombre de paquete más específicos. La propiedad packages puede ser un nombre de paquete único, un patrón global o una lista YAML de nombres de paquete y patrones globales.

La lista registries también se puede colocar dentro de un archivo codeql-workspace.yml. Si esto ocurre, podrás definir los registros que se usarán en un área de trabajo específica, de modo que se pueda compartir entre otros usuarios de CodeQL del área de trabajo. La lista registries de codeql-workspace.yml se combinará con la lista en el archivo qlconfig.yml global y tendrá prioridad sobre esta. Para obtener más información acerca de codeql-workspace.yml, consulta Acerca de las áreas de trabajo de CodeQL.

Ahora puedes usar codeql pack publish, codeql pack download y codeql database analyze para administrar paquetes en el GitHub Enterprise Server.

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.

De forma similar, puedes autenticarte en un Container registry del GitHub Enterprise Server o en varios registros simultáneamente (por ejemplo, para descargar o ejecutar paquetes privados de varios registros) de dos maneras:

1. Pasa la opción --registries-auth-stdin a la CodeQL CLI y, después, proporcione una cadena de autenticación del registro mediante la entrada estándar.
2. Establece la variable de entorno CODEQL_REGISTRIES_AUTH en una cadena de autenticación del registro.

Una cadena de autenticación del registro es una lista separada por comas de pares <registry-url>=<token>, donde registry-url es una dirección URL del Container registry, como https://containers.GHE_HOSTNAME/v2/, y token es un token de GitHub Apps o personal access token para ese Container registry de GitHub. Esto garantiza que cada token se pasa únicamente al Container registry que especifiques. Por ejemplo, la cadena de autenticación del registro siguiente especifica que la CodeQL CLI debe autenticarse en el Container registry en el GitHub.com con el token <token1> y en el Container registry para la instancia de GHES en GHE_HOSTNAME mediante el token <token2>:

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>