Personalización del análisis con paquetes de CodeQL

Acerca de los paquetes de CodeQL

Los paquetes de CodeQL se usan para crear, compartir y ejecutar consultas y bibliotecas de CodeQL, así como para establecer dependencias de ellas. Puedes publicar tus propios paquetes de CodeQL y descargar paquetes creados por otros usuarios. Los paquetes de CodeQL contienen consultas, archivos de biblioteca, conjuntos de consultas y metadatos.

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 representaciones precompiladas de cada consulta, además de los orígenes de las consultas. 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.

Puedes usar los comandos de administración de paquetes en la CodeQL CLI para crear paquetes de CodeQL, agregar dependencias a los paquetes e instalar o actualizar dependencias. Para obtener más información, vea «Creación y uso de paquetes de CodeQL». También puedes publicar y descargar paquetes de CodeQL con la CodeQL CLI. Para obtener más información, vea «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.

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.

Descargar y utilizar paquetes de consultas de CodeQL

El paquete de CodeQL CLI incluye consultas que mantienen los expertos de GitHub, los investigadores de seguridad y los contribuyentes de la comunidad. Si quieres ejecutar consultas que desarrollan otras organizaciones, los paquetes de consultas de CodeQL proporcionan una forma confiable y eficiente de descargarlas y ejecutarlas. Para obtener más información, vea «Acerca del examen de código con CodeQL».

Para poder usar un paquete de CodeQL para analizar una base de datos, debes descargar los paquetes que necesites del Container registry de GitHub. Puedes hacerlo si usas la marca --download como parte del comando codeql database analyze. Si un paquete no está disponible públicamente, deberás usar una GitHub App o un personal access token para autenticarte. Para obtener más información y ver un ejemplo, consulta "Carga de resultados en GitHub Enterprise Cloud".

Opción	Obligatorio	Uso
<scope/name@version:path>		Especifica el alcance y nombre de uno o más paquetes de consultas de CodeQL a descargar mediante una lista separada por comas. Opcionalmente, incluye la versión para descargar y descomprimir. Se descarga la versión más reciente de este paquete predeterminadamente. Opcionalmente, incluye una ruta de acceso a una consulta, directorio o conjunto de consultas que se vaya a ejecutar. Si no se incluye ninguna ruta de acceso, ejecuta las consultas predeterminadas de este paquete.
--github-auth-stdin		Pasa a la CLI la instancia de GitHub App o el personal access token que creaste para autenticarte con la API REST de GitHub desde el almacén de secretos a través de una entrada estándar. Esto no es necesario si el comando tiene acceso a una variable de entorno GITHUB_TOKEN establecida con este token.

Ejemplo básico de descarga y uso de paquetes de consulta

En este ejemplo se ejecuta el comando codeql database analyze con la opción --download para:

1. Descargar la versión más reciente del paquete octo-org/security-queries.
2. Descargar una versión del paquete octo-org/optional-security-queries que sea compatible con la versión 1.0.1 (en este caso, es la versión 1.0.2). Para obtener más información sobre la compatibilidad de SemVer, consulta la documentación del intervalo de versiones semánticas de npm.
3. Ejecutar todas las consultas predeterminadas en octo-org/security-queries.
4. Ejecutar solo la consulta queries/csrf.ql de octo-org/optional-security-queries

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Descarga directa de paquetes de CodeQL

Si quieres descargar un paquete de CodeQL sin ejecutarlo inmediatamente, puedes usar el comando codeql pack download. Esto resulta útil si quieres evitar acceder a Internet al ejecutar consultas de CodeQL. Al ejecutar el análisis de CodeQL, puedes especificar paquetes, versiones y rutas de acceso de la misma manera que en el ejemplo anterior:

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Descarga de paquetes de CodeQL de varios registros de contenedor de GitHub

Si tus paquetes de CodeQL están en varios registros de contenedor, debes indicar a la CodeQL CLI dónde encontrar cada paquete. Para obtener más información, vea «Personalizar la configuración avanzado de para el análisis de código».

Especificación de las consultas que se deben a ejecutar en un paquete de CodeQL

Los especificadores de consulta se usan en codeql database analyze y en otros comandos que operan en un conjunto de consultas. La forma completa de un especificador de consulta es scope/name@range:path, donde:

• scope/name es el nombre completo de un paquete de CodeQL.
• range es un intervalo de SemVer.
• path es una ruta de acceso del sistema de archivos a una sola consulta, un directorio que contiene consultas o un archivo de conjunto de consultas.

Cuando se especifica scope/name, range y path son opcionales. Si range se omite, se usa la versión más reciente del paquete especificado. Si path se omite, se usa el conjunto de consultas predeterminado del paquete especificado.

path puede ser un archivo de consulta .ql, un directorio que contiene una o varias consultas o un archivo de conjunto de consultas .qls. Si se omite el nombre de paquete, debes proporcionar path, que se interpretará en relación con el directorio de trabajo del proceso actual. No se admiten patrones globales.

Si se especifica scope/name y path, el valor de path no puede ser absoluto. Se interpreta en relación con la raíz del paquete de CodeQL.

Especificadores de consulta de ejemplo

• codeql/python-queries: todas las consultas del conjunto de consultas predeterminado de la versión más reciente del paquete codeql/python-queries.

• codeql/python-queries@1.2.3: todas las consultas del conjunto de consultas predeterminado de la versión 1.2.3 del paquete codeql/python-queries.

• codeql/python-queries@~1.2.3: todas las consultas del conjunto de consultas predeterminado de la versión más reciente del paquete codeql/python-queries que es >= 1.2.3 y < 1.3.0.

• codeql/python-queries:Functions: todas las consultas del directorio Functions en la versión más reciente del paquete codeql/python-queries.

• codeql/python-queries@1.2.3:Functions: todas las consultas del directorio Functions de la versión 1.2.3 del paquete codeql/python-queries.

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls: todas las consultas del directorio codeql-suites/python-code-scanning.qls de la versión 1.2.3 del paquete codeql/python-queries.

• suites/my-suite.qls: todas las consultas del archivo suites/my-suite.qls en relación con el directorio de trabajo actual.

Acerca de los paquetes publicados

Cuando se publica un paquete para su uso en análisis, el comando codeql pack create o codeql pack publish comprueba que el contenido está completo y también le agrega algunos fragmentos de contenido adicionales:

• En el caso de los paquetes de consultas, una copia de cada uno de los paquetes de biblioteca de los que depende, en las versiones específicas con las que se ha desarrollado. Los usuarios del paquete de consultas no tendrán que descargar estos paquetes de biblioteca por separado.

• En el caso de los paquetes de consultas, representaciones precompiladas de cada una de las consultas. Son más rápidos de ejecutar que si se compilara el origen de QL para la consulta en cada análisis.

La mayoría de estos datos se encuentran en un directorio denominado .codeql en el paquete publicado, pero las consultas precompiladas están en archivos con un sufijo .qlx junto al origen .ql de cada consulta. Al analizar una base de datos con una consulta de un paquete publicado, CodeQL cargará estos archivos en lugar del origen .ql. Si necesitas modificar el contenido de un paquete publicado, asegúrate de quitar todos los archivos .qlx, ya que podrían impedir que las modificaciones de los archivos .ql surtieran efecto.