Skip to main content

Esta versão do GitHub Enterprise será descontinuada em 2022-10-12. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Configurar o executor do CodeQL no seu sistema 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.

Code scanning is available for organization-owned repositories in GitHub Enterprise Server. This feature requires a license for GitHub Advanced Security. Para obter mais informações, confira "Sobre o GitHub Advanced Security".

Observação: o CodeQL runner está sendo preterido. No GitHub Enterprise Server 3.0 e superior, você pode instalar a CodeQL CLI versão 2.6.3 para substituir o CodeQL runner.

Para obter mais informações, confira a reprovação do executor do CodeQL. Para obter informações sobre como migrar para a CodeQL CLI, confira "Como migrar do executor do CodeQL para a CLI do CodeQL".

Observação: o administrador do site precisa habilitar a code scanning para o your GitHub Enterprise Server instance para que você possa usar esse recurso. Para obter mais informações, confira "Como configurar a code scanning para seu dispositivo".1

Sobre a configuração de CodeQL code scanning no seu sistema de CI

Para integrar code scanning ao seu sistema de CI, você pode usar o CodeQL runner. Para obter mais informações, confira "Como executar o CodeQL runner no seu sistema de CI".

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

$ /path/to-runner/codeql-runner-OS  

/path/to-runner/ depende do local em que você baixou o CodeQL runner no seu sistema de CI. codeql-runner-OS depende do sistema operacional usado. Há 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 verifica o código, use sinalizadores, como --languages e --queries, ou especifique configurações personalizadas em um arquivo de configuração separado.

Fazer a varredura de pull requests

A varredura de código sempre que uma pull request é criada impede que os desenvolvedores introduzam novas vulnerabilidades e erros no código.

Para verificar uma solicitação de pull, execute o comando analyze e use o sinalizador --ref para especificar a solicitação de pull. A referência é refs/pull/<PR-number>/head ou refs/pull/<PR-number>/merge, dependendo se você fez check-out do commit HEAD do branch de solicitação de pull ou de um commit de mesclagem com o branch base.

$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge

Observação: se você analisar o código com uma ferramenta de terceiros e desejar que os resultados seja exibidos como verificações de solicitação de pull, execute o comando upload e use o sinalizador --ref para especificar a solicitação de pull em vez do branch. A referência é refs/pull/<PR-number>/head ou refs/pull/<PR-number>/merge.

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 repositório contiver código em mais de uma das linguagens com suporte, você poderá escolher quais linguagens deseja analisar. Há vários motivos pelos quais você talvez queira impedir que uma linguagem seja analisada. Por exemplo, o projeto pode ter dependências em uma linguagem diferente do corpo principal do seu código e você pode preferir não ver alertas para essas dependências.

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

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

Executar consultas adicionais

When you use CodeQL to scan code, the CodeQL analysis engine generates a database from the code and runs queries on it. CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries.

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About code scanning with CodeQL."

You can specify a single .ql file, a directory containing multiple .ql files, a .qls query suite definition file, or any combination. For more information about query suite definitions, see "Creating CodeQL query suites."

Os conjuntos de consulta a seguir foram criados em CodeQL code scanning e estão disponíveis para uso.

Conjunto de consultasDescrição
security-extendedConsultas de severidade e precisão menores do que as consultas padrão
security-and-qualityConsultas de security-extended, além de consultas de capacidade de manutenção e confiabilidade

Quando você especificar um pacote de consultas, o mecanismo de análise do CodeQL executará o conjunto padrão de consultas e todas as consultas extras definidas no pacote de consultas adicionais.

Para adicionar uma ou mais consultas, transmita uma lista separada por vírgula de caminhos 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 as configurações personalizadas e 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 desejar executar o conjunto combinado de consultas adicionais especificadas com o sinalizador e no arquivo de configuração, adicione o símbolo + como prefixo ao valor transmitido para --queries. Para obter mais informações, confira "Como usar um arquivo de configuração personalizado".

No exemplo a seguir,. o símbolo + garante que o CodeQL runner usará as consultas adicionais com todas as 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

Usando um arquivo de configuração personalizado

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, confira "Sintaxe de fluxo de trabalho do 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

O arquivo de configuração pode ser localizado no repositório que você está analisando ou em um repositório externo. O uso de um repositório externo permite que você especifique opções de configuração para vários repositórios em um único local. Ao fazer referência a um arquivo de configuração localizado em um repositório externo, você poderá usar a sintaxe OWNER/REPOSITORY/FILENAME@BRANCH . Por exemplo, octo-org/shared/codeql-config.yml@main.

