Paquetes de CodeQL y la CodeQL CLI
Los paquetes de CodeQL se usan para crear, compartir y ejecutar consultas y bibliotecas de CodeQL, así como para establecer dependencias de ellas. Los paquetes de CodeQL contienen consultas, archivos de biblioteca, conjuntos de consultas y metadatos. 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 tres tipos de paquetes CodeQL: paquetes de consulta, paquetes de biblioteca y paquetes de modelos.
-
Los paquetes de consultas están diseñados para ejecutarse. Cuando se publica un paquete de consultas, la agrupación incluye todas las dependencias transitivas y representaciones compiladas previamente de cada consulta, además de los orígenes de consulta. 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 por separado.
-
Los paquetes de modelos se pueden usar para expandir análisis code scanning para incluir dependencias que no se admiten de forma predeterminada. Los modelos de paquetes están actualmente en beta y están sujetos a cambios. Durante la beta, los paquetes de modelos están disponibles para el análisis de C#, Java/Kotlin y Ruby. Para obtener más información sobre cómo crear tus propios paquetes de modelos, consulta «Creating a CodeQL model pack.»
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, vea «Publicación y uso de paquetes de CodeQL».
Para obtener más información sobre la compatibilidad entre los paquetes de consultas publicados y las diferentes versiones de CodeQL, consulta "Publicación y uso de paquetes de CodeQL".
Los paquetes estándar de CodeQL para todos los lenguajes admitidos se publican en el Container registry. El repositorio de CodeQL contiene archivos de origen para los paquetes estándar de CodeQL para todos los lenguajes admitidos. Los paquetes de consultas principales, que se incluyen en el conjunto de la CLI de CodeQL, pero que también se pueden descargar, son los siguientes:
codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
Estructura de los paquetes de CodeQL
Un paquete de CodeQL debe contener un archivo denominado qlpack.yml
en su directorio raíz. En el archivo qlpack.yml
, el campo name:
debe tener un valor que siga el formato <scope>/<pack>
, donde <scope>
es la organización o cuenta de usuario de GitHub en la que se publicará el paquete y <pack>
es el nombre del paquete. Además, los paquetes de consultas y los paquetes de biblioteca con pruebas CodeQL incluyen un archivo codeql-pack.lock.yml
que contiene las dependencias resueltas del paquete. Este archivo se genera durante una llamada al comando codeql pack install
, no está diseñado para editarse manualmente y debe agregarse al sistema de control de versiones.
Los demás archivos y directorios del paquete deben organizarse de forma lógica. Por ejemplo, normalmente:
-
Las consultas se organizan en directorios para categorías específicas.
-
Las consultas de productos, bibliotecas y marcos específicos se organizan en sus propios directorios de nivel superior.
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.
Creación de un paquete de modelo CodeQL
Nota: Los paquetes de modelos de CodeQL y el editor de modelos de CodeQL se encuentran actualmente en beta y están sujetos a cambios. Los paquetes de modelos son compatibles con el análisis de C#, Java/Kotlin y Ruby.
Los paquetes de modelos se pueden usar para expandir análisis code scanning para reconocer bibliotecas y marcos que no se admiten de forma predeterminada. Los paquetes de modelos usan extensiones de datos, que se implementan como YAML y describen cómo agregar datos para nuevas dependencias. Cuando se especifica un paquete de modelos, las extensiones de datos de ese paquete se agregarán automáticamente al análisis de code scanning. Para obtener más información sobre las extensiones de datos y los paquetes de modelos de CodeQL, consulte “Uso del editor de modelos de CodeQL”.
Un paquete de modelos es un paquete de CodeQL con las siguientes características en el archivo qlpack.yml
:
- Define
library: true
. - No tiene dependencias.
- Tiene uno o varios
extensionTargets
. - Tiene una propiedad
dataExtensions
que apunta a uno o varios archivos de extensión de datos.
Un paquete de modelos insertará sus extensiones de datos especificadas en cada paquete de consultas denominado en extensionTargets
si se encuentra dentro del intervalo de versiones especificado. Por ejemplo:
name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
codeql/java-all: ~1.2.3
codeql/util: ~4.5.6
dataExtensions:
- models/**/*.yml
En este ejemplo, el paquete de modelos insertará todas las extensiones de datos de models/**/
en un paquete de consultas codeql/java-all
que se encuentra en una versión de 1.2.3
hasta e incluye 1.3.0
, y un paquete de consultas codeql/util
que se encuentra en una versión de 4.5.6
hasta e incluye 4.6.0
. Para obtener más información, consulte "Uso del control de versiones semántico" en la documentación npm y "Especificación del control de versiones semántico".
Una vez que haya creado un paquete de modelos, puede publicarlo de la misma manera que otros paquetes CodeQL. Para obtener más información, vea «Publicación y uso de paquetes de CodeQL». A continuación, puede usar paquetes de modelos publicados en un análisis code scanning con la opción --model-packs
. Para obtener más información, vea «Personalización del análisis con paquetes de CodeQL».
Adición e instalación de dependencias en un paquete de CodeQL
Nota: Esto solo se admite para los paquetes de consulta y biblioteca 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.
Notas:
-
La ejecución de los comandos
codeql pack add
ycodeql pack install
generará o actualizará el archivocodeql-pack.lock.yml
. Este archivo debe estar registrado en el control de versiones. El archivocodeql-pack.lock.yml
contiene los números de versión precisos que usa el paquete. Para obtener más información, consulta "Acerca de los archivos codeql-pack.lock.yml". -
De forma predeterminada,
codeql pack install
instalará las dependencias de Container registry en GitHub.com. Puedes instalar dependencias desde Container registry de GitHub Enterprise Server mediante la creación de un archivoqlconfig.yml
. Para más información, consulta "Publicación y uso de paquetes de CodeQL" en la documentación de GitHub Enterprise Server.
Personalización de un paquete de CodeQL descargado
La manera recomendada de experimentar con cambios en un paquete es clonar el repositorio que contiene su código fuente.
Si no hay ningún repositorio de origen disponible y necesitas basar las modificaciones en un paquete descargado de Container registry, ten en cuenta que estos paquetes no están diseñados para ser modificados ni personalizados después de su descarga y su formato puede cambiar en el futuro sin previo aviso. Te recomendamos que sigas estos pasos después de descargar un paquete si necesitas modificar su contenido:
-
Cambia el nombre del paquete en
qlpack.yml
para evitar confusiones con los resultados del paquete sin modificar. -
Quita todos los archivos con el nombre
*.qlx
en la estructura de directorios desempaquetada. Estos archivos contienen versiones precompiladas de las consultas y, en algunos casos, CodeQL los usará de manera preferente frente al origen de QL que has modificado.