Options et étapes de génération CodeQL pour les langages compilés

Étapes Autobuild pour les langages compilés

Les runners hébergés par GitHub sont toujours exécutés avec les logiciels requis par autobuild. Si vous utilisez des runners 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. Pour les runners auto-hébergés, vous devez installer les dépendances directement sur les runners eux-mêmes. Nous fournissons des exemples de dépendances courantes pour C/C++, C# et Java dans chacune des sections autobuild de cet article pour ces langues. Pour plus d’informations, consultez « Exécuteurs auto-hébergés ».

Compiler C/C++

CodeQL prend en charge les modes de build none, autobuild ou manual pour le code C/C++.

Lorsque vous activez la configuration par défaut pour un dépôt contenant du code C/C++, le mode de build est automatiquement défini sur none.

Aucune build pour C/C++

CodeQL déduit les unités de compilation C/C++ à partir des extensions de fichiers source. Pour chaque fichier source trouvé, les indicateurs de compilation et les chemins d’accès include sont déduits en inspectant le codebase sans avoir besoin d’une commande de build de travail.

Précision de l'absence d'analyse de compilation pour C/C++

La création d'une base de données CodeQL C/C++ sans build peut produire des résultats moins précis que l'utilisation de autobuild ou des étapes de compilation manuelles dans certains cas ; par exemple, si :

• Le code dépend fortement des macros personnalisées ou des définitions non disponibles dans les en-têtes existants.
• Le codebase a de nombreuses dépendances externes

Vous pouvez garantir une analyse plus précise en suivant les étapes suivantes :

• Placer des macros et définitions personnalisées dans des fichiers d'en-tête qui sont inclus dans des fichiers sources pertinents
• Vérifiez que les dépendances externes (en-têtes) sont disponibles dans les répertoires d'inclusion système ou dans l’espace de travail
• Exécutez l’extraction sur la plateforme cible. Par exemple, choisissez un agent Windows pour analyser des projets Windows afin d’accorder l’accès à des en-têtes et compilateurs spécifiques à la plateforme.

Résumé d’Autobuild pour C/C++

Type de système pris en charge	Nom du système
Système d’exploitation	Windows, macOS et Linux
Système de build	Windows : scripts de MSBuild et de génération 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 de Windows

Sur Windows, l’étape autobuild tente de détecter automatiquement une méthode de génération appropriée pour C/C++ à l’aide de 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).

Détection automatique 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 relatives au runner pour C/C++

Sur les runners Ubuntu Linux, autobuild peut tenter d’installer automatiquement les dépendances requises par la configuration et les étapes de build détectées. Par défaut, ce comportement est activé sur les runners hébergés par GitHub et désactivé sur les runners auto-hébergés. Vous pouvez activer ou désactiver explicitement cette fonctionnalité en définissant CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES sur true ou false dans l’environnement. Pour plus d’informations sur la définition de variables d’environnement, consultez Stocker des informations dans des variables.

Pour les runners auto-hé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 l’accès aux exécutables clang ou msvc. Vous devrez également installer le système de build (par exemple msbuild, make, cmake, bazel) ainsi que les utilitaires (tels que python, perl, lex et yacc) dont vos projets dépendent. Si vous activez l’installation automatique des dépendances, vous devez vous assurer que le runner utilise Ubuntu et qu’il peut exécuter sudo apt-get sans nécessiter de mot de passe.

Windows coureurs nécessitent powershell.exe d’être sur le PATH.

Compiler C#

CodeQL prend en charge les modes de build none, autobuild ou manual pour le code C#.

Lorsque vous activez la configuration par défaut pour un dépôt contenant du code C#, le mode de build est automatiquement défini sur none.

Analyse sans build pour C#

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

Les dépendances sont restaurées à l’aide de plusieurs heuristiques et stratégies. Les fichiers suivants constituent les principales sources d’information : *.csproj, *.sln, nuget.config, packages.config, global.json et project.assets.json. Si un flux NuGet privé est défini pour l’organisation, il est également utilisé ; consultez Accès de la configuration par défaut de l’analyse du code aux registres privés et Déterminer si la configuration par défaut de l’analyse du code a utilisé des registres privés.

Les fichiers source générés suivants sont optionnels, mais augmentent significativement la justesse de la base de données CodeQL :

•           directives `global``using` générées pour gérer la fonctionnalité implicite `using` de MSbuild.
  

• Les fichiers de vue ASP.NET Core, les fichiers .cshtml sont convertis en fichiers .cs.

Les informations issues des noms d’assembly de dépendances, des fichiers source générés, des dépendances stockées dans des flux privés, et des fichiers source du dépôt sont compilées et utilisées pour créer une base de données CodeQL.

Précision de l’analyse sans build pour C#

La création d’une base de données CodeQL sans compiler l’intégralité du code repose sur la capacité à restaurer les dépendances et à compiler ensemble les fichiers source présents dans le dépôt. Lorsque des problèmes surviennent lors de la restauration des dépendances ou de la compilation du code source, cela peut 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 suivant les étapes suivantes :

