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 do padrão para a configuração avançada de verificação de código
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 Verificação de código em Configurações > Segurança Avançada e selecione o ícone de menu de três pontos (...). No menu suspenso, selecione Alternar para o modo 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.
Essas falhas não impedem a execução da verificação de código, mas podem bloquear a mesclagem dependendo das regras do repositório. Você pode exibir os detalhes de falha da solicitação de pull na guia Alertas de verificação de código em Segurança.
Você pode configurar quais níveis de severidade causam falhas nas verificações de pull request nas configurações do repositório ou por meio de conjuntos de regras do repositório usando a regra Exigir resultados da análise de código. Ambos os mecanismos funcionam, mas os conjuntos de regras são o método de configuração moderno e preferencial.
- 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 Avançada.
- 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.
Fazer triagem e ignorar alertas de verificação de código com responsabilidade
Corrigir o código é a maneira preferida de resolver um alerta de verificação de código. No entanto, alguns alertas podem não exigir uma alteração de código. Por exemplo, o alerta pode ser um falso positivo, aparecer somente no código de teste ou representar um risco que a equipe decidiu não corrigir.
Ignore os alertas somente depois de examinar os detalhes do alerta e confirmar o motivo. Quando você descarta um alerta, GitHub registra o motivo da demissão, remove o alerta da contagem de alertas atual, move-o para a lista fechada e impede que o mesmo código gere o mesmo alerta em verificações futuras. A demissão se aplica em todos os branches.
Escolha o motivo da demissão cuidadosamente porque ele se torna parte do registro de segurança do repositório. Você também pode adicionar um comentário de demissão para explicar a decisão. Esse comentário é adicionado à linha do tempo do alerta e pode dar suporte a futuras revisões de auditoria, relatórios e conformidade.
Use comentários para capturar detalhes como:
Por que o alerta não precisa de uma alteração de código
Quem revisou a decisão
Se a decisão é temporária ou permanente
Quaisquer controles compensatórios ou trabalho de acompanhamento
Para uma governança mais robusta, as organizações podem usar a dispensa delegada de alertas para controlar quem tem permissão para dispensar alertas de análise de código. Isso ajuda a impedir que os desenvolvedores fechem as descobertas de segurança sem revisão e cria um processo de triagem mais responsável.
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
Use as sugestões do Copilot Autofix
O GitHub Copilot Autofix ajuda os desenvolvedores a resolver alertas de análise de código ao sugerir alterações específicas no código. O Autofix usa informações do alerta, da base de código e do pull request para gerar uma possível correção. Você não precisa de uma assinatura separada do GitHub Copilot para usar o Copilot Autofix. Ele está disponível para repositórios públicos em GitHub.com e para repositórios de propriedade da organização com GitHub Code Security habilitado.
Sugestões de autofixo não são correções automáticas. Elas são propostas de alterações que devem ser revisadas, testadas e aprovadas como qualquer outra alteração de código.
Ao analisar uma sugestão do Autofix:
Leia o alerta e entenda o problema de segurança.
Examine as alterações de código sugeridas.
Confirme se a correção trata do alerta sem alterar o comportamento pretendido.
Execute os testes do projeto e todas as verificações de segurança necessárias.
Modifique a sugestão, se necessário.
Confirme a correção na solicitação pull.
Confirme se o alerta de verificação de código foi resolvido depois que as verificações forem executadas novamente.
Se uma sugestão de Autofixo não for apropriada, ignore a sugestão em vez de aplicá-la. Se o alerta em si não precisar ser corrigido, ignore o alerta com o motivo correto e um comentário claro.