Opções e etapas de build do CodeQL para idiomas compilados

Passos de compilação automática para linguagens compiladas

Se você usar executores auto-hospedados para GitHub Actions, talvez seja necessário instalar software adicional para usar o processo autobuild. Além disso, se seu repositório precisar de uma versão específica de uma ferramenta de criação, talvez seja necessário instalá-lo manualmente. Para executores auto-hospedados, você deve instalar as dependências diretamente nos próprios executores. Fornecemos exemplos de dependências comuns para C/C++, C#e Java em cada uma das seções autobuild deste artigo para esses idiomas. Para saber mais, confira Executores auto-hospedados.

Compilação em C/C++

O CodeQL é compatível com modos de build autobuild ou manual para código C/C++.

Resumo de compilação automática para C/C++

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux
Sistema de criação	Windows: MSBuild e scripts de compilação Linux e macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild e scripts de build

O comportamento da etapa autobuild varia de acordo com o sistema operacional em que a extração é executada.

Detecção automática do Windows

No Windows, a etapa autobuild tenta fazer a detecção automática de um método de build adequado para C/C++ usando a seguinte abordagem:

1. Invocar MSBuild.exe no arquivo de solução (.sln) ou de projeto (.vcxproj) mais próximo da raiz. Se autobuild detectar vários arquivos de solução ou de projeto na mesma profundidade (mais curta) do diretório de nível superior, ele tentará compilar todos eles.
2. Invocar um script parecido com um script de build—build.bat, build.cmd e build.exe (nessa ordem).

Detecção automática de Linux e macOS

No Linux e no macOS, a etapa autobuild revisa os arquivos presentes no repositório para determinar o sistema de build usado:

1. Procure um sistema de criação no diretório-raiz.
2. Se nenhum for encontrado, procure um diretório único nos subdiretórios com um sistema de criação para C/C++.
3. Execute um comando apropriado para configurar o sistema.

Requisitos do executor para C/C++

Nos executores do Ubuntu Linux, autobuild pode tentar instalar automaticamente as dependências exigidas pelas etapas de configuração e compilação detectadas. Por padrão, esse comportamento é ativado em executores hospedados pelo GitHub e desabilitado em executores auto-hospedados. Você pode habilitar ou desabilitar esse recurso explicitamente definindo CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES para true ou false no ambiente. Para obter mais informações sobre a definição de variáveis de ambiente, confira Armazenar informações em variáveis.

Para executores auto-hospedados, a menos que a instalação automática de dependências esteja habilitada, você provavelmente precisará instalar o compilador gcc e projetos específicos também podem exigir acesso a executáveis clang ou msvc. Você também precisará instalar o sistema de compilação (por exemplo msbuild, make, cmake, bazel) e utilitários (como python, perl, lex e yacc) dos quais seus projetos dependem. Se você habilitar a instalação automática de dependências, deverá garantir que o executor esteja usando o Ubuntu e que ele possa ser executado sudo apt-get sem a necessidade de uma senha.

Os executores do Windows precisam que o powershell.exe esteja em PATH.

Compilação C#

O CodeQL é compatível com modos de build none, autobuild ou manual para código C#.

Quando você habilita a configuração padrão para um repositório que contém código C#, o modo de compilação é definido automaticamente como none.

Nenhuma compilação para C#

O CodeQL restaura dependências e gera alguns arquivos de origem adicionais, para fornecer resultados mais precisos, antes de criar um banco de dados a partir de todos os arquivos de origem e dependências.

As dependências são restauradas usando várias heurísticas e estratégias. Os seguintes arquivos são a principal fonte de informações: *.csproj, *.sln, nuget.config, packages.config, global.json e project.assets.json. Se um feed NuGet privado estiver definido para a organização, ele também será usado. Consulte Configuração padrão de verificação de código para acesso a registros privados e Determinar se a configuração padrão de verificação de código utilizava algum registro privado.

Os seguintes arquivos de origem gerados são opcionais, mas aumentam significativamente a exatidão do banco de dados CodeQL:

•         `global` gerou diretivas `using` para lidar com o recurso implícito `using` do MSbuild.
  

• Arquivos de exibição do ASP.NET Core, arquivos .cshtml são convertidos em arquivos .cs.

As informações dos nomes de assemblies de dependência, arquivos de origem gerados, dependências armazenadas em feeds privados, e os arquivos de origem no repositório são compilados e usados ​​para criar um banco de dados CodeQL.

Precisão da análise sem compilação para C#

Criar um banco de dados CodeQL sem compilar o código completo depende da capacidade de restaurar dependências e ser capaz de compilar os arquivos de origem juntos no repositório. Quando há problemas para restaurar dependências ou compilar o código-fonte, isso pode afetar a precisão do banco de dados CodeQL e dos resultados da análise do code scanning.

