Como personalizar sua configuração avançada para a verificação de código

Sobre a configuração do code scanning

Você pode executar code scanning em GitHub Enterprise Cloud, usando GitHub Actions ou a partir do seu sistema de integração contínua (CI). Para obter mais informações, confira "Aprenda o GitHub Actions" ou "Sobre a varredura de código de CodeQL no seu sistema de CI".

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, consulte "Como definir a configuração avançada da verificação de 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 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 "Aprenda o GitHub Actions".

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 "Gerenciamento de alertas de varredura 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. 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 "Gerenciando as configurações do GitHub Actions para 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 "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.

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

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

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

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.

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

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

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.

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

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

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: [self-hosted, ubuntu-latest]

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

Se você usa um executor auto-hospedado, é preciso garantir que o Git esteja na variável PATH. 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 em computadores auto-hospedados, 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.

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

- 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 "Using GitHub-hosted runners".

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#
• Go
• Java/Kotlin
• JavaScript/TypeScript
• Python
• Ruby - Swift

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

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

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

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.

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

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

Analisar as dependências do Python

Para executores hospedados pelo GitHub que usam apenas Linux, o Fluxo de trabalho de análise do CodeQL 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@v4
      - 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

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

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - 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

Como definir as gravidades de alerta que apresentam uma falha de verificação para uma 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 gravidade, confira "Sobre alertas de digitalização de códigos".

1. No GitHub.com, navegue até a página principal do repositório.
2. Abaixo do nome do repositório, clique em Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.
3. Na seção "Segurança" da barra lateral, clique em Segurança de código e análise.
4. Em "Code scanning", na seção "Regras de proteção", use o menu suspenso para definir os alertas que devem causar uma falha de verificação. Escolha um nível para alertas do tipo "Segurança" e um nível para todos os outros alertas.

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.

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

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

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ê 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 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 (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

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 automática de token" e "Usar segredos em ações do GitHub."

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

- 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

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.

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

    

- 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: à 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.

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

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

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

Você pode identificar em quais pacotes de consultas uma consulta está incluída navegando pela documentação de ajuda de consultas CodeQL. Para cada consulta, todos os pacotes nos quais ela está incluída são exibidos na parte superior da página com os metadados de consulta. Por exemplo: gravação arbitrária de arquivo durante a extração zip ("Zip Compactado") e solicitação do lado do cliente forjada.

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

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.

- 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

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

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

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

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

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

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

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

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.

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

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.

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

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

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

Para as linguagens interpretadas com as quais CodeQL é compatível (Python, Ruby e JavaScript/TypeScript), você pode restringir code scanning a arquivos em diretórios específicos adicionando uma matriz de 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'

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

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

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.

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

Configurar o code scanning para linguagens compiladas

O CodeQL analisa os arquivos de origem do C/C++, C#, Go, Java, Swift criados no repositório.

Se você habilitar a configuração padrão, a ação autobuild será usada para compilar seu código, como parte do seu Fluxo de trabalho de análise do CodeQL configurado automaticamente. Se você habilitar a instalação avançada, o Fluxo de trabalho de análise do CodeQL básico usará autobuild. Como alternativa, é possível desabilitar autobuild e especificar comandos de compilação explícitos 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, Java e Swift, 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 "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".