Usar o editor de modelos do CodeQL

Sobre o editor CodeQL de modelos

Com CodeQL pacotes de modelos, você pode expandir sua CodeQLcode scanning análise para reconhecer bibliotecas e estruturas personalizadas usadas pela base de código que não têm suporte por padrão. Com o CodeQL editor de modelos, 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 obter mais informações sobre como personalizar code scanning a análise com pacotes de modelos, consulte Editar as definições da configuração padrão e Opções de configuração de fluxo de trabalho para verificação de código.

Quando você abre o editor de modelos, ele analisa o banco de dados selecionado CodeQL 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 faça parte do CodeQL banco de dados selecionado.

O editor de modelos tem dois modos diferentes:

•         **Modo de aplicativo (exibição padrão)**: o editor lista cada estrutura externa usada pelo banco de dados selecionado CodeQL . 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 CodeQL resultados de uma base de código específica.
  

•         **Modo de dependência:** O editor identifica todas as APIs publicamente acessíveis no banco de dados selecionado CodeQL . 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 CodeQL análise de todas as bases de código que usam a dependência.
  

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

Exibindo o editor de modelos CodeQL

1. Abra seu CodeQL espaço de trabalho em 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. Em Visual Studio Code, clique em QL na barra lateral esquerda para exibir a CodeQL extensão.

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

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

5. O CodeQL editor de modelos 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 ao examinar uma base de código específica em que deseja melhorar a precisão dos CodeQL resultados. Isso é útil quando a base de código usa estruturas ou bibliotecas que não têm suporte CodeQLe se o código-fonte da estrutura ou biblioteca não está incluído na análise.

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

1. Em Visual Studio Code, selecione o banco de dados CodeQL que você deseja melhorar a cobertura CodeQL.

2. Exiba o editor de modelos 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 sua base de código para a API é aberto, e uma CodeQL visão "Uso de Métodos" é exibida em VS Code (onde as visões "Problemas" e "Terminal" geralmente são exibidas). A CodeQL exibição "Uso de Métodos" lista todas as chamadas do 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" na exibição CodeQL "Modelagem de Método" da CodeQL extensão. 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 workspace .github/codeql/extensions/CODEQL-MODEl-PACK, onde CODEQL-MODEL-PACK está o nome do banco de dados CodeQL selecionado. Ou seja, o nome do repositório, hífen, a linguagem analisada por CodeQL. Para obter mais informações, consulte 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 terminar de criar e testar o modelo, você poderá publicar o CodeQL pacote de modelos para toda a GitHubContainer registry sua organização usar.

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

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

2. Exiba o editor de modelo 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 workspace .github/codeql/extensions/CODEQL-MODEL-PACK, onde CODEQL-MODEL-PACK é o nome do banco de dados CodeQL selecionado. Ou seja, o nome do repositório, hífen, a linguagem analisada por CodeQL. Para obter mais informações, consulte 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.

Testando CodeQL pacotes de modelos em VS Code

Você pode testar quaisquer pacotes de modelos CodeQL que você criar em VS Code com a configuração "Executando Consultas: Usar Pacotes de Extensão". Para obter mais informações, consulte 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 CodeQL com qualquer pacote de modelo armazenado no diretório .github/codeql/extensions da área de trabalho, atualize o arquivo settings.json com: "codeQL.runningQueries.useExtensionPacks": "all",

• Para executar consultas em um CodeQL banco de dados sem usar pacotes de modelo, atualize o settings.json arquivo 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

•         [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup)
  

•         [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#codeql-model-packs)[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies).