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

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

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 AE, 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, vea «Crear bases de datos de CodeQL» y «Crear bases de datos 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 «Crear 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é consultas se van a utilizar.

   codeql database analyze <database> --format=<format> \
       --output=<output>  <queries>

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

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

Ejemplo básico de 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.

Cargar resultados en GitHub AE

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 AE, 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-url=<URL> \
      --github-auth-stdin

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

Ejemplo básico de carga de resultados en GitHub AE

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-url=https://github.example.com \
    --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 AE 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".

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

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

Información adicional

• Crear bases de datos de CodeQL
• Análisis de bases de datos con la CLI de CodeQL