Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Como personalizar a verificação de código

In this article

Você pode personalizar como o GitHub faz a verificação de vulnerabilidades e erros no código de seu projeto.

Who can use this feature

People with write permissions to a repository can customize code scanning for the repository.

Code scanning está disponível para todos os repositórios públicos no GitHub.com. Code scanning também está disponível em repositórios privados pertencentes às organizações que usam o GitHub Enterprise Cloud e têm uma licença do GitHub Advanced Security. Para obter mais informações, confira "Sobre o GitHub Advanced Security".

Sobre a configuração do code scanning

Você pode executar code scanning em GitHub, usando GitHub Actions ou a partir do seu sistema de integração contínua (CI).

Para obter mais informações, confira "Sobre o GitHub Actions" ou "Sobre a code scanning do CodeQL no seu sistema de CI". Tanto as configurações padrão quanto as avançadas da code scanning são executadas em GitHub Actions.

A configuração padrão detecta automaticamente a melhor configuração de code scanning para seu repositório, enquanto você pode usar a configuração avançada para personalizar um fluxo de trabalho da code scanning. Para obter mais informações, confira "Como configurar code scanning para um repositório". Este artigo trata de , definindo sua configuração avançada para code scanning.

Com a configuração avançada, você pode editar fluxos de trabalho como o CodeQL analysis workflow do GitHub para especificar a frequência das verificações, as linguagens ou os diretórios a serem verificados e o que a code scanning busca em seu código.

Talvez seja necessário editar o fluxo de trabalho se você usar um conjunto específico de comandos para compilar o código.

A análise de CodeQL é apenas um tipo de code scanning que você pode fazer em GitHub.

GitHub Marketplace contém outros fluxos de trabalho de code scanning que você pode usar. Encontre uma seleção deles na página "Introdução à code scanning", que você pode acessar na guia Segurança. Os exemplos específicos fornecidos neste artigo estão relacionados ao arquivo sobre o CodeQL analysis workflow. Edição de um fluxo de trabalho de code scanning

O GitHub salva os arquivos de fluxo de trabalho no diretório .github/workflows do seu repositório.

Você pode encontrar um fluxo de trabalho que adicionou ao pesquisar seu nome de arquivo. Por exemplo, por padrão, o arquivo de fluxo de trabalho da code scanning do CodeQL é chamado codeql-analysis.yml. No seu repositório, pesquise o arquivo do fluxo de trabalho que você deseja editar.

  1. No canto superior direito da exibição de arquivo, para abrir o editor de fluxo de trabalho, clique em .
  2. Botão Editar arquivo de fluxo de trabalho Depois de editar o arquivo, clique em Iniciar confirmação e preencha o formulário "Confirmar alterações".
  3. Você pode optar por confirmar diretamente a ramificação atual ou criar uma nova ramificação e iniciar uma solicitação de pull. Commit da atualização no fluxo de trabalho de codeql.yml Para obter mais informações sobre como editar arquivos de fluxo de trabalho, confira "Saiba mais sobre o GitHub Actions".

Configurar a frequência

Configure o CodeQL analysis workflow para examinar o código conforme um agendamento ou quando eventos específicos ocorrerem 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

Por padrão, o CodeQL analysis workflow usa o evento on.push para disparar uma verificação de código em cada push para o branch padrão do repositório e todos os branches protegidos.

Para code scanning ser acionado em um branch especificado, o fluxo de trabalho deverá existir nesse branch. Para obter mais informações, confira "Sintaxe de fluxo de trabalho do GitHub Actions". Se você fizer a verificação durante o push, os resultados serão exibidos na guia Segurança do repositório.

Para obter mais informações, confira "Como gerenciar alertas de verificação de código do seu repositório". Além disso, quando uma verificação de on:push retorna resultados que podem ser mapeados para uma solicitação de pull aberta, esses alertas aparecem automaticamente na solicitação de pull no mesmo local que os outros alertas da solicitação de pull.

Os alertas são identificados por meio da comparação da análise existente do início da ramificação com a análise da ramificação de destino. Para obter mais informações sobre os alertas da code scanning em solicitações de pull, confira "Como fazer a triagem de alertas da code scanning em solicitações de pull". Fazer a varredura de pull requests

