Configurar el ejecutor de CodeQL en tu sistema de IC

Acerca de configurar el code scanning de CodeQL en tu sistema de IC

Para integrar el code scanning en tu sistema de IC, puedes utilizar el CodeQL runner. Para más información, vea "Ejecución de CodeQL runner en el sistema de CI".

En general, se invoca el CodeQL runner de la siguiente manera.

$ /path/to-runner/codeql-runner-OS  

/path/to-runner/ depende de si ha descargado el CodeQL runner en el sistema de CI. codeql-runner-OS depende del sistema operativo que use. Hay tres versiones de CodeQL runner, codeql-runner-linux, codeql-runner-macos y codeql-runner-win, para Linux, macOS y Windows, respectivamente.

Para personalizar la forma en que CodeQL runner examina el código, puede usar marcas, como --languages y --queries, o bien puede especificar valores personalizados en un archivo de configuración independiente.

Escanear las solicitudes de extracción

El escanear el código cada que se crea una solicitud de cambios previene que los desarrolladores introduzcan vulnerabilidades y errores nuevos a este.

Para examinar una solicitud de incorporación de cambios, ejecute el comando analyze y use la marca --ref para especificar la solicitud de incorporación de cambios. La referencia es refs/pull/<PR-number>/head o refs/pull/<PR-number>/merge, en función de si ha extraído del repositorio la confirmación HEAD de la rama de solicitud de incorporación de cambios o una confirmación de combinación con la rama base.

$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge

Invalidar la detección automática de lenguaje

El CodeQL runner detecta automáticamente y escanea el código que se ha escrito en los lenguajes compatibles.

• C/C++
• C#
• Go
• Java
• JavaScript/TypeScript
• Python

Si el repositorio contiene código en más de uno de los lenguajes admitidos, puede elegir qué lenguajes desea analizar. Hay varias razones por las que es posible que quiera evitar que se analice un lenguaje. Por ejemplo, el proyecto podría tener dependencias en un lenguaje diferente al cuerpo principal del código y es posible que prefiera no ver alertas para esas dependencias.

Para invalidar la detección automática del lenguaje, ejecute el comando init con la marca --languages, seguido de una lista separada por comas de palabras clave del lenguaje. Las palabras clave para los lenguajes compatibles son cpp, csharp, go, java, javascript, and python.

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

Ejecutar consultas adicionales

Cuando utilizas CodeQL para escanear código, el motor de análisis de CodeQL genera una base de datos desde el código y ejecuta consultas en éste. El CodeQL utiliza un conjunto predeterminado de consultas, pero puedes especificar más consultas para que se ejecuten, adicionalmente a las predeterminadas.

Las consultas adicionales que quiera ejecutar deben pertenecer a un paquete de QL en un repositorio. Para más información, vea "Acerca de code scanning con CodeQL".

Puede especificar un único archivo .ql, un directorio con varios archivos .ql, un archivo de definición de conjunto de consultas .qls o cualquier combinación. Para más información sobre las definiciones de conjunto de consultas, vea "Creación de conjuntos de consultas de CodeQL".

Las siguientes suites de consultas se compilan en el CodeQL del code scanning y están disponibles para utilizarse.

Conjunto de consultas	Descripción
security-extended	Consultas del conjunto predeterminado, además de consultas de gravedad y precisión más bajas
security-and-quality	Consultas de security-extended, además de consultas de mantenimiento y confiabilidad.

Al especificar un conjunto de consultas, el motor de análisis de CodeQL ejecutará el conjunto de consultas predeterminado y todas las demás definidas en el conjunto de consultas adicional.

Para agregar una o varias consultas, pase una lista separada por comas de rutas a la marca --queries del comando init. También puedes especificar consultas adicionales en un archivo de configuración.

Si también usa un archivo de configuración para los valores personalizados y además especifica consultas adicionales con la marca --queries, CodeQL runner utilizará las consultas adicionales especificadas con la marca --queries en lugar de las del archivo de configuración. Si quiere ejecutar el conjunto combinado de consultas adicionales especificadas con la marca y en el archivo de configuración, use el símbolo+ como prefijo del valor que se pasa a --queries. Para más información, vea "Uso de un archivo de configuración personalizado".

En el ejemplo siguiente, el símbolo + garantiza que el CodeQL runner use las consultas adicionales junto con cualquier otra que se especifique en el archivo de configuración al que se hace referencia.

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml 
    --queries +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

Uso de un archivo de configuración personalizado

En vez de pasar información adicional a los comandos de CodeQL runner, puedes especificar ajustes personalizados en un archivo de configuración por separado.

El archivo de configuración es un archivo de YAML. Utiliza una sintaxis similar a aquella del flujo de trabajo para GitHub Actions, de acuerdo como se ilustra en los siguientes ejemplos. Para más información, vea "Sintaxis de flujo de trabajo para GitHub Actions".

