Personalizando a configuração avançada para varredura de código

Você pode personalizar como a sua configuração avançada varre o código em seu projeto em busca de vulnerabilidades e erros.

Quem pode usar esse recurso?

Usuários com com acesso para gravação if advanced setup is already enabled

Neste artigo

Observação: o administrador do site precisa habilitar code scanning antes que você possa usar esse recurso. Se você desejar usar o GitHub Actions para fazer a varredura do seu código, o administrador do site também deverá habilitar o GitHub Actions e configurar a infraestrutura necessária. Para obter mais informações, confira "Como configurar a verificação de código do seu dispositivo".

Observação: este artigo descreve os recursos disponíveis na versão da ação do CodeQL e o pacote da CodeQL CLI associado incluído na versão inicial desta versão do GitHub Enterprise Server. Se sua empresa usa uma versão mais recente da ação CodeQL, confira a versão GitHub Enterprise Cloud deste artigo para obter informações sobre os recursos mais recentes. Para obter informações sobre como usar a versão mais recente, consulte "Como configurar a verificação de código do seu dispositivo".

Sobre a configuração do code scanning

Você pode executar code scanning em GitHub Enterprise Server, usando GitHub Actions ou a partir do seu sistema de integração contínua (CI). Para obter mais informações, confira "Escrevendo fluxos de trabalho" ou "Usando a varredura de código com seu sistema de CI existente".

Com a configuração avançada para a code scanning, você pode personalizar um fluxo de trabalho da code scanning para um controle granular sobre a sua configuração. Para obter mais informações, confira "Como definir a configuração avançada para verificação de código".

A análise de CodeQL é apenas um tipo de code scanning que você pode fazer em GitHub. GitHub Marketplace em GitHub.com contém outros fluxos de trabalho de code scanning que você pode usar. Os exemplos específicos fornecidos neste artigo estão relacionados ao arquivo sobre o Fluxo de trabalho de análise do CodeQL.

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.

  1. No seu repositório, pesquise o arquivo do fluxo de trabalho que você deseja editar.
  2. No canto superior direito da exibição de arquivo, para abrir o editor de fluxo de trabalho, clique em .
  3. Depois de editar o arquivo, clique em Iniciar confirmação e preencha o formulário "Confirmar alterações". Você pode optar por confirmar diretamente a ramificação atual ou criar uma nova ramificação e iniciar uma solicitação de pull.

Para obter mais informações sobre como editar arquivos de fluxo de trabalho, confira "Escrevendo fluxos de trabalho".

Configurar a frequência

Configure o Fluxo de trabalho de análise do CodeQL 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 Fluxo de trabalho de análise do CodeQL 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 para o 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 "Avaliar alertas de verificação de código para 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 alertas do code scanning nas solicitações de pull, confira "Alertas de varredura de código de triagem em pull requests".

Fazer a varredura de pull requests

O Fluxo de trabalho de análise do CodeQL 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. O evento pull_request não é disparado se a solicitação de pull foi aberta por meio de um fork privado.

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 "Alertas de varredura de código de triagem em pull requests".

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

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.

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

Note

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

Para obter mais informações sobre como usar on:pull_request:paths-ignore e on:pull_request:paths a fim de determinar quando um fluxo de trabalho será executado para uma solicitação de pull, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".

Fazer a varredura de forma pré-programada

Se você usar o Fluxo de trabalho de análise do CodeQL 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 para o GitHub Actions".

Note

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 Fluxo de trabalho de análise do CodeQL para um repositório em particular que tem um branch padrão chamado main e um branch protegido chamado protected.

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

Este fluxo de trabalho varre:

  • 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

Note

  • A verificação do código Swift usa executores do macOS por padrão. Executores macOS hospedados pelo

  • O Code scanning do código Swift não é compatível com executores que fazem parte de um Actions Runner Controller (ARC), porque os executores ARC usam apenas o Linux e o Swift requer executores macOS. No entanto, você pode ter uma mistura de executores ARC e executores macOS auto-hospedados. Para obter mais informações, confira "Sobe o Controlador de Executores de Ação".

Se o código exigir um sistema operacional específico para ser compilado, configure o sistema operacional no seu Fluxo de trabalho de análise do CodeQL. Edite o valor de jobs.analyze.runs-on para especificar o sistema operacional do computador que executa as ações da code scanning. Você especifica o sistema operacional usando um rótulo apropriado como o segundo elemento em uma matriz de dois elementos, após self-hosted.

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

CodeQL code scanning é compatível com as versões mais recentes do Ubunto, Windows e macOS. 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 para um trabalho" e "Usar rótulos com os executores auto-hospedados."

