Configurar a varredura do código

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

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

Este artigo é sobre a execução de Varredura de código no GitHub Enterprise Server.

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 em GitHub.com contém outros fluxos de trabalho de Varredura de código que você pode usar. Os exemplos específicos indicados neste artigo relacionam-se com o 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.
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.

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

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. O evento pull_request não será acionado se o pull request tiver sido aberto a partir de uma bifurcação privada.

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

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'

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

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: '40 7 * * 2'

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 terça-feira às 7h40 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. Você especifica o sistema operacional usando uma etiqueta apropriada como segundo elemento em uma matriz de dois elementos, depois de 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" e "Usar etiquetas com executores auto-hospedados".

Você deve garantir que o Git esteja na variável PATH nos seus executores auto-hospedados.

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

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 repositório privado.

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Forneça uma token para acessar 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.

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.

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.

- 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
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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 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: ./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 análises, adicionando um array de paths-ignore.

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

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