Acerca de los paquetes de CodeQL
Note
En este artículo se describen las características disponibles con el paquete CodeQL CLI 2.15.5 que se incluye en la versión inicial de GitHub Enterprise Server 3.12.
Si el administrador del sitio ha actualizado tu versión de la CodeQL CLI a una versión más reciente, consulta la versión de GitHub Enterprise Cloud de este artículo para obtener información sobre las características más recientes.
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 beta y están sujetos a cambios. Durante la beta, los paquetes de modelos están disponibles para el análisis de Java/Kotlin. 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 (beta) 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
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 «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 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.
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 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.
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.