Uso de la CLI de CodeQL

8 minutos

Además de la interfaz gráfica de usuario de GitHub.com, también puede acceder a muchas de las mismas características principales de CodeQL mediante una interfaz de la línea de comandos.

En esta unidad se describirá el uso de la CLI de CodeQL para crear bases de datos, analizarlas y cargar los resultados en GitHub.

Comandos de la CLI de CodeQL

Una vez que haya puesto la CLI de CodeQL a disposición de los servidores del sistema de CI y se haya asegurado de que se pueden autenticar con GitHub, estará listo para generar datos.

Puede usar tres comandos diferentes para generar resultados y cargarlos en GitHub:

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.
database analyze para ejecutar consultas a fin de analizar cada base de datos de CodeQL y resumir los resultados en un archivo SARIF.
github upload-results para cargar los archivos SARIF resultantes en GitHub donde los resultados se comparan con una rama o solicitud de incorporación de cambios, y se muestran como alertas de examen de código.

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

La carga de datos SARIF para mostrarlos como resultados de examen de código en GitHub se admite en repositorios propiedad de la organización con la GitHub Advanced Security habilitado y en repositorios públicos en GitHub.com.

Creación de bases de datos de CodeQL para analizar

Siga estos pasos para crear bases de datos de CodeQL para analizar:

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, extraiga del repositorio la confirmación principal o bien una confirmación de combinación generada por GitHub.
Configure el entorno para el código base y asegúrese de que las dependencias estén disponibles.
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.
Ejecute codeql database create desde la raíz de extracción del repositorio y compile el código base:
- Para crear una base de datos de CodeQL para un único lenguaje compatible, use el siguiente comando:
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Para crear una base de datos de CodeQL por lenguaje para todos los admitidos, use el siguiente comando:
```
codeql database create <database> --command <build> \
  --db-cluster --language=<language-identifier>,<language-identifier>
```

Nota:

Si usa una compilación en contenedores, tendrá que ejecutar la CLI de CodeQL dentro del contenedor donde tiene lugar la tarea de compilación.

La lista completa de parámetros para el comando database create se muestra en la tabla siguiente:

Opción	Uso obligatorio
`<database>`	Especifique el nombre y la ubicación de un directorio que se 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.
`--language`	Especifique el identificador del lenguaje para el que se 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). Cuando se usa con `--db-cluster`, la opción acepta una lista separada por comas o se puede especificar más de una vez.
`--command`	Se 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-cluster`	Opcional. Se usa en códigos base de varios lenguajes para generar una base de datos para cada lenguaje especificado por `--language`.
`--no-run-unnecessary-builds`	Se recomienda su uso. Se usa para suprimir el comando de compilación para los lenguajes en los que la CLI de CodeQL no necesita supervisar la compilación (por ejemplo, Python y JavaScript o TypeScript).
`--source-root`	Opcional. 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.

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 varios lenguajes

En este ejemplo se crean dos bases 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.
$

Análisis de una base de datos de CodeQL

Después de crear la base de datos de CodeQL, siga estos pasos para analizarla:

Opcionalmente, ejecute codeql pack download <packs> para descargar los paquetes de CodeQL (beta) que quiera ejecutar durante el análisis.
Ejecute codeql database analyze en la base de datos y especifique qué paquetes o consultas usar.

codeql database analyze <database> --format=<format> \
    --output=<output>  <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. Al cargar los resultados en GitHub, el examen de código usa esta categoría para almacenar los resultados de 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>

La lista completa de parámetros para el comando database analyze se muestra en la tabla siguiente:

Opción	Uso obligatorio
`<database>`	Especifique la ruta del directorio que contiene la base de datos de CodeQL que se analizará.
`<packs,queries>`	Especifique los paquetes de CodeQL o las consultas que se ejecutarán. Para ejecutar las consultas estándar usadas para el examen de código, omita este parámetro. Puede encontrar los otros conjuntos de consultas incluidos en el paquete de la CLI de CodeQL en `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. Para obtener información sobre cómo crear un conjunto de consultas propio, vea Creación de conjuntos de consultas de CodeQL^[5] en la documentación de la CLI de CodeQL.
`--format`	Especifique el formato del archivo de resultados generado por el comando. Para realizar la carga en GitHub, esto debe ser: `sarif-latest`.
`--output`	Especifique dónde guardar el archivo de resultados de SARIF.
`--sarif-category`	Opcional 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-help`	Opcional. 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.
`<packs>`	Opcional. Se usa si se han descargado los paquetes de consulta de CodeQL y quiere ejecutar las consultas predeterminadas o los conjuntos de consultas especificados en los paquetes.
`--threads`	Opcional. 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.
`--verbose`	Opcional. 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.

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 tiene más de una base de datos de CodeQL para analizar una sola confirmación 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.

Carga de resultados en GitHub

La carga de SARIF admite un máximo de 25 000 resultados por carga, pero solo se mostrarán los 5000 resultados principales, clasificados por gravedad. Si una herramienta genera demasiados resultados, debe actualizar la configuración para centrarse en los resultados de las reglas o consultas más importantes.

Para cada carga, la carga de SARIF admite un tamaño máximo de 10 MB para el archivo SARIF comprimido con gzip. Se rechazarán las cargas que superen este límite. Si el archivo SARIF es demasiado grande porque contiene demasiados resultados, debe actualizar la configuración para centrarse en los resultados de las reglas o consultas más importantes. Para obtener más información sobre las limitaciones y la validación de archivos SARIF, consulte la documentación^[6].

Para poder cargar los resultados en GitHub, debe determinar la mejor manera de pasar la aplicación de GitHub o el token de acceso personal que ha creado antes a la CLI de CodeQL. Se recomienda revisar las instrucciones del sistema de CI sobre el uso seguro de un almacén de secretos. La CLI de CodeQL admite lo siguiente:

Interacción con un almacén de secretos mediante la opción --github-auth-stdin. Esta es la manera de autenticarse recomendada.
Guardar el secreto en la variable de entorno GITHUB_TOKEN y ejecutar la CLI sin incluir la opción --github-auth-stdin.
Pase la opción de la línea de comandos --github-auth-stdin y proporcione un token temporal por medio de la entrada estándar. Esto se recomienda con fines de prueba.

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

La lista completa de parámetros para el comando github upload-results se muestra en la tabla siguiente.

Opción	Uso obligatorio
`--repository`	Especifique el PROPIETARIO/NOMBRE del repositorio en el que se van a cargar los datos. El propietario debe ser una organización dentro de una empresa que tenga una licencia para GitHub Advanced Security y GitHub Advanced Security debe estar habilitado para el repositorio, a menos que sea público.
`--ref`	Especifique el nombre de la referencia que ha extraído del repositorio y ha analizado para que los resultados puedan coincidir con el código correcto. Para una rama use `refs/heads/BRANCH-NAME`; para la confirmación principal de una solicitud de incorporación de cambios use `refs/pulls/NUMBER/head`, o bien, para la confirmación de combinación generada por GitHub de una solicitud de incorporación de cambios, use `refs/pulls/NUMBER/merge`.
`--commit`	Especifique el SHA completo de la confirmación que ha analizado.
`--sarif`	Especifique el archivo SARIF que se cargará.
`--github-auth-stdin`	Opcional. Se usa para pasar a la CLI la aplicación de la GitHub o el token de acceso personal creado para la autenticación con la API REST de GitHub por medio de la entrada estándar. Esto no es necesario si el comando tiene acceso a una variable de entorno `GITHUB_TOKEN` establecida con este token.

Continuar