Opciones y pasos de compilación de CodeQL para lenguajes compilados

Adición de pasos de Autobuild para lenguajes compilados

Si usa ejecutores autoalojados para GitHub Actions, es posible que tenga 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. En el caso de los ejecutores autohospedados, debe instalar dependencias directamente en los propios ejecutores. Se proporcionan ejemplos de dependencias comunes para C/C++, C# y Java en cada una de las secciones de autobuild de este artículo para esos lenguajes. Para más información, consulta Ejecutores autohospedados.

Compilación de C/C++

CodeQL admite modos de compilación none, autobuild o manual para código de C/C++.

Cuando se habilita la configuración predeterminada para un repositorio que contiene código de C/C++, el modo de compilación se establece en none automáticamente.

No hay ninguna compilación para C/C++

CodeQL deducirá las unidades de compilación de C/C++ a través de extensiones de archivos fuente. Para cada archivo de origen encontrado, las marcas de compilación y las rutas de acceso de inclusión se deducen inspeccionando el código base sin necesidad de un comando de compilación en funcionamiento.

Precisión del análisis sin compilación para C/C++

La creación de una base de datos de C/C+ de CodeQL sin una compilación puede producir resultados menos precisos que usar autobuild o los pasos de compilación manual en algunos casos; por ejemplo:

• El código depende en gran medida de macros/defines personalizados que no están disponibles en las cabeceras existentes.
• El código base tiene muchas dependencias externas.

Para garantizar un análisis más preciso, siga estos pasos:

• Coloque macros personalizadas y defina en los archivos de encabezado que se incluyen en los archivos de código fuente pertinentes.
• Asegúrese de que las dependencias externas (encabezados) están disponibles en los directorios include del sistema o en el área de trabajo.
• Ejecute la extracción en la plataforma de destino. Por ejemplo, elija un runner de Windows para analizar proyectos de Windows y así conceder acceso a encabezados y compiladores específicos de la plataforma.

Resumen de compilación automática para C/C++

Tipo de sistema compatible	Nombre del sistema
Sistema operativo	Windows, macOS y Linux
Sistema de compilación	Windows: 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.

detección automática de Windows

En Windows, el paso autobuild intenta detectar automáticamente un método de compilación adecuado para C/C++ mediante el siguiente enfoque:

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

Detección automática de Linux y macOS

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.

Requisitos del ejecutor para C/C++

En los ejecutores de Ubuntu Linux, autobuild puede intentar instalar automáticamente las dependencias necesarias para 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, consulte Almacenamiento de información en variables.

En el caso de los ejecutores autohospedados, a menos que la instalación automática de dependencias esté habilitada, es probable que tenga que instalar el compilador gcc y es posible que proyectos específicos también necesiten acceso a los archivos ejecutables clang o 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 habilita la instalación automática de dependencias, debe asegurarse de que el ejecutor usa Ubuntu y que se puede ejecutar sudo apt-get sin necesidad de una contraseña.

Los ejecutores de Windows demandan que powershell.exe esté en PATH.

Compilación de C#

CodeQL admite los modos de compilación none, autobuild o manual para código C#.

Cuando se habilita la configuración predeterminada para un repositorio que contiene código de C#, el modo de compilación se establece en none automáticamente.

No hay ninguna compilación para C#

CodeQL restaura las dependencias y genera algunos archivos de origen adicionales, para proporcionar resultados más precisos, antes de crear una base de datos a partir de todos los archivos de origen y dependencias.

Las dependencias se restauran mediante varias heurísticas y estrategias. Los archivos siguientes son el origen principal de la información: *.csproj, *.sln, nuget.config, packages.config, global.json y project.assets.json. Si se define una fuente privada de NuGet para la organización, también se usa, consulte Acceso predeterminado de configuración de análisis de código a registros privados y Determinar si la configuración predeterminada de análisis de código usó registros privados.

Los siguientes archivos de origen generados son opcionales, pero aumentan significativamente la exactitud de la base de datos CodeQL:

•           Directivas de `global` generadas `using` para controlar la característica implícita `using` de MSbuild.
  

• Archivos de vista principales ASP.NET, los archivos .cshtml se convierten en archivos .cs.

La información de los nombres de ensamblado de dependencias, archivos de origen generados, dependencias almacenadas en fuentes privadas , y los archivos de origen en el repositorio se compila y usa para crear una base de datos de CodeQL.

Precisión del análisis de no compilación para C#

Crear una base de datos de CodeQL sin compilar el código completo se basa en poder restaurar las dependencias y poder compilar juntos los archivos de origen en el repositorio. Cuando hay problemas al restaurar dependencias o compilar el código fuente, esto puede afectar a la precisión de la base de datos de CodeQL y los resultados de análisis de code scanning.

Para garantizar un análisis más preciso, siga estos pasos:

• Proporcione acceso a la red pública de Internet o asegúrese de que el acceso a una fuente privada de NuGet está disponible, consulte Acceso predeterminado de análisis de código a registros privados.
• Compruebe si el repositorio requiere varias versiones de la misma dependencia de NuGet. CodeQL solo puede usar una versión y normalmente elige la versión más reciente en la que hay varias versiones. Este enfoque puede no funcionar para todos los repositorios.
• Compruebe si se hace referencia a varias versiones de .NET, por ejemplo, net48, net5.0 y netstandard1.6. CodeQL solo puede usar una versión y esto puede afectar a la precisión.
• Evite la colisión de nombres de clase; de lo contrario, esto puede provocar que falten destinos de llamada de método, lo que tiene un impacto en el análisis del flujo de datos.

Resumen de compilación automática para C#

Tipo de sistema compatible	Nombre del sistema
Sistema operativo	Windows, macOS y Linux
Sistema de compilación	.NET y MSbuild, así como scripts de compilación

detección automática de Windows

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.exe en el archivo de solución o 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. Invoque un script similar a un script de compilación: build.bat, build.cmd, y build.exe (en ese orden).

Requisitos de ejecutor para C# en 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, necesitará Microsoft Build Tools (para msbuild) y la CLI de NuGet (para nuget).

Los ejecutores de Windows demandan que powershell.exe esté en PATH.

Si tiene previsto crear bases de datos de CodeQL mediante build-mode: none, también debe proporcionar acceso a la red pública de Internet, o debe asegurarse de que el acceso a una fuente privada de NuGet esté disponible.

Detección automática de Linux y macOS

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 en el archivo de solución o 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. Invoque un script similar a un script de compilación: build y build.sh (en ese orden).

Requisitos de ejecutor para C# en Linux y macOS

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, necesitará Mono Runtime (para ejecutar mono, msbuild o nuget).

Si tiene previsto crear bases de datos de CodeQL mediante build-mode: none, también debe proporcionar acceso a la red pública de Internet, o debe asegurarse de que el acceso a una fuente privada de NuGet esté disponible.

Marcas del compilador de C# inyectadas por CodeQL para compilaciones manuales

El seguimiento de CodeQL permite la extracción de todos los lenguajes compilados interceptando los procesos de compilación y reenviando información a los extractores de lenguaje de CodeQL pertinentes. El seguimiento inyecta algunas marcas en la invocación del compilador de C# para asegurarse de que todos los componentes se compilan e incluyen en la base de datos de CodeQL, lo que puede hacer que el código de C# se compile de forma diferente a lo que espera durante el análisis de CodeQL.

/p:MvcBuildViews=true

Cuando esta opción se establece en true, las vistas de ASP.NET proyectos model-view-controller (MVC) se precompilan como parte del proceso de compilación, lo que puede ayudar a detectar errores y mejorar el rendimiento. El seguimiento inyecta esta marca para asegurarse de que CodeQL encuentra y resalta los problemas de seguridad que pueden implicar el flujo de datos a través del código generado a partir de estas vistas. Para obtener más información, consulte Adición de una vista a una aplicación MVC en Microsoft Learn.

/p:UseSharedCompilation=false

Establecer esta opción en false deshabilita el uso de la característica de compilación compartida, lo que puede dar lugar a tiempos de compilación más lentos. Cuando /p:UseSharedCompilation=falseno se especifica, msbuild inicia un proceso de servidor del compilador y toda la compilación la llevará a cabo ese único proceso. Sin embargo, el seguimiento de CodeQL depende de la inspección de los argumentos de los procesos recién creados.

/p:EmitCompilerGeneratedFiles=true

Al establecer esta opción en true, se emitirán archivos generados por el compilador durante el proceso de compilación. Esta opción hace que el compilador genere archivos de código fuente adicionales que se usan para admitir características como la compatibilidad mejorada con expresiones regulares, la serialización y la generación de vistas de aplicaciones web. Normalmente el compilador no escribe estos artefactos generados en el disco, sino que establecer la opción en true fuerza la escritura de los archivos en el disco, por lo que el extractor puede procesar los archivos.

Para algunos proyectos antiguos y proyectos que usan archivos .sqlproj, es posible que vea que la propiedad /p:EmitCompilerGeneratedFiles=true inyectada provoca problemas inesperados con msbuild. Para obtener más información sobre la solución de problemas, consulte Errores inesperados del compilador de C#.

Compilación de Go

CodeQL admite los modos de compilación autobuild o manual para código Go.

Resumen de compilación automática para Go

Tipo de sistema compatible	Nombre del sistema
Sistema operativo	Windows, macOS y Linux
Sistema de compilación	Módulos de Go, dep y Glide, así como scripts de compilación, incluidos scripts de Makefiles y Ninja

Detección automática para Go

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

Opciones de extractor para Go

De manera predeterminada, no se analiza el código de prueba (código en archivos que terminan en _test.go). Puede invalidar esto con la opción --extractor-option extract_tests=true al usar CodeQL CLI o estableciendo la variable de entorno CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS en true.

Además, los directorios vendor se excluyen del análisis de CodeQL de Go de manera predeterminada. Puede invalidar esto con la opción --extractor-option extract_vendor_dirs=true al usar CodeQL CLI o estableciendo la variable de entorno CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS en true.

Construcción de Java y Kotlin

CodeQL admite los siguientes modos de compilación.

