Publicación y uso de paquetes de CodeQL

Comparta o descargue un paquete CodeQL y a continuación, analice la base de datos de CodeQL.

¿Quién puede utilizar esta característica?

CodeQL está disponible para los siguientes tipos de repositorios:

En este artículo

Autenticación en Container registries de GitHub

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

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.

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.

Nota:

Si vas a publicar paquetes de modelos en el Container registry de GitHub para extender la cobertura a todos los repositorios de una organización como parte de una configuración predeterminada, debe asegurarte de que los repositorios que ejecutan el análisis de código puedan acceder a esos paquetes de modelos. Para más información, consulta Editar la configuración predeterminada y Configurar la visibilidad y el control de accesos de un paquete.

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>

Nota:

El comando codeql pack download almacena el paquete que descarga en una ubicación interna que no está pensada para la modificación local. Si el paquete se modifica después de la descarga se puede producir un comportamiento inesperado (con problemas difíciles de solucionar). Para obtener más información acerca de la personalización de paquetes, consulte Creación y uso de paquetes de CodeQL.