Configurar a varredura de código
Você pode configurar como o GitHub varre o código em seu projeto em busca de vulnerabilidades e erros. Ao escolher sua própria configuração, você economiza tempo e decide a melhor frequência de varredura de código para seu projeto. Nesta unidade, você aprenderá os conceitos básicos da configuração de varredura de código. Você também aprenderá a configurar a frequência de varreduras e a agendá-las para se ajustar melhor às suas necessidades de repositório e desenvolvimento.
Como discutimos nas unidades anteriores, você pode executar a varredura de código no GitHub, usando GitHub Actions, ou de seu sistema de CI (integração contínua). Selecionar a opção Avançada no GitHub gera um arquivo de fluxo de trabalho personalizável que você pode commitar diretamente no seu repositório. Normalmente, você não precisa editar este fluxo de trabalho. No entanto, se necessário, você pode personalizar algumas das configurações.
Por exemplo, você pode editar o fluxo de trabalho de análise de CodeQL do GitHub para especificar a frequência de varreduras, as linguagens ou diretórios a serem varridos e o que a varredura de código CodeQL procura em seu código. Talvez você também precise editar o fluxo de trabalho de análise de CodeQL se usar um conjunto específico de comandos para compilar seu código. A análise de CodeQL é apenas um tipo de varredura de código que você pode executar no GitHub. O GitHub Marketplace contém vários outros fluxos de trabalho de varredura de código.
Alternar da configuração de verificação de código padrão para a avançada
Se você já tiver um repositório configurado para usar a verificação de código com o método de instalação padrão, alterne para o uso da configuração Avançada nas configurações. Navegue até a seção Digitalização de código em Configurações > Segurança e análise de código e selecione o ícone de estouro de três pontos (...). No menu suspenso, selecione Alternar para avançado. Em seguida, siga os prompts para desabilitar o CodeQL e reative-o com o arquivo de fluxo de trabalho gerado pela configuração avançada.
Editar o fluxo de trabalho de verificação de código
O GitHub salva arquivos de fluxo de trabalho no diretório .github/fluxos de trabalho do 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 para verificação de código CodeQL é chamado codeql-analysis.yml.
Siga estas etapas para editar um arquivo de fluxo de trabalho:
Para abrir o editor de fluxo de trabalho, selecione o ícone Editar no canto superior direito do modo de exibição de arquivo.
Faça suas edições.
Depois de editar o arquivo, selecione Confirmar alterações e conclua 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.
Revise as seções a seguir para ver algumas opções comuns de configuração de varredura de código.
Configurar a frequência
Uma edição comum do arquivo de fluxo de trabalho é ajustar a frequência com a qual a varredura de código ocorre. Você pode configurar o fluxo de trabalho de análise do CodeQL para varrer o código em um agendamento ou quando eventos específicos ocorrem em um repositório. Também é possível editar o arquivo de fluxo de trabalho para verificar o código quando alguém envia uma alteração e sempre que um pull request é criado. Ajustar essa frequência impede que os desenvolvedores introduzam novas vulnerabilidades e erros no código. A verificação de código de acordo com um agendamento informa sobre as vulnerabilidades e erros mais recentes descobertos pelo GitHub, os pesquisadores de segurança e a comunidade. Mesmo quando os desenvolvedores não estão mantendo ativamente o repositório.
Varredura em push
Por padrão, o fluxo de trabalho de análise do CodeQL usa o evento on:push para disparar uma varredura de código em cada push para a ramificação padrão do repositório e quaisquer ramificações protegidas. Para que a varredura de código seja disparada em uma ramificação especificada, o fluxo de trabalho deverá existir nessa ramificação. Se você fizer uma varredura após um push, os resultados aparecerão na guia Segurança do repositório.
Além disso, quando uma varredura on:push retorna um resultado que pode ser mapeado para uma solicitação de pull aberta, esses alertas aparecem automaticamente em uma solicitação de pull no mesmo local que outros alertas de 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.
Varredura em PR
O fluxo de trabalho de análise do CodeQL padrão usa o evento pull_request para disparar uma varredura de código em solicitações de pull direcionadas à ramificação padrão. Se uma solicitação de pull for de uma bifurcação privada, o evento pull_request só será disparado se você tiver selecionado a opção "Executar fluxos de trabalho da bifurcação de solicitações de pull" nas configurações do repositório. Se você verificar as pull requests, os resultados serão exibidos como alertas em uma verificação de pull request.
Se você usar o gatilho pull_request, configurado para verificar o commit de mesclagem da pull request em vez do commit do 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 puder ser configurado para disparar em solicitações de pull, ainda poderá usar o gatilho on:push para que a varredura de código mapeie os resultados para solicitações de pull em aberto na ramificação e adicione os alertas como anotações em uma solicitação de pull.
Definir as severidades que causam falha na verificação da solicitação de pull
Por padrão, somente os alertas com o nível de gravidade Error ou o nível de gravidade de segurança Critical ou High causam uma falha de verificação de pull request. As falhas de pull request não interrompem uma verificação de código, mas representam um bloqueador ao tentar mesclar o código. Você pode encontrar a lista de falhas de solicitação de pull na guia Alertas de verificação de código na Segurança do repositório. Nas configurações do repositório, você pode alterar os níveis de gravidade de alerta e de segurança que causam uma falha na verificação de solicitação de pull.
No GitHub.com, acesse a página principal do repositório. No nome do repositório, selecione Configurações.
Na barra lateral esquerda, selecione Segurança e análise de código.
Na seção Varredura de código sob Regras de proteção, use o menu suspenso para selecionar o nível de severidade que você gostaria para disparar uma falha de verificação de solicitação de pull.
Evitar varreduras desnecessárias de solicitações de pull
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 fluxo de trabalho da verificação de código. 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'
Ajustar agendamento de varredura
Se você usar o fluxo de trabalho de análise CodeQL padrão, o fluxo de trabalho examinará o código em seu repositório uma vez por semana em um dia e horário gerados aleatoriamente, além das verificações disparadas por eventos. Para ajustar essa agenda, edite o valor cron no fluxo de trabalho.
O seguinte exemplo mostra um fluxo de trabalho de análise do CodeQL para um repositório com 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