Ejecutar el ejecutor de CodeQL en tu sistema de IC

Puedes utilizar el Ejecutor de CodeQL para llevar a cabo el escaneo de código de CodeQL en un sistema de integración contínua de terceros.

El Escaneo de código se encuentra disponible para todos los repositorios públicos y para los privados que pertenecen a organizaciones en donde se habilitó la 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.

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. Para obtener más información, consulta la sección "Acerca del escaneo de código con CodeQL".

En muchos casos es más fácil configurar el escaneo de código de CodeQL utilizando el CodeQL CLI directamente en tu sistema de IC.

Como alternativa, puedes utilizar las GitHub Actions en tu sistema de IC, o al escaneo de código dentro de GitHub. 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. Estos resultados se muestran como alertas del escaneo de código en el repositorio.

Nota:

  • El Ejecutor de CodeQL utiliza el CLI de CodeQL para analizar el código y, por lo tanto, tiene las mismas condiciones de licencia. Se puede utilizar gratuitamente en los repositorios que mantiene GitHub.com, y está disponible para utilizarse en aquellos que pertenecen a los clientes con una licencia de Advanced Security. Para obtener información, consulta la sección "Términos y condiciones del CodeQL de GitHub" y CLI de CodeQL".

Descargar el Ejecutor de CodeQL

Puedes descargar el Ejecutor de CodeQL desde https://github.com/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://github.com/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://github.com/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.

Para ambos comandos, debes especificar la URL de GitHub, 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".

Notas:

  • SARIF upload supports a maximum of 5000 results per upload. Cualquier resultado que sobrepase este límite se ignorará. Si una herramienta genera demasiados resultados, debes actualizar la configuración para enfocarte en los resultados de las reglas o consultas más importantes.

  • For each upload, SARIF upload supports a maximum size of 10 MB for the gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.

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

Nota: Si utilizas una compilación que usa contenedores, necesitarás ejecutar el Ejecutor de CodeQL en el contenedor donde toma lugar tu tarea de compilaión.

Leer más

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