Skip to main content

Análisis de código de CodeQL para lenguajes compilados

Comprende el método de autocompilación que utiliza el análisis de CodeQL para compilar código en lenguajes compilados y aprender a personalizar el comando de compilación si es necesario.

¿Quién puede utilizar esta característica?

If you have write permissions to a repository, you can configure code scanning for that repository.

Code scanning está disponible para todos los repositorios públicos en GitHub.com. Code scanning también está disponible para los repositorios privados que pertenecen a las organizaciones que usan GitHub Enterprise Cloud y que tienen una licencia de GitHub Advanced Security. Para obtener más información, vea «Acerca de GitHub Advanced Security».

Acerca de Flujo de trabajo de análisis de CodeQL y los lenguajes compilados

Code scanning funciona ejecutando consultas en una o varias bases de datos. Cada base de datos contiene una representación de todo el código de tu repositorio en un solo lenguaje. Para los lenguajes compilados de C/C++, C#, Go, Java y Swift, el proceso de poblar esta base de datos implica compilar el código y extraer los datos.

CodeQL analiza los archivos de origen C/C++, C#, Go, Java y Swift del repositorio que se han compilado.

Si habilita la configuración predeterminada, la acción autobuild se usará para compilar el código como parte de las variables de datos de configuración automática Flujo de trabajo de análisis de CodeQL. Si habilita la configuración avanzada, la Flujo de trabajo de análisis de CodeQL básica usa autobuild. Alternativamente, puedes deshabilitar autobuild y en su lugar especificar comandos de compilación explícitos para analizar solo los archivos que se compilan mediante estos comandos personalizados.

Para el code scanning de CodeQL, puedes usar la configuración predeterminada, que analiza el código y configura automáticamente el code scanning, o bien la configuración avanzada, que genera un archivo de flujo de trabajo que puedes editar. Para obtener más información sobre la configuración avanzada, consulta "Establecimiento de la configuración avanzada del examen de código con CodeQL".

Para obtener información sobre los lenguajes, bibliotecas y marcos que se admiten en la versión más reciente de CodeQL, consulta "Lenguajes y marcos admitidos" en la documentación de CodeQL. Para obtener información sobre los requisitos del sistema para ejecutar la versión más reciente de CodeQL, consulta "Requisitos del sistema" en la documentación de CodeQL.

Si en el flujo de trabajo se usa una matriz language, autobuild intenta compilar cada uno de los lenguajes compilados enumerados en la matriz. Sin una matriz, autobuild intentará compilar el lenguaje compilado compatible que tenga más archivos de código fuente en el repositorio. Con la excepción de Go, el análisis de otros lenguajes compilados en tu repositorio siempre fallará a menos de que proporciones comandos de compilación específicos.

Acerca de autobuild para CodeQL

CodeQL analiza los archivos de origen C/C++, C#, Go, Java y Swift del repositorio que se han compilado.

Si habilita la configuración predeterminada, la acción autobuild se usará para compilar el código como parte de las variables de datos de configuración automática Flujo de trabajo de análisis de CodeQL. Si habilita la configuración avanzada, la Flujo de trabajo de análisis de CodeQL básica usa autobuild. Alternativamente, puedes deshabilitar autobuild y en su lugar especificar comandos de compilación explícitos para analizar solo los archivos que se compilan mediante estos comandos personalizados.

Nota: Si usas ejecutores autohospedados para GitHub Actions, es posible que tengas que instalar software adicional para usar el proceso autobuild. Adicionalmente, si tu repositorio requiere de una versión específica de una herramienta de compilación, tal vez necesites instalarla manualmente. Los ejecutores hospedados en GitHub siempre se ejecutan con el software que necesita autobuild.

autobuild para C/C++

Tipo de sistema compatibleNombre del sistema
Sistema operativoWindows, macOS y Linux.
Sistema de compilaciónWindows: MSbuild y scripts de compilación
Linux y macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild y scripts de compilación

El comportamiento del paso autobuild varía en función del sistema operativo en el que se ejecute la extracción. En Windows, el paso autobuild intenta detectar de forma automática un método de compilación adecuado para C/C++ mediante el enfoque siguiente:

  1. Se invoca MSBuild.exe en el archivo de solución (.sln) o proyecto (.vcxproj) más cercano a la raíz. Si autobuild detecta varios archivos de solución o del proyecto en la misma profundidad (la más corta) con respecto al directorio de nivel superior, intentará compilarlos todos.
  2. Invoque un script similar a un script de compilación:build.bat, build.cmd y build.exe (en ese orden).

En Linux y macOS, el paso autobuild revisa los archivos presentes en el repositorio para determinar el sistema de compilación que usar:

  1. Busca un sistema de compilación en el directorio raíz.
  2. Si no se encuentra ninguno, busca un directorio único en los subdirectorios, el cual cuente con un sistema de compilación para C/C++.
  3. Ejecuta un comando adecuado para configurar el sistema.