O CodeQL analysis workflow padrão usa o evento pull_request para disparar uma verificação de código nas solicitações de pull direcionadas ao branch padrão.

Se uma solicitação de pull for proveniente de um fork privado, o evento pull_request só será disparado se você tiver selecionado a opção "Executar fluxos de trabalho por meio de solicitações de pull" nas configurações do repositório. Para obter mais informações, confira "Como gerenciar as configurações do GitHub Actions de um repositório". Para obter mais informações sobre o evento pull_request, confira "Eventos que disparam fluxos de trabalho".

Se você examinar as solicitações de pull, os resultados serão exibidos como alertas em uma verificação de solicitação de pull.

Para obter mais informações, confira "Como fazer a triagem de alertas de verificação de código em solicitações de pull". Se você usar o gatilho pull_request, configurado para verificar o commit de mesclagem da solicitação de pull em vez do commit de cabeçalho, ele produzirá resultados mais eficientes e precisos do que a verificação do cabeçalho do branch em cada push.

No entanto, se você usar um sistema de CI/CD que não possa ser configurado para disparo em solicitações de pull, ainda poderá usar o gatilho on:push e a code scanning mapeará os resultados para as solicitações de pull em aberto no branch e adicionará os alertas como anotações na solicitação de pull. Para obter mais informações, confira "Verificação durante o push". Definição das severidades que causam falha na verificação de solicitação de pull

Por padrão, apenas alertas com o nível de severidade Error ou nível de severidade de segurança Critical ou High causarão falha na verificação de solicitação de pull. As verificações com alertas de menor severidade serão bem-sucedidas.

Você pode alterar os níveis de severidades de alerta e de severidades de segurança que causarão uma falha de verificação de solicitação de pull nas configurações do repositório. Para obter mais informações sobre os níveis de severidade, confira "Sobre os alertas da verificação de código". 1. No GitHub.com, navegue até a página principal do repositório. 1. Abaixo do nome do repositório, clique em Configurações. Botão Configurações do repositório

  1. Na seção "Segurança" da barra lateral, clique em Segurança de código e análise.

Em "Varredura de código", à direita de "Verificar falha", use o menu suspenso para selecionar o nível de gravidade que você gostaria de fazer com que um pull request falhasse.

  1. Configuração de verificação de falha Evitar varreduras desnecessárias de pull requests

Talvez você queira evitar que uma varredura de código seja disparada em solicitações de pull específicas direcionadas à ramificação padrão, independentemente dos arquivos que foram alterados.

Configure isso especificando on:pull_request:paths-ignore ou on:pull_request:paths no fluxo de trabalho da code scanning. Por exemplo, se as únicas alterações em uma solicitação de pull forem para arquivos com as extensões de arquivo .md ou .txt, você poderá usar a matriz paths-ignore a seguir.

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 uma solicitação de pull.

  • Eles não determinam quais arquivos serão analisados quando as ações forem executadas. Quando uma solicitação de pull contém arquivos sem correspondência com on:pull_request:paths-ignore ou on:pull_request:paths, o fluxo de trabalho executa as ações e verifica todos os arquivos alterados na solicitação de pull, incluindo aqueles correspondentes a on:pull_request:paths-ignore ou on:pull_request:paths, a menos que eles tenham sido excluídos. Para obter informações sobre como excluir arquivos da análise, confira "Como especificar os diretórios para verificação". Nos arquivos de fluxo de trabalho da code scanning do CodeQL, 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 code scanning precisam conseguir comparar novas alterações com a análise do commit anterior.

Para obter 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 uma solicitação de pull, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

Fazer a varredura de forma pré-programada

Se você usar o CodeQL analysis workflow padrão, o fluxo de trabalho examinará o código no repositório uma vez por semana, além das verificações disparadas pelos eventos.

Para ajustar essa agenda, edite o valor cron no fluxo de trabalho. Para obter mais informações, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

Observação: o GitHub só executa os trabalhos agendados 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 tem um branch padrão chamado main e um branch protegido chamado protected.

Este fluxo de trabalho varre:

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

Cada push para a ramificação padrão e a ramificação protegida

  • Cada solicitação de pull para a ramificação padrão
  • A ramificação padrão a cada segunda-feira às 14h20 UTC
  • Especificar um sistema operacional

