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 do código

Você pode configurar como o GitHub faz a varredura do código no seu projeto com relação a vulnerabilidades e erros.

Pessoas com permissões de gravação para um repositório podem configurar Varredura de código para o repositório.

Neste artigo

Did this doc help you?

Nota: Varredura de código está atualmente em versão beta e sujeito a alterações. To request access to the beta, join the waitlist.

Sobre a configuração do Varredura de código

Você pode executar Varredura de código em GitHub, usando GitHub Actions ou a partir do seu sistema de integração contínua (CI), usando o CodeQL runner. Para obter mais informações sobre GitHub Actions, consulte "Sobre GitHub Actions." Para obter mais informações sobre o CodeQL runner, consulte "Executar Varredura de código no seu sistema de CI".

Este artigo está relacionado à execução de Varredura de código dentro de GitHub.

Antes de poder configurar o Varredura de código para um repositório, você deve habilitar o Varredura de código adicionando um fluxo de trabalho do GitHub Actions ao repositório. Para obter mais informações, consulte "Habilitando Varredura de código.

De modo geral, você não precisa editar o fluxo de trabalho padrão para Varredura de código. However, if required, you can edit the workflow to customize some of the settings. For example, you can edit GitHub's CodeQL Analysis workflow to specify the frequency of scans, the languages or directories to scan, and what CodeQL Varredura de código looks for in your code. You might also need to edit the workflow if you use a specific set of commands to compile your code or if there is more than one compiled language in your repository.

A análise de CodeQL é apenas um tipo de Varredura de código que você pode fazer em GitHub. GitHub Marketplace contém outros fluxos de trabalho de Varredura de código que você pode usar. Você pode encontrar uma seleção destes na página "Comece com Varredura de código", que você pode acessar na aba Segurança. Os exemplos específicos fornecidos neste artigo estão relacionados ao arquivo de CodeQL Analysis workflow.

Editing a code scanning workflow

O GitHub salva arquivos de fluxo de trabalho no diretório .github/workflows do seu repositório. You can find the workflow by searching for its file name. For example, the default workflow file for CodeQL code scanning is called codeql-analysis.yml.

  1. No seu repositório, pesquise o arquivo do fluxo de trabalho que você deseja editar.
  2. No canto superior direito da vista do arquivo, clique em para abrir o editor do fluxo de trabalho.
    Edite o botão do arquivo do fluxo de trabalho
  3. Depois de ter editado o arquivo, clique em Iniciar commit e preencha o formulário "Alterações do commit". Você pode escolher o "commit" diretamente no branch atual ou criar um novo branch e iniciar um pull request.
    Atualização do commit para o fluxo de trabalho do codeql.yml

Para obter mais informações sobre edição de arquivos de fluxo de trabalho, consulte "Configurar um fluxo de trabalho".

Configurar a frequência

Você pode fazer a varredura de código de forma pré-programada ou quando ocorrerem eventos específicos em um repositório.

A varredura do código a cada push para o repositório, e toda vez que um pull request é criado, isso impede que os desenvolvedores introduzam novas vulnerabilidades e erros no código. A varredura do código de forma pré-programada informa as últimas vulnerabilidades e erros de GitHub, que os pesquisadores de segurança e da comunidade, mesmo quando desenvolvedores não estão mantendo o repositório de forma ativa.

Fazer a varredura no push

Se você usar o fluxo de trabalho padrão, o Varredura de código fará a varredura do código no repositório uma vez por semana, além das varreduras acionadas pelos eventos. Para ajustar essa programação, edite o valor CRON no fluxo de trabalho. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Fazer a varredura de pull requests

Observação: As palavras-chave caminhos e paths-ignore usadas no contexto do arquivo de configuração de Varredura de código não devem ser confundidas com as mesmas palavras-chave quando usadas para on.<push|pull_request>.paths. Quando estão acostumados a modificar on.<push|pull_request> em um arquivo de fluxo de trabalho, eles determinam se as ações serão executadas quando alguém modificar o código nos diretórios especificados. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Para obter mais informações sobre o evento pull_request , consulte "Sintaxe de fluxo de trabalho para GitHub Actions".

Fazer a varredura de forma pré-programada

O fluxo de trabalho padrão do Varredura de código usa o evento on.push para acionar uma varredura de código em cada push para qualquer branch que contém o arquivo de fluxo de trabalho. Para ajustar essa programação, edite o valor CRON no fluxo de trabalho. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Observação: GitHub executa apenas trabalhos programados que estão em fluxos de trabalho no branch-padrão. Alterar a programação de um fluxo de trabalho em qualquer outro branch não terá efeito até que você mescle o branch com o branch-padrão.

