Publicación y uso de paquetes de CodeQL

Trabajar con los CodeQL paquetes en GitHub Enterprise Server

De forma predeterminada, CodeQL CLI espera descargar paquetes de CodeQL y publicar paquetes en Container registry en GitHub.com. Sin embargo, también puede trabajar con CodeQL paquetes en un Container registry en GitHub Enterprise Server creando un archivo qlconfig.yml para decir 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 siguiente qlconfig.yml archivo asocia todos los paquetes con el Container registry en https://GHE_HOSTNAME, excepto aquellos paquetes que coinciden con codeql/\* o con la organización other-org/*, que están asociados con Container registry en GitHub.com.

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

          CodeQL CLI Determinará qué registro usar para un nombre de paquete determinado mediante la búsqueda del primer elemento de la `registries` lista con una `packages` propiedad 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 lo hace, podrá definir los registros que se usarán en un área de trabajo específica, de modo que se pueda compartir entre otros CodeQL usuarios 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 downloady codeql database analyze para administrar paquetes en GitHub Enterprise Server.

Autenticación en GitHubContainer registries

Puede publicar paquetes y descargar paquetes privados mediante la autenticación en el adecuado GitHubContainer registry.

Autenticándose en Container registries en GitHub.com

Puede autenticarse Container registry de dos maneras:

1. Pase la --github-auth-stdin opción a CodeQL CLIy proporcione un GitHub Apps token o personal access token a través de la entrada estándar.
2. Establezca la variable de entorno GITHUB_TOKEN a un token GitHub Apps o personal access token.

Autenticándose en Container registries en GitHub Enterprise Server

Del mismo modo, puede autenticarse en un Container registry en GitHub Enterprise Servero autenticarse en varios registros simultáneamente (por ejemplo, para descargar o ejecutar paquetes privados desde varios registros) de dos maneras:

1. Pase la --registries-auth-stdin opción a CodeQL CLIy proporcione una cadena de autenticación del Registro a través de 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 Container registry, como https://containers.GHE_HOSTNAME/v2/, y token es un token GitHub Apps o personal access token para ese Container registry. Esto garantiza que cada token solo se pasa al Container registry especificado.

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

• Utilice el token <token1> para autenticarse en Container registry en GitHub.com.
• Usa el token <token2> para autenticarse en Container registry para la empresa ubicada en https://containers.GHE_HOSTNAME/v2/.

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

Publicación del CodeQL paquete

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

Configuración del archivo qlpack.yml antes de publicarlo

Puede comprobar y modificar los detalles de configuración de su paquete CodeQL antes de publicarlo. 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 a la que se 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é listo para publicar un paquete en GitHubContainer registry, puede ejecutar el siguiente comando en la raíz del directorio del pack:

codeql pack publish

El paquete publicado se mostrará en la sección de paquetes de la organización especificada por el ámbito en el archivo qlpack.yml.

Descarga de un paquete existente CodeQL

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 desde la cual 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 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 un rendimiento degradado cuando se usan con paquetes de consultas que se han anclado a una versión muy antigua. Para obtener más información, vea Referencia de paquetes de consulta de CodeQL.

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

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

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

•         `<database>`: la CodeQL base de datos que se va a analizar.
  

•         `<scope>`: el nombre de la organización a la GitHub que se publica 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 cualquier CodeQL paquetes especificados. Puede especificar varios CodeQL paquetes que se usarán para analizar una CodeQL base de datos. Por ejemplo:

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