Sobre a varredura de código com CodeQL

Você pode usar CodeQL para identificar vulnerabilidades e erros no seu código. Os resultados são exibidos como alertas de code scanning em GitHub.

Quem pode usar esse recurso?

O Repositórios pertencentes à organização com GitHub Advanced Security habilitado

Neste artigo

Note

O administrador do site precisa habilitar a code scanning antes que você possa usar esse recurso. Para obter mais informações, confira "Como configurar a verificação de código do seu dispositivo".

Talvez você não consiga habilitar ou desabilitar o code scanning se um proprietário da empresa tiver definido uma política GitHub Advanced Security (GHAS) no nível da empresa. Para obter mais informações, confira "Como impor políticas para segurança e análise de código na empresa".

CodeQL é o mecanismo de análise de código desenvolvido por GitHub para automatizar verificações de segurança. Você pode analisar seu código usando CodeQL e exibir os resultados como alertas de code scanning.

Existem três maneiras principais de usar a análise do CodeQL para code scanning:

  • Use a configuração padrão para definir rapidamente a análise do CodeQL para a code scanning no seu repositório. A configuração padrão escolhe automaticamente as linguagens a serem analisadas, o pacote de consultas a ser executado e os eventos que disparam as verificações. Se preferir, selecione manualmente o conjunto de consultas a ser executado e as linguagens a serem analisadas. Depois de habilitar o CodeQL, o GitHub Actions vai disparar execuções de fluxo de trabalho para verificar seu código. Para saber mais, confira Como definir a configuração padrão da verificação de código.

  • Use a configuração avançada para adicionar o fluxo de trabalho do CodeQL ao seu repositório. Isso gera um arquivo de fluxo de trabalho personalizável que usa o github/codeql-action para executar o CodeQL CLI. Para saber mais, confira Como definir a configuração avançada para verificação de código.

  • Execute a CodeQL CLI diretamente em um sistema de CI externo e faça o upload dos resultados em GitHub. Para saber mais, confira Usando a varredura de código com seu sistema de CI existente.

Note

No GitHub Enterprise Server 3.14, a ação CodeQL usa a CodeQL CLI versão 2.17.6 por padrão. Recomendamos que você use a mesma versão da CodeQL CLI para executar a análise em um sistema de CI externo.

Para mais informações sobre os alertas da code scanning confira Sobre alertas de digitalização de códigos.

Sobre o CodeQL

CodeQL é uma linguagem de programação e ferramentas associadas que tratam o código como dados. Ele foi criado explicitamente para facilitar a análise do código e encontrar possíveis vulnerabilidades no código com maior confiança do que os analisadores estáticos tradicionais.

  1. Você gera um banco de dados de CodeQL para representar a sua base de código.
  2. Em seguida, você executa consultas de CodeQL nesse banco de dados para identificar problemas na base de código.
  3. Os resultados da consulta são exibidos como alertas de code scanning em GitHub Enterprise Server quando você usa CodeQL com code scanning.

O CodeQL dá suporte a linguagens compiladas e interpretadas e pode encontrar vulnerabilidades e erros no código escrito nas linguagens compatíveis.

  • C/C++
  • C#
  • Ir
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby
  • Swift

Note

  • Use java-kotlin para analisar o código escrito em Java, Kotlin ou ambos.
  • Use javascript-typescript para analisar código escrito em Java, TypeScript ou ambos.

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

Modelar estruturas personalizadas ou de nicho

Especialistas em GitHub, pesquisadores de segurança e colaboradores da comunidade criam bibliotecas para modelar o fluxo de dados nas estruturas e bibliotecas mais usadas. Se você usar dependências personalizadas que não são modeladas, poderá usar a extensão CodeQL para Visual Studio Code para criar modelos dessas dependências e usá-los para ampliar sua análise. Para saber mais, confira Usar o editor de modelos do CodeQL.

Consultas CodeQL

Especialistas, pesquisadores de segurança e contribuidores da comunidade GitHub escrevem e mantêm as consultas padrão de CodeQL usadas por code scanning. As consultas são atualizadas regularmente para melhorar a análise e reduzir quaisquer resultados falsos positivos. Para obter detalhes das consultas disponíveis nos pacotes padrão e estendido, confira Consultas incluídas nos pacotes de consultas padrão e de segurança estendida.

Escrevendo suas próprias consultas

As consultas são de software livre, portanto, você pode exibir e contribuir para as consultas no repositório github/codeql . Para saber mais, confira Sobre as consultas do CodeQL na documentação do CodeQL.

Executar consultas adicionais

Se estiver verificando o código com a configuração avançada ou com um sistema de CI externo, execute consultas adicionais como parte da análise.

Essas consultas precisam pertencer a um pacote de consultas do CodeQL ou a um pacote do CodeQL em um repositório.

  • Quando um pacote de consultas do CodeQL é publicado no GitHub Container registry, todas as dependências transitivas exigidas pelas consultas e um cache de compilação são incluídos no pacote. Isto melhora o desempenho e garante que a execução de consultas no pacote dê resultados idênticos toda vez até que você fizer a autalização para uma nova versão do pacote ou para o CLI.

  • Os pacotes de consultas do CodeQL podem ser baixados de vários registros de contêiners de GitHub. Para saber mais, confira Personalizando a configuração avançada para varredura de código.

Para saber mais, confira Como personalizar a análise com pacotes CodeQL.