Nota: La funcionalidad de administración de paquetes de CodeQL, incluidos los de CodeQL, se encuentra disponible actualmente en versión beta y está sujeta a cambios. Durante la versión beta, los paquetes de CodeQL solo están disponibles si se usa GitHub Packages: el Container registry. Para usar esta funcionalidad beta, instala la versión más reciente del paquete de la CodeQL CLI desde https://github.com/github/codeql-action/releases.
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
Nota: La funcionalidad de administración de paquetes de CodeQL, incluidos los de CodeQL, se encuentra actualmente en versión beta y está sujeta a cambios.
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. |
Nota: Si especificas que se use una versión determinada de un paquete de consultas, ten en cuenta que la versión que indiques podría ser demasiado antigua para que la versión más reciente de CodeQL la use de forma eficiente. Para garantizar un rendimiento óptimo, si necesitas especificar versiones concretas del paquete de consultas, debes volver a evaluar a qué versiones anclas cada vez que actualices la CodeQL CLI que usas.
Para obtener más información sobre la compatibilidad de los paquetes, consulte "Publicación y uso de paquetes de CodeQL".
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:
- Descargar la versión más reciente del paquete
octo-org/security-queries
. - 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. - Ejecutar todas las consultas predeterminadas en
octo-org/security-queries
. - Ejecutar solo la consulta
queries/csrf.ql
deocto-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 paquetecodeql/python-queries
. -
codeql/python-queries@1.2.3
: todas las consultas del conjunto de consultas predeterminado de la versión1.2.3
del paquetecodeql/python-queries
. -
codeql/python-queries@~1.2.3
: todas las consultas del conjunto de consultas predeterminado de la versión más reciente del paquetecodeql/python-queries
que es >=1.2.3
y <1.3.0
. -
codeql/python-queries:Functions
: todas las consultas del directorioFunctions
en la versión más reciente del paquetecodeql/python-queries
. -
codeql/python-queries@1.2.3:Functions
: todas las consultas del directorioFunctions
de la versión 1.2.3 del paquetecodeql/python-queries
. -
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls
: todas las consultas del directoriocodeql-suites/python-code-scanning.qls
de la versión 1.2.3 del paquetecodeql/python-queries
. -
suites/my-suite.qls
: todas las consultas del archivosuites/my-suite.qls
en relación con el directorio de trabajo actual.
Sugerencia
El conjunto de consultas predeterminado de los paquetes de consultas estándar de CodeQL es codeql-suites/<lang>-code-scanning.qls
. También se pueden encontrar otros conjuntos de consultas útiles en el directorio codeql-suites
de cada paquete. Por ejemplo, el paquete codeql/cpp-queries
contiene los siguientes conjuntos de consultas:
-
cpp-code-scanning.qls
: consultas de examen de código estándar para C++. Es el conjunto de consultas predeterminado para este paquete. -
cpp-security-extended.qls
: consultas del conjuntocpp-code-scanning.qls
predeterminado para C++, además de consultas de gravedad y precisión más bajas. -
cpp-security-and-quality.qls
: consultas decpp-security-extended.qls
, además de consultas de mantenimiento y confiabilidad.
Puedes ver los orígenes de estos conjuntos de consultas en el repositorio de CodeQL. Los conjuntos de consultas de otros lenguajes son similares.
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.