Exécution de requêtes CodeQL à grande échelle avec l’analyse de variantes multi-référentiels

À propos de l’exécution de requêtes CodeQL à grande échelle avec l’analyse de variantes multi-référentiels

Avec l’analyse de variantes multi-référentiels (MRVA), vous pouvez exécuter des requêtes CodeQL sur une liste allant jusqu’à 1000 référentiels sur GitHub depuis Visual Studio Code.

Lorsque vous exécutez MRVA sur une liste de référentiels, votre requête est exécutée sur chaque référentiel avec une base de données CodeQL disponible pour analyser. GitHub crée et stocke la base de données CodeQL la plus récente pour les branches par défaut de milliers de référentiels publics, y compris chaque référentiel qui exécute code scanning en utilisant CodeQL.

Vous devez activer code scanning à l’aide de CodeQL sur GitHub, à l’aide de la configuration par défaut ou de la configuration avancée, avant d’ajouter votre dépôt à une liste pour analyse. Pour plus d’informations sur l’activation code scanning à l’aide de CodeQL, consultez « Définition de la configuration par défaut pour l’analyse du code ».

Comment MRVA exécute des requêtes sur les bases de données CodeQL sur GitHub.com

Lorsque vous exécutez MRVA, l’analyse est entièrement exécutée à l’aide de GitHub Actions. Vous n’avez pas besoin de créer de flux de travail, mais vous devez spécifier quel référentiel le CodeQL pour l’extension Visual Studio Code doit utiliser en tant que référentiel de contrôleur. À mesure que l’analyse de chaque référentiel se termine, les résultats sont envoyés à VS Code pour vous permettre d’afficher.

L’extension CodeQL génère un pack CodeQL avec votre bibliothèque et toutes les dépendances de bibliothèque. Le pack CodeQL et votre liste de référentiels sélectionnés sont publiés sur un point de terminaison d’API sur GitHub, ce qui déclenche un flux de travail dynamique GitHub Actions dans votre référentiel de contrôleur. Le flux de travail fait tourner plusieurs projets parallèles pour exécuter la requête CodeQL sur les référentiels de la liste, en optimisant l’exécution des requêtes. À mesure que chaque référentiel est analysé, les résultats sont traités et affichés dans VS Code.

Prérequis

• Vous devez définir un référentiel de contrôleur avant de pouvoir exécuter votre première analyse de variantes multi-référentiels.

• Les référentiels de contrôleur peuvent être vides, mais ils doivent avoir au moins une validation.

• Sur GitHub.com, la visibilité du référentiel de contrôleur peut être « publique » si vous envisagez d’analyser uniquement les référentiels publics. L’analyse des variantes sera gratuite.

• La visibilité du référentiel de contrôleur doit être « privée » si vous devez analyser des référentiels privés ou internes sur GitHub.com.

Toutes les minutes d’actions que vous utilisez pour exécuter l’analyse de variantes sur des référentiels privés ou internes, au-dessus de la limite gratuite, sont facturées au propriétaire du référentiel. Pour plus d’informations sur les minutes gratuites et la facturation, consultez « Facturation GitHub Actions ».

Configuration d’un référentiel de contrôleurs pour MRVA

1. Dans la vue « Référentiels d’analyse de variantes », cliquez sur Configurer le référentiel de contrôleurs pour afficher un champ pour le référentiel de contrôleurs.

   

2. Saisissez le propriétaire et le nom du référentiel sur GitHub que vous souhaitez utiliser comme votre référentiel de contrôleur et appuyez sur la touche Entrée.

3. Si vous êtes invité à vous authentifier avec GitHub, suivez les instructions et connectez-vous à votre compte. Une fois que vous avez terminé, une invite de l’authentification GitHub peut demander l’autorisation d’ouvrir dans Visual Studio Code, cliquez sur Ouvrir.

Le nom du référentiel du contrôleur est enregistré dans vos paramètres pour l’extension CodeQL. Pour plus d’informations sur la modification du référentiel du contrôleur, consultez « Personnaliser les paramètres ».

Exécution d’une requête à grande échelle à l’aide de MRVA

1. Par défaut, la vue « Référentiels d’analyse de variantes » affiche les listes par défaut des 10 premiers, 100 premiers et 1000 dépôts publics sur GitHub.com pour la langue que vous analysez. Si votre référentiel de contrôleur est hébergé sur SUBDOMAIN.ghe.com, ces listes ne sont pas disponibles.