Exemplo de arquivos de configuração

This configuration file adds the security-and-quality query suite to the list of queries run by CodeQL when scanning your code. For more information about the query suites available for use, see "Running additional queries."

name: "My CodeQL config"

queries:
  - uses: security-and-quality

The following configuration file disables the default queries and specifies a set of custom queries to run instead. It also configures CodeQL to scan files in the src directory (relative to the root), except for the src/node_modules directory, and except for files whose name ends in .test.js. Files in src/node_modules and files with names ending .test.js are therefore excluded from analysis.

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:
  - src 
paths-ignore: 
  - src/node_modules
  - '**/*.test.js'

Configurar o code scanning 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. No entanto, em contraste com as outras linguagens compiladas, todos os arquivos Go no repositório são extraídos, não apenas aqueles que são compilados. Você pode usar comandos de compilação personalizados para pular a extração de arquivos Go que não são tocados pela compilação.

Para muitos sistemas de criação comuns, o CodeQL runner pode construir o código automaticamente. Para tentar compilar o código automaticamente, execute autobuild entre as etapas init e analyze. 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 só tentará compilar uma linguagem compilada para um repositório. A linguagem selecionada automaticamente para análise é a linguagem com mais arquivos. Caso deseje escolher uma linguagem explicitamente, use o sinalizador --language do comando autobuild.

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

Se o comando autobuild não puder compilar o código, execute as etapas de build por conta própria, entre as etapas init e analyze. Para obter mais informações, confira "Como executar o CodeQL runner no seu sistema de CI".

Como carregar dados da code scanning no GitHub

Por padrão, o CodeQL runner carrega os resultados da code scanning quando você executa o comando analyze. Você também pode carregar arquivos SARIF separadamente usando o comando upload.

Depois de enviar os dados, o GitHub exibirá os alertas no 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-auth-stdinLeia o token de GitHub Apps ou token de acesso pessoal da entrada padrão.
--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. Isso substitui a configuração queries no arquivo de configuração personalizado.
--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.
--trace-process-nameAvançado, apenas para Windows. Nome do processo em que um rastreador do Windows deste processo é injetado.
--trace-process-levelAvançado, apenas para Windows. Número de níveis acima do processo principal em que um rastreador do Windows deste processo é injetado.
-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. Execute autobuild entre as etapas init e analyze.

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 carrega os resultados no GitHub Enterprise Server.

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 a ser analisada, por exemplo, refs/heads/main ou refs/pull/42/merge. No Git ou no Jenkins, isso corresponde ao valor de git symbolic-ref HEAD. No Azure DevOps, isso corresponde a $(Build.SourceBranch).
--github-urlURL da instância do GitHub onde seu repositório está hospedado.
--github-auth-stdinLeia o token de GitHub Apps ou token de acesso pessoal da entrada padrão.
--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 carregue os resultados no GitHub Enterprise Server.
--output-dirDiretório onde os arquivos SARIF de saída são armazenados. O padrão está no diretório de arquivos temporários.
--ramA quantidade de memória a ser usada ao executar consultas. O padrão é usar toda a memória disponível.
--no-add-snippetsNenhum. Exclui snippets de código da saída de SARIF.
--categoryA categoria a incluir no arquivo de resultados SARIF para esta análise. Uma categoria pode ser usada para distinguir várias análises para a mesma ferramenta e commit, mas executado em diferentes linguagens ou diferentes partes do código. Esse valor será exibido como a propriedade <run>.automationDetails.id no SARIF v2.1.0.
--threadsNúmero de threads a serem usados ao executar consultas. O padrão é usar todos os núcleos disponíveis.
--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.

upload

Carrega arquivos SARIF no GitHub Enterprise Server.

Observação: se você analisar o código com o executor do CodeQL, o comando analyze carregará os resultados SARIF por padrão. Use o comando upload para carregar os resultados SARIF que foram gerados por outras ferramentas.

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 ou refs/pull/42/merge. No Git ou no Jenkins, isso corresponde ao valor de git symbolic-ref HEAD. No Azure DevOps, isso corresponde a $(Build.SourceBranch).
--github-urlURL da instância do GitHub onde seu repositório está hospedado.
--github-auth-stdinLeia o token de GitHub Apps ou token de acesso pessoal da entrada padrão.
--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.