Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Esta versión de GitHub Enterprise se discontinuó el 2023-01-18. No se realizarán lanzamientos de patch, ni siquiera para problemas de seguridad críticos. Para obtener rendimiento mejorado, seguridad mejorada y nuevas características, actualice a la versión más reciente de GitHub Enterprise. Para obtener ayuda con la actualización, póngase en contacto con el soporte técnico de GitHub Enterprise.

Ejecutar el ejecutor de CodeQL en tu sistema de IC

Puedes utilizar el CodeQL runner para llevar a cabo el code scanning de CodeQL en un sistema de integración contínua de terceros.

Code scanning está disponible para repositorios que son propiedad de una organización en GitHub Enterprise Server. Esta característica requiere una licencia para la 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 para puedas utilizar esta característica. Para más información, vea "Configuración de code scanning para el dispositivo".

Acerca de las variables de datos CodeQL runner

El CodeQL runner es una herramienta que puedes utilizar para ejecutar el code scanning en el código que estás procesando en un sistema de integración contínua (IC) de terceros. Code scanning 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 Enterprise Server. Para obtener información, consulta "Acerca de code scanning con CodeQL".

En muchos casos es más fácil configurar el code scanning 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 code scanning dentro de GitHub Enterprise Server. Para información, consulta "Configuración de code scanning para un repositorio".

El CodeQL runner es una herramienta de línea de comandos que ejecuta un análisis de CodeQL en un control de un repositorio de GitHub. Puedes agregar el ejecutor a tu sistema de terceros y, luego, llamarlo para que analice el código y cargue los resultados en GitHub Enterprise Server. Estos resultados se muestran como alertas del code scanning en el repositorio.

Nota:

  • El CodeQL runner se encuentra disponible para los clientes con una licencia de Advanced Security.

Descarga de las variables de datos CodeQL runner

Puedes descargar CodeQL runner 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 normalmente no requiere ningún cambio en los permisos.

Agregar el CodeQL runner a tu sistema de IC

Una vez que descargas el CodeQL runner y verificas que puede ejecutarse, debes poner el ejecutor disponible para cada servidor de IC que pretendas utilizar para el code scanning. 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 GitHub App o personal access token para el CodeQL runner que se van a usar. Debes usar un token de acceso con el ámbito repo o una GitHub App con el permiso de escritura security_events y los permisos de lectura metadata y contents. Para obtener información, consulta "Compilación de GitHub Apps" y "Creación de un personal access token".
  • Acceso al paquete de CodeQL asociado con este lanzamiento del CodeQL runner. 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 información, consulta "CLI de CodeQL".

Las opciones para proporcionar acceso al paquete de CodeQL son:

  1. Permitir que los servidores de CI accedan a https://HOSTNAME/github/codeql-action para que el CodeQL runner pueda descargar el paquete automáticamente.
  2. Descargar o extraer el paquete manualmente, almacenarlo con otros recursos centrales y usar la marca --codeql-path para especificar la ubicación del paquete en las llamadas para inicializar el CodeQL runner.

Llamada a CodeQL runner

Debes llamar al CodeQL runner 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 rellenar las bases de datos de CodeQL, analizarlas y cargar los resultados en GitHub Enterprise Server.

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

Puedes configurar en qué lugar el CodeQL runner almacena la agrupación de CodeQL para el análisis futuro en un servidor mediante la marca --tools-dir y dónde almacena los archivos temporales durante el análisis mediante --temp-dir.

Para ver la referencia de línea de comandos para el ejecutor, usa la marca -h. Por ejemplo, para enumerar todos los comandos ejecuta codeql-runner-OS -h, o bien para enumerar todas las marcas disponibles para el comando init ejecuta codeql-runner-OS init -h (donde OS varía según el ejecutable que se use). Para obtener más información, consulta "Configuración de code scanning en el sistema de CI".

Notas:

  • La carga de SARIF admite un máximo de 5000 resultados por carga. Los resultados que superen este límite se omiten. Si una herramienta genera demasiados resultados, debe actualizar la configuración para centrarse en los resultados de las reglas o consultas más importantes.

  • Para cada carga, la carga de SARIF admite un tamaño máximo de 10 MB para el archivo SARIF comprimido con gzip. Se rechazarán las cargas que superen este límite. Si el archivo SARIF es demasiado grande porque contiene demasiados resultados, debe actualizar la configuración para centrarse en los resultados de las reglas o consultas más importantes.

Ejemplo básico

En este ejemplo se ejecuta el análisis de CodeQL en un servidor de CI de Linux para el repositorio octo-org/example-repo hospedado 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 la agrupación CodeQL directamente desde el repositorio github/codeql-action, así que no hay necesidad de usar la marca --codeql-path.

  1. Verifica el repositorio a analizar.

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

  3. Inicializa el CodeQL runner 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. Rellene las bases de datos de CodeQL, analícelas y cargue los resultados a GitHub Enterprise Server. Los resultados aparecerán en la pestaña Security del 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 de code scanning como comprobaciones de solicitudes de incorporación de cambios, especifique la solicitud de incorporación de cambios mediante la marca --ref. Se recomienda configurar CodeQL runner 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 más información sobre cómo ver las alertas de code scanning, vea "Evaluación de prioridades de alertas de examen de código en solicitudes de incorporación de cambios" y "Administración de alertas de análisis de código para el 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 CI y ejecutar el comando analyze.

  1. Verifica el repositorio a analizar.

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

  3. Inicializa el CodeQL runner 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 a fin de configurar el entorno para supervisar 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. Compilación del código. En macOS, necesitarás agregar un prefijo al comando de compilación con la variable de entorno $CODEQL_RUNNER. Para más información, vea "Solución de problemas de CodeQL runner en el sistema de CI".

  6. Rellene las bases de datos de CodeQL, analícelas y cargue los resultados a GitHub Enterprise Server. Los resultados aparecerán en la pestaña Security del 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 de code scanning como comprobaciones de solicitudes de incorporación de cambios, especifique la solicitud de incorporación de cambios mediante la marca --ref. Se recomienda configurar CodeQL runner 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 más información sobre cómo ver las alertas de code scanning, vea "Evaluación de prioridades de alertas de examen de código en solicitudes de incorporación de cambios" y "Administración de alertas de análisis de código para el repositorio".

Nota: Si usas una compilación contenedorizada, deberás ejecutar el CodeQL runner en el contenedor donde tiene lugar la tarea de compilación.

Información adicional