2. Si vous le souhaitez, vous pouvez ajouter un nouveau référentiel, une organisation ou une liste.

   1. Dans la vue « Référentiels d’analyse de variantes », cliquez + pour ajouter une nouvelle base de données.

   2. Dans le menu déroulant, sélectionnez ** Dans un référentiel GitHub** ou Tous les référentiels de l’org ou du propriétaire GitHub.

   3. Tapez l’identificateur du référentiel ou de l’organisation que vous souhaitez utiliser dans le champ.

3. Sélectionnez le référentiel ou les référentiels GitHub sur lesquels vous souhaitez exécuter votre requête.

   

4. Ouvrez la requête que vous souhaitez exécuter, cliquez avec le bouton droit dans le fichier de requête, puis sélectionnez CodeQL : Exécutez l’analyse des variantes pour démarrer l’analyse de variantes.

Sélection d’un référentiel ou d’une organisation GitHub pour l’analyse

1. Dans la vue « Référentiels d’analyse de variantes », cliquez + pour ajouter une nouvelle base de données.

2. Dans le menu déroulant, sélectionnez ** Dans un référentiel GitHub** ou Tous les référentiels de l’org ou du propriétaire GitHub.

3. Tapez l’identificateur du référentiel ou de l’organisation que vous souhaitez utiliser dans le champ.

Erreurs et avertissements

Lorsque vous exécutez MRVA, il existe deux emplacements clés où les erreurs et les avertissements sont affichés :

• Erreurs Visual Studio Code : les problèmes liés à la création d’un pack CodeQL et à l’envoi de l’analyse à GitHub sont signalés en tant qu’erreurs Visual Studio Code dans le coin inférieur droit de l’application. Les informations sont également disponibles dans la vue « Problèmes ».

• « Résultats de l’analyse de variantes » : tous les problèmes liés à l’exécution d’analyse de variante sont signalés dans cette vue.

Exploration de vos résultats

Dès qu’un flux de travail pour exécuter votre analyse de variantes sur GitHub est en cours d’exécution, une vue « Résultats de l’analyse de variantes » s’ouvre pour afficher les résultats dès qu’ils sont prêts. Vous pouvez utiliser cette vue pour surveiller la progression, voir les erreurs et accéder aux journaux de flux de travail dans votre référentiel de contrôleur.

Lorsque votre exécution d’analyse de variantes est planifiée, la vue « Résultats » s’ouvre automatiquement. Initialement, l’affichage affiche une liste de chaque référentiel qui a été planifié pour l’analyse. À mesure que chaque référentiel est analysé, la vue est mise à jour pour afficher un résumé du nombre de résultats. Pour afficher les résultats détaillés d’un référentiel (y compris les chemins d’accès aux résultats), cliquez sur le nom du référentiel.

Pour chaque référentiel, vous pouvez voir :

• Nombre de résultats trouvés par la requête

• Visibilité du référentiel

• Indique si l’analyse est toujours en cours d’exécution ou si elle est terminé

• Nombre d’étoiles que le référentiel contient sur GitHub

Affichage des résultats d’un référentiel

1. Cliquez sur le nom du référentiel pour afficher un résumé de chaque résultat.

2. Explorez les informations disponibles pour chaque résultat à l’aide de liens vers les fichiers sources sur GitHub. Pour les requêtes de flux de données, il y aura un lien supplémentaire « Afficher les chemins ».

   

Exporter vos résultats

Vous pouvez exporter vos résultats pour une analyse plus approfondie ou pour les discuter avec des collaborateurs. Dans la vue « Résultats », cliquez sur Exporter les résultats pour exporter les résultats vers un gist secret sur GitHub ou vers un fichier Markdown dans votre espace de travail.

Création d’une liste personnalisée de référentiels

1. Dans la vue « Référentiels d’analyse de variantes », cliquez sur l’icône « Ajouter une liste ».

   

2. Tapez le nom de la nouvelle liste, puis appuyez sur Entrée.

3. Sélectionnez votre liste dans l’affichage, puis cliquez sur + pour ajouter un référentiel à votre liste.

Gestion de vos listes personnalisées de référentiels

Vous pouvez gérer et modifier vos listes personnalisées en cliquant avec le bouton droit sur le nom de la liste ou un nom de référentiel dans la liste, puis en sélectionnant une option dans le menu local.

