Ejecución de consultas CodeQL a gran escala con análisis de variantes de varios repositorios

Acerca de la ejecución de consultas de CodeQL a gran escala con análisis de variantes de varios repositorios

Con el análisis de variantes de varios repositorios (MRVA), puedes ejecutar consultas de CodeQL en una lista de hasta 1000 repositorios en GitHub desde Visual Studio Code.

Al ejecutar MRVA en una lista de repositorios, la consulta se ejecuta en cada repositorio que tiene una base de datos de CodeQL disponible para analizar. GitHub crea y almacena la base de datos más reciente de CodeQL para la rama predeterminada de miles de repositorios públicos, incluidos todos los repositorios que ejecutan code scanning mediante CodeQL.

Debes habilitar code scanning con CodeQL en GitHub, usando la configuración predeterminada o la configuración avanzada, antes de añadir el repositorio a una lista para su análisis. Para obtener información sobre la habilitación de code scanning con CodeQL, consulta Establecimiento de la configuración avanzada para el examen del código.

Cómo ejecuta MRVA consultas en bases de datos de CodeQL en GitHub.com

Al ejecutar MRVA, el análisis se ejecuta completamente con GitHub Actions. No tienes que crear ningún flujo de trabajo, pero debes especificar qué repositorio debe utilizar la extensión CodeQL para Visual Studio Code como repositorio controlador. A medida que se completa el análisis de cada repositorio, los resultados se envían a VS Code para que pueda ver.

La extensión CodeQL compila un paquete de CodeQL con la biblioteca y las dependencias de la biblioteca. El paquete de CodeQL y la lista de repositorios seleccionada se publican en un punto de conexión de API en GitHub, lo que desencadena un flujo de trabajo dinámico de GitHub Actions en el repositorio del controlador. El flujo de trabajo pone en marcha varios trabajos paralelos para ejecutar la consulta de CodeQL en los repositorios de la lista, lo que optimiza la ejecución de consultas. A medida que se analiza cada repositorio, los resultados se procesan y muestran en VS Code.

Requisitos previos

• Debe definir un repositorio de controladores para poder ejecutar el primer análisis de variantes de varios repositorios.

• Los repositorios del controlador pueden estar vacíos, pero deben tener al menos una confirmación.

• El repositorio del controlador debe hospedarse en el mismo sitio que los repositorios que deseas analizar mediante MRVA, es decir, GitHub.com o SUBDOMAIN.ghe.com. Si deseas ejecutar MRVA en Nube de GitHub Enterprise con residencia de datos, consulta Cambio de la dirección URL de GitHub usada por la extensión.

• En GitHub.com, la visibilidad del repositorio del controlador puede ser "pública" si tiene previsto analizar solo repositorios públicos. El análisis de variantes será gratuito.

• La visibilidad del repositorio del controlador debe ser “privada” si necesita analizar cualquier repositorio privado o interno en GitHub.com.

Los minutos de acción que utilices para ejecutar análisis de variantes en repositorios privados o internos, por encima del límite gratuito, se cobran al propietario del repositorio. Para más información sobre los minutos gratuitos y la facturación, consulta Acerca de la facturación para las Acciones de GitHub.

Configuración de un repositorio de controlador para MRVA

1. En la vista “Repositorios de análisis de variantes”, haga clic en Configurar repositorio de controladores para mostrar un campo para el repositorio de controladores.

   

2. Escribe el propietario y el nombre del repositorio en GitHub que deseas usar como repositorio del controlador y presione la tecla Entrar. Este repositorio debe estar en la misma instancia de GitHub que los repositorios que deseas analizar, consulta Cambio de la dirección URL de GitHub usada por la extensión.

3. Si se te pide que te autentiques con GitHub, sigue las instrucciones e inicia sesión en tu cuenta. Cuando hayas terminado, una solicitud de autenticación de GitHub puede solicitar permiso para abrirse en Visual Studio Code, haz clic en Abrir.

El nombre del repositorio del controlador se guarda en la configuración de la extensión CodeQL. Para obtener información sobre cómo editar el repositorio del controlador, consulta Personalización de la configuración.

Ejecución de una consulta a gran escala mediante MRVA

1. De forma predeterminada, la vista “Repositorios de análisis de variantes” muestra las listas predeterminadas de los 10, los 100 y los 1000 repositorios públicos principales en GitHub.com para el idioma que está analizando. Si el repositorio del controlador se hospeda en SUBDOMAIN.ghe.com, estas listas no están disponibles.

2. Opcionalmente, puede agregar un nuevo repositorio o una nueva organización o lista.

   1. En la vista “Repositorios de análisis de variantes”, haga clic en + para agregar una nueva base de datos.

   2. En el menú desplegable, selecciona De un repositorio GitHub o Todos los repositorios de organizador o propietario GitHub.

   3. Escriba el identificador del repositorio o la organización que desea usar en el campo .

3. Selecciona el repositorio o repositorios de GitHub en los que deseas ejecutar tu consulta.

   

4. Abra la consulta que desea ejecutar, haga clic con el botón derecho en el archivo de consulta y seleccione CodeQL: Ejecutar análisis de variantes para iniciar el análisis de variantes.

Selección de un único repositorio de GitHub u organización para su análisis

