Um guia para iniciantes sobre como executar e gerenciar consultas CodeQL personalizadas

Você já desejou poder consultar seu código da mesma forma que consulta um banco de dados SQL? Bem, é exatamente isso que o CodeQL do GitHub permite que você faça. É um mecanismo de análise de código semântico que transforma seu código em um banco de dados estruturado que você pode usar para descobrir vulnerabilidades de segurança ou descobrir novos insights.

Você não precisa aprender nada sobre análise estática ou consultas estruturadas para se beneficiar do CodeQL. O recurso de verificação de código do GitHub executa centenas de consultas predefinidas imediatamente, gratuitamente em repositórios públicos ou como parte do GitHub Advanced Security para empresas. Existem também muitos outros “pacotes de consulta” de nicho disponíveis que vão muito além das verificações padrão. Mas embora o número de consultas prontas cresça constantemente, você também pode criar suas próprias consultas para atender às suas necessidades específicas.

Escrevemos consultas CodeQL personalizadas na Betsson há cerca de dois anos, incluindo aquelas para moderar o uso de pacotes, pesquisar e quantificar código e métricas de qualidade e facilitar a adesão à estrutura do código e ao design de arquitetura preferencial. Neste guia, compartilho um pouco do que aprendemos para ajudá-lo a começar a usar consultas personalizadas o mais rápido possível.

Neste guia, você aprenderá:

• Como construir uma configuração local rápida e mínima.
• Como criar e executar uma consulta personalizada simples.
• Como adicionar verificações CodeQL ao seu CI com GitHub Actions.
• Possibilidades de consulta personalizada mais avançadas.

Configure um ambiente local simples

Neste guia, usaremos JavaScript e Visual Studio Code , mas você poderá acompanhar independentemente da linguagem e do editor de código de sua escolha. Convido você a fazer um fork deste pequeno repositório onde coletei a maior parte da configuração usada neste artigo, incluindo um aplicativo mínimo chamado “health-app” que podemos verificar. 

Você precisa da ferramenta de interface de linha de comando (CLI) CodeQL para criar e configurar bancos de dados, um pacote de idiomas para sua linguagem de programação preferida para converter seu código em um banco de dados com possibilidade de consulta e um ou mais pacotes de consulta. Você pode encontrar a CLI, os pacotes e o plug-in do Visual Studio Code na página de ferramentas do CodeQL. Para obter ajuda para configurar tudo, você pode consultar a documentação de início rápido do CodeQL CLI.

Você fará a maior parte do trabalho do CodeQL no plug-in do Visual Studio Code ou em um plug-in semelhante para o editor de código de sua preferência. O plug-in do Visual Studio Code permite que você se conecte a diferentes destinos de verificação, projete consultas usando o IntelliSense e execute/visualize resultados de suas verificações a partir de relatórios SARIF (Static Analysis Results Interchange Format) produzidos.

Crie e execute sua primeira consulta personalizada

Antes de executar uma verificação, você precisa do seguinte: 

1. O código-fonte/repositório do projeto
2. Um banco de dados CodeQL construído a partir desse repositório
3. Um arquivo de configuração CodeQL para o projeto

Lembre-se de que sua configuração do CodeQL – que inclui scripts, pacotes e bancos de dados – ficará em um diretório separado do projeto que você está verificando.

Vamos começar executando todos os comandos do diretório raiz do projeto (se você estiver usando meu repositório health-app, tudo isso já foi feito): 

Inicie o CodeQL executando o seguinte (“.” representa o diretório atual):

1 codeql pack init -d . codeql        

Isto criará o arquivo qlpack.yml em um novo subdiretório chamado codeql no diretório raiz do projeto.

Configure qlpack.yml adicionando a referência da linguagem JavaScript:

1 codeql pack add --dir ./codeql codeql/javascript-all        

Crie um banco de dados a partir da sua base de código:

1 codeql database create codeql/db -s . -l javascript        

Isso cria um novo subdiretório dentro do diretório raiz chamado db.

Agora vamos fazer nossa primeira consulta personalizada! Crie um novo arquivo em seu editor de código com o seguinte:

1 import javascript
2 from PackageDependencies deps, string name
3 where deps.getADependency(name, _)
4 select deps, "Dependency found'" + name + "'."        

Esta é uma consulta simples que retornará todas as dependências de um projeto. Salve-o como um arquivo .ql dentro do codeql subdiretório recém-criado do diretório do projeto. Claro, você pode criar consultas muito mais interessantes e sofisticadas, mas vamos começar por aqui. No plugin VS Code, selecione o db diretório que você acabou de criar. Em seguida, clique com o botão direito em qualquer lugar do arquivo .ql para executar a primeira verificação. A consulta deve produzir uma lista de dependências package.json.