En los ejecutores de Ubuntu Linux, autobuild puede intentar instalar automáticamente las dependencias requeridas por los pasos de configuración y compilación detectados. De forma predeterminada, este comportamiento está habilitado en ejecutores hospedados por GitHub y deshabilitados en ejecutores autohospedados. Puedes habilitar o deshabilitar esta característica explícitamente estableciendo CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES en true o false en el entorno. Para obtener más información sobre cómo definir variables de entorno, consulta "variables."

En el caso de los ejecutores autohospedados, a menos que la instalación automática de dependencias esté habilitada, es probable que tengas que instalar el compilador gcc y es posible que proyectos específicos también requieran acceso a clang archivos ejecutables msvc . También deberás instalar el sistema de compilación (por ejemplo msbuild, make, cmake, bazel) y utilidades (como python, perl, lex y yacc) de los que dependen los proyectos. Si habilitas la instalación automática de dependencias, debes asegurarte de que el ejecutor usa Ubuntu y que se puede ejecutar sudo apt-get sin necesidad de una contraseña.

autobuild para C#

Tipo de sistema compatibleNombre del sistema
Sistema operativoWindows, macOS y Linux.
Sistema de compilación.NET y MSbuild, así como los scripts de compilación

El proceso autobuild intenta detectar de forma automática un método de compilación adecuado para C# mediante el enfoque siguiente:

  1. Se invoca dotnet build en el archivo de solución (.sln) o proyecto (.csproj) más cercano a la raíz.
  2. Se invoca MSbuild (Linux) o MSBuild.exe (Windows) en el archivo de solución o del proyecto más cercano a la raíz. Si autobuild detecta varios archivos de solución o del proyecto en la misma profundidad (la más corta) con respecto al directorio de nivel superior, intentará compilarlos todos.
  3. Se invoca un script similar a un script de compilación: build y build.sh (en ese orden, para Linux), o bien build.bat, build.cmd y build.exe (en ese orden, para Windows).

Para el desarrollo de aplicaciones de .NET Core en ejecutores autohospedados, se requiere el SDK de .NET (para dotnet).

Para el desarrollo de aplicaciones de .NET Framework, en Windows, necesitarás Microsoft Build Tools (para msbuild) y la CLI de Nuget (para nuget). En Linux y macOS, necesitarás Mono Runtime (para ejecutar mono, msbuild o nuget).

autobuild para Go

Tipo de sistema compatibleNombre del sistema
Sistema operativoWindows, macOS y Linux.
Sistema de compilaciónMódulos de Go, dep y Glide, así como scripts de compilación, incluidos scripts de Makefiles y Ninja

El proceso autobuild intenta detectar automáticamente una forma adecuada de instalar las dependencias necesarias para un repositorio de Go antes de extraer todos los archivos .go:

  1. Invoca make, ninja``./build o ./build.sh (en ese orden) hasta que uno de estos comandos se complete correctamente y otro comando go list ./... posterior también lo haga, lo que indica que las dependencias necesarias se han instalado.
  2. Si ninguno de esos comandos se completa correctamente, busca go.mod, Gopkg.toml o glide.yaml y ejecuta go get (a menos que se use el traslado al directorio "vendor"), dep ensure -v o glide install respectivamente para intentar instalar las dependencias.
  3. Por último, si no hay forma de encontrar los archivos de configuración de estos administradores de dependencias, reorganiza la estructura de directorios del repositorio adecuada para la adición a GOPATH y usa go get para instalar las dependencias. La estructura de directorios vuelve a su estado normal después de que se complete la extracción.
  4. Extrae todo el código de Go en el repositorio, similar a ejecutar go build ./....

Nota: Si usas la configuración predeterminada, se buscará un archivo go.mod para instalar automáticamente una versión compatible del lenguaje Go.

autobuild para Java y Kotlin

Tipo de sistema compatibleNombre del sistema
Sistema operativoWindows, macOS, y Linux (sin restricción)
Sistema de compilaciónGradle, Maven y Ant

El proceso autobuild intenta determinar el sistema de compilación para las bases de código de Java mediante la aplicación de esta estrategia:

  1. Busca un archivo de compilación en el directorio raíz. Busca a Gradle en Maven y luego Ant compila los archivos.
  2. Ejecuta el primer archivo de compilación que encuentre. Si tanto los archivos de Gradle como los de Maven están presentes, se utiliza el archivo de Gradle.
  3. De lo contrario, usca los archivos de compilación en los subidrectorios directos del directorio raíz. Si solo un subdirectorio contiene archivos de compilación, ejecuta el primer archivo identificado en este subdirectorio (utilizando la misma preferencia que para 1). Si más de un subdirectorio contiene archivos de compilación, reporta un error.

Si usas ejecutores autohospedados, las versiones requeridas de Java deben estar presentes:

  • Si el ejecutor se usará para analizar repositorios que necesitan una sola versión de Java, debe instalarse la versión de JDK adecuada y debe estar presente en la variable PATH (de modo que java y javac se puedan encontrar).

  • Si el ejecutor se usará para analizar repositorios que requieren varias versiones de Java, es necesario instalar las versiones de JDK adecuadas y se puede especificar a través del archivo toolchains.xml. Se trata de un archivo de configuración, que normalmente usa Apache Maven, que permite especificar la ubicación de las herramientas, la versión de las herramientas y cualquier configuración adicional necesaria para usarlas. Para más información, consulta "Guía para usar cadenas de herramientas" en la documentación de Apache Maven.

