Note: The Executor do CodeQL is being deprecated. Please use the CodeQL CLI version 2.6.2 or greater instead. GitHub Enterprise Server 3.3 will be the final release series that supports the Executor do CodeQL. On GitHub Enterprise Cloud, the Executor do CodeQL will be supported until March 2022. For more information, see the CodeQL runner deprecation.
Observação: Varredura de código está em beta em GitHub Enterprise Server 2.22. Para a versão geralmente disponível do varredura de código, atualize para a versão mais recente de GitHub Enterprise Server.
Observação: O administrador do site deve habilitar Varredura de código para sua instância do GitHub Enterprise Server antes de usar este recurso. Para obter mais informações, consulte "Configurar o Varredura de código para seu aplicativo ".
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 Executor do CodeQL. Para obter mais informações, consulte "Executar CodeQL Varredura de código no seu sistema de CI".
De modo geral, você invoca o Executor do CodeQL da seguinte forma.
$ /path/to-runner/codeql-runner-OS
/path/to-runner/
depende do local onde você fez o download do Executor do CodeQL no seu sistema de CI. codeql-runner-OS
depende do sistema operacional que você usa. Existem três versões do Executor do CodeQL, codeql-runner-linux
, codeql-runner-macos
e codeql-runner-win
, para os sistemas Linux, macOS e Windows, respectivamente.
Para personalizar a maneira como o Executor do CodeQL 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.
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 fazer a varredura de um pull request, execute o comando analyze
e use o sinalizador --ref
para especificar o pull request. A referência é refs/pull/<PR-number>/head
ou refs/pull/<PR-number>/merge
, dependendo se você verificou o commit HEAD do branch do pull request ou um commit de merge com o branch de 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 apareçam como verificações de pull request, você deverá executar o comando upload
e usar o sinalizador --ref
para especificar o pull request 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 Executor do CodeQL 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 os idiomas 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. 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.
Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About Varredura de código."
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".
Os conjuntos de consulta a seguir foram criados em CodeQL Varredura de código e estão disponíveis para uso.
Suite de consulta | Descrição |
---|---|
security-extended | Consultas de menor gravidade e precisão que as consultas-padrão |
security-and-quality | Consultas 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 Executor do CodeQL usará as consultas adicionais especificadas com o sinalizador --queries
--queries
+
. 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 Executor do CodeQL 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 Executor do CodeQL, 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
$ /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 especificar opções de configuração para vários repositórios em um único lugar. Ao fazer referência a um arquivo de configuração localizado em um repositório externo, você pode usar a sintaxe OWNER/REPOSITORY/FILENAME@BRANCH. Por exemplo, octo-org/shared/codeql-config.yml@main.
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. Também configura CodeQL para fazer a varredura de arquivos no diretório src (relativo à raiz), exceto o diretório src/node_modules e os arquivos cujo nome termina com .test.js. Os arquivos em src/node_modules e arquivos com nomes terminados em .test.js são, portanto, excluídos da análise.
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 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. Você pode usar comandos de criação personalizados para ignorar arquivos de Go de extração que não são tocados pela compilação.
Para muitos sistemas de criação comuns, o Executor do CodeQL 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 Executor do CodeQL 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.
- Se você fez o upload de um pull request como, por exemplo,
--ref refs/pull/42/merge
ou--ref refs/pull/42/head
, os resultados aparecerão como alertas em uma verificação de pull request. Para obter mais informações, consulte "Alertas de varredura de código de triagem em pull requests". - Se você fez upload de um branch como, por exemplo
--ref refs/heads/my-branch
, os resultados aparecerão na aba Segurança do seu repositório. Para obter mais informações, consulte "Gerenciar alertas de varredura de código para seu repositório. "
Comando de referência de Executor do CodeQL
O Executor do CodeQL é compatível os seguintes comandos e sinalizadores.
init
Inicializa o Executor do CodeQL e cria um banco de dados de CodeQL para cada linguagem a ser analisada.
Sinalizador | Obrigatório | Valor de entrada |
---|---|---|
--repository | ✓ | Nome do repositório a ser inicializado. |
--github-url | ✓ | URL da instância do GitHub onde seu repositório está hospedado. |
--github-auth | ✓ | Um token de Aplicativos do GitHub ou token de acesso pessoal. |
--languages | Lista de linguagens para análise separada por vírgulas. Por padrão, o Executor do CodeQL detecta e analisa todas as linguagens compatíveis no repositório. | |
--queries | Lista separada por vírgulas de consultas adicionais a serem executadas, além do conjunto-padrão de consultas de segurança. | |
--config-file | Caminho para o arquivo de configuração personalizado. | |
--codeql-path | Caminho para uma cópia do CLI de CodeQL executável a ser usado. Por padrão, o Executor do CodeQL faz o download de uma cópia. | |
--temp-dir | Diretório onde os arquivos temporários são armazenados. O padrão é ./codeql-runner . | |
--tools-dir | Diretó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-path | O caminho para o checkout do seu repositório. O padrão é o diretório de trabalho atual. | |
--debug | Nenhum. Imprime mais resultados verbose. | |
-h , --help | Nenhum. 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
.
Sinalizador | Obrigatório | Valor de entrada |
---|---|---|
--language | A linguagem a ser criada. Por padrão, o Executor do CodeQL cria a linguagem compilada com mais arquivos. | |
--temp-dir | Diretório onde os arquivos temporários são armazenados. O padrão é ./codeql-runner . | |
--debug | Nenhum. Imprime mais resultados verbose. | |
-h , --help | Nenhum. 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 Enterprise Server.
Sinalizador | Obrigatório | Valor de entrada |
---|---|---|
--repository | ✓ | Nome do repositório a ser analisado. |
--commit | ✓ | SHA 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 . |
--ref | ✓ | Nome da referência para análise, por exemplo refs/heads/main ou refs/pull/42/merge . No Git ou no Jenkins, isso corresponde ao valor de git simbolic-ref HEAD . No Azure DevOps, isso corresponde a $(Build.SourceBranch) . |
--github-url | ✓ | URL da instância do GitHub onde seu repositório está hospedado. |
--github-auth | ✓ | Um token de Aplicativos do GitHub ou token de acesso pessoal. |
--checkout-path | O caminho para o checkout do seu repositório. O padrão é o diretório de trabalho atual. | |
--no-upload | Nenhum. Impede que o Executor do CodeQL faça o upload dos resultados para GitHub Enterprise Server. | |
--output-dir | Diretório onde os arquivos SARIF de saída são armazenados. O padrão está no diretório de arquivos temporários. | |
--ram | A quantidade de memória a ser usada ao executar consultas. O padrão é usar toda a memória disponível. | |
--no-add-snippets | Nenhum. Exclui snippets de código da saída de SARIF. | |
--threads | Número de threads a serem usados ao executar consultas. O padrão é usar todos os núcleos disponíveis. | |
--temp-dir | Diretório onde os arquivos temporários são armazenados. O padrão é ./codeql-runner . | |
--debug | Nenhum. Imprime mais resultados verbose. | |
-h , --help | Nenhum. Exibe ajuda para o comando. |
fazer upload
Faz o upload dos arquivos SARIF para GitHub Enterprise Server.
Observação: Se você analisar o código com o executor do CodeQL, o comando analyze
irá carregar os resultados SARIF, por padrão. Você pode usar o comando upload
para carregar os resultados SARIF que foram gerados por outras ferramentas.
Sinalizador | Obrigatório | Valor de entrada |
---|---|---|
--sarif-file | ✓ | O arquivo SARIF a ser subido ou um diretório que contém vários arquivos SARIF. |
--repository | ✓ | Nome do repositório que foi analisado. |
--commit | ✓ | SHA 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 . |
--ref | ✓ | Nome 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 simbolic-ref HEAD . No Azure DevOps, isso corresponde a $(Build.SourceBranch) . |
--github-url | ✓ | URL da instância do GitHub onde seu repositório está hospedado. |
--github-auth | ✓ | Um token de Aplicativos do GitHub ou token de acesso pessoal. |
--checkout-path | O caminho para o checkout do seu repositório. O padrão é o diretório de trabalho atual. | |
--debug | Nenhum. Imprime mais resultados verbose. | |
-h , --help | Nenhum. Exibe ajuda para o comando. |