Opções de configuração de fluxo de trabalho para verificação de código

Observação

O administrador do site precisa habilitar a 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 saber mais, 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 saber mais sobre como usar a versão mais recente, confira "Como configurar a verificação de código do seu dispositivo".

Pré-requisitos

Você deve usar a configuração avançada para code scanning e ser capaz de editar o arquivo de fluxo de trabalho onde sua configuração está definida.

Os exemplos fornecidos neste artigo estão relacionados ao Fluxo de trabalho de análise do CodeQL arquivo. Por padrão, esse arquivo é definido em .github/workflows/codeql-analysis.yml.

Frequência de varredura

Você pode configurar o Fluxo de trabalho de análise do CodeQL para escanear o código de acordo com um cronograma 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 verificação de código de forma programada informa sobre as vulnerabilidades e erros mais recentes que foram descobertos por GitHub, pesquisadores de segurança e a comunidade, mesmo quando os desenvolvedores do repositório não estão mantendo-o ativamente.

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 quaisquer branches protegidos. Para code scanning ser disparado em um branch especificado, o fluxo de trabalho deve existir nesse branch. Para saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.

Se você fizer a varredura no push, os resultados aparecerão na aba Security do repositório. Para saber mais, confira Avaliar 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 code scanning alertas em solicitações de pull, consulte 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 nos pull requests direcionados ao branch padrão. O pull_request evento não será disparado se a solicitação de pull foi aberta de uma bifurcação privada.

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 saber mais, 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 pode ser configurado para ser acionado por solicitações de pull, ainda poderá usar o on:push gatilho, e code scanning irá mapear os resultados para as solicitações de pull abertas na branch e adicionar 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. Você pode configurar isso especificando on:pull_request:paths-ignore ou on:pull_request:paths no code scanning fluxo de trabalho. 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'

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