Se o código exigir um sistema operacional específico para ser compilado, configure o sistema operacional no seu CodeQL analysis workflow.

Edite o valor de jobs.analyze.runs-on para especificar o sistema operacional do computador que executa as ações da code scanning. Se optar por usar um executor auto-hospedado para a verificação de código, especifique um sistema operacional usando um rótulo apropriado como o segundo elemento em uma matriz de dois elementos, após self-hosted.

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

CodeQL code scanning é compatível com as versões mais recentes do Ubunto, Windows e macOS.

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

Os valores típicos dessa configuração são: ubuntu-latest, windows-latest e macos-latest. Para obter mais informações, confira "Escolhendo o executor de um trabalho" e "Usando rótulos com executores auto-hospedados". Se você usa um executor auto-hospedado, você deve garantir que o Git esteja na variável PATH. Para obter mais informações, confira "Sobre executores auto-hospedados" e "Adicionando executores auto-hospedados".

Para obter especificações recomendadas (RAM, núcleos de CPU e disco) para executar a análise do CodeQL em computadores auto-hospedados, confira "Recursos de hardware recomendados para execução do CodeQL".

Especificar o local para bancos de dados de CodeQL

Em geral, você não precisa se preocupar com o lugar em que o CodeQL analysis workflow coloca os bancos de dados do CodeQL, pois as etapas posteriores encontrarão automaticamente os bancos de dados criados nas etapas anteriores.

No entanto, se estiver escrevendo uma etapa de fluxo de trabalho personalizado que exija que o banco de dados CodeQL esteja em um local específico do disco, por exemplo, para carregar o banco de dados como um artefato de fluxo de trabalho, especifique esse local usando o parâmetro db-location na ação init. O CodeQL analysis workflow vai esperar que o caminho fornecido em db-location seja gravável, não exista ou seja um diretório vazio.

- uses: github/codeql-action/init@v2
  with:
    db-location: '${{ github.workspace }}/codeql_dbs'

Ao usar este parâmetro em um trabalho em execução em um executor auto-hospedado ou usando um contêiner Docker, é responsabilidade do usuário garantir que o diretório escolhido seja limpo entre execuções, ou que os bancos de dados sejam removidos depois de deixarem de ser necessários. Isto não é necessário para trabalhos em execução em executores auto-hospedados GitHub, que obtêm uma instância nova e um sistema de arquivos limpo toda vez que forem executados. Para obter mais informações, confira "Sobre os executores hospedados no GitHub". Se esse parâmetro não for usado, o CodeQL analysis workflow criará os bancos de dados em uma localização temporária escolhida por ele.

Alterar as linguagens que são analisadas

O CodeQL code scanning detecta automaticamente código escrito nas linguagens compatíveis.

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

Notas:

  • A análise do CodeQL para Kotlin está na versão beta. Durante a versão beta, a análise do CodeQL para Kotlin será menos abrangente do que para outras linguagens.
  • Use java para analisar o código escrito em Java, Kotlin ou ambos.
  • Use javascript para analisar o código escrito em JavaScript, TypeScript ou ambos.

Para obter mais informações, confira a documentação no site do CodeQL: "Linguagens e estruturas compatíveis".

O arquivo do CodeQL analysis workflow padrão contém uma matriz chamada language que lista as linguagens no repositório que são analisadas.

O CodeQL preenche automaticamente esta matriz quando você adiciona o code scanning a um repositório. O uso da matriz language otimiza o CodeQL a executar cada análise em paralelo. Recomendamos que todos os fluxos de trabalho adotem essa configuração devido aos benefícios de desempenho da paralelização de compilações. Para obter mais informações sobre matrizes, confira "Usando uma matriz para seus trabalhos". 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.

Se o seu fluxo de trabalho usar a matriz language, o CodeQL será embutido em código para analisar apenas as linguagens da matriz.

Para alterar as linguagens que você deseja analisar, edite o valor da variável de 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 a code scanning foi configurada. Por exemplo, se o repositório inicialmente só continha o JavaScript quando a code scanning foi configurada e, posteriormente, você adicionou o código Python, você precisa adicionar o python à matriz. Se o fluxo de trabalho não contiver uma matriz chamada language, o CodeQL será configurado para executar a análise sequencialmente.

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

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. Caso deseje escolher as linguagens que serão analisadas sem usar uma matriz, use o parâmetro languages na ação init.

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

