Skip to main content

Configurar el ejecutor de CodeQL en tu sistema de IC

Puedes configurar la forma en la que CodeQL runner escanea el código en tu proyecto y en la que carga los resultados a GitHub.

Code scanning is available for organization-owned repositories in GitHub Enterprise Server. This feature requires a license for GitHub Advanced Security. Para más información, consulte "Acerca de GitHub Advanced Security".

Nota: CodeQL runner está en desuso. En GitHub Enterprise Server 3.0 y posterior, puede instalar la versión 2.6.3 de CodeQL CLI para reemplazar CodeQL runner.

Para más información, vea Ejecutor de CodeQL en desuso. Para obtener información sobre la migración a CodeQL CLI, vea "Migración del ejecutor de CodeQL a la CLI de CodeQL".

Nota: El administrador del sitio debe habilitar code scanning para your GitHub Enterprise Server instance antes de que pueda utilizar esta característica. Para más información, vea "Configuración de code scanning para el dispositivo".

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

Nota: Si analiza código con una herramienta de terceros y quiere que los resultados aparezcan como comprobaciones de solicitudes de incorporación de cambios, debe ejecutar el comando upload y usar la marca --ref para especificar la solicitud de incorporación de cambios en lugar de la rama. La referencia es refs/pull/<PR-number>/head o refs/pull/<PR-number>/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 consultasDescripción
security-extendedConsultas del conjunto predeterminado, además de consultas de gravedad y precisión más bajas
security-and-qualityConsultas 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. CodeQL también ejecuta una compilación para que los proyectos de Go configuren el proyecto. Sin embargo, a diferencia de los demás lenguajes compilados, se extraen todos los archivos de Go del repositorio, no solo los compilados. Puede usar comandos de compilación personalizados para omitir la extracción de archivos de Go que no se han tocado en la compilación.

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.

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.

MarcaObligatorioValor de entrada
--repositoryNombre del repositorio a inicializar.
--github-urlURL de la instancia de GitHub donde se hospeda tu repositorio.
--github-auth-stdinLee el token de las GitHub Apps o token de acceso personal desde la entrada estándar.
--languagesLista separada por comas de los lenguajes a analizar. Predeterminadamente, el CodeQL runner detecta y analiza todos los lenguajes compatibles en el repositorio.
--queriesLista 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-fileRuta al archivo de configuración personalizado.
--codeql-pathRuta a una copia del CLI ejecutable de CodeQL a utilizar. Predeterminadamente, el CodeQL runner descarga una copia.
--temp-dirDirectorio donde se almacenan los archivos temporales. El valor predeterminado es ./codeql-runner.
--tools-dirDirectorio donde las herramientas de CodeQL y otros archivos se almacenan entre ejecuciones. El predeterminado es un subdirectorio del directorio principal.
--checkout-pathLa ruta a la confirmación de salida de tu repositorio. El predeterminado es el directorio de trabajo.
--debugNinguno. Imprime una salida más verbosa.
--trace-process-nameAvanzado y solo para Windows. Nombre del proceso en donde se inyecta un rastreador de Windows para este proceso.
--trace-process-levelAvanzado y solo para Windows. Cantidad de niveles ascendentes del proceso padre en donde se inyecta un rastreador de Windows para este proceso.
-h, --helpNinguno. 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.

MarcaObligatorioValor de entrada
--languageEl lenguaje a compilar. Predeterminadamente, el CodeQL runner compila el lenguaje con más archivos.
--temp-dirDirectorio donde se almacenan los archivos temporales. El valor predeterminado es ./codeql-runner.
--debugNinguno. Imprime una salida más verbosa.
-h, --helpNinguno. 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.

MarcaObligatorioValor de entrada
--repositoryNombre del repositorio que se analizará.
--commitSHA 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.
--refNombre 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-urlURL de la instancia de GitHub donde se hospeda tu repositorio.
--github-auth-stdinLee el token de las GitHub Apps o token de acceso personal desde la entrada estándar.
--checkout-pathLa ruta a la confirmación de salida de tu repositorio. El predeterminado es el directorio de trabajo.
--no-uploadNinguno. Impide que CodeQL runner cargue los resultados a GitHub Enterprise Server.
--output-dirDirectorio en donde se almacenan los archivos SARIF de salida. El predeterminado está en el directorio de archivos temporales.
--ramCantidad de memoria a utilizar cuando ejecutes consultas. El valor predeterminado es utilizar toda la memoria disponible.
--no-add-snippetsNinguno. Excluye los fragmentos de código de la salida de SARIF.
--categoryCategorí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.
--threadsCantidad de hilos a utilizar cuando se ejecutan las consultas. El valor predeterminado es utilizar todos los núcleos disponibles.
--temp-dirDirectorio donde se almacenan los archivos temporales. El valor predeterminado es ./codeql-runner.
--debugNinguno. Imprime una salida más verbosa.
-h, --helpNinguno. Muestra la ayuda para el comando.

upload

Carga los archivos SARIF a GitHub Enterprise Server.

Nota: Si analiza código con el ejecutor de CodeQL, el comando analyze carga los resultados de SARIF de forma predeterminada. Puede usar el comando upload para cargar los resultados SARIF que han generado otras herramientas.

MarcaObligatorioValor de entrada
--sarif-fileEl archivo SARIF a cargar, o un directorio que contiene varios archivos SARIF.
--repositoryNombre del repositorio que se analizó.
--commitSHA 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.
--refNombre 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-urlURL de la instancia de GitHub donde se hospeda tu repositorio.
--github-auth-stdinLee el token de las GitHub Apps o token de acceso personal desde la entrada estándar.
--checkout-pathLa ruta a la confirmación de salida de tu repositorio. El predeterminado es el directorio de trabajo.
--debugNinguno. Imprime una salida más verbosa.
-h, --helpNinguno. Muestra la ayuda para el comando.