Exemplo

O exemplo a seguir mostra um CodeQL Analysis workflow para um repositório em particular que possui um branch-padrão denominado principal e um branch protegido denominado protegido.

on:
  push:
  pull_request:
  schedule:
    - cron: '0 15 * * 0'

Este fluxo de trabalho faz a varredura:

  • Cada push para o branch-padrão e o branch protegido
  • Cada pull request para o branch-padrão
  • O branch-padrão às 15h. todo domingo

Especificar um sistema operacional

Se seu código exigir um sistema operacional específico para compilar, você poderá configurar o sistema operacional em seu CodeQL Analysis workflow. Edite o valor de jobs.<job_id>.runs-on para especificar o sistema operacional para a máquina que executa suas ações em Varredura de código.

O Varredura de código é compatível com as versões mais recentes do macOS, Ubuntu, e Windows. Portanto, os valores típicos para essa configuração são ubuntu-latest, windows-latest e macos-latest. Para obter mais informações, consulte "Sintaxe do fluxo de trabalho para o GitHub Actions".

Sobrescrever a detecção automática de linguagem

If the C/C++, C#, or Java code in your repository has a non-standard build process or if it's written in more than one compiled language, autobuild may fail. You will need to remove the autobuild step from the workflow, and manually add build steps. For more information about how to configure Varredura de código for compiled languages, see "Configuring Varredura de código for compiled languages."

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

Se o seu repositório contiver código em várias linguagens, você poderá especificar as linguagens que você 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 linguagem, adicione with:languages: à ação init no seu fluxo de trabalho. As palavras-chave para as linguagens compatíveis são cpp, csharp, go, java, javascript e python.

Por exemplo, a configuração a seguir limita Varredura de código para C/C++, C#, e Python.

- uses: github/codeql-action/init@v1
  with:
    languages: cpp, csharp, python

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. Para obter mais informações, consulte "Sobre Varredura de código".

CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries. 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. For more information, see "About CodeQL queries."

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. For more information about query suite definitions, see "Creating CodeQL query suites."

We don't recommend referencing query suites directly from the github/codeql repository, like github/codeql/cpp/ql/src@main. Such queries may not be compiled with the same version of CodeQL as used for your other queries, which could lead to errors during analysis.

Para adicionar uma ou mais consultas, adicione uma entrada with: queries: na seção uses: github/codeql-action/init@v1 do fluxo de trabalho.

- uses: github/codeql-action/init@v1
  with:
    - queries: COMMA-SEPARATED LIST OF PATHS

Você também pode executar suítes de consultas adicionais especificando-os em um arquivo de configuração. Os suítes de consulta são coleções de consultas, geralmente agrupados por finalidade ou linguagem.

The following query suites are built into CodeQL Varredura de código and are available for use.

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

When you specify a query suite, the CodeQL analysis engine will run the queries contained within the suite for you, in addition to the default set of queries.

Você pode executar consultas adicionais especificando-as em um arquivo de configuração. Se você desejar executar o conjunto combinado de consultas adicionais especificadas aqui e no arquivo de configuração, determine previamente o valor de consultas no fluxo de trabalho com o símbolo +. Para obter exemplos de arquivos de configuração, consulte "Exemplo de arquivos de configuração".

Para incluir um ou mais suites de consulta, adicione uma seção consultas ao seu arquivo de configuração.

queries:
  - name: DESCRIPTION OF YOUR CHOICE
    uses: PATH

Usar uma ferramenta de varredura de código de terceiros

Como alternativa à especificação de quais consultas executar no arquivo de fluxo de trabalho, você poderá fazer isso em um arquivo de configuração separado. Você também pode usar um arquivo de configuração para desativar as consultas-padrão e especificar quais diretórios escanear durante a análise.

No arquivo de workflow use o parâmetro config-file da ação init para especificar 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.

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml

O arquivo de configuração pode ser localizado no repositório local ou em um repositório remoto público. Para repositórios remotos, você pode usar a sintaxe owner/repository/file.yml@branch. As configurações no arquivo são escritas no formato YAML.

Especificar consultas adicionais

Você especifica consultas adicionais em um array de consultas. Cada elemento do array contém um parâmetro de uso com um valor que identifica um único arquivo de consulta, um diretório que contém arquivos de consulta ou um arquivo de definição do conjunto de consulta.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

Opcionalmente, você pode dar um nome a cada elemento do array, conforme mostrado nos exemplos de arquivos de configuração abaixo.