Use la marca --config-file del comando initpara especificar el archivo de configuración. El valor --config-file es la ruta al archivo de configuración que quiere usar. En este ejemplo se carga el archivo de configuración .github/codeql/codeql-config.yml.

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml

El archivo de configuración se puede encontrar en el repositorio que va a analizar o en un repositorio externo. El uso de un repositorio externo permite especificar opciones de configuración para varios repositorios en un solo lugar. Al hacer referencia a un archivo de configuración ubicado en un repositorio externo, puede usar la sintaxis OWNER/REPOSITORY/FILENAME@BRANCH . Por ejemplo, octo-org/shared/codeql-config.yml@main.

Archivos de configuración de ejemplo

Este archivo de configuración agrega el conjunto de consultas security-and-quality a la lista de consultas que se ejecutan con CodeQL al examinar el código. Para más información sobre los conjuntos de consultas disponibles, vea "Ejecución de consultas adicionales".

name: "My CodeQL config"

queries:
  - uses: security-and-quality

El siguiente archivo de configuración inhabilita las consultas predeterminadas y especifica un conjunto de consultas personalizadas para ejecutarse en vez de éstas. También configura CodeQL para examinar los archivos en el directorio src (relativo a la raíz), a excepción del directorio src/node_modules y de los archivos cuyo nombre termine en .test.js. Por tanto, los archivos de src/node_modules y los archivos con nombres que terminan en .test.js se excluyen del análisis.

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src 
paths-ignore: 
  - src/node_modules
  - '**/*.test.js'

Configurar code scanning para los lenguajes compilados

Para los lenguajes C/C++, C#, y Java, CodeQL compila el código antes de analizarlo. For these three languages, CodeQL analyzes the source files in your repository that are built. CodeQL also runs a build for Go projects to set up the project, but then analyzes all Go files in the repository, not just the files that are built. For any of these languages, including Go, you can disable autobuild and instead use custom build commands in order to analyze only the files that are built by these custom commands.

Para varios sistemas de compilación comunes, el CodeQL runner puede compilar el código automáticamente. Para intentar compilar el código automáticamente, ejecute autobuild entre los pasos init y analyze. Nota que, si tu repositorio necesita una versión específica de una herramienta de compilación, puede que necesites instalar dicha herramienta manualmente primero.

El proceso autobuild solo intenta crear un lenguaje compilado para un repositorio. El lenguaje que se selecciona automáticamente para su análisis es aquél presente en más archivos. Si quiere elegir un lenguaje de forma explícita, use la marca --language del comando autobuild.

$ /path/to-runner/codeql-runner-linux autobuild --language csharp

Si el comando autobuild no puede compilar el código, puede ejecutar los pasos de compilación personalmente, entre los pasos init y analyze. Para más información, vea "Ejecución de CodeQL runner en el sistema de CI".

Carga de datos de code scanning en GitHub

De manera predeterminada, CodeQL runner carga los resultados de code scanning al ejecutar el comando analyze. También puede cargar archivos SARIF por separado mediante el comando upload.

Una vez que hayas cargado los datos, GitHub mostrará las alertas en tu repositorio.

• Si ha realizado la carga en una solicitud de incorporación de cambios, por ejemplo --ref refs/pull/42/merge o --ref refs/pull/42/head, los resultados aparecen como alertas en una comprobación de solicitud de incorporación de cambios. Para más información, vea "Evaluación de prioridades de alertas de análisis de código en solicitudes de incorporación de cambios".
• Si ha realizado la carga en una rama, por ejemplo --ref refs/heads/my-branch, los resultados aparecen en la pestaña Seguridad del repositorio. Para más información, vea "Administración de alertas de análisis de código para el repositorio".

Referencia de comandos de CodeQL runner

El CodeQL runner es compatible con los siguientes comandos y marcadores.

init

Inicializa el CodeQL runner y crea una base de datos de CodeQL para analizar cada lenguaje.

Marca	Obligatorio	Valor de entrada
--repository	✓	Nombre del repositorio a inicializar.
--github-url	✓	URL de la instancia de GitHub donde se hospeda tu repositorio.
--github-auth-stdin	✓	Lee el token de las GitHub Apps o token de acceso personal desde la entrada estándar.
--languages		Lista separada por comas de los lenguajes a analizar. Predeterminadamente, el CodeQL runner detecta y analiza todos los lenguajes compatibles en el repositorio.
--queries		Lista separada por comas de las consultas adicionales a ejecutar, adicionalmente a la suite predeterminada de consultas de seguridad. Esto invalida el valor queries en el archivo de configuración personalizado.
--config-file		Ruta al archivo de configuración personalizado.
--codeql-path		Ruta a una copia del CLI ejecutable de CodeQL a utilizar. Predeterminadamente, el CodeQL runner descarga una copia.
--temp-dir		Directorio donde se almacenan los archivos temporales. El valor predeterminado es ./codeql-runner.
--tools-dir		Directorio donde las herramientas de CodeQL y otros archivos se almacenan entre ejecuciones. El predeterminado es un subdirectorio del directorio principal.
--checkout-path		La ruta a la confirmación de salida de tu repositorio. El predeterminado es el directorio de trabajo.
--debug		Ninguno. Imprime una salida más verbosa.
--trace-process-name		Avanzado y solo para Windows. Nombre del proceso en donde se inyecta un rastreador de Windows para este proceso.
--trace-process-level		Avanzado y solo para Windows. Cantidad de niveles ascendentes del proceso padre en donde se inyecta un rastreador de Windows para este proceso.
-h, --help		Ninguno. Muestra la ayuda para el comando.

