Usar o editor de modelos do CodeQL

Sobre o editor de modelos do CodeQL

Com os pacotes de modelo do CodeQL, você pode expandir sua análise de code scanning do CodeQL para reconhecer bibliotecas e estruturas personalizadas usadas por sua base de código que não são compatíveis por padrão. Com o editor de modelos do CodeQL, você pode criar seus próprios pacotes de modelos. O editor de modelos guia você pela modelagem das chamadas para dependências externas em seu aplicativo ou pela modelagem completa de todos os pontos públicos de entrada e saída em uma dependência externa.

Para saber mais sobre como personalizar a análise de code scanning com pacotes de modelos confira Editar as definições da configuração padrão e Personalizando a configuração avançada para varredura de código.

Quando você abre o editor de modelos, ele analisa o banco de dados do CodeQL selecionado no momento e identifica onde o aplicativo usa APIs externas e todos os métodos públicos. Uma API externa (ou de terceiros) é qualquer API que não faz parte do banco de dados do CodeQL selecionado.

O editor de modelos tem dois modos diferentes:

• Modo de aplicativo (modo de exibição padrão): o editor lista cada estrutura externa usada pelo banco de dados do CodeQL selecionado. Quando você expande uma estrutura, uma lista de todas as chamadas de e para a API externa é mostrada com as opções disponíveis para modelar o fluxo de dados por meio de cada chamada. Esse modo é mais útil para melhorar os resultados do CodeQL para uma base de código específica.

• Modo de dependência: o editor identifica todas as APIs acessíveis publicamente no banco de dados do CodeQL selecionado. Esse modo de exibição guia você pela modelagem de cada API pública que a base de código disponibiliza. Quando terminar de modelar toda a API, você poderá salvar o modelo e usá-lo para melhorar a análise do CodeQL para todas as bases de código que usam a dependência.

O restante deste artigo aborda os aspectos práticos das dependências de modelos usando o editor de modelos CodeQL. Para obter informações técnicas, consulte Personalizando modelos de biblioteca para Java e Kotlin, Personalizando modelos de biblioteca para Ruby e Personalizando modelos de biblioteca para C# na documentação da linguagem de CodeQL.

Exibir o editor de modelos do CodeQL

1. Abra seu espaço de trabalho do CodeQL no VS Code. Por exemplo, o espaço de trabalho vscode-codeql-starter. Se você estiver usando o espaço de trabalho inicial, atualize o submódulo ql de main para garantir que você tenha as consultas usadas para coletar dados para o editor de modelos.

2. No Visual Studio Code, clique em QL na barra lateral esquerda para exibir a extensão do CodeQL.

3. No modo de exibição "Bancos de Dados", selecione o banco de dados do CodeQL do qual você deseja modelar.

4. No modo de exibição "Modelagem de Método" do CodeQL, clique em Iniciar modelagem para exibir o editor de modelos. Como alternativa, use o VS Code Command Palette para executar o comando CodeQL: Open Model Editor (Beta).

5. O editor de modelos do CodeQL executa uma série de consultas de telemetria para identificar APIs no código, e o editor é exibido em uma nova guia.

6. Quando as consultas de telemetria são concluídas, as APIs que foram identificadas são mostradas no editor.

Modelar as chamadas que sua base de código faz para APIs externas

Normalmente, você usa essa abordagem quando está examinando uma base de código específica na qual deseja melhorar a precisão dos resultados do CodeQL. Isso é útil quando a base de código usa estruturas ou bibliotecas que não são compatíveis com o CodeQL e se o código-fonte da estrutura ou biblioteca não está incluído na análise.

Esta seção usa um projeto Java de código aberto chamado "sofa-jraft" como exemplo. A experiência de modelagem de chamadas para APIs externas escritas em outras linguagens compiladas é semelhante.

1. No Visual Studio Code, selecione o banco de dados do CodeQL para o qual você deseja melhorar a cobertura do CodeQL.

2. Exibir o editor de modelos do CodeQL. Por padrão, o editor é executado no modo de aplicativo, portanto, a lista de APIs externas usadas pela base de código selecionada é mostrada.

   

3. Clique para expandir uma API externa e exibir a lista de chamadas da base de código para a dependência externa.

   

4. Clique em Exibir associado a um método ou chamada de API para mostrar onde ele é usado em sua base de código.

5. O arquivo que contém a primeira chamada da base de código para a API é aberto e um modo de exibição "Uso de Métodos" do CodeQL é exibido no VS Code (em que os modos de exibição "Problemas" e "Terminal" geralmente são exibidos). O modo de exibição "Uso de Métodos" do CodeQL lista todas as chamadas do seu código para a API, agrupadas por método. Você pode clicar em cada uso para decidir como modelar seu uso do método.

6. Depois de determinar como modelar o uso do método, você pode selecionar um tipo de modelo diferente. Clique na lista suspensa em "Tipo de Modelo" no modo de exibição "Modelagem de Método" do CodeQL da extensão do CodeQL. Essa alteração é refletida automaticamente no editor de modelos principal.