Para obter mais informações sobre consultas adicionais, consulte "Executar consultas adicionais acima.

Desativar as consultas-padrão

Se você desejar apenas executar consultas personalizadas, você poderá desabilitar as consultas de segurança padrão adicionando disable-default-queries: true ao seu arquivo de configuração.

Especificar diretórios para serem varridos

Para as linguagens interpretadas com as quais CodeQL é compatível (Python e JavaScript/TypeScript), você pode restringir Varredura de código para arquivos em diretórios específicos adicionando um array de caminhos para o arquivo de configuração. Você pode excluir os arquivos em diretórios específicos das varreduras, adicionando um array de paths-ignore.

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

Observação:

  • As palavras-chave caminhos e paths-ignore, usados no contexto do arquivo de configuração do Varredura de código, não deve ser confundido com as mesmas palavras-chave usadas para on.<push|pull_request>.paths em um fluxo de trabalho. Quando estão acostumados a modificar on.<push|pull_request> em um fluxo de trabalho, eles determinam se as ações serão executadas quando alguém modifica o código nos diretórios especificados. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".
  • ** Note: ** characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix ** and other characters. Por exemplo, foo/**, **/foo e foo/**/bar são todos de sintaxe permitida, mas **foo não é. No entanto, você pode usar estrelas únicas junto com outros caracteres, conforme mostrado no exemplo. Você precisará colocar entre aspas qualquer coisa que contenha um caractere *.

Para C/C++, C#, e Java, se você desejar limitar Varredura de código a diretórios específicos no seu projeto, você deverá especificar etapas de criação apropriadas no fluxo de trabalho. Os comandos que você precisa usar para excluir um diretório da criação dependerão do seu sistema de criação. Para obter mais informações, consulte "Configurar a ação de CodeQL para linguagens compiladas".

Você pode rapidamente analisar pequenas partes de um monorepo ao modificar o código em diretórios específicos. Você deverá excluir diretórios nas suas etapas de criação e usar as palavras-chave paths-ignore e caminhos para on.<push|pull_request> no seu arquivo de fluxo de trabalho.

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

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), and to exclude the node_modules directory (also relative to the root), as well as any file whose name ends in .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

For compiled languages like C/C++, C#, and Java, the autobuild step in the default workflow attempts to build code before the action performs CodeQL analysis. Ao contrário das outras linguagens compiladas, CodeQL analisa Go sem criar o código.

O processo autobuild sempre tenta criar uma linguagem compilada para um repositório. The language automatically selected for analysis is the language with most files.

If the C/C++, C#, or Java code in your repository has a non-standard build process or if it's written in more than one compiled language, autobuild may fail. You will need to remove the autobuild step from the workflow, and manually add build steps. Para obter mais informações sobre como configurar CodeQL Varredura de código para linguagens compiladas, consulte "Configurar a ação do CodeQL para linguagens compiladas".

Acessar repositórios privados

Se o seu fluxo de trabalho para Varredura de código acessar repositórios privados no GitHub, você deverá configurar o Git para efetuar a autenticação com um token de acesso pessoal. Defina o segredo no ambiente do executor usando jobs.<job_id>.steps.env no seu fluxo de trabalho antes de qualquer ação do CodeQL. Para mais informações consulte "Criar um token de acesso pessoal para a linha de comando" e "Criar e armazenar segredos criptografados".

Por exemplo, a configuração a seguir faz com que o Git substitua todas as URLs para os repositórios github/foo, github/bar e github/baz em GitHub.com por URLs que incluem o token de acesso pessoal que você armazena na variável de ambiente ACCESS_TOKEN.

steps:
- name: Configure access to private repository on GitHub.com
  env:
    TOKEN: ${{ secrets.ACCESS_TOKEN }}
  run: |
    git config --global url."https://${TOKEN}@github.com/github/foo".insteadOf "https://github.com/github/foo"
    git config --global url."https://${TOKEN}@github.com/github/bar".insteadOf "https://github.com/github/bar"
    git config --global url."https://${TOKEN}@github.com/github/baz".insteadOf "https://github.com/github/baz"

Varredura de código usa GitHub Actions.

Você pode exibir análise de código de uma ferramenta de terceiros em GitHub, adicionando a ação de upload-sarif ao seu fluxo de trabalho. Você pode fazer o upload de dados de análise de código com a ação upload-sarif. Para obter mais informações, consulte "Fazer o upload de um arquivo SARIF para o GitHub".

Did this doc help you?