Analisar as dependências do Python

Para os executores hospedados no GitHub que usam apenas o Linux, o CodeQL analysis workflow tentará instalar automaticamente as dependências do Python para fornecer mais resultados para a análise do CodeQL.

Controle esse comportamento especificando o parâmetro setup-python-dependencies para a ação chamada pela etapa "Inicializar o CodeQL". Por padrão, esse parâmetro é definido como true: Se o repositório contiver código escrito em Python, a etapa "Initialize CodeQL" instalará as dependências necessárias no executor hospedado pelo GitHub.

  • Se a instalação automática for bem-sucedida, a ação também definirá a variável de ambiente CODEQL_PYTHON para o arquivo executável Python que inclui as dependências. Se o repositório não tiver dependências do Python ou se as dependências forem especificadas de forma inesperada, você receberá um aviso e a ação continuará com os trabalhos restantes.

  • A ação pode ser executada com sucesso, mesmo quando houver problemas de interpretação de dependências, mas os resultados podem estar incompletos. Alternativamente, você pode instalar as dependências do Python manualmente em qualquer sistema operacional.

Você precisará adicionar setup-python-dependencies e defini-lo como false, bem como definir CODEQL_PYTHON como o executável Python que inclui as dependências, conforme mostrado neste extrato de fluxo de trabalho:

jobs:
  CodeQL-Build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ];
          then pip install -r requirements.txt;
          fi
          # Set the `CODEQL-PYTHON` environment variable to the Python executable
          # that includes the dependencies
          echo "CODEQL_PYTHON=$(which python)" >> $GITHUB_ENV
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: python
          # Override the default behavior so that the action doesn't attempt
          # to auto-install Python dependencies
          setup-python-dependencies: false

Configurar uma categoria para a análise

Use category para distinguir entre várias análises da mesma ferramenta e do mesmo commit, mas executadas em diferentes linguagens ou em diferentes partes do código.

A categoria especificada no seu fluxo de trabalho será incluída no arquivo de resultados SARIF. Esse parâmetro é particularmente útil se você trabalhar com monorepos e tiver vários arquivos SARIF para diferentes componentes do monorepo.

Se você não especificar um parâmetro category no fluxo de trabalho, o GitHub vai gerar um nome de categoria para você, com base no nome do arquivo de fluxo de trabalho que dispara a ação, o nome da ação e todas as variáveis da matriz.

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

Por exemplo: O fluxo de trabalho .github/workflows/codeql-analysis.yml e a ação analyze produzirão a categoria .github/workflows/codeql.yml:analyze.

  • O fluxo de trabalho .github/workflows/codeql-analysis.yml, a ação analyze e as variáveis da matriz {language: javascript, os: linux} produzirão a categoria .github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux.
  • O valor category será exibido como a propriedade <run>.automationDetails.id no SARIF v2.1.0.

Para obter mais informações, confira "Suporte do SARIF à code scanning". A categoria especificada não substituirá os detalhes do objeto runAutomationDetails no arquivo SARIF, se incluído.

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.

Você também pode especificar as consultas que deseja excluir da análise ou incluir na análise. Isso requer o uso de um arquivo de configuração personalizado. Para obter mais informações, confira "Como usar um arquivo de configuração personalizado" e "Como excluir consultas específicas da análise", abaixo.

Você poderá executar consultas extras se elas fizerem parte de um pacote do CodeQL (beta) publicado no GitHub Container registry ou um pacote do QL armazenado em um repositório. Para obter mais informações, confira "Sobre a code scanning com o CodeQL".

As opções disponíveis para especificar as consultas adicionais que você deseja executar são:

  • packs para instalar um ou mais pacotes de consulta (beta) do CodeQL e executar o pacote de consultas padrão ou as consultas desses pacotes.
  • queries para especificar um arquivo .ql individual, um diretório que contém vários arquivos .ql, um arquivo de definição de pacote de consultas .qls ou qualquer combinação. Para obter mais informações sobre as definições do pacote de consultas, confira "Como criar pacotes de consultas do CodeQL".

Use packs e queries no mesmo fluxo de trabalho.

