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.

People with write permissions to a repository can configure Varredura de código for the repository.

Varredura de código está disponível como parte de Segurança Avançada GitHub, que é grátis durante a versão beta. Para obter mais informações, consulte "Sobre Segurança Avançada GitHub".

Nota: Varredura de código está atualmente em versão beta e sujeito a alterações.

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

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

Este artigo é sobre a execução de Varredura de código em GitHub AE usando ações.

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

De modo geral, você não precisa editar o fluxo de trabalho padrão para Varredura de código. No entanto, se necessário, você editar o fluxo de trabalho para personalizar algumas das configurações. Por exemplo, você pode editar os Fluxo de trabalho de análise do CodeQL de GitHub para especificar a frequência das digitalizações, as linguagens ou diretórios a serem digitalizados e o que CodeQL Varredura de código procura no seu código. Talvez você precise editar o Fluxo de trabalho de análise do CodeQL se você usar um conjunto específico de comandos para compilar seu código.

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. Os exemplos específicos fornecidos neste artigo estão relacionados ao arquivo de Fluxo de trabalho de análise do CodeQL.

Editing a code scanning workflow

O GitHub salva arquivos de fluxo de trabalho no diretório .github/workflows do seu repositório. Você pode encontrar um fluxo de trabalho que você adicionou procurando o nome do seu arquivo. 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 a edição de arquivos do fluxo de trabalho, consulte "Aprenda GitHub Actions".

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

Se você fizer uma varredura no push, os resultados aparecerão na aba Segurança do repositório. Para obter mais informações, consulte "Gerenciar alertas de varredura de código para seu repositório. "

Fazer a varredura de pull requests

O padrão Fluxo de trabalho de análise do CodeQL usa o evento pull_request para acionar uma verificação de código em pull requests direcionadas ao branch padrão. Se um pull request for de um fork privado, o evento pull_request só será acionado se você tiver selecionado a opção "Executar fluxos de trabalho a partir de pull requests" nas configurações do repositório. Para obter mais informações, consulte "Gerenciar configurações de GitHub Actions para um repositório".

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

Se você realizar uma varredura de pull requests, 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".

Evitar varreduras desnecessárias de pull requests

Você pode querer evitar que uma varredura de código seja acionada em pull requests específicos para o branch padrão, Independentemente de os arquivos terem sido alterados. Você pode configurar isso, especificando no:pull_request:paths-ignore ou on:pull_request:paths no fluxo de trabalho de Varredura de código. Por exemplo, se as únicas alterações em um pull request são para arquivos com extensões de arquivo .md ou .txt, você poderá usar o seguinte array paths-ignore.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

Observações

  • on:pull_request:paths-ignore e on:pull_request:paths definem condições que determinam se as ações no fluxo de trabalho serão executadas em um pull request. Eles não determinam quais arquivos serão analisados quando as ações são executadas. Quando uma pull request contém quaisquer arquivos não correspondidos por on:pull_request:paths-ignore ou on:pull_request:paths, o fluxo de trabalho executa as ações e faz a varredura de todos os arquivos alterados no pull request, incluindo aqueles que correspondidos por on:pull_request:paths-ignore ou on:pull_request:paths, a menos que os arquivos tenham sido excluídos. Para obter informações sobre como excluir arquivos da análise, consulte "Especificar diretórios a serem varridos".
  • Para arquivos do fluxo de trabalho de CodeQL Varredura de código, não use as palavras-chave paths-ignore ou paths com o evento on:push, pois é provável que isso gere análises ausentes. Para resultados precisos, CodeQL Varredura de código precisam conseguir comparar novas alterações com a análise do commit anterior.

Para mais informações sobre como usar on:pull_request:paths-ignore e on:pull_request:paths para determinar quando um fluxo de trabalho será executado para um 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 Fluxo de trabalho de análise do CodeQL para um repositório em particular que possui um branch-padrão denominado principal e um branch protegido denominado protegido.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

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 toda segunda-feira às 14h20 UTC

Especificar um sistema operacional

Se seu código exigir um sistema operacional específico para compilar, você poderá configurar o sistema operacional em seu Fluxo de trabalho de análise do CodeQL. Edite o valor de jobs.analyze.runs-on para especificar o sistema operacional para a máquina que executa suas ações de Varredura de código.

Se você optar por usar um executor auto-hospedado para varredura de código, você pode especificar um sistema operacional usando uma etiqueta apropriada como segundo elemento em um array de dois elementos, após auto-hospedado.

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

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 de fluxo de trabalho para o GitHub Actions."

