Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Configurar a varredura de código do CodeQL no seu sistema de de CI

Você pode configurar como o CodeQL runner faz a varredura do código no seu projeto e faz o upload dos resultados para o GitHub.

Varredura de código está disponível em repositórios públicos e em repositórios públicos e privados pertencentes a organizações com uma licença para Segurança Avançada. Para obter mais informações, consulte "produtos de GitHub

Neste artigo

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Ou, learn how to contribute.

Observação: Os CodeQL runner está atualmente em fase beta e sujeito a alterações.

Sobre a configuração de CodeQL Varredura de código no seu sistema de CI

Para integrar Varredura de código ao seu sistema de CI, você pode usar o CodeQL runner. Para obter mais informações, consulte "Executar CodeQL Varredura de código no seu sistema de CI".

De modo geral, você invoca o CodeQL runner da seguinte forma.

$ /path/to-runner/codeql-runner-OS <COMMAND> <FLAGS>

/path/to-runner/ depende do local onde você fez o download do CodeQL runner no seu sistema de CI. codeql-runner-OS depende do sistema operacional que você usa. Existem três versões do CodeQL runner, codeql-runner-linux, codeql-runner-macos e codeql-runner-win, para os sistemas Linux, macOS e Windows, respectivamente.

Para personalizar a maneira como o CodeQL runner faz a varredura do seu código, você pode usar sinalizadores, como --languages e --queries, ou você pode especificar configurações personalizadas em um arquivo de configuração separado.

Sobrescrever a detecção automática de linguagem

O CodeQL runner detecta e faz a varredura automática do código escrito nas linguagens compatíveis.

  • C/C++
  • C#
  • Go
  • Java
  • JavaScript/TypeScript
  • Python

Se o seu repositório contiver código em mais de uma das linguagens compatíveis, você poderá escolher quais linguagens deseja analisar. Há vários motivos para impedir que uma linguagem seja analisada. Por exemplo, o projeto pode ter dependências em uma linguagem diferente do texto principal do seu código, e você pode preferir não ver os alertas para essas dependências.

Para substituir a detecção automática de idioma, execute o comando init com o sinalizador --languages, seguido de uma lista de palavras-chave de linguagem separada por vírgulas. As palavras-chave para as linguagens compatíveis são cpp, csharp, go, java, javascript e python.

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

Executar consultas adicionais

Ao usar CodeQL para fazer a varredura do código, o mecanismo de análise de CodeQL gera um banco de dados do código e executa consultas no mesmo. Para obter mais informações, consulte "Sobre Varredura de código".

A análise de CodeQL usa um conjunto-padrão de consultas, mas você pode especificar outras consultas a serem executadas, além das consultas-padrão. As consultas que você desejar executar devem pertencer a um pacote do QL e podem estar no seu próprio repositório ou em qualquer repositório público. Para obter mais informações, consulte "Sobre os pacotes de QL.

As consultas só devem depender das bibliotecas-padrão (ou seja, as bibliotecas referenciadas por uma declaração de LINGUAGEM de importação na sua consulta), ou bibliotecas no mesmo pacote do QL da consulta. As bibliotecas-padrão estão localizadas no repositório github/codeql. Para obter mais informações, consulte "Sobre consultas do CodeQL".

Você pode especificar um único arquivo .ql, um diretório que contém múltiplos arquivos .ql, um arquivo de definição de suite de consultas .qls ou qualquer outra combinação. Para obter mais informações sobre definições do conjunto de consultas, consulte "Criar as conjuntos de consulta do CodeQL".

Não recomendamos fazer referências a conjuntos de consulta diretamente a partir do repositório github/codeql, como github/codeql/cpp/ql/src@main. Tais consultas não podem ser compiladas com a mesma versão do CodeQL que é usada para outras consultas, que poderia gerar erros durante a análise.

Os conjuntos de consulta a seguir foram criados em CodeQL Varredura de código e estão disponíveis para uso.

Suite de consultaDescrição
security-extendedConsultas de menor gravidade e precisão que as consultas-padrão
security-and-qualityConsultas de security-extended, mais consultas de manutenção e confiabilidade

Ao especificar um conjunto de pesquisas, o mecanismo de análise de CodeQL executará as consultas contidas no conjunto para você além do conjunto-padrão de consultas.

