Ejecutar el ejecutor de CodeQL en tu sistema de IC

Acerca de Ejecutor de CodeQL

El Ejecutor de CodeQL es una herramienta que puedes utilizar para ejecutar el escaneo de código en el código que estás procesando en un sistema de integración contínua (IC) de terceros. Escaneo de código es una característica que utilizas para analizar el código en un repositorio de GitHub para encontrar vulnerabilidades de seguridad y errores de código. Cualquier problema que se identifique con el análisis se muestra en GitHub AE. Para obtener más información, consulta la sección "Acerca del escaneo de código con CodeQL".

Como alternativa, puedes utilizar las GitHub Actions en tu sistema de IC, o al escaneo de código dentro de GitHub AE. Para obtener más información, consulta la sección "Configurar el escaneo de código en un repositorio".

El Ejecutor de CodeQL es una herramienta de línea de comandos que ejecuta un análisis de CodeQL en un control de un repositorio de GitHub. Agregas el ejecutor a tu sistema de terceros y luego lo llamas para que analice el código y cargue los resultados a GitHub AE. Estos resultados se muestran como alertas del escaneo de código en el repositorio.

Descargar el Ejecutor de CodeQL

Puedes descargar el Ejecutor de CodeQL desde https://HOSTNAME/github/codeql-action/releases. En algunos sistemas operativos, puede que necesites cambiar permisos para el archivo de descarga antes de que lo puedas ejecutar.

En Linux:

chmod +x codeql-runner-linux

En macOS:

chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos

En Windows, el archivo codeql-runner-win.exe habitualmente no necesita que se hagan cambios a los permisos.

Agregar el Ejecutor de CodeQL a tu sistema de IC

Una vez que descargas el Ejecutor de CodeQL y verificas que puede ejecutarse, debes poner el ejecutor disponible para cada servidor de IC que pretendas utilizar para el escaneo de código. Por ejemplo, podrías configurar cada servidor para que copie el ejecutor desde una ubicación interna y central. Como alternativa, puedes utilizar la API de REST para obtener el ejecutor directamente de GitHub, por ejemplo:

wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

Además, cada servidor de IC necesitará también:

• Un token de acceso personal o de GitHub App para que utilice el Ejecutor de CodeQL. Debes utilizar un token de acceso con el alcance repo, o una GitHub App con el permiso de escritura security_events, y los permisos de lectura metadata y contents. Para obtener más información, consulta las secciones "Crear GitHub Apps" y "Crear un token de acceso personal".
• Acceso al paquete de CodeQL asociado con este lanzamiento del Ejecutor de CodeQL. Este paquete contiene consultas y bibliotecas necesarias para el análisis de CodeQL, adicionado con el CLI de CodeQL, el cual utiliza internamente el ejecutor. Para obtener más información, consulta la sección "CLI de CodeQL".

Las opciones para proporcionar acceso al paquete de CodeQL son:

1. Permite que los servidores de IC accedan a https://HOSTNAME/github/codeql-action para que el Ejecutor de CodeQL pueda descargar el paquete automáticamente.
2. Descarga/extrae manualmente el paquete, almacénalo con otros recursos centrales y utiliza el --codeql-path para especificar la ubicación del paquete en los llamados para inicializar el Ejecutor de CodeQL.

Llamar al Ejecutor de CodeQL

Debes llamar al Ejecutor de CodeQL desde la ubicación de verificación del repositorio que quieres analizar. Los dos comandos principales son:

1. init que se requiere para inicializar el ejecutor y para crear una base de datos de CodeQL para que se analice cada lenguaje. Estas bases de datos se llenan y analizan mediante comandos subsecuentes.
2. analyze que se requiere para llenar las bases de datos de CodeQL, analizarlas y cargar los resultados a GitHub AE.

Para ambos comandos, debes especificar la URL de GitHub AE, el PROPIETARIO/NOMBRE del repositorio, y el token de GitHub Apps o de acceso personal a utilizar para la autenticación. También necesitas especificar la ubicación del paquete de CodeQL, a menos de que el servidor de IC tenga acceso para descargarlo directamente del repositorio de github/codeql-action.

Puedes configurar la ubicación en la que Ejecutor de CodeQL almacenará el paquete de CodeQL para un análisis futuro un un servidor utilizando el marcador --tools-dir , así como en dónde almacena archivos temporales utilizando el marcador --temp-dir.