autobuild

Intenta compilar el código para los lenguajes compilados de C/C++, C#, y Java. Para estos lenguajes, CodeQL compila el código antes de analizarlo. Ejecute autobuild entre los pasos init y analyze.

Marca	Obligatorio	Valor de entrada
--language		El lenguaje a compilar. Predeterminadamente, el CodeQL runner compila el lenguaje con más archivos.
--temp-dir		Directorio donde se almacenan los archivos temporales. El valor predeterminado es ./codeql-runner.
--debug		Ninguno. Imprime una salida más verbosa.
-h, --help		Ninguno. Muestra la ayuda para el comando.

analyze

Analiza el código en las bases de datos de CodeQL y carga los resultados a GitHub Enterprise Server.

Marca	Obligatorio	Valor de entrada
--repository	✓	Nombre del repositorio que se analizará.
--commit	✓	SHA de la confirmación que se analizará. En Git y en Azure DevOps, esto se corresponde al valor de git rev-parse HEAD. En Jenkins, esto se corresponde a $GIT_COMMIT.
--ref	✓	Nombre de la referencia que se va a analizar, por ejemplo refs/heads/main o refs/pull/42/merge. En Git o en Jenkins, esto se corresponde al valor de git symbolic-ref HEAD. En Azure DevOps, esto se corresponde a $(Build.SourceBranch).
--github-url	✓	URL de la instancia de GitHub donde se hospeda tu repositorio.
--github-auth-stdin	✓	Lee el token de las GitHub Apps o token de acceso personal desde la entrada estándar.
--checkout-path		La ruta a la confirmación de salida de tu repositorio. El predeterminado es el directorio de trabajo.
--no-upload		Ninguno. Impide que CodeQL runner cargue los resultados a GitHub Enterprise Server.
--output-dir		Directorio en donde se almacenan los archivos SARIF de salida. El predeterminado está en el directorio de archivos temporales.
--ram		Cantidad de memoria a utilizar cuando ejecutes consultas. El valor predeterminado es utilizar toda la memoria disponible.
--no-add-snippets		Ninguno. Excluye los fragmentos de código de la salida de SARIF.
--category		Categoría para incluir el archivo de resultados SARIF para este análisis. La categoría puede utilizarse pra distinguir análisis múltiples de la misma herramienta y confirmación, pero que se llevan a cabo en lenguajes diferentes o en partes diferentes del código. Este valor aparecerá en la propiedad <run>.automationDetails.id de SARIF v2.1.0.
--threads		Cantidad de hilos a utilizar cuando se ejecutan las consultas. El valor predeterminado es utilizar todos los núcleos disponibles.
--temp-dir		Directorio donde se almacenan los archivos temporales. El valor predeterminado es ./codeql-runner.
--debug		Ninguno. Imprime una salida más verbosa.
-h, --help		Ninguno. Muestra la ayuda para el comando.

upload

Carga los archivos SARIF a GitHub Enterprise Server.

Marca	Obligatorio	Valor de entrada
--sarif-file	✓	El archivo SARIF a cargar, o un directorio que contiene varios archivos SARIF.
--repository	✓	Nombre del repositorio que se analizó.
--commit	✓	SHA de la confirmación que se analizó. En Git y en Azure DevOps, esto se corresponde al valor de git rev-parse HEAD. En Jenkins, esto se corresponde a $GIT_COMMIT.
--ref	✓	Nombre de la referencia que se ha analizado, por ejemplo refs/heads/main o refs/pull/42/merge. En Git o en Jenkins, esto se corresponde al valor de git symbolic-ref HEAD. En Azure DevOps, esto se corresponde a $(Build.SourceBranch).
--github-url	✓	URL de la instancia de GitHub donde se hospeda tu repositorio.
--github-auth-stdin	✓	Lee el token de las GitHub Apps o token de acceso personal desde la entrada estándar.
--checkout-path		La ruta a la confirmación de salida de tu repositorio. El predeterminado es el directorio de trabajo.
--debug		Ninguno. Imprime una salida más verbosa.
-h, --help		Ninguno. Muestra la ayuda para el comando.