Você pode garantir uma análise mais precisa seguindo estas etapas:

• Forneça acesso à internet pública ou assegure que o acesso a um feed NuGet privado esteja disponível, consulte Configuração padrão de verificação de código para acesso a registros privados.
• Verifique se o repositório requer várias versões da mesma dependência NuGet. CodeQL pode usar apenas uma versão e geralmente escolhe a versão mais recente onde existem várias versões. Essa abordagem pode não funcionar para todos os repositórios.
• Verifique se várias versões de .NET são referenciadas, por exemplo, net48, net5.0 e netstandard1.6. CodeQL pode usar apenas uma versão e isso pode afetar a precisão.
• Evite colidir nomes de classe, caso contrário, isso pode ocasionar destinos de chamada de método ausentes, o que afeta a análise de fluxo de dados.

Resumo de compilação automática para C#

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux
Sistema de criação	.NET e MSbuild, bem como criar scripts

Detecção automática do Windows

O processo autobuild tenta fazer a detecção automática de um método de build adequado para C# usando a seguinte abordagem:

1. Invocar dotnet build no arquivo de solução (.sln) ou de projeto (.csproj) mais próximo da raiz.
2. Invocar MSBuild.exe no arquivo de solução ou de projeto mais próximo da raiz. Se autobuild detectar vários arquivos de solução ou de projeto na mesma profundidade (mais curta) do diretório de nível superior, ele tentará compilar todos eles.
3. Invocar um script parecido com um script de build—build.bat, build.cmd, e build.exe (nessa ordem).

Requisitos de executor para C# no Windows

Para o desenvolvimento de aplicativos .NET Core em executores auto-hospedados, o SDK do .NET é necessário (para dotnet).

Para o desenvolvimento de aplicativos do .NET Framework, você precisará de ferramentas de Microsoft Build (para msbuild) e CLI do NuGet (para nuget).

Os executores do Windows precisam que o powershell.exe esteja em PATH.

Se você planeja criar bancos de dados CodeQL usando build-mode: none, você também precisa fornecer acesso à internet pública ou garantir que o acesso a um feed NuGet privado esteja disponível.

Detecção automática de Linux e macOS

1. Invocar dotnet build no arquivo de solução (.sln) ou de projeto (.csproj) mais próximo da raiz.
2. Invocar MSbuild no arquivo de solução ou de projeto mais próximo da raiz. Se autobuild detectar vários arquivos de solução ou de projeto na mesma profundidade (mais curta) do diretório de nível superior, ele tentará compilar todos eles.
3. Invocar um script parecido com um script de build—build e build.sh (nessa ordem).

Requisitos do executor para C# no Linux e macOS

Para o desenvolvimento de aplicativos .NET Core em executores auto-hospedados, o SDK do .NET é necessário (para dotnet).

Para o desenvolvimento de aplicativos do .NET Framework, você exigirá o Mono Runtime (para executar mono, msbuild ou nuget).

Se você planeja criar bancos de dados CodeQL usando build-mode: none, você também precisa fornecer acesso à internet pública ou garantir que o acesso a um feed NuGet privado esteja disponível.

Sinalizadores do compilador C# injetadas por CodeQL para compilações manuais

O rastreador CodeQL permite a extração de todas as linguagens compiladas, interceptando os processos de compilação e encaminhando as informações para os extratores de linguagem CodeQL relevantes. O rastreador injeta certos sinalizadores na invocação do compilador C# para garantir que cada componente seja construído e incluído no banco de dados CodeQL, o que pode fazer com que seu código C# seja compilado de uma maneira diferente da esperada durante a análise do CodeQL.

/p:MvcBuildViews=true

Quando essa opção é definida como true, os modos de exibição em projetos ASP.NET MVC (model-view-controller) são pré-compilados como parte do processo de build, o que pode ajudar a capturar erros e melhorar o desempenho. O rastreador injeta esse sinalizador para garantir que CodeQL encontre e destaque problemas de segurança que possam envolver o fluxo de dados através do código gerado a partir dessas visualizações. Para obter mais informações, consulte Adicionando uma exibição a um aplicativo MVC no Microsoft Learn.

/p:UseSharedCompilation=false

Definir essa opção para false desabilita o uso do recurso de compilação compartilhada, o que pode resultar em tempos de compilação mais lentos. Quando /p:UseSharedCompilation=false não é especificado, o msbuild inicia um processo do servidor do compilador e toda a compilação será feita por esse único processo. No entanto, o rastreador CodeQL depende da inspeção dos argumentos de processos recém-criados.

/p:EmitCompilerGeneratedFiles=true

