Skip to main content
Publicamos actualizaciones para la documentación con frecuencia y es posible que aún se esté traduciendo esta página. Para obtener la información más reciente, consulta la documentación en inglés.

Configurar el CLI de CodeQL en tu sistema de IC

Puedes configurar tu sistema de integración continua para que ejecute el CodeQL CLI, realice un análisis de CodeQL y cargue los resultados en GitHub para mostrarlos como alertas del code scanning.

Code scanning está disponible para todos los repositorios públicos en GitHub.com. Code scanning también está disponible para los repositorios privados que pertenecen a las organizaciones que usan GitHub Enterprise Cloud y que tienen una licencia de GitHub Advanced Security. Para más información, consulte "Acerca de GitHub Advanced Security".

Acerca de generar los resultados del escaneo de código con el CodeQL CLI

Una vez que hayas puesto el CodeQL CLI disponible en los servidores de tu sistema de IC y de que te hayas asegurado que se pueden autenticar con GitHub, estarás listo para generar datos.

Utilizarás tres comandos diferentes para generar los resultados y cargarlos a GitHub:

  1. database create para crear una base de datos de CodeQL que represente la estructura jerárquica de cada lenguaje de programación admitido en el repositorio.
  2. database analyze para ejecutar consultas para analizar cada base de datos de CodeQL y resumir los resultados en un archivo SARIF.
  3. github upload-results para cargar los archivos SARIF resultantes a GitHub, donde los resultados se comparan con una rama o solicitud de incorporación de cambios y se muestran como alertas del code scanning.

Puede mostrar la ayuda de la línea de comandos para cualquier comando mediante --help.

Nota: Cargar datos de SARIF para mostrarlos como resultados de code scanning en GitHub es compatible para los repositorios que pertenezcan a organizaciones con la GitHub Advanced Security habilitada y para los repositorios públicos en GitHub.com. Para más información, vea "Administración de la configuración de seguridad y análisis para el repositorio".

Crear bases de datos de CodeQL para analizar

  1. Extraiga del repositorio el código que quiera analizar:

    • En el caso de una rama, extraiga del repositorio el inicio de la rama que quiera analizar.
    • Para una solicitud de incorporación de cambios, compruebe la confirmación del encabezado de la solicitud o una confirmación de combinación generada por GitHub de esa solicitud.
  2. Configure el entorno para el código base y asegúrese de que las dependencias estén disponibles. Para obtener más información, consulta "Creación de bases de datos para lenguajes no compilados" y "Creación de bases de datos para lenguajes compilados".

  3. Busque el comando de compilación, si lo hay, para el código base. Normalmente está disponible en un archivo de configuración en el sistema de CI.

  4. Ejecute codeql database create desde la raíz de extracción del repositorio y compile el código base.

    # Single supported language - create one CodeQL database
    codeql database create <database> --command<build> --language=<language-identifier>
    
    # Multiple supported languages - create one CodeQL database per language
    codeql database create <database> --command<build> \
          --db-cluster --language=<language-identifier>,<language-identifier>

    Nota: Si utiliza una compilación con contenedores, deberá ejecutar el CodeQL CLI dentro del contenedor donde tiene lugar la tarea de compilación.