7. Os campos restantes nessa linha são atualizados com as opções disponíveis para o tipo de modelo escolhido:

   • "Origem": escolha o elemento "Output" para modelar.
   • "Coletor": escolha o elemento "Input" para modelar.
   • "Resumo do fluxo": escolha os elementos "Input" e "Output" para modelar.

8. Defina o "Tipo" de fluxo de dados para o modelo.

9. Quando terminar a modelagem, exiba o editor de modelos principal e clique em Salvar tudo ou Salvar (mostrado no canto inferior direito de cada lista expandida de métodos). A porcentagem de métodos modelados no editor é atualizada.

Os modelos são armazenados em seu espaço de trabalho em .github/codeql/extensions/CODEQL-MODEl-PACK, em que CODEQL-MODEL-PACK é o nome do banco de dados do CodeQL selecionado. Ou seja, o nome do repositório, o hífen e a linguagem analisada pelo CodeQL. Para saber mais, confira Como criar e trabalhar com pacotes do CodeQL.

Os modelos são armazenados em uma série de arquivos de extensão de dados YAML, um para cada API externa. Por exemplo:

.github/codeql/extensions/sofa-jraft-java # the model pack directory
    models
        jmh-core.model.yml                  # models calls to jmh-core@1.20
        rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3

Modelar a API pública de uma base de código

Normalmente, você usa esse método quando deseja modelar uma estrutura ou biblioteca que sua organização usa em mais de uma base de código. Depois de concluir a criação e o teste do modelo, você pode publicar o pacote de modelos do CodeQL no GitHub Container registry para toda a organização usar.

Esta seção usa um projeto Java de código aberto chamado "sofa-jraft" como exemplo. A experiência de modelagem de chamadas para APIs externas escritas em outras linguagens compiladas é semelhante.

1. Selecione o banco de dados do CodeQL que você deseja modelar.

2. Exibir o editor de modelos do CodeQL. Por padrão, o editor é executado no modo de aplicativo. Clique em Modelo como dependência para exibir o modo de dependência. A tela muda para mostrar a API pública da estrutura ou biblioteca.

   

3. Clique para expandir um pacote e exibir a lista de métodos disponíveis.

4. Clique em Exibir associado a um método para mostrar sua definição.

   

5. Quando você tiver determinado como modelar o método, defina o "Tipo de Modelo".

6. Os campos restantes nessa linha são atualizados com as opções disponíveis para o tipo de modelo escolhido:

   • "Origem": escolha o elemento "Output" para modelar.
   • "Coletor": escolha o elemento "Input" para modelar.
   • "Resumo do fluxo": escolha os elementos "Input" e "Output" para modelar.

7. Defina o "Tipo" de fluxo de dados para o modelo.

8. Quando terminar a modelagem, clique em Salvar tudo ou Salvar (mostrado no canto inferior direito de cada lista expandida de chamadas). A porcentagem de chamadas modeladas no editor é atualizada.

Os modelos são armazenados em seu espaço de trabalho em .github/codeql/extensions/CODEQL-MODEL-PACK, em que CODEQL-MODEL-PACK é o nome do banco de dados do CodeQL selecionado. Ou seja, o nome do repositório, o hífen e a linguagem analisada pelo CodeQL. Para saber mais, confira Como criar e trabalhar com pacotes do CodeQL.

Os modelos são armazenados em uma série de arquivos de extensão de dados YAML, um para cada método público. Por exemplo:

.github/codeql/extensions/sofa-jraft-java          # the model pack directory
    models
        com.alipay.sofa.jraft.option.model.yml # models public methods in package
        com.alipay.sofa.jraft.rhea.options.model.yml

O editor criará um arquivo de modelo separado para cada pacote que você modelar.

Métodos de modelagem com múltiplos fluxos potenciais

Alguns métodos são compatíveis com mais de um fluxo de dados. É importante modelar todos os fluxos de dados para um método, caso contrário, você pode não detectar todos os problemas potenciais associados ao uso do método. Primeiro, modele um fluxo de dados para o método e, em seguida, use o botão + na linha do método para especificar um segundo modelo de fluxo de dados.

Testar os pacotes de modelos do CodeQL no VS Code

Você pode testar quaisquer pacotes de modelos do CodeQL criados no VS Code com a configuração "Consultas em Execução: Usar Pacotes de Extensão". Para saber mais, confira Configurações personalizadas. Esse método funciona tanto para bancos de dados quanto para repositórios de análise de variantes.

• Para executar consultas em um banco de dados do CodeQL com quaisquer pacotes de modelos armazenados no diretório .github/codeql/extensions do espaço de trabalho, atualize seu arquivo settings.json com: "codeQL.runningQueries.useExtensionPacks": "all",

• Para executar consultas em um banco de dados do CodeQL sem usar pacotes de modelos, atualize seu arquivo settings.json com: "codeQL.runningQueries.useExtensionPacks": "none",

Se o seu modelo estiver funcionando bem, você verá uma diferença nos resultados das duas execuções diferentes. Se você não vir nenhuma diferença nos resultados, talvez seja necessário introduzir um bug conhecido para verificar se o modelo se comporta conforme o esperado.

Leitura adicional

• Editar as definições da configuração padrão
• Personalizando a configuração avançada para varredura de código Como personalizar a análise com pacotes CodeQL.