Résolution des problèmes de workflow CodeQL

Production de journaux détaillés pour le débogage

Pour produire une sortie de journalisation plus détaillée, vous pouvez activer la journalisation du débogage par étape. Pour plus d’informations, consultez « Enabling debug logging ».

Création d’artefacts de débogage CodeQL

Vous pouvez obtenir des artefacts pour vous aider à déboguer CodeQL. Les artefacts de débogage sont chargés sur l’exécution du workflow en tant qu’artefact nommé debug-artifacts. Les données contiennent les journaux CodeQL, la ou les bases de données CodeQL et tout fichier SARIF généré par le workflow.

Ces artefacts vous aident à déboguer les problèmes avec CodeQL code scanning. Si vous contactez le support GitHub, il se peut qu’il vous demande ces données.

Création d’artefacts de débogage CodeQL avec un indicateur de workflow

Vous pouvez créer des artefacts de débogage CodeQL en utilisant un indicateur dans votre workflow. Pour ce faire, vous devez modifier l’étape init de votre fichier Workflow d’analyse CodeQL et définir debug: true.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Échec de la génération automatique pour un langage compilé

Si une génération automatique de code pour un langage compilé au sein de votre projet échoue, essayez les étapes de résolution de problèmes suivantes.

• Supprimez l’étape autobuild de votre workflow d’code scanning et ajoutez des étapes de génération spécifiques. Pour obtenir des informations sur la modification du workflow, consultez « Personnalisation de l’analyse du code ». Pour plus d’informations sur le remplacement de l’étape autobuild, consultez « Configuration du workflow CodeQL pour les langages compilés ».

• Si votre workflow ne spécifie pas explicitement les langages à analyser, CodeQL détecte implicitement les langages pris en charge dans votre base de code. Dans cette configuration, parmi les langages compilés C/C++, C#, et Java, CodeQL analyse uniquement celui qui a le plus de fichiers sources. Modifiez le workflow et ajoutez une matrice spécifiant les langages que vous souhaitez analyser. Le workflow d’analyse CodeQL par défaut utilise ce genre de matrice.

  Les extraits suivants d’un workflow montrent comment utiliser une matrice dans la stratégie de travail pour spécifier des langages, puis référencer chaque langage dans l’étape « Initialiser CodeQL » :

  jobs:
    analyze:
      permissions:
        security-events: write
        actions: read
      ...
      strategy:
        fail-fast: false
        matrix:
          language: ['csharp', 'cpp', 'javascript']
  
      steps:
      ...
        - name: Initialize CodeQL
          uses: github/codeql-action/init@v2
          with:
            languages: ${{ matrix.language }}
  

  Pour plus d’informations sur la modification du workflow, consultez « Personnalisation de l’analyse du code ».

Aucun code trouvé pendant la génération

Si votre workflow échoue avec une erreur No source code was seen during the build ou The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32, cela indique que CodeQL n’a pas pu superviser votre code. Plusieurs raisons peuvent expliquer un tel échec :

1. Le dépôt peut ne pas contenir de code source écrit dans des langages pris en charge par CodeQL. Vérifiez la liste des langages pris en charge et, si c’est le cas, supprimez le workflow CodeQL. Pour plus d’informations, consultez « À propos de l’analyse du code avec CodeQL ».

2. La détection automatique du langage a identifié un langage pris en charge, mais il n’existe aucun code analysable de ce langage dans le dépôt. Par exemple, notre service de détection de langage trouve un fichier associé à un langage de programmation particulier, tel qu’un fichier .hou .gyp, mais aucun code exécutable correspondant n’est présent dans le dépôt. Pour résoudre le problème, vous pouvez définir manuellement les langages que vous souhaitez analyser en mettant à jour la liste des langages dans la matrice language. Par exemple, la configuration suivante analyse uniquement Go et JavaScript.

   strategy:
     fail-fast: false
     matrix:
       # Override automatic language detection by changing the list below.
       # Supported options are listed in a comment in the default workflow.
       language: ['go', 'javascript']
   

   Pour plus d’informations, consultez l’extrait de workflow dans « Échec de la génération automatique pour un langage compilé » ci-dessus.