1. En la vista “Repositorios de análisis de variantes”, haga clic en + para agregar una nueva base de datos.

2. En el menú desplegable, selecciona De un repositorio GitHub o Todos los repositorios de organizador o propietario GitHub.

3. Escriba el identificador del repositorio o la organización que desea usar en el campo .

Errores y advertencias

Al ejecutar MRVA, hay dos lugares clave en los que se muestran errores y advertencias:

• Errores de Visual Studio Code: los problemas con la creación de un paquete CodeQL y el envío del análisis a GitHub se notifican como errores de Visual Studio Code en la esquina inferior derecha de la aplicación. La información también está disponible en la vista “Problemas”.

• “Resultados de análisis de variantes”: los problemas con la ejecución de análisis de variantes se notifican en esta vista.

Exploración de los resultados

En cuanto se ejecuta un flujo de trabajo para ejecutar el análisis de variantes en GitHub, se abre una vista "Resultados de análisis de variantes" para mostrar los resultados a medida que están listos. Puede usar esta vista para supervisar el progreso, ver los errores y acceder a los registros de flujo de trabajo en el repositorio de controladores.

Cuando se programa la ejecución de análisis de variantes, se abre automáticamente la vista “Resultados”. Inicialmente, la vista muestra una lista de todos los repositorios programados para su análisis. A medida que se analiza cada repositorio, la vista se actualiza para mostrar un resumen del número de resultados. Para ver los resultados detallados de un repositorio (incluidas las rutas de acceso de resultados), haga clic en el nombre del repositorio.

Para cada repositorio, puede ver:

• Número de resultados encontrados por consulta

• Visibilidad del repositorio

• Si el análisis todavía se está ejecutando o ha finalizado

• Número de estrellas que tiene el repositorio en GitHub

Ver los resultados de un repositorio

1. Haga clic en el nombre del repositorio para mostrar un resumen de cada resultado.

2. Explora la información disponible para cada resultado mediante vínculos a los archivos de origen en GitHub. En el caso de las consultas de flujo de datos, habrá un vínculo adicional “Mostrar rutas de acceso”.

   

Exportación de los resultados

Puede exportar los resultados para su análisis adicional o analizarlos con colaboradores. En la vista "Resultados", haz clic en Exportar resultados para exportar los resultados a un gist secreto en GitHub o en un archivo Markdown en el área de trabajo.

Creación de una lista personalizada de repositorios

1. En la vista “Repositorios de análisis de variantes”, haga clic en el icono “Agregar lista”.

   

2. Escriba un nombre para la nueva lista y presione Entrar.

3. Seleccione la lista en la vista y haga clic en + para agregar un repositorio a la lista.

Administración de listas personalizadas de repositorios

Para administrar y editar las listas personalizadas, haga clic con el botón derecho en el nombre de la lista o en un nombre de repositorio dentro de la lista y seleccione una opción en el menú contextual.

Las listas personalizadas se almacenan en el área de trabajo en un archivo databases.json. Si desea editar este archivo directamente en Visual Studio Code, puede abrirlo haciendo clic en { } en el encabezado de vista.

Por ejemplo, si desea seguir analizando un conjunto de repositorios que tenían resultados para la consulta, haga clic en Copiar lista de repositorios en la vista “Resultados de análisis de variantes” para agregar una lista de solo los repositorios que tienen resultados en el portapapeles como JSON.

En el siguiente fragmento de código de ejemplo, my-organization/my-repository tenía resultados para una consulta:

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

A continuación, puede insertar los repositorios new-repo-list en databases.json para facilitar el acceso en la vista “Repositorios de análisis de variantes”.

Uso de la búsqueda de código GitHub para agregar repositorios a una lista personalizada

Puedes usar la búsqueda de código directamente en la extensión CodeQL para agregar un subconjunto de repositorios de GitHub a una lista personalizada.

Por ejemplo, para agregar todos los repositorios de la organización rails en GitHub, busca org:rails.

Puede agregar un máximo de 1000 repositorios a una lista personalizada por búsqueda.

1. En la vista “Repositorios de análisis de variantes”, elija la lista a la que desea agregar repositorios. Puede crear una lista o elegir una lista existente que ya contiene repositorios.

2. Haz clic con el botón derecho en la lista que has elegido y, a continuación, haz clic en Add repositories with GitHub code search.

3. En el elemento emergente que aparece en la parte superior de la aplicación, en la barra de búsqueda, seleccione un idioma para la búsqueda en las opciones de la lista desplegable.

4. En la barra de búsqueda, escriba la consulta de búsqueda que desea usar y presione Entrar.

Puede ver el progreso de la búsqueda en la esquina inferior derecha de la aplicación en un cuadro con el texto Searching for repositories.... Si hace clic en Cancelar, no se agregará ningún repositorio a la lista. Una vez completado, verá que los repositorios resultantes aparecen en la lista desplegable de la lista personalizada en la vista Repositorios de análisis de variantes.

Algunos de los repositorios resultantes no tendrán bases de datos de CodeQL y es posible que algunos no permitan el acceso de la extensión CodeQL para Visual Studio Code. Al ejecutar un análisis en la lista, la vista “Resultados de análisis de variantes” mostrará qué repositorios se analizaron, cuáles denegaron el acceso y cuáles no tenían una base de datos CodeQL.