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’à 1 000 référentiels sur GitHub.com à partir de 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 branche par défaut de milliers de référentiels publics, y compris chaque référentiel qui exécute code scanning à l’aide de CodeQL.

Vous devez activer code scanning à l’aide de CodeQL sur GitHub.com, à l’aide de la configuration par défaut ou de la configuration avancée, avant d’ajouter votre référentiel à 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 GitHub référentiel l’extension CodeQL for Visual Studio Code doit utiliser en tant que référentiel de contrôleurs. À 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.com, ce qui déclenche un flux de travail dynamique GitHub Actions dans votre référentiel de contrôleurs. 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.

• La visibilité du référentiel des contrôleurs peut être « publique » si vous envisagez d’analyser les dépôts publics. L’analyse des variantes sera gratuite.

• La visibilité du référentiel du contrôleur doit être « privée » si vous devez analyser des référentiels privés ou internes. Toutes les minutes d’actions utilisées par l’analyse de variantes, au-dessus de la limite libre, seront facturées au propriétaire du référentiel. Pour plus d’informations sur les minutes gratuites et la facturation, consultez « À propos de la facturation de 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.com que vous souhaitez utiliser comme 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 personnel ou d’organisation. 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.

2. Si vous le souhaitez, vous pouvez ajouter un nouveau référentiel, une organisation ou une liste. Pour plus d’informations, consultez « Création de listes personnalisées de référentiels.

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.

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.com 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 variante » 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.com. 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.com ou vers un fichier Markdown dans votre espace de travail.

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.

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 de GitHub.com à 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 sur la liste que vous avez choisie, puis cliquez sur Ajouter des référentiels avec la recherche de code GitHub.

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.