Es probable que los siguientes ejecutables sean necesarios para diferentes proyectos de Java y deben estar presentes en la variable PATH, pero no serán esenciales en todos los casos:

  • mvn (Apache Maven)
  • gradle (Gradle)
  • ant (Apache Ant)

También deberás instalar el sistema de compilación (por ejemplo make, cmake, bazel) y utilidades (como python, perl, lex y yacc) de los que dependen los proyectos.

autobuild para Swift

Tipo de sistema compatibleNombre del sistema
Sistema operativomacOS
Sistema de compilaciónXcode

El proceso autobuild intenta compilar el destino más grande desde un proyecto o área de trabajo de Xcode.

Notas:

  • El análisis de CodeQL para Swift se encuentra actualmente en versión beta. Durante la versión beta, el análisis del código de Swift, y la documentación complementaria, no serán tan exhaustivos como para otros lenguajes. Swift 5.8 aún no se admite.
  • El análisis puede bloquearse ocasionalmente, lo que hará que se agote el tiempo de espera de los trabajos. Para limitar el número de minutos de acciones que usan los trabajos que están bloqueados o para los que se está agotando el tiempo de espera, se recomienda establecer un tiempo de espera de cuatro veces el tiempo de compilación normal.

El examen de código de Swift usa ejecutores de macOS de forma predeterminada. Dado que los ejecutores de macOS hospedados por GitHub son más caros que los ejecutores de Linux y Windows, se recomienda compilar solo el código que se vaya a analizar. Para más información sobre los precios de los ejecutores hospedados por GitHub, consulta "Acerca de la facturación para las Acciones de GitHub."

Code scanning del código Swift no se admite para los ejecutores que forman parte de un Actions Runner Controller (ARC), ya que los ejecutores de ARC solo usan Linux y Swift requiere ejecutores de macOS. Sin embargo, puedes tener una combinación de ejecutores de ARC y ejecutores de macOS autohospedados. Para obtener más información, vea «Acerca de Actions Runner Controller».

Personalizar la compilación de Swift en un Flujo de trabajo de análisis de CodeQL

xcodebuild y swift build son compatibles con compilaciones de Swift. Se recomienda trabajar con una sola arquitectura durante la compilación. Por ejemplo, ARCH=arm64 para xcodebuild o --arch arm64 para swift build.

Puedes pasar las opciones archive y test a xcodebuild. Sin embargo, se recomienda el comando estándar xcodebuild, ya que es el más rápido y es todo lo que CodeQL necesita para un examen correcto.

Para el análisis de Swift, siempre debes instalar explícitamente las dependencias administradas a través de CocoaPods o Carthage antes de generar la base de datos de CodeQL.

Agregar pasos de compilación para un lenguaje compilado

Si se produce un error de autobuild o quiere analizar un conjunto diferente de archivos de origen de los compilados por el proceso autobuild, deberá quitar el paso autobuild del flujo de trabajo y agregar manualmente pasos de compilación. Para proyectos de C/C++, C#, Go, Kotlin, Java y Swift, CodeQL analizará cualquier código fuente compilado mediante los pasos de compilación especificados. Para información sobre cómo editar el archivo de flujo de trabajo, consulta "Personalizar la configuración avanzado de para el análisis de código".

Después de quitar el paso autobuild, quite la marca de comentario del paso run y agregue comandos de compilación que sean adecuados para el repositorio. El paso run del flujo de trabajo ejecuta herramientas de línea de comandos mediante el shell del sistema operativo. Puede modificar estos comandos y agregar más comandos para personalizar el proceso de compilación.

- run: |
    make bootstrap
    make release

Para obtener más información sobre la palabra clave run, consulte "Sintaxis del flujo de trabajo para Acciones de GitHub".

Si el repositorio contiene varios lenguajes compilados, puede especificar comandos de compilación específicos del lenguaje. Por ejemplo, si el repositorio contiene C/C++, C# y Java, y autobuild compila correctamente C/C++ y C# pero no puede compilar Java, podría usar la configuración siguiente en el flujo de trabajo, después del paso init. Esto especifica los pasos de compilación para Java mientras se sigue usando autobuild para C/C++ y C#:

- if: matrix.language == 'c-cpp' || matrix.language == 'csharp'
  name: Autobuild
  uses: github/codeql-action/autobuild@v3
- if: matrix.language == 'java-kotlin'
  name: Build Java
  run: |
    make bootstrap
    make release

Para más información sobre el condicional if, consulta "Sintaxis del flujo de trabajo para Acciones de GitHub".

Para obtener sugerencias y trucos sobre por qué autobuild no compila el código, consulta "Error de compilación automática para un lenguaje compilado".

Si agregas pasos de compilación manualmente para los lenguajes compilados y el code scanning aún no funciona en tu repositorio, contacta a con nosotros a través del Soporte técnico de GitHub.