Se você usa um executor auto-hospedado, você deve garantir que o Git esteja na variável de PATH.

Alterar as linguagens que são analisadas

O CodeQL Varredura de código detecta automaticamente código escrito nas linguagens compatíveis.

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

O arquivo padrão do Fluxo de trabalho de análise do CodeQL contém uma matriz de criação denominada linguagem que lista as linguagens no seu repositório que são analisadas. O CodeQL preenche automaticamente esta matriz quando você adiciona o Varredura de código a um repositório. Usar a matriz de linguagem otimiza CodeQL para executar cada análise em paralelo. Recomendamos que todos os fluxos de trabalho adotem esta configuração devido aos benefícios de desempenho de criações paralelas. Para obter mais informações sobre matrizes de criação, consulte "Gerenciar fluxos de trabalho complexos".

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.

Se o seu fluxo de trabalho usar a matriz de linguagem , o CodeQL será codificado para analisar apenas as linguagens da matriz. Para alterar as linguagens que você deseja analisar, edite o valor da variável da matriz. Você pode remover uma linguagem para evitar que ele seja analisado ou adicionar uma linguagem que não estava presente no repositório quando o Varredura de código estava configurado. Por exemplo, se o repositório inicialmente continha apenas JavaScript quando Varredura de código foi configurado e, posteriormente, você adicionou o código Python, você precisará adicionar o <code>python à matriz.

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript', 'python']

Se o seu fluxo de trabalho não contiver uma matriz denominada linguagem, o CodeQL será configurado para executar a análise sequencialmente. Se você não especificar as linguagens no fluxo de trabalho, o CodeQL irá detectar automaticamente e tentará analisar quaisquer linguagens compatíveis no repositório. Se você quiser escolher quais linguagens analisar sem usar uma matriz, você poderá usar o parâmetro linguagens na ação init.

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

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 with 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".

Para adicionar uma ou mais consultas, adicione uma entrada with: queries: na seção uses: github/codeql-action/init@v1 do fluxo de trabalho. Se as consultas estiverem em um repositório privado, use o parâmetro external-repository-token para especificar um token que tenha acesso ao check-out do repositório privado.

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Forneça um token de acesso para consultas armazenadas em repositórios privados.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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.

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.

Se você também usar um arquivo de configuração para configurações personalizadas, todas os consultas especificadas no seu fluxo de trabalho serão usados em vez daqueles especificados no arquivo de configuração. Se você quiser executar o conjunto combinado de consultas, prefixe 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".

No exemplo a seguir, o símbolo + garante que os consultas especificados sejam usados em conjunto com qualquer um especificado no arquivo de configuração referenciado.

- uses: github/codeql-action/init@v1
  with:
    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

Um arquivo de configuração personalizado é uma forma alternativa de especificar as consultas adicionais de a serem executadas. Você também pode usar o arquivo para desabilitar as consultas padrão e especificar quais diretórios digitalizar 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 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.

Se o arquivo de configuração estiver localizado em um repositório privado externo, use o parâmetro external-repository-token da ação init para especificar um token que tenha acesso ao repositório privado.

- uses: github/codeql-action/init@v1
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

As configurações no arquivo de configuração estã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: ./query-suites/my-security-queries.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 análises, adicionando um array de paths-ignore.

paths:
  - src
paths-ignore:
  - src/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".
  • Os caracteres de filtros padrão ?, +, [, ] e ! não são compatíveis e serão correspondidos literalmente.
  • ** 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 linguagens compiladas, se você deseja limitar Varredura de código a diretórios específicos no seu projeto, você deverá especificar os passos de compilação adequados 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 o fluxo de trabalho do 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

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 compatíveis, você pode usar a ação autobuild no Fluxo de trabalho de análise do CodeQL para criar o seu código. Isso evita que você tenha que especificar comandos de criação explícitos para C/C++, C#, e Java. 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.

Se o código de C/C++, C#, ou Java no seu repositório tiver um processo de criação não padrão, poderá ocorrer uma falha no autobuild. Você deverá remover a etapa autobuild do fluxo de trabalho e adicionar manualmente etapas de criação. Se você quiser especificar quais arquivos de Go no seu repositório devem ser extraídos, você deverá adicionar as etapas de criação. Para obter mais informações sobre como configurar CodeQL Varredura de código para linguagens compiladas, consulte "Configurar o fluxo de trabalho do CodeQL para linguagens compiladas".

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

Esse documento ajudou você?

Política de Privacidade

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.