Configurar el ejecutor de CodeQL en tu sistema de IC

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

El Escaneo de código se encuentra disponible para los repositorios que pertenecen a organizaciones donde se habilitó el GitHub Advanced Security. Para obtener más información, consulta la sección "Acerca de GitHub Advanced Security".

Nota: El Ejecutor de CodeQL se va a obsoletizar. Por favor, utiliza la versión 2.6.2 de CodeQL CLI o superior en su lugar. GitHub Enterprise Server 3.3 será la última serie de lanzamiento que será compatible con el Ejecutor de CodeQL. En Nube de GitHub Enterprise, el Ejecutor de CodeQL será compatible hasta marzo del 2022. Para obtener más información, consulta la obsoletización del ejecutor de CodeQL.

Nota: Tu administrador de sitio debe habilitar el escaneo de código para your GitHub Enterprise Server instance antes de que puedas utilizar esta característica. Para obtener más información, consulta "Configurar el escaneo de código en tu aplicativo."

Acerca de configurar el escaneo de código de CodeQL en tu sistema de IC

Para integrar el escaneo de código en tu sistema de IC, puedes utilizar el Ejecutor de CodeQL. Para obtener más información, consulta la sección "Ejecutar el Ejecutor de CodeQL en tu sistema de IC".

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

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

/path/to-runner/ depende de si descargaste el Ejecutor de CodeQL en tu sistema de IC. codeql-runner-OS depende del sistema operativo que utilices. Hay tres versiones del Ejecutor de CodeQL, codeql-runner-linux, codeql-runner-macos, y codeql-runner-win, para sistemas Linux, macOS y Windows respectivamente.

Para personalizar la forma en la que el Ejecutor de CodeQL escanea tu código, puedes utilizar marcadores, tales como --languages y --queries,o puedes especificar configuraciones personalizadas en un archivo de configuración por separado.

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 escanear una solicitud de cambios, ejecuta el comando analyze y utiliza el marcador --ref para especificar la solicitud de cambios. La referencia es refs/pull/<PR-number>/head o refs/pull/<PR-number>/merge, dependiendo de si seleccionaste la confirmación HEAD de la rama de la solicitud de cambios o una confirmación de fusión con la rama base.

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

Nota: Si analizas código con una herramienta de terceros y quieres que los resultados aparezcan como verificaciones de solicitudes de cambios, debes ejecutar el comando upload y utilizar el marcador --ref para especificar la solicitud de cambios en vez 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 Ejecutor de CodeQL 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 tu repositorio contiene código en más de uno de los lenguajes compatibles, puedes elegir qué lenguajes quieres analizar. Hay varias razones que por las cuales querrías prevenir que un lenguaje se analice. Por ejemplo, el proyecto puede tener dependencias en un lenguaje distinto al del cuerpo principal de tu código, y tal vez prefieras no ver las alertas para esas dependencias.

Para anular la detección automática de lenguajes, ejecuta el comando init con el marcador --languages, seguido de una lista separada por comas de las palabras clave de los lenguajes. 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.

Cualquier consulta adicional que quieras ejecutar debe pertenecer a un paquete de QL en un repositorio. Para obtener más información, consulta la sección "Acerca del escaneo de código con CodeQL".

Puedes especificar un solo archivo .ql, un directorio que contenga varios archivos .ql, un archivo de definición de suite de consulta .qls, o cualquier combinación de éstos. Para obtener más información acerca de las definiciones de la suite de consultas, diríjete a la sección "Crear suites de consultas de CodeQL".

Las siguientes suites de consultas se compilan en el CodeQL del escaneo de código y están disponibles para utilizarse.

Conjunto de consultasDescripción
security-extendedLas consultas de severidad y precisión más baja que aquellas predeterminadas
security-and-qualityLas consultas de security-extended, mas aquellas de mantenibilidad y confiabilidad

Cuando especificas una suite de consultas, el motor de análisis de CodeQL ejecutará las consultas dentro de la suite para ti, adicionalmente a el conjunto de consultas adicional.

Para agregar una o más consultas, pasa una lista separada por comas de las rutas al marcador --queries del comando init. También puedes especificar consultas adicionales en un archivo de configuración.

Si también estás usando un archivo de configuración para los ajustes personalizados y también estás especificando consultas adicionales con el marcador de --queries, el Ejecutor de CodeQL utilizará consultas adicionales que se especifican con el marcador --queries en vez de con cualquier otro en el archivo de configuración. Si quieres ejecutar el conjunto combinado de consultas adicionales que se especifican con el marcador y en el archivo de configuración, usa un prefijo en el valor que se pasa a --queries con el símbolo +. Para encontrar ejemplos de archivos de configuración, consulta la sección "Ejemplos de archivos de configuración".

En el siguiente ejemplo, el símbolo + garantiza que el Ejecutor de CodeQL utilizará consultas adicionales junto con cualquier otra consulta que se especifique en el archivo de configuración referenciado.

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

Utilizar una herramienta de escaneo de código de terceros