Não recomendamos referenciar pacotes de consultas diretamente do repositório github/codeql, como github/codeql/cpp/ql/src@main. Essas consultas teriam que ser recompiladas e talvez não sejam compatíveis com a versão do CodeQL ativa no momento no GitHub Actions, o que poderia causar erros durante a análise.

Usando pacotes de consulta de CodeQL

Observação: a funcionalidade de gerenciamento de pacotes do CodeQL, incluindo pacotes do CodeQL, está atualmente em beta e está sujeita a alterações.

Para adicionar um ou mais pacotes de consulta do CodeQL (beta), adicione uma entrada with: packs: à seção uses: github/codeql-action/init@v2 do fluxo de trabalho.

Em packs, você especifica um ou mais pacotes a serem usados e, opcionalmente, a versão que será baixada. Quando você não especificar uma versão, a versão mais recente será baixada. Se você quiser usar pacotes que não estão publicamente disponíveis, precisará definir a variável de ambiente GITHUB_TOKEN para um segredo que tenha acesso aos pacotes. Para obter mais informações, confira "Autenticação em um fluxo de trabalho" e "Segredos criptografados".

Observação: para fluxos de trabalho que geram bancos de dados do CodeQL para várias linguagens, você precisará especificar pacotes de consulta do CodeQL em um arquivo de configuração.

Para obter mais informações, confira "Como especificar pacotes de consulta do CodeQL" abaixo.

No exemplo abaixo, scope é a organização ou a conta pessoal que publicou o pacote.

Quando o fluxo de trabalho é executado, os três pacotes de consulta do CodeQL são baixados do GitHub e das consultas ou conjunto de consultas padrão de cada execução de pacote: A última versão do pack1 é baixada e todas as consultas padrão são executadas.

  • A versão 1.2.3 do pack2 é baixada e todas as consultas padrão são executadas.
  • A última versão do pack3 que é compatível com a versão 3.2.1 é baixada e todas as consultas são executadas.
  • A versão 4.5.6 é pack4 baixada e somente as consultas encontradas em path/to/queries são executadas.
- uses: github/codeql-action/init@v2
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Observação: se você especificar uma versão específica de um pacote de consultas a ser usado, cuidado para que a versão especificada não fique muito antiga para ser usada com eficiência pelo mecanismo padrão do CodeQL usado pela ação do CodeQL.

Para garantir o desempenho ideal, se você precisar especificar versões exatas do pacote de consultas, considere examinar periodicamente se a versão fixada do pacote de consultas precisa ser atualizada. Para obter mais informações sobre a compatibilidade do pacote, confira "Sobre a compatibilidade de pacotes do CodeQL".

Como baixar pacotes do CodeQL do GitHub Enterprise Server

Se o fluxo de trabalho usa pacotes publicados em uma instalação do GitHub Enterprise Server, você precisa informar ao fluxo de trabalho onde encontrá-los.

Você pode fazer isso usando a entrada registries da ação github/codeql-action/init@v2. Essa entrada aceita uma lista de propriedades url, packages e token, como é mostrado abaixo. Os padrões de pacote na lista de registros são examinados em ordem, portanto, coloque os padrões de pacote mais específicos em primeiro lugar.

- uses: github/codeql-action/init@v2
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

    

Os valores de token precisam ser um personal access token (classic) gerado pela instância do GitHub da qual você está baixando com a permissão read:packages. Observe o | após o nome da propriedade registries.

Isso é importante, pois as entradas do GitHub Actions só podem aceitar cadeias de caracteres. O uso de | converte o texto subsequente em uma cadeia de caracteres, que é analisada depois pela ação github/codeql-action/init@v2. Usando consultas em pacotes QL

Para adicionar uma ou mais consultas, adicione uma entrada with: queries: à seção uses: github/codeql-action/init@v2 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 para fazer check-out do repositório privado. Você também pode especificar conjuntos de consulta no valor de queries.

- uses: github/codeql-action/init@v2
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Os conjuntos de consulta são coleções de consultas, geralmente agrupadas por finalidade ou linguagem. 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 do pacote padrão, além de consultas de gravidade e precisão inferiores
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. Os pacotes de consultas security-extended e security-and-quality do JavaScript contêm consultas experimentais. Para obter mais informações, confira "Sobre os alertas da code scanning".

Trabalhando com arquivos de configuração personalizados

