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 análise de variantes de vários repositórios (MRVA), você pode executar consultas do CodeQL em uma lista de até 1.000 repositórios em GitHub.com no 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 ao branch padrão de milhares de repositórios públicos, incluindo todos os repositórios que executam code scanning usando o 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 padrão da 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 deve especificar qual repositório do GitHub a extensão do CodeQL para Visual Studio Code deve usar como 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 em GitHub.com, o que aciona 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.

• A visibilidade do repositório do controlador pode ser "pública" caso planeje analisar repositórios públicos. A análise das variantes será gratuita.

• A visibilidade do repositório do controlador deve ser "privada" caso precise analisar quaisquer repositórios privados ou internos. Quaisquer minutos de ações usados pela análise de variantes, acima do limite gratuito, serã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 em GitHub.com que você deseja usar como repositório do controlador e pressione a tecla Enter.

3. Se você for solicitado a autenticar com o GitHub, siga as instruções e entre em sua conta pessoal ou da organização. Quando terminar, uma solicitação da autenticação do GitHub poderá pedir permissão para abrir no Visual Studio Code, clique em Abrir.

O nome do repositório do controlador é salvo em suas configurações para a extensão do CodeQL. Para obter informações sobre 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.

2. Opcionalmente, você pode adicionar um novo repositório, organização ou lista. Para obter mais informações, consulte "Criar listas personalizadas de repositórios".

3. Selecione em qual repositório, ou repositórios, do GitHub você deseja executar sua 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.

Erros e avisos

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

• Erros do Visual Studio Code: quaisquer problemas com a criação de um pacote do CodeQL e o envio da análise para GitHub.com 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, o modo de exibição "Resultados da Análise de Variantes" será aberto para exibir os resultados à medida que estiverem 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 em GitHub.com. 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. No modo de exibição "Resultados", clique em Exportar resultados para exportar os resultados para um gist secreto em GitHub.com ou para um arquivo Markdown em seu espaço de trabalho.

Selecionar um único repositório ou organização 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 do GitHub ou Todos os repositórios da organização ou do proprietário do GitHub.

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

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".

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 do CodeQL para adicionar um subconjunto de repositórios de GitHub.com a uma lista personalizada.

Por exemplo, para adicionar todos os repositórios na 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 Adicionar repositórios com a pesquisa de código do GitHub.

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.