En vez de pasar información adicional a los comandos de Ejecutor de CodeQL, 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 obtener más información, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

Utiliza el marcador --config-file del comando init para especificar el archivo de configuración. El valor de --config-file es la ruta al archivo de configuración que quieres utilizar. Este ejemplo 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 puede ubicarse dentro del repositorio que estás analizando o en un repositorio externo. El utilizar un repositorio externo te permite especificar las opciones de configuración para repositorios múltiples en un solo lugar. Cuando referencias un archivo de configuración que se ubica en un repositorio externo, puedes utilizar la sintaxis OWNER/REPOSITORY/FILENAME@BRANCH. Por ejemplo, octo-org/shared/codeql-config.yml@main.

Ejemplos de archivos de configuración

Este archivo de configuración agrega el conjunto de consultas security-and-quality a la lista de consultas que se ejecutan con CodeQL cuando se escanea tu código. Para obtener más información acerca de los conjuntos de consultas que están disponibles para utilizarse, consulta la sección "Ejecutar 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 a CodeQL para escanear archivos en el directorio src (relativo a la raíz), con excepción del directorio src/node_modules y de los archivos cuyo nombre termine en .test.js. Los archivos en src/node_modules y aquellos cuyos nombres terminan en .test.js se excluyen por lo tanto 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 escaneo de código 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, en contraste con el resto de los lenguajes compilados, todos los archivos de Go en el repositorio se extraen, y no únicamente aquellos que se compilaron. Puedes utilizar comandos personalizados de compilación para saltarte la extracción de archivos de Go que no haya tocado la compilación.

Para varios sistemas de compilación comunes, el Ejecutor de CodeQL puede compilar el código automáticamente. Para intentar compilar el código automáticamente, ejecuta autobuild entre los pasos de 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 de autobuild solo intenta siempre compilar un solo 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 quieres elegir un lenguaje explícitamente, utiliza el marcador --language del comando autobuild.

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

Si el comando autobuild no puede compilar tu código, tú mismo puedes ejecutar los pasos de compilación entre los pasos de init y analyze. Para obtener más información, consulta la sección "Ejecutar el Ejecutor de CodeQL en tu sistema de IC".

Puedes escribir un archivo de configuración para escaneo de código.

Predeterminadamente, el Ejecutor de CodeQL carga los resultados del escaneo de código cuando ejecutas el comando analyze. También puedes cargar archivos de SARIF por separado si utilizas el comando upload.

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

Referencia de comandos de Ejecutor de CodeQL

El Ejecutor de CodeQL es compatible con los siguientes comandos y marcadores.

init

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

MarcadorRequeridoValor de entrada
--repositorioNombre 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.

| --languages | | Lista separada por comas de los lenguajes a analizar. Predeterminadamente, el Ejecutor de CodeQL 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 anula la configuración de 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 Ejecutor de CodeQL descarga una copia. | | --temp-dir | | Directorio donde se almacenan los archivos temporales. El 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. Ejecuta autobuild entre los pasos de init y analyze.

MarcadorRequeridoValor de entrada
--languageEl lenguaje a compilar. Predeterminadamente, el Ejecutor de CodeQL compila el lenguaje con más archivos.
--temp-dirDirectorio donde se almacenan los archivos temporales. El 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.

MarcadorRequeridoValor de entrada
--repositorioNombre del repositorio que se analizará.
--commitSHA de la confirmación que se analizará. En Git y en Azure DevOps, este corresponde al valor de git rev-parse HEAD. En Jenkins, este corresponde a $GIT_COMMIT.
--refNombre de la referencia a analizar, por ejemplo refs/heads/main o refs/pull/42/merge. Tanto en Git como en Jenkins, esto corresponde al valor de git symbolic-ref HEAD. En Azure DevOps, esto 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-path | | La ruta a la confirmación de salida de tu repositorio. El predeterminado es el directorio de trabajo. | | --no-upload | | Ninguno. Impide que el Ejecutor de CodeQL 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. | | --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 predeterminado es ./codeql-runner. | | --debug | | Ninguno. Imprime una salida más verbosa. | | -h, --help | | Ninguno. Muestra la ayuda para el comando. |

cargar

Carga los archivos SARIF a GitHub Enterprise Server.

Nota: Si analizas el código con el ejecutor de CodeQL, el comando analyze carga los resultados de SARIF predeterminadamente. Puedes utilizar el comando upload para cargar los resultados SARIF que generaron otras herramientas.

MarcadorRequeridoValor de entrada
--sarif-fileEl archivo SARIF a cargar, o un directorio que contiene varios archivos SARIF.
--repositorioNombre del repositorio que se analizó.
--commitSHA de la confirmación que se analizó. En Git y en Azure DevOps, este corresponde al valor de git rev-parse HEAD. En Jenkins, este corresponde a $GIT_COMMIT.
--refNombre de la referencia que se analizó, por ejemplo, refs/heads/main o refs/pull/42/merge. Tanto en Git como en Jenkins, esto corresponde al valor de git symbolic-ref HEAD. En Azure DevOps, esto 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-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. |

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.