Les listes personnalisées sont stockées dans votre espace de travail dans un fichier databases.json. Si vous souhaitez modifier ce fichier directement dans Visual Studio Code, vous pouvez l’ouvrir en cliquant sur { } dans l’en-tête d’affichage.

Par exemple, si vous souhaitez continuer à analyser un ensemble de référentiels ayant des résultats pour votre requête, cliquez sur Copier la liste des référentiels dans la vue « Résultats de l’analyse des variantes » pour ajouter une liste des seuls référentiels qui ont des résultats dans le presse-papiers en tant que JSON.

Dans l’exemple d’extrait de code suivant, my-organization/my-repository les résultats d’une requête ont été obtenus :

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

Vous pouvez ensuite insérer le new-repo-list des référentiels databases.jsonpour faciliter l’accès dans la vue « Référentiels d’analyse de variantes ».

Utilisation de la recherche de code GitHub pour ajouter des référentiels à une liste personnalisée

Vous pouvez utiliser la recherche de code directement dans l’extension CodeQL pour ajouter un sous-ensemble de référentiels depuis GitHub vers une liste personnalisée.

Par exemple, pour ajouter tous les référentiels de l’organisation rails sur GitHub, recherchez org:rails.

Vous pouvez ajouter un maximum de 1 000 référentiels à une liste personnalisée par recherche.

1. Dans la vue « Référentiels d’analyse de variantes », choisissez la liste à laquelle vous souhaitez ajouter des référentiels. Vous pouvez créer une liste ou choisir une liste existante qui contient déjà des référentiels.

2. Cliquez avec le bouton droit de la souris sur la liste que vous avez choisie, puis cliquez sur Ajouter des dépôts avec GitHub recherche de code.

3. Dans la fenêtre contextuelle qui s’affiche en haut de l’application, sous la barre de recherche, sélectionnez une langue pour votre recherche dans les choix de la liste déroulante.

4. Dans la barre de recherche, tapez la requête de recherche que vous souhaitez utiliser et appuyez sur Entrée.

Vous pouvez afficher la progression de votre recherche dans le coin inférieur droit de l’application dans une zone avec le texte Searching for repositories.... Si vous cliquez sur Annuler, aucun référentiel n’est ajouté à votre liste. Une fois l’opération terminée, vous verrez que les référentiels qui en résultent apparaissent dans la liste déroulante sous votre liste personnalisée dans la vue Référentiels d’analyse de variantes.

Certains référentiels résultants n’ont pas de bases de données CodeQL et certains peuvent ne pas autoriser l’accès par l’extension CodeQL pour Visual Studio Code. Lorsque vous exécutez une analyse sur la liste, la vue « Résultats de l’analyse des variantes » affiche les référentiels qui ont été analysés, qui ont refusé l’accès et qui n’ont pas de base de données CodeQL.

Exécution de requêtes CodeQL avec analyse de variantes multi-référentiels sur des exécuteurs auto-hébergés

Pour exécuter des requêtes CodeQL avec analyse de variantes multi-référentiels sur des exécuteurs auto-hébergés, vous devez tout d’abord vous assurer que vous avez ajouté un exécuteur auto-hébergé à votre référentiel de contrôleurs, ou vous assurer que le référentiel du contrôleur a accès à un exécuteur au niveau de l’organisation ou de l’entreprise.

Vous devez ensuite ajouter une nouvelle variable de référentiel Actions dans votre référentiel de contrôleurs avec le nom MRVA_RUNNER_OS contenant une liste au format JSON des étiquettes de l’exécuteur auto-hébergé que vous souhaitez utiliser. Par exemple :

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

Pour plus d’informations, consultez « Ajout d’exécuteurs auto-hébergés » et « Gestion de l’accès aux exécuteurs auto-hébergés à l’aide de groupes ».

Lorsque vous exécutez une requête avec l’analyse de variantes multi-référentiels sur un exécuteur auto-hébergé, l’analyse est entièrement exécutée sur l’exécuteur auto-hébergé. Vous n’avez pas besoin de créer de nouveaux flux de travail, mais vous devez spécifier quel référentiel le CodeQL pour l’extension Visual Studio Code doit utiliser en tant que référentiel de contrôleur. À mesure que l’analyse de chaque référentiel se termine, les résultats sont envoyés à VS Code pour vous permettre d’afficher.