Preparar um banco de dados para CodeQL

Concluído

O CodeQL trata o código como dados. Você cria um banco de dados usando dados que podem ser consultados extraídos da base de código. Em seguida, você pode executar consultas CodeQL neste banco de dados para identificar vulnerabilidades de segurança, bugs e outros erros. Você pode escrever suas próprias consultas ou executar consultas CodeQL padrão escritas por pesquisadores do GitHub e colaboradores da comunidade.

Nesta unidade, você aprenderá a criar um banco de dados. Esta etapa é necessária para que você possa analisar seu código. Você precisa criar um banco de dados CodeQL que contenha todos os dados necessários para executar consultas em seu código.

A análise do CodeQL depende da extração de dados relacionais do código e do uso dele para criar um banco de dados CodeQL. Esses bancos de dados contêm todas as informações importantes sobre uma base de código.

Você pode usar o produto autônomo da CLI do CodeQL para analisar o código e gerar uma representação de banco de dados de uma base de código. Depois que o banco de dados estiver pronto, você poderá consultar o banco de dados ou executar um conjunto de consultas para gerar um conjunto de resultados no SARIF (Formato de Intercâmbio de Resultados de Análise Estática).

Preparação do banco de dados para CodeQL

Antes de gerar um banco de dados CodeQL, você precisa instalar e configurar a CLI do CodeQL. Em seguida, você precisa verificar a versão da base de código que deseja analisar.

Para idiomas compilados, o diretório deve estar pronto para ser compilado, com todas as dependências já instaladas. O CodeQL começa extraindo uma única representação relacional de cada arquivo de origem na base de código para criar um banco de dados. Você usa esse banco de dados para analisar seu código.

Para idiomas interpretados, o extrator é executado diretamente no código-fonte. Essa funcionalidade fornece uma representação precisa da base de código e resolve todas as dependências.

A extração do arquivo de origem da base de código funciona monitorando o processo de compilação normal para linguagens compiladas. O CodeQL faz uma cópia do arquivo de origem sempre que você invoca um compilador para processar um arquivo de origem. Ele coleta todas as informações relevantes sobre o código-fonte com cada arquivo de origem.

Configuração da CLI

Use as etapas a seguir para configurar a CLI do CodeQL.

1. Baixe o pacote .zip do bundle CLI do CodeQL

Recomendamos que você instale a CLI do CodeQL e as consultas baixando o pacote empacotado. Esse método ajuda a garantir a compatibilidade e o desempenho aprimorado, em vez de baixar a CLI e as consultas separadamente.

O pacote de download da CLI do CodeQL é um arquivo .zip que contém ferramentas, scripts e vários arquivos específicos do CodeQL. O pacote inclui: a CLI do CodeQL, versões compatíveis das consultas e bibliotecas do repositório GitHub do CodeQL e as versões pré-compiladas das consultas incluídas.

1. Vá para a página de Lançamentos do repositório público CodeQL.
2. Baixe o pacote específico da plataforma em Ativos.

Na página Versões, você também pode exibir as listas de alterações das versões e baixar versões anteriores do pacote CodeQL. Se necessário, você pode baixar codeql-bundle.tar.gz, que contém a CLI para todas as plataformas com suporte.

2. Extrair o arquivo .zip

Se você estiver usando Linux, Windows ou macOS, poderá extrair o arquivo .zip no diretório de sua escolha.

Os usuários do macOS Catalina (ou mais recente) precisam seguir outras etapas. Para obter mais informações, consulte a documentação do CodeQL sobre como começar a usar a CLI.

3. Executar processos CodeQL

Após a extração, execute uma das seguintes etapas para usar o codeql arquivo executável para executar os processos do CodeQL:

• Execute <extraction-root>/codeql/codeql, onde <extraction-root> está a pasta na qual você extraiu o pacote da CLI do CodeQL.
• Adicione <extraction-root>/codeql à sua PATH entrada, para que você possa executar o arquivo executável como apenas codeql.

Agora você pode executar comandos CodeQL.

Verificação da configuração da CLI

Você pode executar subcomandos da CLI do CodeQL para verificar se configurou corretamente a CLI e pode analisar bancos de dados:

• Execute codeql resolve packs (se você adicionou codeql a PATH) para mostrar quais packs CodeQL a CLI pode encontrar. Caso contrário, use /<extraction-root>/codeql/codeql resolve packs. Esse comando exibe os nomes dos pacotes CodeQL incluídos no pacote da CLI do CodeQL, mostrados nas etapas anteriores como <extraction-root>.

  Se a CLI do CodeQL não encontrar os pacotes CodeQL para os idiomas esperados, verifique se você baixou o pacote CodeQL e não uma cópia autônoma da CLI do CodeQL.

• Execute codeql resolve languages para mostrar quais idiomas o pacote da CLI do CodeQL dá suporte por padrão.

Criação do banco de dados

Crie um banco de dados CodeQL executando esse comando na raiz de check-out do seu projeto:

codeql database create <database> --language=<language-identifier>

No comando:

• Substitua <database> pelo caminho para o novo banco de dados a ser criado.
• Substitua <language-identifier> pelo identificador do idioma que você está usando para criar o banco de dados. Você pode usar esse identificador --db-cluster para aceitar listas separadas por vírgula ou especifique-o mais de uma vez.