Para ver la referencia de línea de comandos para el ejecutor, utiliza el marcador -h. Por ejemplo, para listar todos los comandos, ejecuta: codeql-runner-OS -h, o para listar todos los marcadores disponibles para el comando init, ejecuta: codeql-runner-OS init -h (en donde el OS variará de acuerdo con el ejecutable que estés utilizando). Para obtener más información, consulta la sección "Configurar el escaneo de código en tu sistema de IC".

Ejemplo básico

Este ejemplo ejecuta un análisis de CodeQL en un servidor de IC con Linux para el repositorio de octo-org/example-repo en https://github.example.com. El proceso es muy simple, ya que el repositorio contiene únicamente los lenguajes que puede analizar CodeQL directamente, sin que se tenga que compilar (es decir, Go, JavaScript, Python, y TypeScript).

En este ejemplo, el servidor tiene acceso para descargar el paquete de CodeQL directamente desde el repositorio github/codeql-action, así que no hay necesidad de utilizar el marcador --codeql-path.

1. Verifica el repositorio a analizar.

2. Posiciónate en el directorio donde se seleccionó el repositorio.

3. Inicializa el Ejecutor de CodeQL y crea bases de datos de CodeQL para los lenguajes detectados.

   $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
       --github-url https://github.example.com --github-auth-stdin
   > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
   > ...
   > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.

4. Llena las bases de datos de CodeQL, analízalas, y carga los resultados aGitHub AE. Los resultados aparecerán en la pestaña de Seguridad de tu repositorio.

   $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
       --github-url https://github.example.com --github-auth-stdin
       --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
   > Finalizing database creation
   > ...
   > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
   > Successfully uploaded results

5. Para cargar los resultados del escaneo de código como verificaciones de solicitudes de cambios, especifica la solicitud de cambios utilizando el mrcador --ref . Te recomendamos configurar el Ejecutor de CodeQL para que se ejecute en el evento de webhook pull_request.

   $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
       --github-url https://github.example.com --github-auth-stdin
       --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
   > Finalizing database creation
   > ...
   > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
   > Successfully uploaded results

Para obtener más información sobre cómo ver las alertas del escaneo de código, consulta la sección "Clasificar las alertas de las solicitudes de cambios del escaneo de código" y "Administrar las alertas del escaneo de código para tu repositorio".

Ejemplo de lenguaje compilado

Este ejemplo es similar al anterior, sin embargo, esta vez el repositorio tiene código en C/C++, C#, o Java. Para crear una base de datos de CodeQL para estos lenguajes, el CLI necesita monitorear la compilación. Al final del proceso de inicialización, el ejecutor reportará el comando que necesitas configurar en el ambiente antes de compilar el código. Necesitas ejecutar este comando antes de llamar al proceso normal de compilación de IC y luego ejecutar el comando analyze.

1. Verifica el repositorio a analizar.

2. Posiciónate en el directorio donde se seleccionó el repositorio.

3. Inicializa el Ejecutor de CodeQL y crea bases de datos de CodeQL para los lenguajes detectados.

   $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
       --github-url https://github.example.com --github-auth-stdin
   > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner
   > ...
   > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json"
     and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
     Please export these variables to future processes so that CodeQL can monitor the build, for example by running 
     ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".

4. Proporciona el script que generó la acción init para configurar el ambiente para monitorear la compilación. Toma en cuenta el primer punto y espacio en el siguiente extracto de código.

   $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh

5. Compila el código. En macOS, necesitarás agregar un prefijo al comando de la compilación con la variable de ambiente $CODEQL_RUNNER. Para obtener más información, consulta la sección "Solución de problemas para el Ejecutor de CodeQL en tu sistema de IC".

6. Llena las bases de datos de CodeQL, analízalas, y carga los resultados aGitHub AE. Los resultados aparecerán en la pestaña de Seguridad de tu repositorio.

   $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
       --github-url https://github.example.com --github-auth-stdin
       --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
   > Finalizing database creation
   > ...
   > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
   > Successfully uploaded results

7. Para cargar los resultados del escaneo de código como verificaciones de solicitudes de cambios, especifica la solicitud de cambios utilizando el mrcador --ref . Te recomendamos configurar el Ejecutor de CodeQL para que se ejecute en el evento de webhook pull_request.

   $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
       --github-url https://github.example.com --github-auth-stdin
       --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
   > Finalizing database creation
   > ...
   > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
   > Successfully uploaded results

Para obtener más información sobre cómo ver las alertas del escaneo de código, consulta la sección "Clasificar las alertas de las solicitudes de cambios del escaneo de código" y "Administrar las alertas del escaneo de código para tu repositorio".

Leer más

• "Configurar el Ejecutor de CodeQL en tu sistema"
• "Solucionar problemas del Ejecutor de CodeQL en tu sistema de IC"