OpciónObligatorioUso
<database>Especifica el nombre y ubicación de un directorio a crear para la base de datos de CodeQL. Se producirá un error en el comando si intenta sobrescribir un directorio existente. Si también especifica --db-cluster, este es el directorio primario y se crea un subdirectorio para cada lenguaje analizado.
--languageEspecifique el identificador para el lenguaje para el que se va a crear una base de datos, uno de los siguientes: cpp`, `csharp`, `go`, `java`, `javascript`, `python` y `ruby (use javascript para analizar código de TypeScript y java para analizar código de Kotlin). Cuando se usa con --db-cluster, la opción acepta una lista separada por comas o se puede especificar más de una vez.
--commandSe recomienda su uso. Se usa para especificar el comando de compilación o el script que invoca el proceso de compilación para el código base. Los comandos se ejecutan desde la carpeta actual, o donde se define, desde --source-root. No es necesario para el análisis de Python y JavaScript o TypeScript.
--db-clusterOpcional. Se usa en códigos base de varios lenguajes para generar una base de datos para cada lenguaje especificado por --language.
--no-run-unnecessary-buildsSe recomienda su uso. Utilízalo para suprimir el comando de compilación para los lenguajes en donde el CodeQL CLI no necesite monitorear la compilación (por ejemplo, Python y JavaScript/TypeScript).
--source-rootOpcional. Se usa si ejecuta la CLI fuera de la raíz de extracción del repositorio. De manera predeterminada, el comando database create supone que el directorio actual es el directorio raíz de los archivos de origen. Use esta opción para especificar otra ubicación.
--codescanning-config(Opcional (Avanzado). Úsalo si tienes un archivo de configuración que especifica cómo crear las bases de datos CodeQL y qué consultas ejecutar en pasos posteriores. Para más información, consulta "Personalización de code scanning" y "Creación de una base de datos".

Para obtener más información, consulta "Creación de bases de datos de CodeQL".

Ejemplo de un solo lenguaje

En este ejemplo se crea una base de datos de CodeQL para el repositorio extraído en /checkouts/example-repo. Usa el extractor de JavaScript para crear una representación jerárquica del código JavaScript y TypeScript en el repositorio. La base de datos resultante se almacena en /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Ejemplo de lenguaje múltiple

En este ejemplo se crean dos base de datos de CodeQL para el repositorio extraído en /checkouts/example-repo-multi. Usa:

  • --db-cluster para solicitar el análisis de más de un lenguaje.
  • --language para especificar los lenguajes para los que se crearán las bases de datos.
  • --command para indicarle a la herramienta el comando de compilación para el código base, en este caso make.
  • --no-run-unnecessary-builds para indicarle a la herramienta que omita el comando de compilación para los lenguajes en los que no es necesario (como Python).

Las bases de datos resultantes se almacenan en los subdirectorios python y cpp de /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Analizar una base de datos de CodeQL

  1. Crea una base de datos de CodeQL (se explica anteriormente).
  2. Ejecuta codeql database analyze en la base de datos y especifica qué paquetes o consultas se van a utilizar.
    codeql database analyze <database> --format=<format> \
        --output=<output>  --download <packs,queries>

Nota: Si analiza más de una base de datos de CodeQL para una sola confirmación, debe especificar una categoría SARIF para cada conjunto de resultados generados por este comando. Cuando cargas los resultados en GitHub, el code scanning utiliza esta categoría para almacenar los resultados para cada lenguaje por separado. Si olvida hacerlo, cada carga sobrescribe los resultados anteriores.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>
OpciónObligatorioUso
<database>Especifica la ruta del directorio que contiene la base de datos de CodeQL a analizar.
<packs,queries>Especifica los paquetes o consultas de CodeQL a ejecutar. Para ejecutar las consultas estándar que se utilizan para el code scanning, omite este parámetro. Para ver los demás conjuntos de consultas incluidos en el conjunto de la CodeQL CLI, busque en /<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites. Para obtener información sobre cómo crear un conjunto de consultas propio, consulte Creación de conjuntos de consultas de CodeQL en la documentación de la CodeQL CLI.
--formatEspecifique el formato del archivo de resultados generado por el comando. Para cargarlo en GitHub, debe ser: sarif-latest. Para obtener más información, consulte "Compatibilidad con SARIF para code scanning".
--outputEspecifique dónde guardar el archivo de resultados de SARIF.
--sarif-categoryOpcional para el análisis de base de datos única. Necesario para definir el lenguaje al analizar varias bases de datos para una sola confirmación en un repositorio. Especifique una categoría que se incluirá en el archivo de resultados de SARIF para este análisis. Una categoría se usa para distinguir varios análisis de la misma herramienta y confirmación, pero se ejecuta en distintos lenguajes o partes del código.
--sarif-add-query-helpOpcional. Se usa si se quiere incluir cualquier ayuda de consulta representada por Markdown disponible para las consultas personalizadas que se usan en el análisis. Cualquier ayuda de consulta para consultas personalizadas incluidas en la salida de SARIF se mostrará en la interfaz de usuario de examen de código si la consulta correspondiente genera una alerta. Para obtener más información, consulta "Análisis de bases de datos con la CodeQL CLI".
<packs>Opcional. Úsalo si quieres incluir paquetes de consulta de CodeQL en el análisis. Para obtener más información, consulta "Descarga y uso de paquetes de CodeQL".
--downloadOpcional. Úsalo si algunos de los paquetes de consulta de CodeQL aún no están en el disco y deben descargarse antes de ejecutar consultas.
--threadsOpcional. Se usa si se quiere usar más de un subproceso para ejecutar consultas. El valor predeterminado es 1. Puede especificar más subprocesos para acelerar la ejecución de consultas. Para establecer el número de subprocesos en el número de procesadores lógicos, especifique 0.
--verboseOpcional. Se usa para obtener información más detallada sobre el proceso de análisis y datos de diagnóstico del proceso de creación de la base de datos.

Para obtener más información, consulta "Análisis de bases de datos con la CodeQL CLI".

Ejemplo básico

En este ejemplo se analiza una base de datos de CodeQL almacenada en /codeql-dbs/example-repo y se guardan los resultados como un archivo SARIF: /temp/example-repo-js.sarif. Usa --sarif-category para incluir información adicional en el archivo SARIF que identifica los resultados como JavaScript. Esto es esencial cuando tienes más de una base de datos de CodeQL que analizar para una confirmación única en un repositorio.

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Cargar resultados en GitHub

Puedes comprobar que las propiedades SARIF tienen el tamaño compatible para la carga y que el archivo es compatible con el examen de código. Para obtener más información, consulta "Validación del archivo SARIF".

Para poder cargar resultados en GitHub, debes determinar la mejor forma de pasar la GitHub App o el personal access token que creaste anteriormente a la CodeQL CLI (consulta Instalación de la CodeQL CLI en el sistema de CI). Se recomienda revisar las instrucciones del sistema de CI sobre el uso seguro de un almacén de secretos. El CodeQL CLI es compatible con:

  • Pasar el token a la CLI por medio de la entrada estándar mediante la opción --github-auth-stdin (recomendado).
  • Guardar el secreto en la variable de entorno GITHUB_TOKEN y ejecutar la CLI sin incluir la opción --github-auth-stdin.

Cuando haya decidido el método más seguro y confiable para el servidor de CI, ejecute codeql github upload-results en cada archivo de resultados de SARIF e incluya --github-auth-stdin a menos que el token esté disponible en la variable de entorno GITHUB_TOKEN.

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin
OpciónObligatorioUso
--repositoryEspecifique el PROPIETARIO/NOMBRE del repositorio en el que se cargarán los datos. El propietario debe ser una organización dentro de una empresa que tenga una licencia de GitHub Advanced Security, y la GitHub Advanced Security debe estar habilitada para el repositorio, a menos que sea público. Para más información, vea "Administración de la configuración de seguridad y análisis para el repositorio".
--refEspecifique el nombre de la ref que ha extraído del repositorio y ha analizado para que los resultados puedan coincidir con el código correcto. Para usarla en una rama: refs/heads/BRANCH-NAME, para la confirmación del encabezado de una solicitud de incorporación de cambios use refs/pull/NUMBER/head, y para la confirmación de la combinación generada por GitHub de una solicitud de incorporación de cambios use refs/pull/NUMBER/merge.
--commitEspecifique el SHA completo de la confirmación que ha analizado.
--sarifEspecifica el archivo SARIF que se va a cargar.
--github-auth-stdinOpcional. Utilízala para pasar a la CLI la GitHub App o el personal access token que creaste para autenticarte con la API de REST de GitHub 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.

Para obtener más información, consulte github upload-results en la documentación de la CodeQL CLI.

Ejemplo básico

En este ejemplo se cargan los resultados del archivo temp/example-repo-js.sarif SARIF en el repositorio my-org/example-repo. Se indica a la API de code scanning que los resultados son para la confirmación de deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 en la rama de main.

$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

No hay salida para este comando a menos de que la carga no sea exitosa. El símbolo de sistema regresa cuando la carga se completa e inicia el procesamiento de datos. En bases de código más pequeñas, debes poder explorar las alertas del code scanning en GitHub poco tiempo después. Puede ver las alertas directamente en la solicitud de incorporación de cambios o en la pestaña Security de las ramas, en función del código que haya extraído. Para obtener más información, consulte "Evaluación de prioridades de las alertas de code scanning en solicitudes de incorporación de cambios" y "Administración de alertas de code scanning para el repositorio".

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, consulte "Acerca del análisis 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, consulte la sección anterior "Carga de resultados en GitHub".

OpciónObligatorioUso
<scope/name@version:path>Especifica el alcance y nombre de uno o más paquetes de consultas de CodeQL a descargar utilizando 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-stdinOpcional. Pasa a la CLI la GitHub App o el personal access token que creaste para autenticarte con la API de REST de GitHub en la CLI 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 CLI de CodeQL que usas.

Para obtener más información sobre la compatibilidad de paquetes, consulta "Acerca de la compatibilidad de paquetes de CodeQL".

Ejemplo básico

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 más información, consulta "Personalización de code scanning".

Configuración de IC de ejemplo para el análisis de CodeQL

Este es un ejemplo de la serie de comandos que puedes utilizar para analizar una base de código con dos lenguajes compatibles y luego cargar los resultados a GitHub.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

# Upload the SARIF file with the Python results: 'python-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

Solucionar problemas del CodeQL CLI en tu sistema de IC

Visualizar la información diangóstica y de la bitácora

Cuando analices una base de datos de CodeQL utilizando un conjunto de consultas del code scanning adicionalmente a generar información detallada sobre las alertas, el CLI reporta datos de diagnóstico desde el paso de generación de base de datos y las métricas de resumen. En el caso de los repositorios con pocas alertas, puede que esta información te sea útil para determinar si genuinamente hay pocos problemas en el código o si hubieron errores que se generaron en la base datos de CodeQL. Para obtener un resultado más detallado de codeql database analyze, utilice la opción --verbose.

Para obtener más información sobre el tipo de información de diagnóstico disponible, consulte "Visualización de registros de code scanning".

El Code scanning solo muestra los resultados de análisis de uno de los lenguajes analizados

Predeterminadamente, el code scanning espera un archivo de resultado SARIF por cada análisis de un repositorio. Como consecuencia, cuando cargues un segundo archivo de resultados SARIF para una confirmación, este se tratará como un reemplazo para el conjunto de datos original.

Si quieres cargar más de un conjunto de resultados a la API del code scanning para una confirmación en un repositorio, debes identificar cada conjunto de resultados como un conjunto único. En el caso de los repositorios donde crees más de una base de datos de CodeQL para analizar cada confirmación, utilice la opción --sarif-category para especificar un lenguaje u otra categoría única para cada archivo SARIF que genere para ese repositorio.

Problemas con la extracción de Python

Vamos a dejar en desuso la compatibilidad de Python 2 con la CodeQL CLI, más concretamente, para la fase de generación de bases de datos CodeQL (extracción de código).

Si usas la CodeQL CLI para ejecutar el code scanning de CodeQL en código escrito en Python, debes asegurarte de que el sistema de CI tiene Python 3 instalado.

Información adicional