Você deve garantir que o Git esteja na variável PATH em seus executores auto-hospedados. Para obter mais informações, confira "Sobre executores auto-hospedados" e "Adicionar executores auto-hospedados".

Para especificações recomendadas (RAM, núcleos de CPU e disco) para executar análises do CodeQL, confira "Recursos de hardware recomendados para executar o CodeQL".

Especificar o local para bancos de dados de CodeQL

Em geral, você não precisa se preocupar com o lugar em que o Fluxo de trabalho de análise do CodeQL 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.

YAML
- uses: github/codeql-action/init@v2
  with:
    db-location: '${{ github.runner_temp }}/my_location'

O Fluxo de trabalho de análise do CodeQL vai esperar que o caminho fornecido em db-location seja gravável, não exista ou seja um diretório vazio. 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 "Usar executores hospedados no GitHub".

Se esse parâmetro não for usado, o Fluxo de trabalho de análise do CodeQL criará os bancos de dados em uma localização temporária escolhida por ele. Atualmente, o valor padrão é ${{ github.runner_temp }}/codeql_databases.

Alterar as linguagens que são analisadas

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

  • C/C++
  • C#
  • Ir
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby
  • Swift

Note

  • Use java para analisar o código escrito em Java, Kotlin ou ambos.
  • Use javascript para analisar código escrito em Java, TypeScript ou ambos.

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

O CodeQL usa os seguintes identificadores de idioma:

IdiomaIdentificador
C/C++cpp
C#csharp
Irgo
Java/Kotlinjava
JavaScript/TypeScriptjavascript
Pythonpython
Rubyruby
Swiftswift

O arquivo do Fluxo de trabalho de análise do CodeQL 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 "Executando variações de trabalhos em um fluxo de trabalho".

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.

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

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

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

Definindo as severidades de alerta que causam uma falha de verificação para uma solicitação de pull

Quando você habilitar o code scanning em pull requests, a verificação falhará somente se um ou mais alertas de gravidade error ou gravidade de segurança critical ou high forem detectados. A verificação será bem-sucedida se forem detectados alertas com gravidades ou gravidades de segurança mais baixas. Para bases de código importantes, convém que a verificação do code scanning falhe se algum alerta for detectado, de modo que o alerta deve ser corrigido ou descartado antes que a alteração de código seja mesclada. Para obter mais informações sobre níveis de gravidade, consulte "Sobre a gravidade de alertas e níveis de gravidade de segurança".

Você pode editar quais níveis de alertas de gravidade e gravidade de segurança causam uma falha de verificação. Para obter mais informações, confira "Editar as definições da configuração padrão".

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.

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

Se você não especificar um parâmetro category no fluxo de trabalho, o GitHub Enterprise Server 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. 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 SARIF para a varredura de código".

A categoria especificada não substituirá os detalhes do objeto runAutomationDetails no arquivo SARIF, se incluído.

Estendendo a cobertura do CodeQL com pacotes de modelos do CodeQL

Se sua base de código depender de uma biblioteca ou estrutura que não seja reconhecida pelas consultas padrão no CodeQL, você poderá estender a cobertura do CodeQL no seu fluxo de trabalho do code scanning especificando pacotes de modelos publicados do CodeQL. Para obter mais informações sobre como criar seus próprios pacotes de modelo, confira "Como criar e trabalhar com pacotes do CodeQL".

Observação: os pacotes de modelos do CodeQL e o editor de modelos do CodeQL estão atualmente em beta e estão sujeitos a alterações. Os pacotes de modelo são compatíveis com a análise do Java/Kotlin.

Para adicionar um ou mais pacotes de modelos do CodeQL publicados, especifique-os na entrada with: packs: com a 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 automática de token" e "Usar segredos em ações do GitHub."

YAML
- uses: github/codeql-action/init@v2
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

Neste exemplo, as consultas padrão serão executadas para Java, bem como as consultas de uma versão superior ou igual a 7.8.9 e inferior a 7.9.0 do pacote de consultas my-company/my-java-queries. As dependências modeladas na versão mais recente do pacote de modelos my-repo/my-java-model-pack estarão disponíveis para as consultas padrão e aquelas no my-company/my-java-queries.

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, consulte "Como usar um arquivo de configuração personalizado" e "Como excluir consultas específicas da análise" abaixo.

Você pode executar consultas adicionais se elas fizerem parte de um pacote do CodeQL publicado no GitHub Container registry ou um pacote do armazenado em um repositório. Para obter mais informações, confira "Sobre a varredura de código com 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 do CodeQL e executar o conjunto 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.

Usando pacotes de consultas

Para adicionar um ou mais pacotes de consultas do CodeQL, 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 automática de token" e "Usar segredos em ações do GitHub."

