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, 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 générer la codebase (pris en charge pour tous les langages interprétés, et pris en charge en version bêta pour Java).
• 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 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 (version bêta prise en charge pour Java).
• 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 « Définition de la configuration avancée 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 du 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

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.

Exigences pour l’exécuteur

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 « 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.

Génération de C#

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

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

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).

Exigences pour l’exécuteur

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).

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).

Exigences pour l’exécuteur

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).

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

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

Détection automatique

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 ».

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

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

Détection automatique

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.

Exigences pour l’exécuteur

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.

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

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.