Executar consultas do CodeQL em escala com análise de variantes de vários repositórios

Sobre a execução de consultas do CodeQL em escala com análise de variantes de vários repositórios

Com a MRVA (análise de variantes de vários repositórios), você pode executar consultas CodeQL em uma lista de até 1.000 repositórios no GitHub por meio do Visual Studio Code.

Quando você executa a MRVA em uma lista de repositórios, sua consulta é executada em cada repositório que tem um banco de dados do CodeQL disponível para análise. O GitHub cria e armazena o banco de dados do CodeQL mais recente para o branch padrão de milhares de repositórios públicos, incluindo todos os repositórios que executam a code scanning por meio do CodeQL.

Você precisa habilitar a code scanning usando CodeQL em GitHub, usando a configuração padrão ou a configuração avançada, antes de adicionar o repositório a uma lista para análise. Para obter informações sobre habilitar a code scanning usando o CodeQL, confira Como definir a configuração avançada para verificação de código.

Como a MRVA executa consultas em bancos de dados do CodeQL em GitHub.com

Quando você executa a MRVA, a análise é executada inteiramente usando o GitHub Actions. Você não precisa criar nenhum fluxo de trabalho, mas precisa especificar o repositório que a extensão CodeQL para Visual Studio Code deve usar como um repositório do controlador. À medida que a análise de cada repositório é concluída, os resultados são enviados para o VS Code para visualização.

A extensão do CodeQL cria um pacote do CodeQL com sua biblioteca e quaisquer dependências de biblioteca. O pacote do CodeQL e a lista de repositórios selecionados são postados em um ponto de extremidade de API no GitHub, o que dispara um fluxo de trabalho dinâmico do GitHub Actions no repositório do controlador. O fluxo de trabalho inicia vários trabalhos paralelos para executar a consulta do CodeQL nos repositórios na lista, otimizando a execução da consulta. À medida que cada repositório é analisado, os resultados são processados e exibidos no VS Code.

Pré-requisitos

• Você deve definir um repositório de controlador antes de executar sua primeira análise de variantes de vários repositórios.

• Os repositórios do controlador podem estar vazios, mas devem ter pelo menos um commit.

• O repositório do controlador precisa ser hospedado no mesmo site dos repositórios que você deseja analisar usando a MRVA, ou seja: GitHub.com ou SUBDOMAIN.ghe.com. Caso deseje executar a MRVA no GitHub Enterprise Cloud com residência de dados, confira Como alterar a URL do GitHub usada pela extensão.

• No GitHub.com, a visibilidade do repositório do controlador pode ser “pública” se você pretende analisar apenas os repositórios públicos. A análise das variantes será gratuita.

• A visibilidade do repositório do controlador precisa ser “privada” caso você precise analisar os repositórios privados ou internos do GitHub.com.

Todos os minutos de ações que você usa para executar a análise de variantes em repositórios privados ou internos acima do limite gratuito são cobrados do proprietário do repositório. Para obter mais informações sobre minutos gratuitos e cobrança, confira Sobre a cobrança das GitHub Actions.

Configurar um repositório de controlador para MRVA

1. No modo de exibição "Repositórios de Análise de Variantes", clique em Configurar repositório do controlador para exibir um campo para o repositório do controlador.

   

2. Digite o proprietário e o nome do repositório no GitHub que você deseja usar como o repositório do controlador e pressione a tecla ENTER. Esse repositório precisa estar na mesma instância do GitHub dos repositórios que você deseja analisar. Confira Como alterar a URL do GitHub usada pela extensão.

3. Se precisar se autenticar no GitHub, siga as instruções e entre na sua conta. Quando terminar, uma solicitação da Autenticação do GitHub poderá pedir permissão para abrir no Visual Studio Code. Selecione Abrir.

O nome do repositório do controlador é salvo em suas configurações para a extensão do CodeQL. Para saber como editar o repositório do controlador, confira Configurações personalizadas.

Executar uma consulta em escala usando MRVA

1. Por padrão, o modo de exibição "Repositórios de Análise de Variantes" mostra as listas padrão dos repositórios públicos Top 10, Top 100 e Top 1000 em GitHub.com para a linguagem que você está analisando. Se o repositório do controlador estiver hospedado no SUBDOMAIN.ghe.com, essas listas não estarão disponíveis.

2. Opcionalmente, você pode adicionar um novo repositório, organização ou lista.

   1. No modo de exibição "Repositórios de Análise de Variantes", clique em + para adicionar um novo banco de dados.

   2. No menu suspenso, selecione De um repositório GitHub ou Todos os repositórios do proprietário ou da organização do GitHub.

   3. Digite o identificador do repositório ou organização que você deseja usar no campo.

3. Selecione os repositórios do GitHub nos quais você deseja executar a consulta.

   

4. Abra a consulta que deseja executar, clique com o botão direito do mouse no arquivo de consulta e selecione CodeQL: Run Variant Analysis para iniciar a análise de variantes.

Como selecionar um repositório ou uma organização individual do GitHub para análise

1. No modo de exibição "Repositórios de Análise de Variantes", clique em + para adicionar um novo banco de dados.

2. No menu suspenso, selecione De um repositório GitHub ou Todos os repositórios do proprietário ou da organização do GitHub.