Para adicionar uma ou mais consultas, passe uma lista de caminhos separados por vírgulas para o sinalizador --queries do comando init. Você também pode especificar consultas adicionais em um arquivo de configuração.

Se você também estiver usando um arquivo de configuração para configurações personalizadas, e você também estiver especificando consultas adicionais com o sinalizador --queries, o CodeQL runner usará as consultas adicionais especificadas com o sinalizador --queries em vez de qualquer um no arquivo de configuração. Se você desejar executar o conjunto combinado de consultas adicionais especificadas com o sinalizador e no arquivo de configuração, determine previamente o valor passado para --queries com o símbolo +. Para obter exemplos de arquivos de configuração, consulte "Exemplo de arquivos de configuração".

No exemplo a seguir,. o símbolo + garante que o CodeQL runner usará as consultas adicionais junto com quaisquer consultas especificadas no arquivo de configuração referenciado.

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml 
    --queries +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

Usar uma ferramenta de varredura de código de terceiros

Em vez de passar informações adicionais para os comandos de CodeQL runner, você pode especificar configurações personalizadas em um arquivo de configuração separado.

O arquivo de configuração é um arquivo YAML. Ele usa uma sintaxe semelhante à sintaxe do fluxo de trabalho do GitHub Actions, conforme ilustrado nos exemplos abaixo. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Use o sinalizador --config-file do comando init para especificar o arquivo de configuração. O valor de --config-file é o caminho para o arquivo de configuração que você deseja usar. Este exemplo carrega o arquivo de configuração .github/codeql/codeql-config.yml.

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml

Exemplo de arquivo de configuração

Este arquivo de configuração adiciona o suite de consulta de security-and-quality para a lista de consultas executadas por CodeQL ao fazer a varredura do seu código. Para obter mais informações sobre o suite de consultas disponível para uso, consulte "Executar consultas adicionais".

name: "My CodeQL config"

queries:
  - uses: security-and-quality

O seguinte arquivo de configuração desabilita as consultas-padrão e especifica um conjunto de consultas personalizadas para serem executadas. Ele também configura o CodeQL para fazer a varredura de arquivos no diretório src (relativas à raiz) e para excluir o diretório node_modules (também relativo à raiz), bem como qualquer arquivo cujo nome termina em .test.js.

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths-ignore: 
  - node_modules
  - '**/*.test.js'
paths:
  - src 

Configurar o Varredura de código para linguagens compiladas

Para as linguagens compiladas C/C++, C#, e Java, o CodeQL constrói o código antes de analisá-lo. CodeQL também executa uma criação para projetos Go para configurar o projeto. Entretanto, diferente das outras linguagens compiladas, todos os Go no repositório são extraídos, não apenas aqueles construídos. Comandos de compilação personalizados não são compatíveis com o Go.

Para muitos sistemas de criação comuns, o CodeQL runner pode construir o código automaticamente. Para tentar construir o código automaticamente, execute autobuild entre init e analise as etapas. Observe que, se seu repositório precisar de uma versão específica de uma ferramenta de criação, primeiro você precisará instalar a ferramenta de criação manualmente.

O processo autobuild sempre tenta criar uma linguagem compilada para um repositório. A linguagem selecionada automaticamente para análise é a linguagem com mais arquivos. Se você quiser escolher um idioma explicitamente, use o sinalizador --language do comando autobuild.

$ /path/to-runner/codeql-runner-linux autobuild --language csharp

Se o comando autobuild não puder criar o seu código, você poderá executar as etapas de compilação, entre as etapas de init e de análise. Para obter mais informações, consulte "Executar CodeQL Varredura de código no seu sistema de CI".

Varredura de código usa GitHub Actions.

Por padrão, o CodeQL runner faz o upload dos resultados a partir de Varredura de código quando você executa o comando de análise. Você também pode carregar arquivos do SARIF separadamente, usando o comando upload.

Depois de enviar os dados, o GitHub exibirá os alertas no seu repositório. Para obter mais informações, consulte "Gerenciar alertas de Varredura de código para o seu repositório".

Comando de referência de CodeQL runner

O CodeQL runner é compatível os seguintes comandos e sinalizadores.

init

Inicializa o CodeQL runner e cria um banco de dados de CodeQL para cada linguagem a ser analisada.