Definir essa opção como true emitirá arquivos gerados pelo compilador durante o processo de compilação. Essa opção faz com que o compilador gere arquivos de origem adicionais que são usados ​​para dar suporte a recursos como suporte aprimorado a expressões regulares, serialização e geração de visualizações de aplicativos web. Esses artefatos gerados normalmente não são gravados em disco pelo compilador, mas definir a opção para true força a gravação dos arquivos no disco e, portanto, o extrator pode processar os arquivos.

Para alguns projetos legados e projetos que utilizam .sqlproj, você pode ver que a propriedade /p:EmitCompilerGeneratedFiles=true injetada causa problemas inesperados com o msbuild. Para obter informações sobre como solucionar esse problema, consulte Compilador C# falhando de forma inesperada.

Compilação Go

O CodeQL dá suporte a modos de build autobuild ou manual para código Go.

Resumo de compilação automática para Go

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux
Sistema de criação	Módulos Go, dep e Glide, bem como scripts de build, incluindo Makefiles e scripts Ninja

Detecção automática para Go

O processo autobuild tenta fazer a detecção automática de uma forma adequada para instalar as dependências necessárias em um repositório Go antes de extrair todos os arquivos .go:

1. Invoque make, ninja, ./build ou ./build.sh (nessa ordem) até que um desses comandos seja bem-sucedido e um próximo go list ./... também seja bem-sucedido, indicando que as dependências necessárias foram instaladas.
2. Se nenhum desses comandos for bem-sucedido, procure go.mod, Gopkg.toml ou glide.yaml e execute go get (a menos que a cópia para a pasta Vendor esteja em uso), dep ensure -v ou glide install, respectivamente, para tentar instalar as dependências.
3. Por fim, se os arquivos de configurações desses gerenciadores de dependência não forem encontrados, reorganize a estrutura de diretório do repositório adequada para adição a GOPATH e use go get para instalar as dependências. A estrutura de diretório é revertida para normal após a conclusão da extração.
4. Extraia todo o código Go no repositório, semelhante à execução de go build ./....

Opções de extrator para Go

Por padrão, o código de teste (código em arquivos terminados em _test.go) não é analisado. Você pode sobrescrever isso com a opção --extractor-option extract_tests=true Ao usar o CodeQL CLI ou ao definir a variável de ambiente CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS como true.

Além disso, os diretórios vendor são excluídos da análise do Go CodeQL por padrão. Você pode sobrescrever isso passando a opção --extractor-option extract_vendor_dirs=true ao usar o CodeQL CLI ou ao definir a variável de ambiente CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS como true.

Criando Java e Kotlin

O CodeQL dá suporte aos modos de build a seguir.

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

Quando você habilita a configuração padrão para um repositório pela primeira vez, se apenas Java código for detectado, o modo de build será definido como none. Se o Kotlin ou uma combinação de código Java e Kotlin for detectado, o modo de build será definido como autobuild.

Se, posteriormente, você adicionar o código Kotlin a um repositório que usa o modo de compilação none, a análise CodeQL relatará uma mensagem de aviso explicando que o Kotlin não é suportado. Você precisará desativar a configuração padrão e reativá-la. Quando você reativar a instalação padrão, o modo de compilação será alterado para autobuild para que ambos os idiomas possam ser analisados. Como alternativa, você pode alterar para uma configuração avançada. Para saber mais, confira Aviso: Detectados X arquivos Kotlin no seu projeto que não puderam ser processados sem compilação.

Nenhuma compilação para Java

O CodeQL tentará executar o Gradle ou o Maven para extrair informações precisas de dependência (mas não para invocar uma compilação), antes de criar um banco de dados a partir de todos os arquivos Java presentes. Cada arquivo de projeto raiz do Maven ou do Gradle (um script de compilação sem qualquer script de compilação presente em um diretório ancestral) é consultado para obter informações de dependência e, em caso de conflito, as versões de dependência mais recentes são preferidas. Para obter informações sobre os requisitos do executor do Maven ou do Gradle, consulte Requisitos do Runner para Java.

Se um registro Maven privado estiver definido para a organização, este também será usado, consulte Configuração padrão de verificação de código para acesso a registros privados e Determinar se a configuração padrão de verificação de código utilizava algum registro privado.

Precisão da análise sem compilação para Java

A criação de um banco de dados Java do CodeQL sem uma compilação poderá produzir resultados menos precisos do que usar o autobuild ou etapas de compilação manual se:

• Os scripts de build do Gradle ou Maven não puderem ser consultados para obter informações de dependência, e as suposições de dependência (baseadas em nomes de pacotes Java) forem imprecisas.
• O repositório normalmente gera código durante o processo de compilação. Isso seria analisado se você criasse o banco de dados CodeQL usando um modo diferente.

Você pode garantir uma análise mais precisa seguindo estas etapas:

• Forneça acesso à internet pública ou assegure que o acesso a um repositório de artefatos privado esteja disponível, consulte Configuração padrão de verificação de código para acesso a registros privados.
• Verifique se o repositório requer várias versões da mesma dependência. CodeQL pode usar apenas uma versão e geralmente escolhe a versão mais recente onde existem várias versões. Essa abordagem pode não funcionar para todos os repositórios.
• Verifique se mais de uma versão da API do JDK é necessária por diferentes arquivos de Java de origem. Quando várias versões forem detectadas, CodeQL usará a versão mais recente exigida por qualquer script de compilação. Isso pode significar que alguns arquivos que exigem uma versão inferior do JDK serão analisados ​​parcialmente. Por exemplo, se alguns arquivos exigirem o JDK 8, mas um ou mais scripts de compilação exigirem o JDK 17, CodeQL usará o JDK 17. Quaisquer arquivos que exijam o JDK 8 e não possam ser compilados usando o JDK 17 serão parcialmente analisados.
• Evite colidir nomes de classes (por exemplo, vários arquivos definindo org.myproject.Test), caso contrário, isso poderá causar destinos de chamadas de método ausentes, o que afeta a análise do fluxo de dados.

Resumo da construção automatizada para Java

Tipo de sistema compatível	Nome do sistema
Sistema operacional	Windows, macOS e Linux (sem restrição)
Sistema de criação	Gradle, Maven e Ant

Autodeteção para Java

O processo autobuild tenta determinar o sistema de build para bases de código Java ao aplicar esta estratégia:

1. Procurar um arquivo de criação no diretório-raiz. Verifique o arquivos do Gradle, do Maven e, em seguida, do Ant.
2. Execute o primeiro arquivo de criação encontrado. Se os arquivos do Gradle e do Maven estiverem presentes, será usado o arquivo do Gradle.
3. Caso contrário, procure arquivos de criação nos subdiretórios diretos do diretório-raiz. Se apenas um subdiretório contiver arquivos de criação, execute o primeiro arquivo identificado nesse subdiretório (usando a mesma preferência de 1). Se mais de um subdiretório conter arquivos de criação, relate um erro.

Requisitos do executor para Java

Se você estiver usando executores auto-hospedados, as versões necessárias de Java deverão estar presentes:

• Se o executor for usado para analisar repositórios que precisam de uma única versão do Java, a versão apropriada do JDK precisa ser instalada e precisa estar presente na variável PATH (para que java e javac possam ser encontrados).

• Se o executor for usado para analisar repositórios que precisam de várias versões do Java, as versões apropriadas do JDK precisarão ser instaladas e poderão ser especificadas por meio do arquivo toolchains.xml. Este é um arquivo de configuração, normalmente usado pelo Apache Maven, que permite especificar o local e a versão das ferramentas, além de qualquer configuração adicional necessária para utilizá-las. Para obter mais informações, consulte Guia para usar cadeia de ferramentas na documentação do Apache Maven.

Os seguintes executáveis provavelmente serão necessários para um intervalo de projetos Java e devem estar presentes na variável PATH, mas eles não serão essenciais em todos os casos:

•         `mvn` (Apache Maven)
  

•         `gradle` (Gradle)
  

•         `ant` (Apache Ant)
  

Você também precisará instalar o sistema de compilação (por exemplo make, cmake, bazel) e utilitários (como python, perl, lex e yacc) dos quais seus projetos dependem.

Os executores do Windows precisam que o powershell.exe esteja em PATH.

Compilação Swift

O CodeQL dá suporte a modos de build autobuild ou manual para código Swift.

Resumo de compilação automática para Swift

Tipo de sistema compatível	Nome do sistema
Sistema operacional	macOS
Sistema de criação	Xcode

O processo autobuild tenta criar o maior destino de um projeto ou workspace Xcode.

A verificação do código Swift usa executores do macOS por padrão.

O Code scanning do código Swift não é compatível com executores que fazem parte de um Actions Runner Controller (ARC), porque os executores ARC usam apenas o Linux e o Swift requer executores macOS. No entanto, você pode ter uma mistura de executores ARC e executores macOS auto-hospedados. Para saber mais, confira Controlador de Ações Runner.

Como personalizar a compilação Swift em um Fluxo de trabalho de análise do CodeQL

          `xcodebuild` e `swift build` são compatíveis com builds Swift. Recomendamos direcionar apenas uma arquitetura durante o build. Por exemplo, `ARCH=arm64` para `xcodebuild` ou `--arch arm64` para `swift build`.

Você pode passar as opções archive e test para xcodebuild. No entanto, o comando xcodebuild padrão é recomendado, pois deve ser o mais rápido e deve ser tudo o que o CodeQL exige para uma verificação bem-sucedida.

Para a análise do Swift, você sempre deve instalar explicitamente as dependências gerenciadas por meio do CocoaPods ou Carthage antes de gerar o banco de dados do CodeQL.