• Fournissez un accès à l’internet public ou assurez-vous que l’accès à un flux NuGet privé est disponible, consultez Accès de la configuration par défaut de l’analyse du code aux registres privés.
• Vérifiez si le dépôt requiert plusieurs versions d’une même dépendance NuGet. CodeQL ne peut utiliser qu’une seule version et choisit généralement la plus récente lorsqu’il existe plusieurs versions. Cette approche peut ne pas convenir à tous les dépôts.
• 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 collisions de noms de classes, sinon cela peut entraîner l’absence de cibles d’appel de méthode, ce qui a un impact sur l’analyse de flux de données.

Résumé d’Autobuild pour C#

Type de système pris en charge	Nom du système
Système d’exploitation	Windows, macOS et Linux
Système de build	.NET et MSBuild, ainsi que des scripts de génération

Détection automatique de 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. Appeler MSBuild.exe sur le fichier de solution ou de 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. Appeler un script ressemblant à un script de build —build.bat, build.cmd et build.exe (dans cet ordre).

Conditions requises pour l'exécution de C# sur Windows

Pour le développement d’applications .NET Core sur les exécuteurs auto-hébergés, le kit sdk .NET est requis (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).

Windows coureurs nécessitent powershell.exe d’être sur le PATH.

Si vous prévoyez 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.

Détection automatique Linux et macOS

1. Appeler dotnet build sur le fichier solution (.sln) ou projet (.csproj) le plus proche de la racine.
2. Appeler MSbuild sur le fichier de solution ou de 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. Appeler un script ressemblant à un script de build —build et build.sh (dans cet ordre).

Exigences relatives au runner pour C# sous Linux et macOS

Pour le développement d’applications .NET Core sur les exécuteurs auto-hébergés, le kit sdk .NET est requis (pour dotnet).

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

Si vous prévoyez 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.

Indicateurs du compilateur C# injectés par CodeQL pour les builds manuels

Le traceur CodeQL permet l’extraction de tous les langages compilés en interceptant les processus de build et en transmettant les informations aux extracteurs de langage CodeQL pertinents. Le traceur injecte certains indicateurs dans l’appel du compilateur C# afin de garantir que chaque composant est compilé et inclus dans la base de données CodeQL, ce qui peut amener votre code C# à se compiler différemment de ce que vous attendez pendant l’analyse CodeQL.

/p:MvcBuildViews=true

Lorsque cette option est définie sur true, les vues dans ASP.NET projets MVC (model-view-controller) sont précompilées dans le cadre du processus de génération, ce qui peut aider à intercepter les erreurs et à améliorer les performances. Le traceur injecte cet indicateur pour s’assurer que CodeQL détecte et met en évidence des problèmes de sécurité pouvant impliquer des flux de données traversant le code généré à partir de ces vues. Pour plus d’informations, consultez Ajouter un affichage à une application MVC dans Microsoft Learn.

/p:UseSharedCompilation=false

Définir cette option sur false désactive l’utilisation de la fonctionnalité de compilation partagée, ce qui peut entraîner des temps de build plus longs. Lorsque /p:UseSharedCompilation=false n’est pas spécifié, msbuild démarre un processus serveur de compilateur et toutes les compilations seront effectuées par ce seul processus. Cependant, le traceur CodeQL dépend de l’inspection des arguments des processus nouvellement créés.

/p:EmitCompilerGeneratedFiles=true

Définir cette option sur true émet des fichiers générés par le compilateur pendant le processus de build. Cette option entraîne la génération par le compilateur de fichiers source supplémentaires utilisés pour prendre en charge des fonctionnalités telles que l’amélioration de la prise en charge des expressions régulières, la sérialisation et la génération de vues d’applications web. Ces artefacts générés ne sont généralement pas écrits sur le disque par le compilateur, mais le fait de définir l’option sur true force l’écriture des fichiers sur le disque afin que l’extracteur puisse les traiter.

Pour certains projets hérités et les projets qui utilisent des fichiers .sqlproj, vous pouvez constater que la propriété /p:EmitCompilerGeneratedFiles=true injectée entraîne des problèmes inattendus avec msbuild. Pour plus d’informations sur le dépannage, consultez Échec inattendu du compilateur C#.

Compiler Go

CodeQL prend en charge les modes de build autobuild ou manual pour le code Go.

Résumé d’Autobuild pour Go

Type de système pris en charge	Nom du 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 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 ./....

Options de l’extracteur pour Go

Par défaut, le code de test (code dans les fichiers se terminant par _test.go) n’est pas analysé. Vous pouvez remplacer ce comportement avec l’option --extractor-option extract_tests=true lors de l’utilisation du CodeQL CLI, ou en définissant la variable d’environnement CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS sur true.

De plus, les répertoires vendor sont exclus par défaut de l’analyse Go de CodeQL. Vous pouvez remplacer ce comportement en passant l’option --extractor-option extract_vendor_dirs=true lors de l’utilisation du CodeQL CLI, ou en définissant la variable d’environnement CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS sur true.