Você também pode especificar as opções a seguir. Essas opções dependem do local do arquivo de origem, se o código precisa ser compilado ou se você deseja criar bancos de dados CodeQL para mais de um idioma.

• Use --source-root para identificar a pasta raiz dos arquivos de origem primários para a criação do banco de dados.
• Use --db-cluster para bases de código de vários idiomas quando quiser criar bancos de dados para mais de um idioma.
• Use --command quando criar um banco de dados para um ou mais idiomas compilados. Você não precisará dessa opção se estiver usando apenas Python e JavaScript.
• Use --no-run-unnecessary-builds junto com --db-cluster para suprimir o comando de build para idiomas em que a CLI do CodeQL não precisa monitorar o build.

Depois de criar o banco de dados com êxito, um novo diretório será exibido no caminho especificado no comando. Se você usou a opção --db-cluster para criar mais de um banco de dados, um subdiretório será criado para cada idioma.

Cada diretório de banco de dados CodeQL contém vários subdiretórios, incluindo os dados relacionais usados para análise e um arquivo de origem. O arquivo de origem é uma cópia dos arquivos de origem feitos no momento em que você criou o banco de dados. O CodeQL o usa para exibir os resultados da análise.

Extratores

Um extrator é uma ferramenta que produz dados relacionais e referência de origem para cada arquivo de entrada, a partir do qual um banco de dados CodeQL pode ser criado. Cada idioma compatível com CodeQL tem um extrator. Essa estrutura garante que o processo de extração seja o mais preciso possível.

Cada extrator define seu próprio conjunto de opções de configuração. codeql resolve extractor --format=betterjson Inserir resultados em dados formatados como o exemplo a seguir:

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

Para descobrir quais opções estão disponíveis para o extrator do idioma, insira codeql resolve languages --format=betterjson ou codeql resolve extractor --format=betterjson. O formato de saída betterjson também fornece a raiz do extrator e outras opções específicas da linguagem de programação.

Dados em um banco de dados CodeQL

Um banco de dados CodeQL é um único diretório que contém todos os dados necessários para análise. Esses dados incluem dados relacionais, arquivos de origem copiados e um esquema de banco de dados específico à linguagem que especifica as relações mútuas nos dados. O CodeQL importa esses dados após a extração.

Os bancos de dados CodeQL fornecem um instantâneo dos dados de consulta de uma linguagem específica que foram extraídos de uma base de código. Esses dados são uma representação hierárquica completa do código. Ele inclui uma representação da árvore de sintaxe abstrata, do grafo de fluxo de dados e do grafo de fluxo de controle.

Os bancos de dados são gerados um idioma de cada vez para bases de código de vários idiomas. Cada idioma tem seu próprio esquema de banco de dados exclusivo. O esquema fornece uma interface entre a análise lexical inicial durante o processo de extração e a análise complexa por meio do CodeQL.

Um banco de dados CodeQL inclui duas tabelas principais:

• A expressions tabela contém uma linha para cada expressão no código-fonte que o CodeQL analisou durante o processo de build.
• A statements tabela contém uma linha para cada instrução no código-fonte que o CodeQL analisou durante o processo de build.

A biblioteca CodeQL define classes para fornecer uma camada de abstração sobre cada uma dessas tabelas. Essa camada inclui as tabelas auxiliares relacionadas Expr e Stmt.

Possíveis deficiências do CodeQL

A criação de banco de dados no fluxo de trabalho de verificação de código tem algumas possíveis deficiências. Esta seção aborda especificamente o uso da ação CodeQL do GitHub.

Você precisa usar uma matriz de linguagem para autobuild para criar cada uma das linguagens compiladas listadas na matriz. Você pode usar uma matriz para criar trabalhos para mais de uma versão com suporte de uma linguagem de programação, sistema operacional ou ferramenta.

Se você não usar uma matriz, autobuild tentará compilar o idioma suportado que possui o maior número de arquivos fonte no repositório. A análise de idiomas compilados, além do Go, geralmente falha, a menos que você forneça comandos explícitos para criar o código antes de executar a etapa de análise.

O comportamento da autobuild etapa varia dependendo do sistema operacional no qual o extrator de idioma é executado. A autobuild etapa tenta detectar automaticamente um método de build adequado para o idioma com base no sistema operacional. Esse comportamento pode levar a resultados não confiáveis para idiomas compilados e, muitas vezes, pode resultar em uma execução com falha.

Recomendamos que você configure uma etapa de build dentro do arquivo de fluxo de trabalho de varredura de código que seja executada antes da análise, em vez de deixar que autobuild tente compilar linguagens. Dessa forma, o arquivo de fluxo de trabalho é adaptado aos requisitos de build do seu sistema e do projeto para verificações mais confiáveis.

Você pode ler mais sobre idiomas específicos e as autobuild etapas na documentação de construção automática do CodeQL.

Extensão do VS Code

Você pode usar o Vs Code (Visual Studio Code) e a extensão CodeQL para compilar e executar consultas, desde que você esteja usando o VS Code 1.39 ou posterior. Você pode baixar a extensão do Visual Studio Code Marketplace ou baixando o arquivo VSIX do CodeQL.

A extensão usa a CLI instalada encontrada em PATH, se ela estiver disponível. Caso contrário, a extensão gerencia automaticamente o acesso ao arquivo executável da CLI para você. O gerenciamento automático garante que a CLI seja compatível com a extensão CodeQL.