Analyse du code CodeQL pour les langages compilés

À propos du Workflow d’analyse CodeQL et des langages compilés

L’Code scanning fonctionne en exécutant des requêtes sur une ou plusieurs bases de données CodeQL. Chaque base de données contient une représentation du code dans un langage unique au sein de votre référentiel. Pour les langages compilés C/C++, C#, Go, Java, et Swift, le processus de remplissage de cette base de données implique souvent la génération du code et l’extraction de données.

Lorsque vous activez code scanning, la configuration par défaut et la configuration avancée génèrent une base de données CodeQL pour l’analyse à l’aide de la méthode la plus simple disponible. Pour Java et C#, la base de données CodeQL est générée directement à partir de la codebase sans nécessiter de génération (mode de génération none). Pour d’autres langages compilés, CodeQL génère la codebase à l’aide du mode de génération autobuild. Sinon, vous pouvez utiliser le mode de génération manual et spécifier à la place des commandes de génération explicites pour analyser uniquement les fichiers générés par ces commandes personnalisées.

Modes de génération CodeQL

L’action CodeQL prend en charge trois modes de génération différents pour les langages compilés :

• none : la base de données CodeQL est créée directement à partir de la codebase sans la générer (pris en charge pour tous les langages interprétés, et en plus pris en charge pour Java et C#).
• autobuild : CodeQL détecte la méthode de génération la plus probable et l’utilise pour tenter de générer le codebase et de créer une base de données pour l’analyse (pris en charge pour tous les langages compilés).
• manual : vous définissez les étapes de génération à utiliser pour la codebase dans le flux de travail (pris en charge pour tous les langages compilés).

Comparaison des modes de génération

Recommandations

Lorsque vous configurez code scanning pour la première fois ou sur plusieurs référentiels, il est préférable d’utiliser la configuration par défaut. La configuration par défaut utilise la méthode la plus simple disponible pour générer une base de données CodeQL et analyser votre code afin de pouvoir commencer à corriger les alertes dès que possible. Une fois que vous avez résolu les alertes initiales, vous pouvez basculer vers une configuration avancée avec un processus de génération manuel pour les référentiels à haut risque.

Utilisation de plusieurs modes de génération dans un référentiel multi-langage

Pour les référentiels avec plusieurs langages compilés, vous pouvez utiliser différents modes de génération pour différents langages. Par exemple, si votre référentiel contient C/C++, C# et Java, vous pouvez fournir des étapes de génération manuelles pour un langage (ici C/C++). Ce workflow spécifie un mode de génération différent pour chaque langage.

strategy:
  matrix:
    include:
      # Analyzes C and C++ code using the commands in `Build C and C++ code`
      - language: c-cpp
        build-mode: manual
      # Analyzes C# code by automatically detecting a build
      - language: csharp
        build-mode: autobuild
      # Analyzes Java code directly from the codebase without a build
      - language: java-kotlin
        build-mode: none # analyzes Java only
steps:
- name: Checkout repository
  uses: actions/checkout@v4

    # Initializes CodeQL tools and creates a codebase for analysis.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v3
      with:
        languages: ${{ matrix.language }}
    - if: ${{ matrix.build-mode == 'manual' }}
      name: Build C and C++ code
      run: |
        echo 'If you are using a "manual" build mode for one or more of the' \
          'languages you are analyzing, replace this with the commands to build' \
          'your code, for example:'
        echo '  make bootstrap'
        echo '  make release'
        exit 1

Pour plus d’informations sur les langages, bibliothèques et cadres pris en charge dans la dernière version de CodeQL, consultez «  Langages et cadres pris en charge » dans la documentation CodeQL. Pour plus d’informations sur la configuration requise pour l’exécution de la dernière version de CodeQL, consultez «  Configuration requise » dans la documentation CodeQL.

À propos du mode de génération Aucun pour CodeQL

Pour Java et C#, CodeQL crée une base de données sans nécessiter de génération lorsque vous activez la configuration par défaut pour code scanning, sauf si le référentiel inclut également du code Kotlin. Si un référentiel contient du code Kotlin en plus du code Java, la configuration par défaut est activée avec le processus de génération automatique car l'analyse Kotlin nécessite une génération.

La création d’une base de données CodeQL sans génération peut produire des résultats moins précis que l’utilisation de autobuild ou les étapes de génération manuelles si :

• Les scripts de génération ne peuvent pas être interrogés pour les informations de dépendance et les estimations de dépendance sont inexactes.
• Le référentiel génère normalement du code pendant le processus de génération.

Pour utiliser autobuild ou des étapes de génération manuelle, vous pouvez utiliser la configuration avancée.

À propos de la génération automatique pour CodeQL

L’action CodeQL utilise autobuild pour analyser les langages compilés dans les cas suivants.

• La configuration par défaut est activée et le langage ne prend pas en charge la génération none (prise en charge pour Java et C#).
• La configuration avancée est activée et le workflow spécifie build-mode: autobuild.
• La configuration avancée est activée et le workflow a une étape de génération automatique pour le langage à l’aide de l’action autobuild (github/codeql-action/autobuild@v3).

Exemple d’utilisation de l’option build-mode

# Initializes the CodeQL tools for scanning.
name: Analyze
strategy:
  matrix:
    include:
      # Analyze C and C++ code
      - language: c-cpp
        build-mode: autobuild
      # Analyze Go code
      - language: go
        build-mode: autobuild

steps:
  - uses: github/codeql-action/init@v3
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}

Exemple utilisant l’étape de génération automatique

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v3
      with:
        languages: ${{ matrix.language }}

    - name: Autobuild
      uses: github/codeql-action/autobuild@v3

À propos de la spécification manuelle des étapes de génération

Vous ne pouvez spécifier que les étapes de génération manuelles si vous avez activé la configuration avancée, consultez « Configuration de la configuration par défaut pour l’analyse du code ».

En cas d’échec de autobuild ou si vous souhaitez analyser un ensemble différent de fichiers source générés par le processus autobuild, vous devez effectuer les opérations suivantes :

• Si votre flux de travail spécifie un mode de génération pour la langue, remplacez le mode de génération par manual.
• Si votre flux de travail contient une étape autobuild, supprimez ou commentez l’étape autobuild dans le flux de travail.

Supprimez ensuite les marques de commentaire de l’étape run et spécifiez manuellement le processus de génération à utiliser. Pour C/C++, C#, Go, Java, et Swift, CodeQL va analyser le code source généré par vos étapes de génération spécifiées. Pour plus d’informations sur la modification du fichier de workflow, consultez « Personnalisation de votre configuration avancée pour l’analyse de code ».

Mettez à jour votre workflow pour définir le build-mode sur manual.

# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
- uses: github/codeql-action/init@v3
  with:
    languages: ${{ matrix.language }}
    build-mode: manual
- uses: github/codeql-action/analyze@v3
  with:
    category: "/language:${{ matrix.language }}"

Vous pouvez également mettre à jour votre workflow pour commenter l’étape « Génération automatique ».

    # Autobuild attempts to build any compiled languages.
    # - name: Autobuild
    #  uses: github/codeql-action/autobuild@v3

Spécification des commandes de build

Lorsque la génération manuelle est activée, supprimez les marques de commentaire de l’étape run dans le workflow et ajoutez des commandes de génération adaptées à votre référentiel. L’étape run exécute des programmes en ligne de commande avec le shell du système d’exploitation. Vous pouvez modifier ces commandes et ajouter d’autres commandes pour personnaliser le processus de build.

- run: |
    make bootstrap
    make release

Pour plus d’informations sur le mot clé run, consultez « Workflow syntax for GitHub Actions ».

Si vous avez ajouté des étapes de génération manuelles pour les langages compilés et que l’code scanning ne fonctionne toujours pas sur votre dépôt, contactez le nous via le portail de support GitHub.

Étapes de génération automatique pour les langages compilés

Les exécuteur hébergés par GitHub sont toujours exécutés avec le logiciel requis par autobuild. Si vous utilisez des exécuteurs auto-hébergés pour GitHub Actions, vous devrez peut-être installer des logiciels supplémentaires pour utiliser le processus autobuild. En outre, si votre dépôt nécessite une version spécifique d’un outil de génération, vous devrez peut-être l’installer manuellement.

• Génération de C/C++
• Génération de C#
• Génération de Go
• Génération de Java et Kotlin
• Génération de Swift

Génération de C/C++

CodeQL prend en charge les modes de génération autobuild ou manual pour le code C/C++.

Résumé de la génération automatique pour C/C++

Type de système pris en charge	Nom système
Système d’exploitation	Windows, macOS et Linux
Système de build	Windows : scripts MSbuild et de build Linux et macOS : Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild et scripts de build

Le comportement de l’étape autobuild varie en fonction du système d’exploitation sur lequel l’extraction s’exécute.

Autodétection Windows

Sur Windows, l’étape autobuild tente de détecter automatiquement une méthode de génération appropriée pour C/C++ en utilisant l’approche suivante :

1. Appeler MSBuild.exe sur le fichier solution (.sln) ou projet (.vcxproj) le plus proche de la racine. Si autobuild détecte plusieurs fichiers solution ou projet à la même profondeur (la plus courte) à partir du répertoire de niveau supérieur, il tente de les générer tous.
2. Appeler un script qui ressemble à un script de build : build.bat, build.cmd et build.exe (dans cet ordre).

Autodétection Linux et macOS

Sur Linux et macOS, l’étape autobuild passe en revue les fichiers présents dans le dépôt pour déterminer le système de build utilisé :

1. Rechercher un système de build dans le répertoire racine.
2. Si aucun répertoire n’est trouvé, rechercher un répertoire unique avec un système de build pour C/C++.
3. Exécuter une commande appropriée pour configurer le système.

Conditions requises pour l’exécuteur pour C/C++

Sur les exécuteurs Ubuntu Linux, il se peut qu’autobuild tente d’installer automatiquement les dépendances requises par les étapes de configuration et de génération détectées. Par défaut, ce comportement est activé sur les exécuteurs hébergés sur GitHub et désactivés sur les exécuteurs autohébergés. Vous pouvez activer ou désactiver cette fonctionnalité explicitement en définissant CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES sur true ou false dans l’environnement. Pour plus d’informations sur les variables d’environnement, consultez « Stocker des informations dans des variables ».

Pour les exécuteurs autohébergés, sauf si l’installation automatique des dépendances est activée, vous devrez probablement installer le compilateur gcc et certains projets peuvent également nécessiter un accès à clang ou msvc des exécutables. Vous devez également installer le système de build (par exemplemsbuild, make, cmake, bazel) et les utilitaires (tels que python, perl, lex et yacc) dont dépendent vos projets. Si vous activez l’installation automatique des dépendances, vous devez vous assurer que l’exécuteur utilise Ubuntu et qu’il peut exécuter sudo apt-get sans demander de mot de passe.

Les exécuteurs Windows exigent que powershell.exe soit sur PATH.

Génération de C#

CodeQL prend en charge les modes de génération none, autobuild ou manual pour le code C#.

Lorsque vous activez la configuration par défaut pour un référentiel contenant du code C#, le mode de génération est automatiquement défini sur none.

Aucune génération pour C#

CodeQL restaure les dépendances et génère quelques fichiers sources supplémentaires, afin d'obtenir des résultats plus précis, avant de créer une base de données à partir de tous les fichiers sources et dépendances.

Les dépendances sont rétablies à l'aide de plusieurs heuristiques et stratégies. Les fichiers suivants constituent la principale source d'information : *.csproj, *.sln, nuget.config, packages.config, global.json, et project.assets.json.

Les fichiers sources générés ci-dessous sont facultatifs, mais ils améliorent considérablement l'exactitude de la base de données CodeQL :

• Les directives global générées par using permettent de gérer la fonctionnalité using implicite de MSbuild.
• ASP.NET core affiche les fichiers, les fichiers .cshtml sont convertis en fichiers .cs.

Les informations provenant des noms d'assembly de dépendances, des fichiers sources générés et des fichiers sources du référentiel sont compilées et utilisées pour créer une base de données CodeQL.

Précision de l'analyse de l'absence de génération pour C#

La création d'une base de données CodeQL sans générer le code complet repose sur la capacité à rétablir les dépendances et à compiler les fichiers sources dans le référentiel. Les problèmes de restauration des dépendances ou de compilation du code source peuvent affecter la précision de la base de données CodeQL et les résultats de l'analyse code scanning.

Vous pouvez garantir une analyse plus précise en prenant les mesures suivantes :

• Fournissez un accès à l'internet public ou s'assurer que l'accès à un flux Nuget privé est disponible.
• Vérifiez si le référentiel nécessite plusieurs versions de la même dépendance Nuget. CodeQL ne peut utiliser qu'une seule version et choisit généralement la version la plus récente lorsqu'il existe plusieurs versions. Cette approche peut ne pas fonctionner pour tous les référentiels.
• Vérifiez si plusieurs versions de .NET sont référencées, par exemple net48, net5.0 et netstandard1.6. CodeQL ne peut utiliser qu'une seule version, ce qui peut affecter la précision.
• Évitez les conflits de noms de classe, car ils peuvent entraîner l'absence de cibles d'appel de méthode, ce qui a un impact sur l'analyse du flux de données.

Résumé de la génération automatique pour C#

Type de système pris en charge	Nom système
Système d’exploitation	Windows, macOS et Linux
Système de build	.NET et MSbuild ainsi que les scripts de build

Autodétection Windows

Le processus autobuild tente de détecter automatiquement une méthode de génération appropriée pour C# en utilisant l’approche suivante :

1. Appeler dotnet build sur le fichier solution (.sln) ou projet (.csproj) le plus proche de la racine.
2. Invoquer MSBuild.exe sur le fichier solution ou projet le plus proche de la racine. Si autobuild détecte plusieurs fichiers solution ou projet à la même profondeur (la plus courte) à partir du répertoire de niveau supérieur, il tente de les générer tous.
3. Invoquer un script qui ressemble à un script de génération : build.bat, build.cmd et build.exe (dans cet ordre).

Configuration requise pour C# sur Windows

Pour le développement d’applications .NET Core sur des exécuteurs auto-hébergés, vous aurez besoin du Kit de développement logiciel (SDK) .NET (pour dotnet).

Pour le développement d’applications .NET Framework, vous aurez besoin de Microsoft Build Tools (pour msbuild) et de l’interface CLI Nuget (pour nuget).

Les exécuteurs Windows exigent que powershell.exe soit sur PATH.

Si vous envisagez de créer des bases de données CodeQL à l'aide de build-mode: none, vous devez également fournir un accès à l'internet public ou vous assurer que l'accès à un flux Nuget privé est disponible.

Autodétection Linux et macOS

1. Appeler dotnet build sur le fichier solution (.sln) ou projet (.csproj) le plus proche de la racine.
2. Invoquer MSbuild sur le fichier solution ou projet le plus proche de la racine. Si autobuild détecte plusieurs fichiers solution ou projet à la même profondeur (la plus courte) à partir du répertoire de niveau supérieur, il tente de les générer tous.
3. Invoquer un script qui ressemble à un script de génération : build et build.sh (dans cet ordre).

Configuration requise pour C# sur Linux et macOS

Pour le développement d’applications .NET Core sur des exécuteurs auto-hébergés, vous aurez besoin du Kit de développement logiciel (SDK) .NET (pour dotnet).

Pour le développement d’applications .NET Framework, vous aurez besoin de runtime Mono (pour exécuter mono, msbuild ou nuget).

Si vous envisagez de créer des bases de données CodeQL à l'aide de build-mode: none, vous devez également fournir un accès à l'internet public ou vous assurer que l'accès à un flux Nuget privé est disponible.

Génération de Go

CodeQL prend en charge les modes de génération autobuild ou manual pour le code Go.

Résumé de la génération automatique pour Go

Type de système pris en charge	Nom système
Système d’exploitation	Windows, macOS et Linux
Système de build	Modules Go, dep et Glide, ainsi que des scripts de génération, notamment des scripts Makefiles et Ninja

Autodetection pour Go

Le processus autobuild tente de détecter automatiquement un moyen approprié d’installer les dépendances dont un dépôt Go a besoin avant d’extraire tous les fichiers .go :

1. Appelez make, ninja, ./build ou ./build.sh (dans cet ordre) jusqu’à ce que l’une de ces commandes réussisse et qu’une commande go list ./... ultérieure réussisse également, indiquant que les dépendances nécessaires ont été installées.
2. Si aucune de ces commandes ne réussit, recherchez go.mod, Gopkg.toml ou glide.yaml, et exécutez go get (sauf si le vendoring est utilisé), dep ensure -v ou glide install respectivement pour essayer d’installer les dépendances.
3. Enfin, si les fichiers de configuration de ces gestionnaires de dépendances sont introuvables, réorganisez la structure de répertoires du dépôt pour l’ajouter à GOPATH et utilisez go get pour installer les dépendances. La structure de répertoires revient à la normale une fois l’extraction terminée.
4. Extrayez tout le code Go dans le dépôt, comme pour l’exécution de go build ./....

Génération de Java et Kotlin

CodeQL prend en charge les modes de génération suivants.

• Java : none, autobuild ou manual
• Kotlin : autobuild ou manual

Lorsque vous activez d’abord la configuration par défaut d’un référentiel, si seul le code Java est détecté, le mode de génération est défini sur none. Si Kotlin ou une combinaison de code Java et Kotlin est détectée, le mode de génération est défini sur autobuild.

Si vous ajoutez ultérieurement du code Kotlin à un référentiel qui utilise le mode de génération none, l’analyse de CodeQL signale un message d’avertissement expliquant que Kotlin n’est pas pris en charge. Vous devez désactiver la configuration par défaut et la réactiver. Lorsque vous réactivez la configuration par défaut, le mode de génération passe à autobuild que les deux langages puissent être analysés. Vous pouvez également passer à une configuration avancée. Pour plus d’informations, consultez « Avertissement : détection de X fichiers Kotlin dans votre projet qui n’ont pas pu être traités sans génération ».

Aucune génération pour Java

CodeQL tente d’exécuter Gradle ou Maven afin d’extraire des informations précises sur les dépendances (mais pas d’invoquer une génération), avant de créer une base de données à partir de tous les fichiers Java présents. Chaque fichier projet Maven ou Gradle racine (un script de génération sans aucun script de génération présent dans un répertoire ancêtre) est interrogé pour obtenir des informations sur les dépendances, et les générations de dépendance plus récentes sont préférées en cas de conflit. Pour plus d'informations sur la configuration requise pour exécuter Maven ou Gradle, consultez « Configuration requise pour l'exécution de Java ».

Précision de l'analyse de l'absence de génération pour Java

La création d’une base de données Java CodeQL sans génération peut produire des résultats moins précis que l’utilisation de autobuild ou les étapes de génération manuelles si :

• Les scripts de génération Gradle ou Maven ne peuvent pas être interrogés pour les informations de dépendance et les estimations de dépendance (basées sur les noms de package Java) sont inexactes.
• Le référentiel génère normalement du code pendant le processus de génération. Ceci serait analysé si vous aviez créé la base de données CodeQL en utilisant un mode différent.

Vous pouvez garantir une analyse plus précise en prenant les mesures suivantes :

• Fournissez un accès à l’Internet public ou assurez-vous que l’accès à un référentiel d’artefacts privé est disponible.
• Vérifiez si le référentiel nécessite plusieurs versions de la même dépendance. CodeQL ne peut utiliser qu'une seule version et choisit généralement la version la plus récente lorsqu'il existe plusieurs versions. Cette approche peut ne pas fonctionner pour tous les référentiels.
• Vérifiez si plusieurs versions de l’API JDK sont requises par différents fichiers Java source. En cas de versions multiples, CodeQL utilisera la version la plus élevée requise par tout script de génération. Cela peut signifier que certains fichiers nécessitant une version inférieure du JDK seront partiellement analysés. Par exemple, si certains fichiers nécessitent JDK 8 mais qu’un ou plusieurs scripts de génération indiquent JDK 17, CodeQL utilisera JDK 17. Tous les fichiers qui nécessitent JDK 8 et qui n’ont pas pu être générés à l’aide de JDK 17 seront partiellement analysés.
• Évitez les collisions de noms de classes (par exemple, plusieurs fichiers définissant org.myproject.Test), car cela peut entraîner l’absence de cibles d’appels de méthodes, ce qui a un impact sur l’analyse du flux de données.

Résumé de la génération automatique pour Java

Type de système pris en charge	Nom système
Système d’exploitation	Windows, macOS et Linux (sans restriction)
Système de build	Gradle, Maven et Ant

Autodetection pour Java

Le processus autobuild tente de déterminer le système de build pour les codebases Java en appliquant cette stratégie :

1. Rechercher un fichier de build dans le répertoire racine. Rechercher les fichiers de build Gradle, puis Maven, puis Ant.
2. Exécuter le premier fichier de build trouvé. Si les fichiers Gradle et Maven sont présents, le fichier Gradle est utilisé.
3. Sinon, rechercher les fichiers de build dans les sous-répertoires directs du répertoire racine. Si un seul sous-répertoire contient des fichiers de build, exécutez le premier fichier identifié dans ce sous-répertoire (en utilisant la même préférence que pour 1). Si plusieurs sous-répertoires contiennent des fichiers de build, signaler une erreur.

Configuration requise pour Java

Si vous utilisez des exécuteurs auto-hébergés, la ou les versions requises de Java doivent être présentes :

• Si l’exécuteur sera utilisé pour analyser les référentiels qui ont besoin d’une version unique de Java, la version JDK appropriée doit être installée et doit être présente dans la variable PATH (afin que java et javac soient trouvés).

• Si l’exécuteur sera utilisé pour analyser les référentiels qui ont besoin de plusieurs versions de Java, les versions JDK appropriées doivent être installées et peuvent être spécifiées via le fichier toolchains.xml. Ceci est un fichier de configuration, généralement utilisé par Apache Maven, qui vous permet de spécifier l’emplacement des outils, la version des outils et toute configuration supplémentaire requise pour utiliser les outils. Pour plus d’informations, consultez «  Guide d’utilisation des chaînes d’outils » dans la documentation Apache Maven.

Les exécutables suivants seront probablement requis pour une gamme de projets Java et doivent être présents dans la variable PATH, mais ils ne seront pas essentiels dans tous les cas :

• mvn (Apache Maven)
• gradle (Gradle)
• ant (Apache Ant)

Vous devez également installer le système de build (par exemplemake, cmake, bazel) et les utilitaires (tels que python, perl, lex et yacc) dont dépendent vos projets.

Les exécuteurs Windows exigent que powershell.exe soit sur PATH.

Génération de Swift

CodeQL prend en charge les modes de génération autobuild ou manual pour le code Swift.

Résumé de la génération automatique pour Swift

Type de système pris en charge	Nom système
Système d’exploitation	macOS
Système de build	Xcode

Le processus autobuild tente de générer la plus grande cible à partir d’un projet ou d’un espace de travail Xcode.

L’analyse du code Swift utilise des exécuteurs macOS par défaut. Étant donné que les exécuteurs macOS hébergés par GitHub sont plus coûteux que les exécuteurs Linux et Windows, nous vous recommandons de générer uniquement le code que vous souhaitez analyser. Pour plus d’informations sur les tarifs des exécuteurs hébergés par GitHub, consultez « À propos de la facturation de GitHub Actions ».

Code scanning du code Swift n’est pas pris en charge pour les exécuteurs qui font partie d’un ARC Actions Runner Controller, car les exécuteurs ARC utilisent uniquement Linux et Swift nécessite des exécuteurs macOS. Toutefois, vous pouvez avoir un mélange d’exécuteurs ARC et d’exécuteurs macOS auto-hébergés. Pour plus d’informations, consultez « À propos d’Actions Runner Controller ».

Personnalisation de la compilation Swift dans un Workflow d’analyse CodeQL

xcodebuild et swift build sont tous deux pris en charge pour les builds Swift. Nous vous recommandons de cibler une seule architecture pendant la génération. Par exemple, ARCH=arm64 pour xcodebuild, ou --arch arm64 pour swift build.

Vous pouvez passer les options archive et test à xcodebuild. Toutefois, la commande standard xcodebuild est recommandée, car elle doit être la plus rapide et doit être tout ce que CodeQL nécessite pour une analyse réussie.

Pour l’analyse Swift, vous devez toujours installer explicitement les dépendances gérées via CocoaPods ou Carthage avant de générer la base de données CodeQL.