Publicación y uso de paquetes de CodeQL

Trabajo con paquetes de CodeQL en Nube de GitHub Enterprise con residencia de datos

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 puede trabajar con paquetes de CodeQL en un Container registry en Nube de GitHub Enterprise con residencia de datos 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 en Linux/MacOS o %HOMEPATH%\.codeql\qlconfig.yml en Windows utilizando su editor de texto preferido y añada entradas para especificar qué registro utilizar para uno o más patrones de nombres de paquetes. Por ejemplo, el archivo qlconfig.yml siguiente asocia todos los paquetes con el Container registry en SUBDOMAIN.ghe.com, excepto los paquetes que coinciden con codeql/\* o la organización other-org/*, que están asociados con el Container registry en el GitHub.com:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `SUBDOMAIN.ghe.com`
  url: https://containers.SUBDOMAIN.ghe.com

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 sobre codeql-workspace.yml, consulta Acerca de las áreas de trabajo de CodeQL.

Ahora puede usar codeql pack publish, codeql pack download y codeql database analyze para administrar paquetes de Nube de GitHub Enterprise con residencia de datos.

Autenticación en Container registries de GitHub

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

Autenticación en Container registries en GitHub.com

Puede autenticarse en Container registry 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.

Autenticación en Container registries en Nube de GitHub Enterprise con residencia de datos

De forma similar, puede autenticarse en un Container registry en Nube de GitHub Enterprise con residencia de datos 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.SUBDOMAIN.ghe.com, y token es un token de GitHub Apps o personal access token para ese Container registry. Esto garantiza que cada token se pasa únicamente al Container registry que especifiques.

Por ejemplo, la siguiente cadena de autenticación del registro especifica que la CodeQL CLI debe autenticarse de la siguiente manera:

• Use el token <token1> para autenticarse en el Container registry en el GitHub.com:
• Use el token <token2> para autenticarse en el Container registry de la empresa en https://containers.SUBDOMAIN.ghe.com.

https://ghcr.io/v2/=<token1>,https://containers.SUBDOMAIN.ghe.com=<token2>

Publicación del paquete de CodeQL

Para compartir el paquete de CodeQL con otras personas, puede publicarlo en el Container registry.

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>
defaultSuite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
defaultSuiteFile: 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 va a publicar y `<pack>` es el nombre del paquete.
  

• Se permite un máximo de un elemento defaultSuite o defaultSuiteFile. 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.

Descarga de un paquete de CodeQL existente

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

•         `<pack>`: el nombre del paquete que quiere 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 escribe scripts que especifican un número de versión determinado de un paquete de consultas que se va a descargar, tenga en cuenta que al actualizar la versión de CodeQL a una versión más reciente, es posible que también tenga 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, consulte 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á 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>