Se você também usar um arquivo de configuração para configurações personalizadas, todos os pacotes ou as consultas especificados no fluxo de trabalho serão usados em vez dos especificados no arquivo de configuração.

Se você quiser executar o conjunto combinado de pacotes ou consultas adicionais, anteceda o valor de packs ou de queries no fluxo de trabalho com o símbolo +. Para obter mais informações, confira "Como usar um arquivo de configuração personalizado". No exemplo a seguir, o símbolo + garante que os pacotes e as consultas adicionais especificados sejam usados em conjunto com qualquer um especificado no arquivo de configuração referenciado.

Usando um arquivo de configuração personalizado

- uses: github/codeql-action/init@v2
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

Um arquivo de configuração personalizado é uma forma alternativa de especificar os pacotes e as consultas adicionais serem executados.

Você também pode usar o arquivo para desabilitar as consultas padrão, excluir ou incluir consultas específicas, e especificar quais diretórios examinar durante a análise. No arquivo de fluxo de trabalho, 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. 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.

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

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.

As configurações no arquivo de configuração são gravadas no formato YAML.

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

Especificando pacotes de consulta de CodeQL

Observação: a funcionalidade de gerenciamento de pacotes do CodeQL, incluindo pacotes do CodeQL, está atualmente em beta e está sujeita a alterações.

Você especificou pacotes de consulta de CodeQL em uma matriz.

Observe que o formato é diferente do formato usado pelo arquivo de fluxo de trabalho.

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

O formato completo para especificar um pacote de consultas é scope/name[@version][:path].

version e path são opcionais. version é o intervalo de versão semver. Se ele estiver ausente, a última versão será usada. Para obter mais informações sobre intervalos semver, confira a documentação do semver no npm. Se tiver um fluxo de trabalho que gera mais de um banco de dados de CodeQL, você poderá especificar todos os pacotes de consulta de CodeQL para executar em um arquivo de configuração personalizado usando um mapa aninhado de pacotes.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Especificar consultas adicionais

As consultas adicionais são especificadas em uma matriz queries.

Cada elemento da matriz contém um parâmetro uses com um valor que identifica um arquivo de consulta individual, um diretório contendo arquivos de consulta ou um arquivo de definição de conjunto de consultas. Opcionalmente, você pode dar um nome a cada elemento do array, conforme mostrado nos exemplos de arquivos de configuração abaixo.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Para obter mais informações sobre consultas adicionais, confira "Como executar consultas adicionais" acima. Desativar as consultas-padrão

Se você quiser apenas executar consultas personalizadas, poderá desabilitar as consultas de segurança padrão usando disable-default-queries: true.

Como excluir consultas específicas da análise

Você pode adicionar os filtros exclude e include ao seu arquivo de configuração personalizado para especificar as consultas que deseja excluir ou incluir na análise.

Isso será útil se você quiser excluir, por exemplo:

Consultas específicas dos pacotes padrão (security, security-extended e security-and-quality).

  • Consultas específicas cujos resultados não interessam a você.
  • Todas as consultas que geram avisos e recomendações.
  • Você pode usar filtros exclude semelhantes aos do arquivo de configuração abaixo para excluir as consultas que deseja remover da análise padrão.

No exemplo do arquivo de configuração abaixo, as consultas js/redundant-assignment as js/useless-assignment-to-local são excluídas da análise. Para localizar a ID de uma consulta, você pode clicar no alerta da lista de alertas na guia Segurança. Isso abre a página de detalhes do alerta.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

O campo Rule ID contém a ID da consulta. Para obter mais informações sobre a página de detalhes do alerta, confira "Sobre alertas de code scanning".

Dicas:

A ordem dos filtros faz diferença.

  • A primeira instrução de filtro exibida após as instruções sobre as consultas e os pacotes de consulta determina se as consultas são incluídas ou excluídas por padrão. As instruções subsequentes são executadas em ordem e as instruções que aparecem posteriormente no arquivo têm precedência sobre as instruções anteriores.

Você pode encontrar outro exemplo ilustrando o uso desses filtros na seção "Arquivos de configuração de exemplo".

Para obter mais informações sobre como usar os filtros exclude e include em seu arquivo de configuração personalizado, confira "Como criar conjuntos de consultas de CodeQL".