Note

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 Enterprise Server 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.
YAML
- 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

Note

Se você especificar uma versão específica de um pacote de consultas a ser usado, tenha 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 de pacotes, confira "Publicar e usar 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.

YAML
- 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 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. 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: dentro da 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. Os conjuntos de consulta são coleções de consultas, geralmente agrupadas por finalidade ou linguagem.

YAML
- uses: github/codeql-action/init@v2
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

Para saber mais, confira "Conjuntos de consultas CodeQL".

Cada um desses conjuntos de consultas contém um subconjunto diferente das consultas incluídas no pacote de consultas integrado CodeQL para esse idioma. Os pacotes de consultas são gerados automaticamente por meio dos metadados de cada consulta. Para obter mais informações, confira "Metadados para consultas CodeQL".

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.

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 consultas adicionais especificados no fluxo de trabalho serão usados em vez daqueles especificados no arquivo de configuração. Caso deseje executar o conjunto combinado de pacotes ou consultas adicionais, coloque o valor de packs ou queries como prefixo do 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 junto com qualquer item especificado no arquivo de configuração referenciado.

YAML
- 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

Usando um arquivo de configuração personalizado

Um arquivo de configuração personalizado é uma maneira alternativa de especificar pacotes e consultas adicionais a serem executados. Use também o arquivo para desabilitar as consultas padrão, excluir ou incluir consultas específicas e para especificar quais diretórios verificar 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.

YAML
- uses: github/codeql-action/init@v2
  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 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.

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.

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

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

Especificando pacotes de consulta de CodeQL

Você especificou pacotes de consulta de CodeQL em uma matriz. Observe que o formato é diferente do formato usado pelo arquivo de fluxo de trabalho.

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

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

YAML
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, 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.

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

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. 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 digitalização de códigos".

Tip

  • 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 do 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

Quando as bases de código são analisadas sem compilar o código, você pode restringir code scanning a arquivos em diretórios específicos adicionando uma matriz paths matriz ao arquivo de configuração. Você também pode excluir os arquivos de diretórios específicos da análise ao adicionar uma matriz paths-ignore. Você pode usar essa opção ao executar as ações de CodeQL em uma linguagem interpretada (Python, Ruby e JavaScript/TypeScript).

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

Note

  • 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 para o 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 *.

Em análises em que o código é compilado, caso deseje limitar code scanning a diretórios específicos no projeto, é necessário especificar as etapas adequadas de build no Workflow. 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 "Verificação de código do CodeQL para 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 CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/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 CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Especificando detalhes de configuração usando a entrada config

Se preferir especificar detalhes de configuração adicionais no arquivo de fluxo de trabalho, você poderá usar a entrada config do comando init da ação CodeQL. O valor dessa entrada deve ser uma cadeia de caracteres YAML que siga o formato de arquivo de configuração documentado em "Usando um arquivo de configuração personalizado" acima.

Configuração de exemplo

Esta etapa em um arquivo de fluxo de trabalho do GitHub Actions usa uma entrada config para desabilitar as consultas padrão, adicionar o conjunto de consultas security-extended e excluir consultas marcadas com cwe-020.

- uses: github/codeql-action/init@v2
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

Você pode usar a mesma abordagem para especificar as opções de configurações válidas no arquivo de fluxo de trabalho.

Tip

Você pode compartilhar uma configuração em vários repositórios usando variáveis de GitHub Actions. Um benefício dessa abordagem é que você pode atualizar a configuração em um único lugar sem editar o arquivo de fluxo de trabalho.

No exemplo a seguir, vars.CODEQL_CONF é uma variável de GitHub Actions. Seu valor pode ser o conteúdo de qualquer arquivo de configuração válido. Para obter mais informações, confira "Armazenar informações em variáveis".

- uses: github/codeql-action/init@v2
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

Configurar o code scanning para linguagens compiladas

Para linguagens compiladas, a ação de CodeQL compila a base de código para criar um banco de dados de CodeQL para análise. Por padrão, CodeQL usa etapas de autobuild para identificar o método de build mais provável para a base de código. Se autobuild falhar ou se você quiser analisar um conjunto diferente de arquivos de origem daqueles criados pelo processo de autobuild, será necessário remova ou comente a etapa de compilação automática no fluxo de trabalho. Em seguida, remova a marca de comentário da etapa de run e especifique manualmente o processo de compilação a ser usado. Para C/C++, C#, Go, Java, Kotlin, e Swift, CodeQL analisará qualquer código-fonte criado pelas etapas de compilação especificadas. Para obter mais informações sobre como configurar a code scanning do CodeQL para as linguagens compiladas, confira "Verificação de código do CodeQL para 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 "Fazer o upload de arquivo SARIF para o GitHub".