3. Votre workflow d’code scanning analyse un langage compilé (C, C++, C#, ou Java), mais le code n’a pas été compilé. Par défaut, le workflow d’analyse CodeQL contient une étape autobuild, mais, suivant votre environnement de génération, il n’est pas garanti que cette étape parvienne à générer votre code. La compilation peut également échouer si vous avez supprimé l’étape autobuild et n’avez pas inclus les étapes de génération manuellement. Pour plus d’informations sur la spécification des étapes de build, consultez « Configuration du workflow CodeQL pour les langages compilés ».

4. Votre workflow analyse un langage compilé (C, C++, C#, ou Java), mais des parties de votre build sont mises en cache pour améliorer les performances (généralement avec des systèmes de génération comme Gradle ou Bazel). Étant donné que CodeQL observe l’activité du compilateur pour comprendre les flux de données dans un dépôt, CodeQL nécessite qu’une génération complète ait lieu pour effectuer une analyse.

5. Votre workflow analyse un langage compilé (C, C++, C#, ou Java), mais la compilation ne se produit pas entre les étapes init et analyze du workflow. CodeQL nécessite que votre génération se produise entre ces deux étapes afin d’observer l’activité du compilateur et d’effectuer une analyse.

6. Votre code compilé (en C, C++, C#, ou Java) a été compilé, mais CodeQL n’a pas pu détecter les appels du compilateur. Les causes les plus courantes sont :

   • Exécution de votre processus de génération dans un conteneur distinct vers CodeQL. Pour plus d’informations, consultez « Exécution de l’analyse du code CodeQL dans un conteneur ».
   • Réalisation de la génération avec un système de génération distribué externe à GitHub Actions, utilisant un processus de démon.
   • CodeQL ne sait pas quel est le compilateur que vous utilisez.

   Pour les projets .NET Framework et pour les projets C# utilisant dotnet build ou msbuild, vous devez spécifier /p:UseSharedCompilation=false à l’étape run de votre workflow quand vous générez votre code.

   Par exemple, la configuration suivante pour C# passe l’indicateur lors de la première étape de génération.

   - run: |
       dotnet build /p:UseSharedCompilation=false
   

   Si vous rencontrez un autre problème avec votre compilateur ou configuration, contactez le votre administrateur de site.

Pour plus d’informations sur la spécification des étapes de build, consultez « Configuration du workflow CodeQL pour les langages compilés ».

Il y a moins de lignes de code analysées que prévu

Pour les langages compilés tels que C/C++, C#, Go et Java, CodeQL analyse uniquement les fichiers générés pendant l’analyse. Ainsi, il y a moins de lignes de code analysées que prévu si une partie du code source n’est pas compilée correctement. Cela peut se produire pour plusieurs raisons :

1. La fonctionnalité autobuild de CodeQL utilise des heuristiques pour générer le code dans un dépôt. Toutefois, cette approche entraîne parfois une analyse incomplète d’un dépôt. Par exemple, quand plusieurs commandes build.sh existent dans un même dépôt, l’analyse peut ne pas être terminée, car l’étape autobuild n’exécute qu’une des commandes, ce qui peut empêcher la compilation de certains fichiers sources.
2. Certains compilateurs ne fonctionnent pas avec CodeQL et peuvent provoquer des problèmes lors de l’analyse du code. Par exemple, Project Lombok utilise des API de compilateur non publiques pour modifier le comportement du compilateur. Les hypothèses utilisées dans ces modifications du compilateur ne sont pas valides pour l’extracteur Java de CodeQL, de sorte que le code ne peut pas être analysé.

Si votre analyse CodeQL analyse moins de lignes de code que prévu, vous pouvez essayer diverses approches pour faire en sorte que tous les fichiers sources nécessaires soient compilés.

Remplacer l’étape autobuild

Remplacez l’étape autobuild par les commandes de génération que vous utiliseriez en production. Ainsi, CodeQL sait exactement comment compiler tous les fichiers sources que vous souhaitez analyser. Pour plus d’informations, consultez « Configuration du workflow CodeQL pour les langages compilés ».

Inspecter la copie des fichiers sources dans la base de données CodeQL

Vous pourriez comprendre pourquoi certains fichiers sources n’ont pas été analysés en inspectant la copie du code source incluse dans la base de données CodeQL. Pour obtenir la base de données à partir de workflow Actions, modifiez l’étape init de votre fichier de workflow CodeQL et définissez debug: true.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Cette opération charge la base de données en tant qu’artefact d’actions que vous pouvez télécharger sur votre ordinateur local. Pour plus d’informations, consultez « Stockage des données de workflow en tant qu’artefacts ».

L’artefact contient une copie archivée des fichiers sources analysés par CodeQL appelée src.zip. Si vous comparez les fichiers de code source dans le dépôt et les fichiers dans src.zip, vous pouvez voir quels types de fichiers sont manquants. Une fois que vous savez quels types de fichiers ne sont pas analysés, il est plus facile de comprendre comment vous devrez peut-être changer le workflow pour l’analyse CodeQL.

Alertes trouvées dans le code généré

Pour les langages compilés tels que Java, C, C++ et C#, CodeQL analyse l’ensemble du code généré au moment de l’exécution du workflow. Pour limiter la quantité de code analysée, générez uniquement le code que vous souhaitez analyser en spécifiant vos propres étapes de génération dans un bloc run. Vous pouvez simultanément spécifier vos propres étapes de génération et utiliser les filtres paths et paths-ignore sur les événements pull_request et push afin que votre workflow ne s’exécute que quand du code spécifique est modifié. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».

Pour les langages tels que Go, JavaScript, Python et TypeScript, que CodeQL analyse sans compiler le code source, vous pouvez spécifier des options de configuration supplémentaires afin de limiter la quantité de code à analyser. Pour plus d’informations, consultez « Personnalisation de l’analyse du code ».

Erreurs d’extraction dans la base de données

L’équipe CodeQL travaille constamment sur les erreurs d’extraction critiques afin que tous les fichiers sources puissent être analysés. Toutefois, les extracteurs CodeQL génèrent parfois des erreurs lors de la création de la base de données. CodeQL fournit des informations sur les erreurs d’extraction et les avertissements générés lors de la création de la base de données dans un fichier journal. Les informations de diagnostic d’extraction indiquent l’intégrité globale de la base de données. La plupart des erreurs d’extraction n’impactent pas considérablement l’analyse. Un petit nombre d’erreurs d’extraction est sain et indique généralement un bon état d’analyse.

Toutefois, si vous voyez des erreurs d’extraction dans une grande majorité des fichiers qui ont été compilés lors de la création de la base de données, vous devez examiner plus en détail les erreurs pour essayer de comprendre pourquoi certains fichiers sources n’ont pas été extraits correctement.

La génération prend trop de temps

Si l’exécution de la génération avec l’analyse CodeQL prend trop de temps, vous pouvez essayer de réduire le temps de génération.

Augmenter la mémoire ou le nombre de cœurs

Si vous utilisez des exécuteurs auto-hébergés pour exécuter l’analyse CodeQL, vous pouvez augmenter la mémoire ou le nombre de cœurs sur ces exécuteurs.

Utiliser des builds de matrice pour paralléliser l’analyse

Le Workflow d’analyse CodeQL par défaut utilise une matrice de langages, ce qui entraîne l’exécution parallèle de l’analyse de chaque langage. Si vous avez spécifié les langages que vous souhaitez analyser directement à l’étape « Initialiser CodeQL », l’analyse de chaque langage se produit de manière séquentielle. Pour accélérer l’analyse de plusieurs langages, modifiez votre workflow de manière à utiliser une matrice. Pour plus d’informations, consultez l’extrait de workflow dans « Échec de la génération automatique pour un langage compilé » ci-dessus.

Réduire la quantité de code analysée dans un même workflow

La durée de l’analyse est généralement proportionnelle à la quantité de code analysé. Vous pouvez réduire le temps d’analyse en réduisant la quantité de code analysée simultanément, par exemple, en excluant le code de test ou en divisant l’analyse en plusieurs workflows qui analysent uniquement un sous-ensemble de votre code à la fois.

Pour les langages compilés tels que Java, C, C++ et C#, CodeQL analyse l’ensemble du code généré au moment de l’exécution du workflow. Pour limiter la quantité de code analysée, générez uniquement le code que vous souhaitez analyser en spécifiant vos propres étapes de génération dans un bloc run. Vous pouvez simultanément spécifier vos propres étapes de génération et utiliser les filtres paths et paths-ignore sur les événements pull_request et push afin que votre workflow ne s’exécute que quand du code spécifique est modifié. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».

Pour les langages tels que Go, JavaScript, Python et TypeScript, que CodeQL analyse sans compiler le code source, vous pouvez spécifier des options de configuration supplémentaires afin de limiter la quantité de code à analyser. Pour plus d’informations, consultez « Personnalisation de l’analyse du code ».

Si vous divisez votre analyse en plusieurs workflows comme décrit ci-dessus, nous vous recommandons toutefois d’avoir au moins un workflow qui s’exécute sur un schedule qui analyse tout le code de votre dépôt. Étant donné que CodeQL analyse les flux de données entre les composants, certains comportements de sécurité complexes peuvent uniquement être détectés sur une génération complète.

Exécuter uniquement pendant un événement schedule

Si votre analyse est encore trop lente pour être exécutée pendant les événements push ou pull_request, vous pouvez limiter le déclenchement de l’analyse à l’événement schedule. Pour plus d’informations, consultez « Comprendre GitHub Actions ».

Vérifier quelles sont les suites de requêtes exécutées par le workflow

Par défaut, il existe trois suites de requêtes principales disponibles pour chaque langage. Si vous avez optimisé la génération de base de données CodeQL, et si le processus est encore trop long, vous pouvez réduire le nombre de requêtes que vous exécutez. La suite de requêtes par défaut est exécutée automatiquement ; elle contient les requêtes de sécurité les plus rapides avec les taux les plus bas de faux résultats positifs.

Vous pouvez exécuter des suites de requêtes ou des requêtes supplémentaires en plus des requêtes par défaut. Vérifiez si le workflow définit l’exécution d’une suite de requêtes supplémentaire ou de requêtes supplémentaires en utilisant l’élément queries. Vous pouvez tester la désactivation de la suite de requêtes ou des requêtes supplémentaires. Pour plus d’informations, consultez « Personnalisation de l’analyse du code ».

Erreur : « Erreur de serveur »

Si l’exécution d’un workflow pour l’code scanning échoue en raison d’une erreur de serveur, essayez de réexécuter le workflow. Si le problème persiste, contactez le votre administrateur de site.

Erreur : « Espace disque insuffisant » ou « Mémoire insuffisante »

Sur les très grands projets, CodeQL peut manquer d’espace disque ou de mémoire sur l’exécuteur. Si vous rencontrez ce problème, essayez d’augmenter la mémoire sur l’exécuteur.

Erreur : « n’est pas un fichier.ql, un fichier.qls, un répertoire ou une spécification de pack de requêtes »

Vous voyez cette erreur si CodeQL ne trouve pas la requête nommée, la suite de requêtes ou le pack de requêtes à l’emplacement demandé dans le workflow. Il existe deux raisons courantes à cette erreur.

• Il y a une faute de frappe dans le workflow.
• Une ressource à laquelle le workflow fait référence par chemin d’accès a été renommée, supprimée ou déplacée vers un nouvel emplacement.

Après avoir vérifié l’emplacement de la ressource, vous pouvez mettre à jour le workflow pour spécifier l’emplacement correct.

Avertissement : « Basculement sur une branche git HEAD^2 plus nécessaire »

Si vous utilisez un ancien workflow CodeQL, vous pouvez recevoir l’avertissement suivant dans la sortie de l’action « Initialiser Initialize CodeQL » :

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer
necessary. Please remove this step as Code Scanning recommends analyzing the merge
commit for best results.

Pour corriger cela, supprimez les lignes suivantes du workflow CodeQL. Ces lignes ont été incluses dans la section steps du travail Analyze dans les versions initiales du workflow CodeQL.

        with:
          # We must fetch at least the immediate parents so that if this is
          # a pull request then we can checkout the head.
          fetch-depth: 2

      # If this run was triggered by a pull request event, then checkout
      # the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

La section steps révisée du flux de travail doit ressembler à ceci :

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2

      ...

Pour plus d’informations sur la modification du fichier de workflow CodeQL, consultez « Personnalisation de l’analyse du code ».