Para obter informações sobre os metadados de consulta nos quais você pode filtrar, confira "Metadados para consultas CodeQL".

Especificar diretórios para serem varridos

Nas linguagens interpretadas compatíveis com o CodeQL (Python, Ruby e JavaScript/TypeScript), você pode restringir a code scanning a arquivos em diretórios específicos adicionando uma matriz paths ao arquivo de configuração.

Você pode excluir os arquivos de diretórios específicos da análise ao adicionar uma matriz paths-ignore.

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

Observação:

As palavras-chave paths e paths-ignore, usadas no contexto do arquivo de configuração da code scanning, não devem ser confundidas com as mesmas palavras-chave quando usadas para on.<push|pull_request>.paths em um fluxo de trabalho.

  • Quando são usadas para modificar on.<push|pull_request> em um fluxo de trabalho, elas determinam se as ações serão executadas quando alguém modificar o código nos diretórios especificados. Para obter mais informações, confira "Sintaxe de fluxo de trabalho do GitHub Actions". Os caracteres de padrão de filtro ?, +, [, ] e ! não têm suporte e serão correspondidos literalmente.
  • ** os caracteres só podem estar no início ou no final de uma linha, ou circundados por barras, e você não pode misturar ** e outros caracteres.
  • Por exemplo, foo/**, **/foo e foo/**/bar são todas as sintaxes permitidas, mas **foo não é. No entanto, você pode usar estrelas únicas junto com outros caracteres, conforme mostrado no exemplo. Você precisará citar qualquer coisa que contenha um caractere *.

Para linguagens compiladas, se você deseja limitar code scanning 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ê precisará usar para excluir um diretório da compilação dependerão do seu sistema de compilação. Para obter mais informações, confira "Como configurar o fluxo de trabalho do CodeQL para as linguagens compiladas". Você pode analisar rapidamente pequenas partes de um repositório único quando modifica o código em diretórios específicos.

Você precisará excluir os diretórios das etapas de build e usar as palavras-chave paths-ignore e paths para on.<push|pull_request> no fluxo de trabalho. Exemplo de arquivos de configuração

Este arquivo de configuração adiciona o conjunto de consulta security-and-quality à lista de consultas executadas pelo CodeQL ao fazer a verificação do seu código. Para obter mais informações sobre os conjuntos de consulta disponíveis para uso, veja "Executando 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. Ele também configura o CodeQL para verificar arquivos no diretório src (em relação à raiz), com exceção do diretório src/node_modules e exceto arquivos cujos nomes terminam em .test.js. Os arquivos no src/node_modules e arquivos com nomes que terminam 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'

O arquivo de configuração a seguir executa apenas consultas que geram alertas de erro de gravidade. A configuração primeiro seleciona todas as consultas padrão, todas as consultas em ./my-queries e o pacote padrão em codeql/java-queries, depois exclui todas as consultas que geram avisos ou recomendações.

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Configurar o code scanning para linguagens compiladas

Para as linguagens compiladas compatíveis, use a ação autobuild no CodeQL analysis workflow para compilar o código. Com isso, você não precisa especificar comandos de compilação explícitos para C/C++, C#, Go, Kotlin e Java. Para essas linguagens, o CodeQL analisa os arquivos de origem no repositório em que são criados. Para qualquer uma dessas linguagens, você pode desabilitar autobuild e usar comandos de build personalizados para analisar apenas os arquivos criados por esses comandos personalizados.

Se autobuild falhar ou você quiser analisar um conjunto de arquivos de origem diferentes daqueles criados pelo processo autobuild, remova a etapa autobuild do fluxo de trabalho e adicione manualmente as etapas de compilação. Para projetos C/C++, C#, Go, Kotlin e Java, o CodeQL analisará qualquer código-fonte criado por suas etapas de compilação especificadas. Para obter mais informações sobre como configurar a code scanning do CodeQL para as linguagens compiladas, confira "Como configurar o fluxo de trabalho do CodeQL para as linguagens compiladas".

Carregar dados do code scanning no GitHub

GitHub pode exibir dados de análise de código gerados externamente por uma ferramenta de terceiros.

Carregue os dados da análise de código com a ação upload-sarif. Para obter mais informações, confira "Como carregar um arquivo SARIF no GitHub". For more information, see "Uploading a SARIF file to GitHub."