Skip to main content

Verificação de código do CodeQL para linguagens compiladas

Compreenda o método de compilação automática que a análise do CodeQL utiliza para compilar código em linguagens compiladas e saiba como você pode personalizar o comando de compilação, caso seja necessário.

Quem pode usar esse recurso?

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

A Code scanning está disponível para todos os repositórios públicos do GitHub.com. A Code scanning também está disponível em repositórios privados pertencentes às organizações que usam o GitHub Enterprise Cloud e que têm uma licença do GitHub Advanced Security. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Sobre o Fluxo de trabalho de análise do CodeQL e as linguagens compiladas

O Code scanning trabalha executando consultas em um ou mais bancos de dados. Cada banco de dados contém uma representação de todo o código em uma linguagem única no seu repositório. Para as linguagens compiladas de C/C++, C#, Go, Java, Swift, o processo de preenchimento deste banco de dados envolve a construção do código e extração de dados.

O CodeQL analisa os arquivos de origem do C/C++, C#, Go, Java, Swift criados no repositório.

Se você habilitar a configuração padrão, a ação autobuild será usada para compilar seu código, como parte do seu Fluxo de trabalho de análise do CodeQL configurado automaticamente. Se você habilitar a instalação avançada, o Fluxo de trabalho de análise do CodeQL básico usará autobuild. Como alternativa, é possível desabilitar autobuild e especificar comandos de compilação explícitos para analisar apenas os arquivos criados por esses comandos personalizados.

Para a code scanning do CodeQL, você pode usar a configuração padrão, que analisa o código e configura automaticamente a code scanning, ou a configuração avançada, que gera um arquivo de fluxo de trabalho que pode ser editado. Para mais informações sobre configuração avançada, confira "Como definir a configuração avançada da verificação de código."

Para obter informações sobre as linguagens, bibliotecas e estruturas compatíveis na versão mais recente do CodeQL, consulte "Linguagens e estruturas compatíveis" na documentação do CodeQL. Para obter mais informações sobre os requisitos do sistema para executar a última versão do CodeQL, consulte "Requisitos do sistema" na documentação do CodeQL.

Se o fluxo de trabalho usar uma matriz language, autobuild tentará criar cada uma das linguagens compiladas listadas na matriz. Sem uma matriz, autobuild tentará criar a linguagem compilada compatível que tem mais arquivos de origem no repositório. Com exceção de Go, a análise de outras linguagens compatíveis no repositório irá falhar, a menos que você forneça comandos de criação explícitos.

Sobre autobuild para o CodeQL

O CodeQL analisa os arquivos de origem do C/C++, C#, Go, Java, Swift criados no repositório.

Se você habilitar a configuração padrão, a ação autobuild será usada para compilar seu código, como parte do seu Fluxo de trabalho de análise do CodeQL configurado automaticamente. Se você habilitar a instalação avançada, o Fluxo de trabalho de análise do CodeQL básico usará autobuild. Como alternativa, é possível desabilitar autobuild e especificar comandos de compilação explícitos para analisar apenas os arquivos criados por esses comandos personalizados.

Nota: Se você usar executores auto-hospedados para o 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. Os executores hospedados no GitHub são sempre executados com o software exigido por autobuild.

autobuild para C/C++

Tipo de sistema compatívelNome do sistema
Sistema operacionalWindows, macOS e Linux
Sistema de criaçãoWindows: MSbuild e scripts de build
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. 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).

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.

Em executores Ubuntu Linux, autobuild pode tentar instalar automaticamente dependências exigidas pela configuração detectada e etapas de compilação. 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 "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 habilitar a instalação automática de dependências, você deverá garantir que o executor esteja usando o Ubuntu e que ele possa executar sudo apt-get sem exigir uma senha.

autobuild para C#

Tipo de sistema compatívelNome do sistema
Sistema operacionalWindows, macOS e Linux
Sistema de criação.NET, MSbuild e scripts de criação

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 (Linux) ou MSBuild.exe (Windows) 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, para o Linux) ou build.bat, build.cmd e build.exe (nessa ordem, para o Windows).

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