Construction Java et Kotlin

CodeQL prend en charge les modes de build 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 Java code 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 ensuite du code Kotlin à un dépôt qui utilise le mode de build none, l’analyse CodeQL affiche un message d’avertissement expliquant que Kotlin n’est pas pris en charge. Vous devrez désactiver la configuration par défaut puis la réactiver. Lorsque vous réactivez la configuration par défaut, le mode de build passera à autobuild afin que les deux langages puissent être analysés. Vous pouvez aussi passer à une configuration avancée. Pour plus d’informations, consultez « Avertissement : X fichiers Kotlin détectés dans votre projet qui n'ont pas pu être traités sans compilation ».

Aucune build pour Java

CodeQL tente d’exécuter Gradle ou Maven pour extraire des informations de dépendance précises (mais pas pour appeler une build), avant de créer une base de données à partir de tous les fichiers Java présents. Chaque fichier de projet Maven ou Gradle racine (un script de build sans script de build présent dans un répertoire ancêtre) est interrogé pour obtenir des informations de dépendances, et les versions de dépendances les plus récentes sont privilégiées en cas de conflit. Pour plus d’informations sur les exigences de l’exécuteur pour exécuter Maven ou Gradle, consultez Conditions requises pour Java.

Si un registre Maven privé est défini pour l’organisation, il est également utilisé ; consultez Accès de la configuration par défaut de l’analyse du code aux registres privés et Déterminer si la configuration par défaut de l’analyse du code a utilisé des registres privés.

Précision de l'analyse sans compilation pour Java

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

• Les scripts de build Gradle ou Maven ne peuvent pas être interrogés pour les informations de dépendance et les estimations de dépendance (basées sur des noms de package Java) sont inexactes.
• Le dépôt génère normalement du code pendant le processus de build. Ce code aurait été analysé si vous aviez créé la base de données CodeQL à l’aide d’un mode différent.

Vous pouvez garantir une analyse plus précise en suivant les étapes suivantes :

• Fournissez un accès à l’internet public ou assurez-vous que l’accès à un dépôt d’artefacts privé est disponible, consultez Accès de la configuration par défaut de l’analyse du code aux registres privés.
• Vérifiez si le dépôt requiert plusieurs versions d’une même dépendance. CodeQL ne peut utiliser qu’une seule version et choisit généralement la plus récente lorsqu’il existe plusieurs versions. Cette approche peut ne pas convenir à tous les dépôts.
• Vérifiez si plusieurs versions de l’API JDK sont requises par différents fichiers Java sources. Lorsque plusieurs versions sont détectées, CodeQL utilisera la version la plus élevée requise par un script de build. 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’une exigence JDK 17 est détectée dans un ou plusieurs scripts de build, CodeQL utilisera JDK 17. Les fichiers nécessitant JDK 8 et qui ne peuvent pas être compilés avec JDK 17 seront partiellement analysés.
• Évitez les collisions de noms de classes (par exemple plusieurs fichiers définissant org.myproject.Test), sinon cela peut entraîner l’absence de cibles d’appel de méthode, ce qui a un impact sur l’analyse de flux de données.

Un résumé de la compilation automatique pour Java

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

Détection automatique pour Java

Le processus autobuild tente de déterminer le système de génération pour les bases de code 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.

Conditions requises pour Runner de 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 nécessitant 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 nécessitant plusieurs versions de Java, les versions JDK appropriées doivent être installées et peuvent être spécifiées via le fichier toolchains.xml. Il s’agit d’un fichier de configuration, généralement utilisé par Apache Maven, qui permet de spécifier l’emplacement des outils, leur version et toute configuration supplémentaire requise pour les utiliser. Pour plus d’informations, consultez le Guide d’utilisation des chaînes d’outils dans la documentation Apache Maven.

Les exécutables suivants seront probablement requis pour une plage 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 devrez également installer le système de build (par exemple make, cmake, bazel) ainsi que les utilitaires (tels que python, perl, lex, et yacc) dont vos projets dépendent.

Windows coureurs nécessitent powershell.exe d’être sur le PATH.

Compilation de Rust

CodeQL prend en charge le mode de build none pour le code Rust.

Aucune build pour Rust

CodeQL utilise rust-analyzer pour compiler et exécuter des scripts de génération (build.rs fichiers) et compiler du code macro, mais n’appelle pas de build complète. Une base de données est créée à partir de tous les fichiers Rust présents. Un Cargo.toml ou rust-project.json fichier doit être présent.

Exigences du runner pour Rust

L’analyse Rust nécessite que rustup et cargo soient installés.

Compiler Swift

CodeQL prend en charge les modes de build autobuild ou manual pour le code Swift.

Résumé d’Autobuild pour Swift

Type de système pris en charge	Nom du 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 la tarification des runners hébergés par GitHub, consultez la facturation de GitHub Actions.

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.