Observação

          `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](#specifying-directories-to-scan).

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 para o GitHub Actions.

Fazer a varredura de forma pré-programada

Se você usar o padrão Fluxo de trabalho de análise do CodeQL, o fluxo de trabalho examinará o código em seu repositório uma vez por semana, além das verificações disparadas por eventos. Para ajustar essa agenda, edite o valor cron do evento on.schedule no fluxo de trabalho. Para saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.

Observação

Esse evento vai disparar apenas um fluxo de trabalho executado se o arquivo de fluxo de trabalho existe no branch padrão.

Exemplo

O exemplo a seguir mostra um Fluxo de trabalho de análise do CodeQL de um repositório específico, 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'

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

Sistema operacional

Observação

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

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 saber mais, confira Controlador de Ações Runner.

Se o código exigir que um sistema operacional específico seja compilado, você poderá configurar o sistema operacional em seu Fluxo de trabalho de análise do CodeQL. Edite o valor de jobs.analyze.runs-on para especificar o sistema operacional para o computador que executa suas code scanning tarefas. Especifique 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]

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

          CodeQL
          code scanning dá suporte às versões mais recentes do Ubuntu, windows e macOS. Os valores típicos dessa configuração são: `ubuntu-latest`, `windows-latest` e `macos-latest`. Para saber mais, confira [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job) e [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners).

          Você deve garantir que o Git esteja na variável PATH em seus executores auto-hospedados. Para saber mais, confira [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) e [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners).

Para obter especificações recomendadas (RAM, núcleos de CPU e disco) para executar CodeQL a análise, consulte Recursos de hardware recomendados para executar o CodeQL.

          CodeQL local do banco de dados

Em geral, você não precisa se preocupar com onde o Fluxo de trabalho de análise do CodeQL coloca os bancos de dados CodeQL, pois as etapas posteriores encontrarão automaticamente os bancos de dados criados por etapas anteriores. No entanto, se você estiver escrevendo uma etapa de fluxo de trabalho personalizada que exija que o CodeQL banco de dados esteja em um local de disco específico, por exemplo, para carregar o banco de dados como um artefato de fluxo de trabalho, você poderá especificar esse local usando o db-location parâmetro sob a ação init .

YAML

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

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

          Fluxo de trabalho de análise do CodeQL vai esperar que o caminho em `db-location` seja gravável e 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. Isso não é necessário para trabalhos em execução em GitHubexecutores hospedados, que obtêm uma instância nova e um sistema de arquivos limpo a cada vez que são executados. Para saber mais, confira [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners).

Se esse parâmetro não for usado, ele Fluxo de trabalho de análise do CodeQL criará bancos de dados em um local temporário de sua própria escolha. Atualmente, o valor padrão é ${{ github.runner_temp }}/codeql_databases.

Idiomas a serem analisados

          CodeQL
          code scanning dá suporte ao código escrito nos seguintes idiomas:

C/C++
C#
Go
Java/Kotlin
JavaScript/TypeScript
Python
Ruby de codeql-rust-public-preview
Rust (versão prévia pública)

Observação

Use java-kotlin para analisar o código escrito em Java, Kotlin ou ambos.
Use javascript-typescript 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.

          CodeQL usa os seguintes identificadores de idioma:

Linguagem	Identificador	Identificadores alternativos opcionais (se houver)
C/C++	`c-cpp`

          `c` ou `cpp` |

Observação

Especificar um dos identificadores alternativos equivale a usar o identificador de linguagem padrão. Por exemplo, especificar javascript em vez de javascript-typescript não excluirá a análise do código TypeScript. Em vez disso, você pode usar um arquivo de configuração personalizado para excluir arquivos da análise usando a configuração paths-ignore. Para obter mais informações, confira Como usar um arquivo de configuração personalizado e Como especificar diretórios a serem digitalizados.

Esses identificadores de linguagem podem ser usados como argumentos para a entrada languages da ação init. Recomendamos que apenas uma linguagem seja fornecida como argumento:

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

O arquivo padrão Fluxo de trabalho de análise do CodeQL criado após a configuração avançada para verificação de código com CodeQL define uma matriz que contém uma propriedade nomeada language que lista os idiomas em seu repositório que serão analisados. Essa matriz foi preenchida automaticamente com linguagens com suporte detectadas em seu repositório. O uso da language matriz permite CodeQL executar cada análise de idioma em paralelo e personalizar a análise para cada idioma. Em uma análise individual, o nome da linguagem da matriz é fornecido à ação init como o argumento para a entrada languages. Recomendamos que todos os fluxos de trabalho adotem essa configuração. Para obter mais informações sobre matrizes, confira Executando variações de tarefas em um workflow.

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

Se o fluxo de trabalho utilizar a language matriz, CodeQL analisará apenas os idiomas na matriz. Para alterar as linguagens que você quer analisar, edite a configuração da matriz. Você pode remover uma linguagem para impedir que ela seja analisada. 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. Você também pode adicionar um idioma que não estava presente no repositório quando code scanning foi configurado. Por exemplo, se o repositório inicialmente continha apenas JavaScript quando code scanning foi configurado e você adicionou posteriormente o código Python, será necessário adicionar python à matriz.

YAML

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

Para linguagens compiladas, a matriz também pode ser usada para configurar qual modo de build usar para a análise alterando o valor da propriedade build-mode. Para obter mais informações sobre modos de build, confira Verificação de código do CodeQL para linguagens compiladas.

Se o fluxo de trabalho não fornecer um argumento para a languages entrada da ação init, CodeQL será configurado para executar análises sequencialmente. Nesse caso, CodeQL detecta e tenta analisar automaticamente todos os idiomas com suporte no repositório. Dependendo do tamanho do repositório e do número de linguagens, isso pode levar muito tempo. Se a análise de uma linguagem falhar nesse modo, a análise de todas as linguagens falhará. Portanto, não recomendamos essa configuração.

Observação

Ao analisar linguagens sequencialmente, o modo de build padrão de cada linguagem será usado. Como alternativa, se você fornecer uma etapa autobuild explícita, todas as linguagens com suporte para o modo autobuild a usarão, enquanto outras linguagens usam o modo padrão. Se for necessária uma configuração de modo de build mais complexa do que essa, você precisará configurar uma matriz.

Severidades de alerta para falhas de verificação

Você pode usar conjuntos de regras para evitar que pull requests sejam mesclados quando uma das seguintes condições for atendida:

Uma ferramenta necessária localiza um alerta code scanning de uma severidade definida no conjunto de regras.
A análise da ferramenta necessária ainda está em andamento.
Uma ferramenta necessária não está configurada para o repositório.

Para saber mais, confira Definir proteção contra mesclagem de verificação de código. Para obter informações gerais sobre conjuntos de regras, confira Sobre os conjuntos de regras.

Categoria de 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@v4
      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@v4
      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 category parâmetro em seu fluxo de trabalho, GitHub 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 quaisquer variáveis de 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-typescript, os: linux} produzirão a categoria .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux.

O valor category será exibido como a propriedade <run>.automationDetails.id no SARIF v2.1.0. Para saber mais, 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.

          CodeQL pacotes de modelos

Se a sua base de código depender de uma biblioteca ou framework que não seja reconhecida pelas consultas padrão em CodeQL, você pode estender a cobertura em seu fluxo de trabalho code scanning especificando pacotes de modelos publicados 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

Atualmente, os pacotes de modelo do CodeQL estão em beta e estão sujeitos a alterações. Os pacotes de modelos são compatíveis com a análise do C/C++, C#, Java/Kotlin, Python, e Ruby.

O editor de modelos do CodeQL na extensão CodeQL para Visual Studio Code dá suporte a dependências de modelagem para C#, Java/Kotlin e Ruby.

Usando CodeQL pacotes de modelos

Para adicionar um ou mais pacotes de modelos publicados CodeQL , especifique-os dentro da with: packs: entrada dentro da uses: github/codeql-action/init@v4 seção 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 saber mais, confira Usar GITHUB_TOKEN para autenticação em fluxos de trabalho e Usar segredos em ações do GitHub.

YAML

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

- uses: github/codeql-action/init@v4
  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 maior ou igual a 7.8.9 e menor que 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.

Consultas não padrão

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.

Dica

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 arquivos de configuração personalizados e exclusão de 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 saber mais, 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](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/).

Use packs e queries no mesmo fluxo de trabalho.

Usando pacotes de consultas

Para adicionar um ou mais CodeQL pacotes de consulta, adicione uma with: packs: entrada na uses: github/codeql-action/init@v4 seção 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 saber mais, confira Usar GITHUB_TOKEN para autenticação em fluxos de trabalho e Usar segredos em ações do GitHub.

Observação

Para fluxos de trabalho que geram CodeQL bancos de dados para vários idiomas, você deve especificar os CodeQL pacotes de consulta em um arquivo de configuração. Para obter mais informações, consulte Especificando CodeQL pacotes de consulta abaixo.

No exemplo abaixo, scope é a organização ou a conta pessoal que publicou o pacote. Quando o fluxo de trabalho é executado, os quatro CodeQL pacotes de GitHub consulta são baixados e as consultas ou o pacote de consultas padrão para cada pacote são executados:

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@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

Observação

Se você especificar uma versão particular de um pacote de consultas a ser usado, esteja ciente de que a versão que você especificar pode eventualmente se tornar muito antiga para ser usada com eficiência pelo mecanismo padrão CodeQL utilizado pela ação 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 Referência de pacotes de consulta CodeQL.

Baixando CodeQL pacotes de GitHub Enterprise Server

Se o fluxo de trabalho usar pacotes publicados em uma GitHub Enterprise Server instalação, você precisará informar ao fluxo de trabalho onde encontrá-los. Você pode fazer isso usando a entrada registries da ação github/codeql-action/init@v4. Essa entrada aceita uma lista de propriedades url, packages e token, como é mostrado abaixo.

YAML

- uses: github/codeql-action/init@v4
  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@v4
  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 para token devem 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 GitHub Actions as entradas só podem aceitar cadeias de caracteres. Usar o | converte o texto subsequente em uma cadeia de caracteres, que é analisada posteriormente pela ação do github/codeql-action/init@v4.

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@v4 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@v4
  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@v4
  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 consultas	Descrição
`security-extended`	Consultas do pacote padrão, além de consultas de gravidade e precisão inferiores
`security-and-quality`	Consultas de `security-extended`, além de consultas de capacidade de manutenção e confiabilidade

Para obter mais informações, 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 saber mais, 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, consulte arquivos de configuração personalizados.

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@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

Arquivos de configuração personalizados

Um arquivo de configuração personalizado é uma maneira alternativa de especificar pacotes e consultas adicionais a 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.

YAML

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

- uses: github/codeql-action/init@v4
  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@v4
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

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

Especificando CodeQL pacotes de consulta

Os pacotes de consulta CodeQL são especificados 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/[email protected]
  # 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/[email protected]
  # 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 você tiver um fluxo de trabalho que gere mais de um banco de dados, poderá especificar todos CodeQL os CodeQL pacotes de consulta a serem executados 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/[email protected]

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/[email protected]

Estendendo a CodeQL cobertura com modelos de ameaça

Observação

Modelos de riscos estão em beta e estão sujeitos a alterações. Durante o beta, os modelos de risco são compatíveis apenas com a análise para Java/Kotlin e C#.

O modelo de risco padrão inclui fontes remotas de dados não confiáveis. Você pode estender o CodeQL modelo de ameaça para incluir fontes locais de dados não confiáveis (por exemplo: argumentos de linha de comando, variáveis de ambiente, sistemas de arquivos e bancos de dados) especificando threat-models: local em um arquivo de configuração personalizado. Se você estender o modelo de risco, o modelo de risco padrão também será usado.

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

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

Opcionalmente, você pode dar um nome a cada elemento do array, conforme mostrado nos exemplos de arquivos de configuração abaixo. Para obter mais informações sobre consultas adicionais, consulte consultas não padrão 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

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

Para localizar a ID de uma consulta, clique no alerta na lista de alertas na Security guia. 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.

Dica

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 criar o código, você pode restringir code scanning arquivos em diretórios específicos adicionando uma 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 CodeQL ações em uma linguagem interpretada (Python, Ruby e JavaScript/TypeScript) ou ao analisar um idioma compilado sem criar o código (atualmente compatível Java).

YAML

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

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 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 saber mais, 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 `*`.

Para a análise em que o código é criado, se você quiser limitar code scanning a diretórios específicos em seu projeto, especifique as etapas de build apropriadas 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 saber mais, 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 em suas etapas de build e usar as palavras-chave paths-ignore e paths para on.<push|pull_request> no seu 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 consultas disponíveis para uso, consulte consultas não padrão.

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

Detalhes da configuração

Se você preferir especificar detalhes adicionais de configuração no arquivo de fluxo de trabalho, poderá usar o config input 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 nos arquivos de configuração personalizados acima.

Configuração de exemplo

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

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      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.

Dica

Você pode compartilhar uma configuração em vários repositórios usando GitHub Actions variáveis. 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 GitHub Actions variável. Seu valor pode ser o conteúdo de qualquer arquivo de configuração válido. Para saber mais, confira Armazenar informações em variáveis.

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

Idiomas compilados

Para idiomas compilados, você pode decidir como a ação CodeQL cria um CodeQL banco de dados para análise. Para obter informações sobre as opções de build disponíveis, confira Verificação de código do CodeQL para linguagens compiladas.

Carregamento de dados

          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 saber mais, confira [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github).

Opções de configuração de fluxo de trabalho para verificação de código

Quem pode usar esse recurso?

Neste artigo

Pré-requisitos

Frequência de varredura

Fazer a varredura no push

Fazer a varredura de pull requests

Evitar varreduras desnecessárias de pull requests

Fazer a varredura de forma pré-programada

Exemplo

Sistema operacional

Idiomas a serem analisados

Severidades de alerta para falhas de verificação

Categoria de análise

Usando CodeQL pacotes de modelos

Consultas não padrão

Usando pacotes de consultas

Baixando CodeQL pacotes de GitHub Enterprise Server

Usando consultas em pacotes QL

Trabalhando com arquivos de configuração personalizados

Arquivos de configuração personalizados

Especificando CodeQL pacotes de consulta

Estendendo a CodeQL cobertura com modelos de ameaça

Especificar consultas adicionais

Desativar as consultas-padrão

Como excluir consultas específicas da análise

Especificar diretórios para serem varridos

Exemplo de arquivos de configuração

Detalhes da configuração

Configuração de exemplo

Idiomas compilados

Carregamento de dados