Como personalizar a verificação de código

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 "Aprenda o GitHub Actions" ou "Sobre a varredura de código de CodeQL no seu sistema de CI".

Este artigo trata de executar code scanning no GitHub Enterprise Server usando ações.

Antes de poder personalizar a code scanning para um repositório, você deve configurá-la adicionando code scanning um fluxo de trabalho de GitHub Actions ao repositório. Para obter mais informações, confira "Como configurar a verificação de código para um repositório".

De modo geral, você não precisa editar o arquivo de fluxo de trabalho gerado para a code scanning. No entanto, se necessário, você editar o fluxo de trabalho para personalizar algumas das configurações. Por exemplo, você pode editar o Fluxo de trabalho de análise do CodeQL do GitHub para especificar a frequência das verificações, as linguagens ou os diretórios a serem verificados e o que é procurado pela code scanning do CodeQL no código. Talvez você precise editar o Fluxo de trabalho de análise do CodeQL caso use um conjunto específico de comandos para compilar o código.

A análise de CodeQL é apenas um tipo de code scanning que você pode fazer em GitHub. GitHub Marketplace 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 "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. 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 "Como personalizar a verificação de código".

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'

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'

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. Você especifica o 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]

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.

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

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

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
• JavaScript/TypeScript
• Python
• Ruby

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']

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

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 sua instância do GitHub Enterprise Server, 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 suspensa "Configurações", selecione o menu suspenso e 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", à direita de "Falha de Verificação", use o menu suspenso para selecionar o nível de gravidade que deseja atribuir em caso de falha de verificação de uma solicitação de pull.

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"

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.

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.

Todas as consultas que você deseja executar precisam pertencer a um pacote do QL em um repositório. Para obter mais informações, confira "Sobre a varredura de código com CodeQL".

Você pode 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".

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

Os conjuntos de consulta a seguir foram criados em CodeQL code scanning e estão disponíveis para uso.

Cada um desses pacotes de consultas contém um subconjunto diferente das consultas incluídas no pacote de consultas interno do CodeQL para essa linguagem. 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.

Se você também usar um arquivo de configuração para configurações personalizadas, todos os 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 consultas adicionais, anteceda o valor 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 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

Usando um arquivo de configuração personalizado

Um arquivo de configuração personalizado é uma forma alternativa de especificar as consultas adicionais serem executados. Você também pode usar o arquivo para desabilitar as consultas padrão 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

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

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

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

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.

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'

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 "Configuração do fluxo de trabalho 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'

Configurar o code scanning para linguagens compiladas

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

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