Você pode realizar muitos tipos diferentes de varreduras com CodeQL. Por exemplo, você pode bloquear o uso vulnerável do log4j em grande escala, proibindo versões afetadas do pacote. Você pode atualizar o exemplo de consulta que criamos acima para proibir explicitamente qualquer biblioteca (dotenv no nosso caso), atribuindo o nível de severidade de segurança apropriado (leia sobrea severidade de segurança e as configurações de alerta para as opções disponíveis). 

1 /**
2 * @name dependencies
3 * @description finds and lists referenced dependencies
4 * @kind problem
5 * @problem.severity error
6 * @security-severity 10.0
7 * @tags setup_check
8 * @id setup
9 */
10 
11
12 import javascript
13 from PackageDependencies deps, string name
14 where deps.getADependency(name, _) and name.matches("dotenv")
15 select deps, "Dependency found'" + name + "'."
16        

Você pode aprender mais sobre análise estática e usar CodeQL para detecção de vulnerabilidades no tutorial recente do GitHub . Um uso mais exótico para CodeQL seria implementar funções de aptidão para buscar proativamente projetos arquitetônicos de maneira mensurável.

Como você pode ver, executar consultas personalizadas localmente é bastante simples. Agora vamos subir de nível com GitHub Actions.

Automatizando verificações CodeQL com GitHub Actions

A maneira mais fácil de executar uma consulta personalizada com GitHub Actions é com o fluxo de trabalho CodeQL Analysis do GitHub, que usa a ação CodeQL do GitHub . Possui três componentes principais: configuração, executor e relatório. Os componentes de configuração e executor são bastante auto explicativos. O repórter carrega os resultados da verificação e um instantâneo do seu banco de dados para o armazenamento de contexto do repositório e os disponibiliza na guia Segurança. A melhor parte é que você pode baixar o banco de dados usando uma chamada de API do GitHub, caso queira investigar mais detalhadamente ou explorar os resultados em modo semi manual. Para executar a consulta de dependência personalizada que criamos acima, certifique-se de adicionar os arquivos .ql e qlpack.yml ao seu repositório. Em seguida, configure o fluxo de trabalho de Ações.

Se você ainda não habilitou GitHub Actions para o repositório, clique em Configurações abaixo do nome do seu repositório. Se você não conseguir ver a guia Ações, selecione o menu suspenso “...” e clique em Ações . Clique no botão que diz Entendo meus fluxos de trabalho, vá em frente e ative-os . Na guia Ações , clique em Novo fluxo de trabalho e pesquise Análise CodeQL. Deve haver um resultado. Clique no botão Configurar .

Você deverá ver um arquivo YAML do fluxo de trabalho do Actions. Adicione esta linha ao arquivo na github/codeql-action/init (lembre-se de incluir o espaço em branco):

1          queries: +./${{ env.CI_TMP_DIR }}/codeql/deps.ql        

Clique em Confirmar. Isso deve iniciar uma varredura CodeQL. Quando a verificação for concluída, você deverá ver algo assim na guia Segurança do repositório:

Observação: se você estiver usando meu repositório de aplicativos de saúde, esteja ciente de que o codeql-custom.yml fluxo de trabalho incluído requer GitHub Advanced Security. Se você não tiver Segurança Avançada, ainda poderá testar o fluxo de trabalho personalizado seguindo as etapas acima.

Embora esse processo funcione para testar nosso fluxo de trabalho, no longo prazo, é melhor usar um arquivo de configuração CodeQL personalizado, não o fluxo de trabalho de Ações, para gerenciar quais consultas personalizadas você executa.

Explorando outras possibilidades

Você pode criar configurações em vários idiomas ou configurações para coletar rapidamente mais informações em uma única execução ou executar várias verificações de uma só vez. Por exemplo, em vez de especificar idiomas antecipadamente, você pode detectar automaticamente quais idiomas são usados em um repositório e gerar verificações apropriadas com base nos resultados. Aqui está um exemplo de como trabalhar com a CLI do GitHub para buscar informações:

1 gh api repos/${{ env.CI_REPOSITORY }}/languages -q 'keys[]'        

E esta documentação detalha como personalizar suas varreduras CodeQL .

Faça algo legal? Compartilhe!

Claro, apenas arranhamos a superfície do que pode e deve ser feito com CodeQL. Há muito mais para ser descoberto na documentação e no próprio aplicativo. Ao explorar essa plataforma poderosa, você provavelmente criará coisas que outras pessoas poderão usar. Se você criar uma consulta que possa ser útil em praticamente todas as bases de código, poderá enviá-la ao repositório de consultas CodeQL de open source. Se for um pouco mais específico (por exemplo, uma consulta que só é aplicável a ações escritas em JavaScript), você podecriar seu próprio pacote de consultase compartilhá-lo por meio de GitHub Package Registry . Estou ansioso para ver o que você vai descobrir.

Autor: Denys Lashchevskyi, Staff Software Engineer, Betsson