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

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

Pré-requisitos

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

• 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 deve ser hospedado no mesmo site que os repositórios que você deseja analisar usando o MRVA, ou seja: GitHub.com ou SUBDOMAIN.ghe.com. Se você quiser executar o MRVA em GitHub Enterprise Cloud com residência de dados, consulte Alterando a URL GitHub usada pela extensão.

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

• A visibilidade do repositório do controlador deve ser "privada" se você precisar acessar quaisquer repositórios privados ou internos em 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, consulte Cobrança do 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 qual você deseja usar como repositório do controlador e pressione a tecla Enter . Esse repositório deve estar na mesma instância dos GitHub repositórios que você deseja analisar, consulte Alterando a GitHub URL usada pela extensão.

3. Se for solicitado que você se autentique, GitHubsiga as instruções e entre em sua conta. Quando você terminar, um prompt da GitHub Autenticação poderá pedir permissão para abrir em Visual Studio Code, clique em Abrir.

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

Executar uma consulta em escala usando MRVA

1. Por padrão, a visualização "Repositórios de Análise Variante" mostra as listas padrão dos Top 10, Top 100 e Top 1000 repositórios públicos GitHub.com para o idioma que você está analisando. Se o repositório do controlador estiver hospedado 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 GitHub repositório ou De todos os repositórios da GitHub organização ou proprietário.

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

3. Selecione em qual GitHub repositório ou repositórios você deseja executar sua consulta.

   

4. Abra a consulta que você deseja executar, clique com o botão direito do mouse no arquivo de consulta e selecione CodeQL: Executar Análise Variant para iniciar a análise variante.

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

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:

•           Visual Studio Code erros: todos os problemas com a criação de um CodeQL pacote e o envio da GitHub análise são relatados como Visual Studio Code erros 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.

Explorando seus resultados

Assim que o fluxo de trabalho para executar sua análise de variantes em GitHub estiver em execução, uma visão dos "Resultados da Análise de Variantes" será aberta 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 painel "Resultados" é aberto 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 em 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 links para os arquivos de origem em 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. No modo de exibição "Resultados", clique em Exportar resultados para exportar os resultados para uma gist secreta no GitHub ou para um arquivo Markdown em seu workspace.

Criar uma lista personalizada de repositórios

          CodeQL a análise sempre requer um CodeQL banco de dados para executar consultas. Quando você executa a análise variante em uma lista de repositórios, sua consulta será executada somente nos repositórios que atualmente têm um CodeQL banco de dados disponível para download. A melhor maneira de disponibilizar um repositório para análise variante é habilitar code scanning com CodeQL. Para obter informações sobre como habilitar code scanning usando CodeQL, consulte [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning).

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. Se você quiser editar este arquivo diretamente em Visual Studio Code, poderá abri-lo clicando em { } na barra de cabeçalho.

Por exemplo, se quiser continuar analisando um conjunto de repositórios que apresentaram resultados para sua consulta, clique em Copiar lista de repositórios na visualização "Resultados da Análise de Variantes" para copiar para a área de transferência, em formato JSON, somente os repositórios que têm resultados.

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.jsonpara facilitar o acesso no modo de exibição "Repositórios de Análise de Variantes".

Usando GitHub a pesquisa de código para adicionar repositórios a uma lista personalizada

Você pode usar a pesquisa de código diretamente na CodeQL extensão para adicionar um subconjunto de repositórios de 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 clique em Adicionar repositórios com GitHub a pesquisa de código.

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 no menu de seleção dentro da sua lista personalizada na visualização Repositórios de Análise de Variantes.

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

Executando CodeQL consultas com análise de variantes em múltiplos repositórios usando executores auto-hospedados

Para executar CodeQL consultas com análise de variantes em múltiplos repositórios em executores auto-hospedados, primeiro você precisa garantir que tenha adicionado um executor auto-hospedado ao repositório do controlador ou garantir que o repositório do controlador tenha acesso a um executor em nível organizacional ou empresarial.

Em seguida, você precisa adicionar uma nova variável de repositório do Actions no repositório do controlador com o nome MRVA_RUNNER_OS, que contém uma lista formatada em JSON dos rótulos do executor auto-hospedado que deseja usar. Por exemplo:

["self-hosted", "macOS", "ARM64"]

Para obter mais informações, consulte Adicionar executores auto-hospedados e Gerenciar o acesso a executores auto-hospedados usando grupos.

Quando você executa uma consulta com análise de variante de vários repositórios em um executor auto-hospedado, a análise é executada inteiramente no executor auto-hospedado. Você não precisa criar novos fluxos de trabalho, mas deve especificar qual repositório a CodeQLVisual Studio Code extensão deve ser usada como um repositório do controlador. À medida que a análise de cada repositório é concluída, os resultados são enviados para VS Code para você visualizar.