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. Los paquetes de CodeQL contienen consultas, archivos de biblioteca, conjuntos de consultas y metadatos. Puedes personalizar el análisis de CodeQL si descargas paquetes creados por otros usuarios y ejecutándolos en el código base.

Hay tres tipos de paquetes CodeQL: paquetes de consulta, paquetes de biblioteca y paquetes de modelos.

Los paquetes de consultas contienen un conjunto de consultas precompiladas que se pueden evaluar en una base de datos CodeQL. 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 reconocer bibliotecas y marcos que no se admiten de forma predeterminada. Los modelos de paquetes están actualmente en versión preliminar pública y están sujetos a cambios. Durante la versión preliminar pública, los paquetes de modelos están disponibles para el análisis de C#, Java/Kotlin, Python, and Ruby. Para más información sobre cómo crear sus propios paquetes de modelos, consulte "Creación y uso de paquetes de CodeQL".

Los paquetes estándar de CodeQL para todos los lenguajes admitidos se publican en el Container registry. Si instalaste la CodeQL CLI de la manera estándar, con el paquete de la CodeQL CLI, los paquetes de consultas principales ya estarán descargados y disponibles. Son los siguientes:

codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
codeql/swift-queries

También puedes usar el comando la CodeQL CLI para crear tus propios paquetes de CodeQL, añadir 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 bases de datos de CodeQL que hayas creado, mediante la CodeQL CLI. Para obtener más información sobre la publicación y descarga de paquetes de CodeQL, consulta «Publicación y uso de paquetes de CodeQL».

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 desea ejecutar consultas desarrolladas por otras organizaciones, los paquetes de consultas de CodeQL proporcionan una manera eficaz y confiable de descargar y ejecutar consultas, mientras que los paquetes de modelos (versión preliminar pública) se pueden usar para expandir análisis de code scanning para reconocer bibliotecas y marcos que no son compatibles de manera predeterminada. Para más información sobre los paquetes de consultas, consulte "Acerca del examen de código con CodeQL". Para obtener información sobre cómo escribir sus propios paquetes de modelos, consulte "Creación y uso de paquetes de CodeQL".

Para poder usar un paquete de consultas CodeQL para analizar una base de datos, debe descargar los paquetes que necesite del GitHub Container registry. Puede hacerlo si usa la marca --download como parte del comando codeql database analyze o ejecutar codeql pack download. 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 un ejemplo, consulta "Carga de los resultados del análisis de CodeQL en GitHub".

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.

Note

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 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 «Personalización de la configuración avanzada para el examen 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.

Tip

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 conjunto cpp-code-scanning.qls predeterminado para C++, además de consultas de gravedad y precisión más bajas.
cpp-security-and-quality.qls: consultas de cpp-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.

Uso de paquetes de modelos para analizar llamadas a dependencias personalizadas

Puede incluir paquetes de modelos publicados en un análisis code scanning con la opción --model-packs. Por ejemplo:

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --model-packs my-repo/my-java-model-pack \
  --output=/temp/my-company.sarif codeql/java-queries

En este ejemplo, las consultas pertinentes del paquete de consultas estándar codeql/java-queries usarán la información de dependencia del paquete de modelos, my-repo/my-java-model-pack, para comprobar si hay vulnerabilidades en el código que llama a esas dependencias.

Puede especificar varios paquetes de modelos publicados en un análisis.

Para más información sobre cómo escribir tus propios paquetes de modelos, consulta «Creación y uso de paquetes de CodeQL».

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.