SinalizadorObrigatórioValor de entrada
--repositoryNome do repositório a ser inicializado.
--github-urlURL da instância do GitHub onde seu repositório está hospedado.
--github-authUm token de Aplicativos do GitHub ou token de acesso pessoal.
--languagesLista de linguagens para análise separada por vírgulas. Por padrão, o CodeQL runner detecta e analisa todas as linguagens compatíveis no repositório.
--queriesLista separada por vírgulas de consultas adicionais a serem executadas, além do conjunto-padrão de consultas de segurança.
--config-fileCaminho para o arquivo de configuração personalizado.
--codeql-pathCaminho para uma cópia do CLI de CodeQL executável a ser usado. Por padrão, o CodeQL runner faz o download de uma cópia.
--temp-dirDiretório onde os arquivos temporários são armazenados. O padrão é ./codeql-runner.
--tools-dirDiretório onde as ferramentas de CodeQL e outros arquivos são armazenados entre as execuções. O padrão é um subdiretório do diretório home.
--checkout-pathO caminho para o checkout do seu repositório. O padrão é o diretório de trabalho atual.
--debugNenhum. Imprime mais resultados verbose.
-h, --helpNenhum. Exibe ajuda para o comando.

autobuild

Tenta construir o código para as linguagens compiladas C/C++, C# e Java. Para essas linguagens, CodeQL cria o código antes de analisá-lo. Executar autobuild entre as etapas de init e analise.

SinalizadorObrigatórioValor de entrada
--languageA linguagem a ser criada. Por padrão, o CodeQL runner cria a linguagem compilada com mais arquivos.
--temp-dirDiretório onde os arquivos temporários são armazenados. O padrão é ./codeql-runner.
--debugNenhum. Imprime mais resultados verbose.
-h, --helpNenhum. Exibe ajuda para o comando.

analyze

Analisa o código nos bancos de dados do CodeQL e faz o upload dos resultados para o GitHub.

SinalizadorObrigatórioValor de entrada
--repositoryNome do repositório a ser analisado.
--commitSHA do commit a ser analisado. No Git e no Azure DevOps, isso corresponde ao valor de git rev-parse HEAD. No Jenkins, isso corresponde a $GIT_COMMIT.
--refNome da referência para análise, por exemplo refs/heads/main. No Git e no Jenkins, isso corresponde ao valor de git simbolic-ref HEAD. No Azure DevOps, isso corresponde a $(Build.SourceBranch).
--github-urlURL da instância do GitHub onde seu repositório está hospedado.
--github-authUm token de Aplicativos do GitHub ou token de acesso pessoal.
--checkout-pathO caminho para o checkout do seu repositório. O padrão é o diretório de trabalho atual.
--no-uploadNenhum. Impede que o CodeQL runner faça o upload dos resultados para GitHub.
--output-dirDiretório onde os arquivos SARIF de saída são armazenados. O padrão está no diretório de arquivos temporários.
--temp-dirDiretório onde os arquivos temporários são armazenados. O padrão é ./codeql-runner.
--debugNenhum. Imprime mais resultados verbose.
-h, --helpNenhum. Exibe ajuda para o comando.

fazer upload

Faz o upload dos arquivos SARIF para GitHub.

SinalizadorObrigatórioValor de entrada
--sarif-fileO arquivo SARIF a ser subido ou um diretório que contém vários arquivos SARIF.
--repositoryNome do repositório que foi analisado.
--commitSHA do commit que foi analisado. No Git e no Azure DevOps, isso corresponde ao valor de git rev-parse HEAD. No Jenkins, isso corresponde a $GIT_COMMIT.
--refNome da referência que foi analisada, por exemplo refs/heads/main. No Git e no Jenkins, isso corresponde ao valor de git simbolic-ref HEAD. No Azure DevOps, isso corresponde a $(Build.SourceBranch).
--github-urlURL da instância do GitHub onde seu repositório está hospedado.
--github-authUm token de Aplicativos do GitHub ou token de acesso pessoal.
--checkout-pathO caminho para o checkout do seu repositório. O padrão é o diretório de trabalho atual.
--debugNenhum. Imprime mais resultados verbose.
-h, --helpNenhum. Exibe ajuda para o comando.

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Ou, learn how to contribute.