• Java: none, autobuild o manual
• Kotlin: autobuild o manual

Cuando se activa por primera vez la configuración predeterminada para un repositorio, si solo se detecta código Java, el modo de compilación se establece en none. Si se detecta Kotlin o una combinación de Java y código de Kotlin, el modo de compilación se establece en autobuild.

Si más adelante agrega código Kotlin a un repositorio que usa el modo de compilación none, el análisis de CodeQL notifica un mensaje de advertencia que explica que el lenguaje Kotlin no es compatible. Tendrá que deshabilitar la configuración predeterminada y volver a habilitarla. Al volver a habilitar la configuración predeterminada, el modo de compilación cambiará a autobuild para que se puedan analizar ambos lenguajes. Como alternativa, puede cambiar a una configuración avanzada. Para más información, consulta Advertencia: se detectaron X archivos Kotlin en el proyecto que no se pudieron procesar sin una compilación.

No hay ninguna compilación para Java

CodeQL intentará ejecutar Gradle o Maven para extraer información de dependencia precisa (pero no invocar una compilación), antes de crear una base de datos a partir de todos los archivos Java presentes. Cada archivo de proyecto de Maven o Gradle raíz (un script de compilación sin ningún script de compilación presente en un directorio antecesor) se consulta para obtener información de dependencia y se prefieren versiones de dependencia más recientes si hay un conflicto. Para obtener información sobre los requisitos del ejecutor para ejecutar Maven o Gradle, consulte Runner requirements for Java.

Si se define un registro de Maven para la organización, también se usa, consulte Acceso predeterminado de configuración de análisis de código a registros privados y Determinar si la configuración predeterminada de análisis de código usó registros privados.

Precisión del análisis sin compilación para Java

La creación de una base de datos de Java con CodeQL sin una compilación puede producir resultados menos precisos que usar autobuild o pasos de compilación manuales si:

• Los scripts de compilación de Gradle o Maven no se pueden consultar para obtener información de dependencia y las estimaciones de dependencia (basadas en nombres de paquete Java) son inexactas.
• Normalmente, el repositorio genera código durante el proceso de compilación. Esto se analizaría si creó la base de datos CodeQL con un modo diferente.

Para garantizar un análisis más preciso, siga estos pasos:

• Proporcione acceso a la red pública de Internet o asegúrese de que el acceso a un repositorio privado de artefactos está disponible, consulte Acceso predeterminado de análisis de código a registros privados.
• Compruebe si el repositorio requiere varias versiones de la misma dependencia. CodeQL solo puede usar una versión y normalmente elige la versión más reciente en la que hay varias versiones. Este enfoque puede no funcionar para todos los repositorios.
• Compruebe si se requiere más de una versión de la API de JDK por diferentes archivos de Java de origen. Cuando se ven varias versiones, CodeQL usará la versión más alta necesaria para cualquier script de compilación. Esto puede significar que algunos archivos que necesiten una versión inferior del JDK se analizarán parcialmente. Por ejemplo, si algunos archivos necesitan JDK 8, pero se encuentra un requisito de JDK 17 en uno o varios scripts de compilación, CodeQL usará JDK 17. Se analizarán parcialmente todos los archivos que necesiten JDK 8 y no se hayan podido compilar mediante JDK 17.
• Evite la colisión de nombres de clase (por ejemplo, varios archivos que definan org.myproject.Test); de lo contrario, esto puede provocar que falten destinos de llamada de método, lo que afecta al análisis del flujo de datos.

Resumen de la compilación automática para Java

Tipo de sistema compatible	Nombre del sistema
Sistema operativo	Windows, macOS y Linux (sin restricción)
Sistema de compilación	Gradle, Maven y Ant

Detección automática de Java

El proceso de autobuild intenta determinar el sistema de compilación para 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, busca 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.

Requisitos del ejecutor para Java

Si usa ejecutores autohospedados, las versiones necesarias 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 se pueda encontrar java y javac).

• Si el ejecutor se usará para analizar repositorios que necesitan 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 obtener más información, consulte Guía para usar cadenas de herramientas en la documentación de Apache Maven.

Es probable que los siguientes ejecutables sean necesarios para un intervalo de 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.

Los ejecutores de Windows demandan que powershell.exe esté en PATH.

Creación de Rust

CodeQL admite el modo de compilación none para el código de Rust.

No hay ninguna compilación para Rust

CodeQL usa rust-analyzer para compilar y ejecutar scripts de compilación (archivos build.rs) y para compilar código de macros, pero no invoca un proceso de compilación completo. Se crea una base de datos a partir de todos los archivos de Rust presentes. Un archivo Cargo.toml o rust-project.json debe estar presente.

Requisitos del ejecutor para Rust

El análisis de Rust requiere que rustup y cargo estén instalados.

Compilación de Swift

CodeQL admite los modos de compilación autobuild o manual para código Swift.

Resumen de la compilación automática para Swift

Tipo de sistema compatible	Nombre del sistema
Sistema operativo	macOS
Sistema de compilación	Xcode

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

El examen de código de Swift usa ejecutores de macOS de forma predeterminada.

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.