Creación y uso de paquetes de CodeQL

Paquetes de CodeQL y la CodeQL CLI

Con los paquetes de CodeQL y los comandos de administración de paquetes de la CodeQL CLI, puedes publicar tus consultas personalizadas e integrarlas en tu análisis del código base.

Hay dos tipos de paquetes de CodeQL: paquetes de consultas y paquetes de biblioteca.

• Los paquetes de consultas están diseñados para ejecutarse. Cuando se publica un paquete de consultas, el conjunto incluye todas las dependencias transitivas y una caché de compilación. Esto garantiza la ejecución coherente y eficaz de las consultas del paquete.
• Los paquetes de biblioteca están diseñados para que los usen paquetes de consulta (u otros paquetes de biblioteca) y no contienen consultas. Las bibliotecas no se compilan y no se incluye ninguna caché de compilación cuando el paquete se publica.

Puedes usar el comando pack en la CodeQL CLI para crear paquetes de CodeQL, agregar dependencias a los paquetes e instalar o actualizar dependencias. También puedes publicar y descargar paquetes de CodeQL con el comando pack. Para obtener más información, consulta "Publicación y uso de paquetes de CodeQL".

Creación de un paquete de CodeQL

Puedes crear un paquete de CodeQL ejecutando el comando siguiente desde la raíz de restauración del proyecto:

codeql pack init <scope>/<pack>

Debe especificar:

• <scope>: el nombre de la organización de GitHub o la cuenta de usuario en la que publicarás el paquete.

• <pack>: el nombre del paquete que estás creando.

El comando codeql pack init crea la estructura de directorios y los archivos de configuración de un paquete de CodeQL. De forma predeterminada, el comando crea un paquete de consultas. Si quieres crear un paquete de bibliotecas, debes editar el archivo qlpack.yml e incluir la propiedad library:true para declarar explícitamente el archivo como un paquete de bibliotecas.

Modificación de un paquete de QL heredado existente para crear un paquete de CodeQL

Si ya tienes un archivo qlpack.yml, puedes editarlo manualmente para convertirlo en un paquete de CodeQL.

1. Edita la propiedad name para que coincida con el formato <scope>/<name>, donde <scope> es el nombre de la organización de GitHub o la cuenta de usuario en la que publicarás el paquete.

2. En el archivo qlpack.yml, incluye una propiedad version con un identificador de SemVer, así como un bloque dependencies opcional.

3. Migra la lista de dependencias de libraryPathDependencies al bloque dependencies. Especifica el intervalo de versiones para cada dependencia. Si el intervalo no es importante o desconoces la compatibilidad, puedes especificar "\*", lo que indica que cualquier versión es aceptable y tendrá como valor predeterminado la versión más reciente al ejecutar codeql pack install.

Para obtener más información sobre las propiedades, consulta "Acerca de los paquetes de CodeQL".

Adición e instalación de dependencias en un paquete de CodeQL

Puedes agregar dependencias en los paquetes de CodeQL mediante el comando codeql pack add. Debes especificar el ámbito, el nombre y (opcionalmente) un intervalo de versiones compatibles.

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

Si no especificas ningún intervalo de versiones, se agregará la versión más reciente. De lo contrario, se agregará la versión más reciente dentro del intervalo especificado.

Este comando actualiza el archivo qlpack.yml con las dependencias solicitadas y las descarga en la caché del paquete. Ten en cuenta que este comando volverá a formatear el archivo y quitará todos los comentarios.

También puedes editar manualmente el archivo qlpack.yml para incluir dependencias e instalarlas con el comando:

codeql pack install

Este comando descarga todas las dependencias en la caché compartida en el disco local.