Configurar el CLI de CodeQL en tu sistema de IC

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 Enterprise Cloud, estarás listo para generar datos.

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

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 Enterprise Cloud, 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.

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" en "Preparación del código para el análisis de CodeQL".

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.

Para obtener más información, vea «Preparación del código para el análisis 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>
   

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

Para obtener más información, vea «Análisis del código con consultas de CodeQL».

Ejemplo básico del análisis de una base de datos de CodeQL

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.

Adición de información de cobertura de archivos a los resultados para la supervisión

Opcionalmente, puedes enviar información de cobertura de archivos a GitHub Enterprise Cloud para su presentación en la página de estado de la herramienta para code scanning. Para más información sobre la página de cobertura de seguridad, consulta "Acerca de la página de estado de la herramienta para el examen de código".

Para incluir información de cobertura de archivos con los resultados de code scanning, agrega la marca --sarif-add-baseline-file-info a la invocación codeql database analyze en el sistema de CI, por ejemplo:

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

Cargar resultados en GitHub Enterprise Cloud

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 más información, consulta "Soporte de SARIF para escaneo de código".

Para poder cargar resultados en GitHub Enterprise Cloud, 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:

• Interacción con un almacén de secretos 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.
• Con fines de prueba, puedes pasar la opción de línea de comandos --github-auth-stdin y proporcionar un token temporal a través de la entrada estándar.

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.

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> 

Para obtener más información, vea «github upload-results».

Ejemplo básico de carga de resultados en GitHub Enterprise Cloud

En este ejemplo se cargan los resultados del archivo SARIF temp/example-repo-js.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. En el ejemplo se da por hecho que la instancia de GitHub App o el personal access token creado para la autenticación con la API REST de GitHub usa la variable de entorno GITHUB_TOKEN.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif 

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 Enterprise Cloud poco tiempo después. Puedes ver alertas directamente en la solicitud de incorporación de cambios o en la pestaña Seguridad de las ramas, según el código extraído del repositorio. Para más información, consulta "Clasificar las alertas del escaneo de código en las solicitudes de cambios" y "Administración de alertas de examen de código para el repositorio".

Carga de información de diagnóstico en GitHub Enterprise Cloud si se produce un error en el análisis

Cuando CodeQL CLI termina de analizar correctamente una base de datos, recopila información de diagnóstico, como la cobertura de archivos, las advertencias y los errores, y lo incluye en el archivo SARIF con los resultados. Al cargar el archivo SARIF en GitHub, la información de diagnóstico se muestra en la página de estado de la herramienta code scanning del repositorio para facilitar la visualización del rendimiento de los datos CodeQL y depura los problemas. Para obtener más información, vea «Acerca de la página de estado de la herramienta para el examen de código».

Sin embargo, si codeql database analyze produce un error por cualquier motivo, no hay ningún archivo SARIF que se cargue en GitHub y no se muestra ninguna información de diagnóstico en la página de estado de la herramienta code scanning para el repositorio. Esto dificulta a los usuarios solucionar problemas de análisis a menos que tengan acceso a los archivos de registro en el sistema de CI.

Se recomienda configurar el flujo de trabajo de CI para exportar y cargar información de diagnóstico en GitHub Enterprise Cloud cuando se produce un error en un análisis. Puedes hacerlo con los siguientes comandos sencillos para exportar la información de diagnóstico y cargarla en GitHub.

Exportación de información de diagnóstico si se produce un error en el análisis

Puedes crear un archivo SARIF para el análisis con errores mediante "exportación de diagnóstico de base de datos", por ejemplo:

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

Este archivo SARIF contendrá información de diagnóstico para el análisis con errores, incluida cualquier información de cobertura de archivos, advertencias y errores generados durante el análisis.

Carga de información de diagnóstico si se produce un error en el análisis

Para que esta información de diagnóstico esté disponible en la página de estado de la herramienta, cargue el archivo SARIF en GitHub Enterprise Cloud con "github upload-results", por ejemplo:

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif 

Esto es el mismo que el proceso para cargar archivos SARIF a partir de análisis correctos.

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, consulte la sección anterior "Carga de resultados en GitHub Enterprise Cloud".

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».

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 Enterprise Cloud.

# 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'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

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

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

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 más información sobre el tipo de información de diagnóstico disponible, consulta "Visualizar las bitácoras del escaneo de código".

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

• "Preparación del código para el análisis de CodeQL".
• "Análisis del código con consultas de CodeQL."
• Publicación y uso de paquetes de CodeQL