Para o desenvolvimento de aplicativos NET Framework, no Windows, você precisará das Ferramentas do Microsoft Build (para msbuild) e da CLI Nuget (para nuget). No Linux e macOS, você precisará do Mono Runtime (para executar mono, msbuild ou nuget).

autobuild para Go

Tipo de sistema compatívelNome do sistema
Sistema operacionalWindows, macOS e Linux
Sistema de criaçãoMódulos Go, dep e Glide, bem como scripts de build, incluindo Makefiles e scripts Ninja

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

Observação: se você usar a configuração padrão, ela procurará por um arquivo go.mod para instalar automaticamente uma versão compatível da linguagem Go

autobuild para Java e Kotlin

Tipo de sistema compatívelNome do sistema
Sistema operacionalWindows, macOS e Linux (sem restrição)
Sistema de criaçãoGradle, Maven e Ant

O processo autobuild tenta determinar o sistema de build para bases de código Java aplicando 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.

Se você estiver usando executores auto-hospedados, a(s) versão(ões) necessária(s) do Java deverá(ão) estar presente(s):

  • Se o executor for usado para analisar repositórios que precisam de uma única versão do Java, a versão apropriada do JDK precisará ser instalada e precisará 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 toolchains" na documentação do Apache Maven.

Os seguintes executáveis provavelmente serão necessários para uma variedade de projetos Java e devem estar presentes na variável PATH, mas 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.

autobuild para Swift

Tipo de sistema compatívelNome do sistema
Sistema operacionalmacOS
Sistema de criaçãoXcode

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

Observações:

  • atualmente, a análise do CodeQL para o Swift está em versão beta. Durante a versão beta, a análise de código Swift e a documentação que o acompanha não serão tão abrangentes quanto para outras linguagens. O Swift 5.8 ainda não tem suporte.
  • A análise pode congelar ocasionalmente, fazendo com os trabalhos atingirem o tempo limite. Para limitar o número de minutos de Ações usados por trabalhos que estão paralisados ou com o tempo limite atingido, recomendamos definir um tempo limite de quatro vezes o tempo normal de build.

A verificação do código Swift usa executores do macOS por padrão. Como os executores de macOS hospedados no GitHub são mais caros do que os executores de Linux e Windows, recomendamos que você crie apenas o código que deseja analisar. Para obter mais informações sobre os preços de executores hospedados no GitHub, confira "Sobre a cobrança das GitHub Actions".

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 obter mais informações, confira "Sobe o Controlador de Executores de Ação".

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.

Adicionar passos de criação a uma linguagem compilada

Se autobuild falhar ou você quiser analisar um conjunto de arquivos de origem diferentes daqueles criados pelo processo autobuild, remova a etapa autobuild do fluxo de trabalho e adicione manualmente as etapas de compilação. Para projetos C/C++, C#, Go, Kotlin, Java e Swift, o CodeQL analisará qualquer código-fonte criado por suas etapas de compilação especificadas. Para obter informações sobre como editar o arquivo de fluxo de trabalho, confira "Como personalizar sua configuração avançada para a verificação de código".

Depois de remover a etapa autobuild, remova o comentário da etapa run e adicione comandos de build adequados ao seu repositório. A etapa run do fluxo de trabalho executa programas de linha de comando usando o shell do sistema operacional. Você pode modificar esses comandos e adicionar mais comandos para personalizar o processo de compilação.

- run: |
    make bootstrap
    make release

Para obter mais informações sobre a palavra-chave run, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Se o repositório contiver várias linguagens compiladas, você poderá especificar comandos de compilação específicos da linguagem. Por exemplo, se o repositório contiver C/C++, C# e Java e autobuild compilar corretamente C/C++ e C#, mas não compila Java, você poderá usar a configuração a seguir no seu fluxo de trabalho, após a etapa init. Isso especifica as etapas de compilação para Java enquanto ainda usa autobuild para C/C++ e 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 obter mais informações sobre o if condicional, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Para obter mais dicas e truques sobre por que autobuild não criar seu código, confira "O build automático falhou em uma linguagem compilada".

Se você adicionou etapas de criação manual para linguagens compiladas, mas o code scanning ainda não está funcionando no seu repositório, entre em contato com conosco por meio do Portal de suporte do GitHub.