3. Digite o identificador do repositório ou organização que você deseja usar no campo.

Erros e avisos

Quando você executa a MRVA, há dois locais principais onde erros e avisos são exibidos:

• Erros do Visual Studio Code: qualquer problema com a criação de um pacote do CodeQL e o envio da análise para o GitHub são relatados como erros do Visual Studio Code no canto inferior direito do aplicativo. As informações também estão disponíveis no modo de exibição "Problemas".

• "Resultados da Análise de Variantes": quaisquer problemas com a execução da análise de variantes são relatados nesse modo de exibição.

Explorar os resultados

Assim que um fluxo de trabalho para executar sua análise de variantes no GitHub estiver em execução, a exibição “Resultados da Análise de Variantes” será aberta para mostrar os resultados conforme eles ficarem prontos. Você pode usar esse modo de exibição para monitorar o progresso, verificar quaisquer erros e acessar os logs do fluxo de trabalho no repositório do controlador.

Quando a execução da análise de variantes está agendada, o modo de exibição "Resultados" abre automaticamente. Inicialmente, o modo de exibição mostra uma lista de todos os repositórios que foram agendados para análise. À medida que cada repositório é analisado, o modo de exibição é atualizado para mostrar um resumo do número de resultados. Para exibir os resultados detalhados de um repositório (incluindo caminhos de resultados), clique no nome do repositório.

Para cada repositório, você poderá verificar:

• Número de resultados encontrados pela consulta

• Visibilidade do repositório

• Se a análise ainda está em execução ou se foi concluída

• Número de estrelas que o repositório tem no GitHub

Verificar os resultados de um repositório

1. Clique no nome do repositório para mostrar um resumo de cada resultado.

2. Explore as informações disponíveis para cada resultado usando os links para os arquivos de origem no GitHub. Para consultas de fluxo de dados, haverá um link adicional "Mostrar caminhos".

   

Exportar os resultados

Você pode exportar seus resultados para uma análise mais aprofundada ou para discuti-los com os colaboradores. Na exibição “Resultados”, selecione Exportar resultados para exportar os resultados para um gist secreto no GitHub ou para um arquivo Markdown no seu workspace.

Criar uma lista personalizada de repositórios

1. No modo de exibição "Repositórios de Análise de Variantes", clique no ícone de "Adicionar lista".

   

2. Digite um nome para a nova lista e pressione Enter.

3. Selecione sua lista no modo de exibição e clique em + para adicionar um repositório à sua lista.

Gerenciar suas listas personalizadas de repositórios

Você pode gerenciar e editar suas listas personalizadas clicando com o botão direito do mouse no nome da lista ou em um nome de repositório na lista e selecionando uma opção no menu de contexto.

As listas personalizadas são armazenadas em seu espaço de trabalho em um arquivo databases.json. Caso queira editar esse arquivo diretamente no Visual Studio Code, você poderá abri-lo clicando em { } no cabeçalho do modo de exibição.

Por exemplo, se quiser continuar analisando um conjunto de repositórios que tiveram resultados para sua consulta, clique em Copiar lista de repositórios no modo de exibição "Resultados da Análise de Variantes" para adicionar uma lista somente dos repositórios que têm resultados para a área de transferência como JSON.

No snippet de exemplo abaixo, my-organization/my-repository teve resultados para uma consulta:

{
    "name": "new-repo-list",
    "repositories": [
        "my-organization/my-repository"
    ]
}

Você pode então inserir o new-repo-list de repositórios em databases.json para facilitar o acesso no modo de exibição "Repositórios de Análise de Variantes".

Como usar a pesquisa de código do GitHub para adicionar repositórios a uma lista personalizada

Você pode usar a pesquisa de código diretamente na extensão CodeQL para adicionar um subconjunto de repositórios do GitHub a uma lista personalizada.

Por exemplo, para adicionar todos os repositórios da organização rails no GitHub, pesquise org:rails.

Você pode adicionar um máximo de 1.000 repositórios a uma lista personalizada por pesquisa.

1. No modo de exibição "Repositórios de Análise de Variantes", escolha a lista à qual você deseja adicionar repositórios. Você pode criar uma nova lista ou escolher uma lista existente que já contenha repositórios.

2. Clique com o botão direito do mouse na lista escolhida e depois em Add repositories with GitHub code search.

3. No pop-up que aparece na parte superior do aplicativo, na barra de pesquisa, selecione uma linguagem para sua pesquisa nas opções na lista suspensa.

4. Na barra de pesquisa, digite a consulta de pesquisa que você deseja usar e pressione Enter.

Você pode visualizar o progresso da sua pesquisa no canto inferior direito do aplicativo em uma caixa com o texto Searching for repositories.... Se você clicar em Cancelar, nenhum repositório será adicionado à sua lista. Depois de concluído, você verá os repositórios resultantes aparecerem na lista suspensa em sua lista personalizada no modo de exibição Repositórios de Análise de Variantes.

Alguns dos repositórios resultantes não terão bancos de dados do CodeQL, e alguns podem não permitir o acesso pela extensão do CodeQL para Visual Studio Code. Quando você executa uma análise na lista, o modo de exibição "Resultados da Análise de Variantes" mostrará quais repositórios foram analisados, quais negaram acesso e quais não tinham nenhum banco de dados do CodeQL.