CodeQL-Buildoptionen und -schritte für kompilierte Sprachen

Autobuild-Schritte für kompilierte Sprachen

benötigten Software ausgeführt. Wenn Sie selbst gehostete Runner für GitHub Actions verwenden, müssen Sie möglicherweise zusätzliche Software installieren, um den autobuild-Prozess zu nutzen. Wenn Ihr Repository zudem eine bestimmte Version eines Buildtools erfordert, müssen Sie dieses möglicherweise manuell installieren. Bei selbstgehosteten Runnern sollten Sie Abhängigkeiten direkt in den Runnern installieren. Wir stellen Beispiele für allgemeine Abhängigkeiten für C/C++, C# und Java in jedem der Abschnitte autobuild dieses Artikels für diese Sprachen bereit. Weitere Informationen findest du unter Selbstgehosteten Runnern.

Erstellen von C/C++

CodeQL unterstützt die Buildmodi autobuild oder manual für C-/C++-Code.

Autobuild-Zusammenfassung für C/C++

Unterstütztes System	Systemname
Betriebssystem	Windows, macOS und Linux
Buildsystem	Windows: MSBuild- und Build-Skripte Linux und macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild und Buildskripts

Das Verhalten des autobuild-Schritts variiert je nach Betriebssystem, auf dem die Extraktion ausgeführt wird.

Windows Automatische Erkennung

Bei Windows versucht der Schritt autobuild, mithilfe des folgenden Ansatzes eine geeignete Buildmethode für C/C++ automatisch zu erstellen:

1. Für die Projektmappe (MSBuild.exe) oder Projektdatei (.sln), die sich am nächsten beim Stamm befindet, wird .vcxproj aufgerufen. Wenn autobuild mehrere Projektmappen oder Projektdateien mit dem gleichen (kürzesten) Abstand zum obersten Verzeichnis erkennt, versucht autobuild, alle zu kompilieren.
2. Ein Skript wird aufgerufen, das wie ein Buildskript aussieht: build.bat, build.cmd und build.exe (in dieser Reihenfolge).

Automatische Erkennung für Linux und macOS

Unter Linux und macOS werden die im Repository vorhandenen Dateien vom autobuild-Schritt überprüft, um das verwendete Buildsystem zu bestimmen:

1. Im Stammverzeichnis wird nach einem Buildsystem gesucht.
2. Wenn keines gefunden wird, werden die Unterverzeichnisse nach einem eindeutigen Verzeichnis mit einem Buildsystem für C/C++ durchsucht.
3. Ein passender Befehl wird ausgeführt, um das System zu konfigurieren.

Runner-Anforderungen für C/C++

          `autobuild` kann auf Ubuntu Linux-Runnern versuchen, Abhängigkeiten automatisch zu installieren, die von den erkannten Konfigurations- und Buildschritten benötigt werden. Dieses Verhalten ist standardmäßig für auf GitHub gehosteten Runnern aktiviert und auf selbst gehosteten Runnern deaktiviert. Sie können dieses Feature explizit aktivieren oder deaktivieren, indem Sie die Einstellung `CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES` auf `true` oder `false` in der Umgebung festlegen. Weitere Informationen zum Definieren von Umgebungsvariablen findest du unter [AUTOTITLE](/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow).

Bei selbst gehosteten Runnern musst du wahrscheinlich den Compiler gcc installieren, es sei denn, die automatische Installation von Abhängigkeiten ist aktiviert, und bestimmte Projekte benötigen möglicherweise auch Zugriff auf ausführbare clang- oder msvc-Dateien. Außerdem müssen Sie das Buildsystem (z. B. msbuild, make, cmake, bazel) und Dienstprogramme (z. B. python, perl, lexund yacc) installieren, von denen die Projekte abhängen. Wenn du die automatische Installation von Abhängigkeiten aktivierst, musst du sicherstellen, dass der Runner Ubuntu verwendet und sudo apt-get ohne Kennwort ausführen kann.

Windows Laufdienste müssen powershell.exe auf dem PATH sein.

Erstellen von C#

CodeQL unterstützt die Buildmodi none, autobuild oder manual für C#-Code.

Wenn Sie das Standardsetup für ein Repository aktivieren, das C#-Code enthält, wird der Buildmodus automatisch auf none festgelegt.

Kein Build für C#

CodeQL stellt Abhängigkeiten wieder her und generiert einige zusätzliche Quelldateien, um genauere Ergebnisse zu erzielen, bevor eine Datenbank aus allen Quelldateien und Abhängigkeiten erstellt wird.

Abhängigkeiten werden mithilfe mehrerer Heuristiken und Strategien wiederhergestellt. Die folgenden Dateien sind die primäre Informationsquelle: *.csproj, , *.sln, nuget.config, packages.config, ,global.jsonund project.assets.json.

Die folgenden generierten Quelldateien sind optional, erhöhen jedoch die Korrektheit der CodeQL-Datenbank erheblich:

•         `global`-generierte `using`-Direktiven zur Behandlung des impliziten `using`-Features von MSbuild.
  

• ASP.NET Core-Kernansichtsdateien werden in .cshtml-Dateien zu .cs-Dateien konvertiert.

Die Informationen aus den Abhängigkeitsassemblynamen, aus den generierten Quelldateien, und aus den Quelldateien im Repository werden kompiliert und zum Erstellen einer CodeQL-Datenbank verwendet.

Genauigkeit der No-Build-Analyse für C#

Das Erstellen einer CodeQL-Datenbank ohne Erstellen des vollständigen Codes basiert darauf, Abhängigkeiten wiederherzustellen und die Quelldateien im Repository zusammenzustellen. Wenn es Probleme beim Wiederherstellen von Abhängigkeiten oder beim Kompilieren des Quellcodes gibt, kann sich dies auf die Genauigkeit der CodeQL-Datenbank und code scanning Analyseergebnisse auswirken.

Sie können eine genauere Analyse sicherstellen, indem Sie die folgenden Schritte ausführen:

• Gewähren Sie Zugriff auf das öffentliche Internet, oder stellen Sie sicher, dass Zugriff auf einen privaten NuGet-Feed verfügbar ist.
• Überprüfen Sie, ob für das Repository mehrere Versionen derselben NuGet-Abhängigkeit erforderlich sind. CodeQL kann nur eine Version verwenden und wählt in der Regel die neuere Version aus, in der mehrere Versionen vorhanden sind. Dieser Ansatz funktioniert möglicherweise nicht für alle Repositories.
• Überprüfen Sie, ob auf mehrere Versionen von .NET verwiesen wird, z. B. net48, net5.0 und netstandard1.6. CodeQL kann nur eine Version verwenden, und dies kann sich auf die Genauigkeit auswirken.
• Vermeiden Sie kollidierende Klassennamen, andernfalls kann dies zu fehlenden Methodenaufrufzielen führen, die Auswirkungen auf die Dataflow-Analyse haben.

Autobuild-Zusammenfassung für C#

Unterstütztes System	Systemname
Betriebssystem	Windows, macOS und Linux
Buildsystem	.NET und MSbuild sowie Buildskripts

Windows automatische Erkennung

Der autobuild-Prozess versucht, mit dem folgenden Ansatz automatisch eine geeignete Buildmethode für C# zu erkennen:

1. Für die Projektmappe (dotnet build) oder Projektdatei (.sln), die sich am nächsten beim Stamm befindet, wird .csproj aufgerufen.
2. Für die Projektmappe oder Projektdatei, die sich am nächsten beim Stamm befindet, wird MSBuild.exe aufgerufen. Wenn autobuild mehrere Projektmappen oder Projektdateien mit dem gleichen (kürzesten) Abstand zum obersten Verzeichnis erkennt, versucht autobuild, alle zu kompilieren.
3. Ein Skript wird aufgerufen, das wie ein Build-Skript aussieht – build.bat, build.cmd und build.exe (in dieser Reihenfolge).

Runner-Anforderungen für C# auf Windows

Für .NET Core-Anwendungsentwicklung auf selbst gehosteten Läufern ist das .NET SDK erforderlich (für dotnet).

Für .NET Framework-Anwendungsentwicklung benötigen Sie Microsoft Build Tools (für msbuild) und NuGet CLI (für nuget).

Windows Runner müssen powershell.exe auf dem PATH sein.

Wenn Sie beabsichtigen, CodeQL-Datenbanken mit build-mode: none zu erstellen, müssen Sie auch Zugriff auf das öffentliche Internet gewähren, oder Sie müssen sicherstellen, dass Zugriff auf einen privaten NuGet-Feed verfügbar ist.

Automatische Erkennung für Linux und macOS

1. Für die Projektmappe (dotnet build) oder Projektdatei (.sln), die sich am nächsten beim Stamm befindet, wird .csproj aufgerufen.
2. Für die Projektmappe oder Projektdatei, die sich am nächsten beim Stamm befindet, wird MSbuild aufgerufen. Wenn autobuild mehrere Projektmappen oder Projektdateien mit dem gleichen (kürzesten) Abstand zum obersten Verzeichnis erkennt, versucht autobuild, alle zu kompilieren.
3. Ein Skript wird aufgerufen, das wie ein Build-Skript aussieht – build und build.sh (in dieser Reihenfolge).

Runner-Anforderungen für C# unter Linux und macOS

Für .NET Core-Anwendungsentwicklung auf selbst gehosteten Läufern ist das .NET SDK erforderlich (für dotnet).

Für .NET Framework-Anwendungsentwicklung benötigen Sie Mono Runtime (zum Ausführen von mono, msbuild oder nuget).

Wenn Sie beabsichtigen, CodeQL-Datenbanken mit build-mode: none zu erstellen, müssen Sie auch Zugriff auf das öffentliche Internet gewähren, oder Sie müssen sicherstellen, dass Zugriff auf einen privaten NuGet-Feed verfügbar ist.

C#-Compilerflags, die von CodeQL für manuelle Builds eingefügt wurden

Der CodeQL-Tracer ermöglicht die Extraktion aller übersetzten Sprachen, indem er Buildprozesse abfängt und Informationen an die entsprechenden CodeQL-Sprachextraktoren weiterleitet. Der Tracer fügt bestimmte Flags in den C#-Compileraufruf ein, um sicherzustellen, dass jede Komponente erstellt und in die CodeQL-Datenbank aufgenommen wird. Dies kann dazu führen, dass Ihr C#-Code während der CodeQL-Analyse anders erstellt wird als erwartet.

/p:MvcBuildViews=true

Wenn diese Option auf true festgelegt ist, werden die Ansichten in ASP.NET MVC-Projekten (Model-View-Controller) im Rahmen des Buildprozesses vorkompiliert, wodurch Fehler abgefangen und die Leistung verbessert werden können. Der Tracer fügt dieses Flag ein, um sicherzustellen, dass CodeQL Sicherheitsprobleme findet und markiert, die den Dataflow über den aus diesen Ansichten generierten Code betreffen können. Weitere Informationen finden Sie unter Hinzufügen einer Ansicht zu einer MVC-Anwendung in Microsoft Learn.

/p:UseSharedCompilation=false

Wenn Sie diese Option auf false setzen, wird die Verwendung der Funktion für die gemeinsame Kompilierung deaktiviert, was zu langsameren Buildzeiten führen kann. Wenn /p:UseSharedCompilation=falsenicht angegeben ist, startet msbuild einen Compilerserverprozess, und die gesamte Kompilierung erfolgt durch diesen einzelnen Prozess. Der CodeQL-Tracer ist jedoch darauf angewiesen, die Argumente neu erstellter Prozesse zu überprüfen.

/p:EmitCompilerGeneratedFiles=true

Bei Festlegung dieser Option auf true werden vom Compiler generierte Dateien während des Buildprozesses ausgegeben. Diese Option veranlasst den Compiler, zusätzliche Quelldateien zu generieren, die zur Unterstützung von Funktionen wie der verbesserten Unterstützung regulärer Ausdrücke, der Serialisierung und der Generierung von Webanwendungsansichten verwendet werden. Diese generierten Artefakte werden normalerweise nicht vom Compiler auf den Datenträger geschrieben, doch bei Festlegung der Option auf true wird das Schreiben der Dateien auf den Datenträger erzwungen, sodass der Extraktor die Dateien verarbeiten kann.

Bei einigen Legacyprojekten und Projekten, die .sqlproj-Dateien verwenden, kann es sein, dass die eingefügte /p:EmitCompilerGeneratedFiles=true-Eigenschaft unerwartete Probleme mit msbuild verursacht. Weitere Informationen zur Behebung dieses Problems finden Sie unter Unerwarteter C#-Compilerfehler.

Erstellen von Go

CodeQL unterstützt die Buildmodi autobuild oder manual für Go-Code.

Autobuild-Zusammenfassung für Go

Unterstütztes System	Systemname
Betriebssystem	Windows, macOS und Linux
Buildsystem	Go-Module, dep und Glide sowie Buildskripts, einschließlich Makefiles und Ninja-Skripts

AutoDetection für Go

Der autobuild-Prozess versucht, automatisch einen geeigneten Weg zu finden, die von einem Go-Repository benötigten Abhängigkeiten zu installieren, bevor alle .go-Dateien extrahiert werden:

1. Rufe make, ninja, ./build oder ./build.sh (in dieser Reihenfolge) auf, bis einer dieser Befehle und ein nachfolgendes go list ./... auch erfolgreich ist, was zeigt, dass die erforderlichen Abhängigkeiten installiert wurden.
2. Wenn keiner dieser Befehle erfolgreich war, suche nach go.mod, Gopkg.toml oder glide.yaml und führe entsprechend go get (sofern Vendoring nicht verwendet wird), dep ensure -v oder glide install aus, um zu versuchen, Abhängigkeiten zu installieren.
3. Wenn keine Konfigurationsdateien für diese Abhängigkeits-Manager gefunden werden, ordne schließlich die Repositoryverzeichnisstruktur so neu an, dass sie GOPATH hinzugefügt werden kann, und installiere mit go get Abhängigkeiten. Die Verzeichnisstruktur wird nach Abschluss der Extraktion in die Normalität zurückgesetzt.
4. Extrahiere den gesamten Go-Code im Repository, ähnlich der Ausführung von go build ./....

Extraktoroptionen für Go

Standardmäßig wird Testcode (Code in Dateien, die auf _test.go enden) nicht analysiert. Sie können dies mit der Option --extractor-option extract_tests=true überschreiben, wenn Sie CodeQL CLI verwenden oder indem Sie die Umgebungsvariable CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS auf true festlegen.

Darüber hinaus werden vendor-Verzeichnisse standardmäßig von CodeQL Go-Analysen ausgeschlossen. Sie können dies durch Übergabe der Option --extractor-option extract_vendor_dirs=true überschreiben, wenn Sie CodeQL CLI verwenden oder indem Sie die Umgebungsvariable CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS auf true festlegen.

Erstellung von Java- und Kotlin-Anwendungen

CodeQL unterstützt die folgenden Buildmodi.

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

Wenn Sie das Standardsetup für ein Repository zum ersten Mal aktivieren, wenn nur Java Code erkannt wird, wird der Buildmodus auf none festgelegt. Wenn Kotlin oder eine Kombination aus Java und Kotlin-Code erkannt wird, wird der Buildmodus auf autobuild festgelegt.

Wenn Sie später Kotlin-Code zu einem Repository hinzufügen, das den none-Build-Modus verwendet, meldet CodeQL Analyse eine Warnmeldung, in der erläutert wird, dass Kotlin nicht unterstützt wird. Sie müssen das Standard-Setup deaktivieren und es erneut aktivieren. Wenn Sie erneut das Standard-Setup aktivieren, ändert sich der Build-Modus zu autobuild, so dass beide Sprachen analysiert werden können. Alternativ können Sie zu einem erweiterten Setup wechseln. Weitere Informationen finden Sie unter Warnung: Es wurden X Kotlin-Dateien in Ihrem Projekt erkannt, die ohne einen Build nicht verarbeitet werden konnten..

Kein Build für Java

CodeQL versucht, Gradle oder Maven auszuführen, um genaue Abhängigkeitsinformationen zu extrahieren (aber keinen Build aufzurufen), bevor eine Datenbank aus allen vorhandenen Java-Dateien erstellt wird. Jede Maven- oder Gradle-Stammprojektdatei (ein Buildskript ohne Buildskript, das in einem Vorgängerverzeichnis vorhanden ist) wird nach Abhängigkeitsinformationen abgefragt und neuere Abhängigkeitsversionen werden bevorzugt, wenn ein Konflikt vorliegt. Informationen zu den Läuferanforderungen für die Ausführung von Maven oder Gradle finden Sie unter Runner requirements for Java.

Genauigkeit der No-Build-Analyse für Java

Das Erstellen einer CodeQL Java-Datenbank ohne Kompilierung kann zu ungenaueren Ergebnissen führen als die Verwendung von autobuild oder manuellen Build-Schritten, wenn:

• Gradle- oder Maven-Build-Skripte können nicht nach Abhängigkeitsinformationen abgefragt werden, und Abhängigkeitsschätzungen (basierend auf Java-Paket-Namen) sind ungenau.
• Das Repository generiert normalerweise Code während des Buildprozesses. Dies würde analysiert, wenn Sie die CodeQL-Datenbank mit einem anderen Modus erstellt haben.

Sie können eine genauere Analyse sicherstellen, indem Sie die folgenden Schritte ausführen:

• Gewähren Sie Zugriff auf das öffentliche Internet, oder stellen Sie sicher, dass Zugriff auf ein privates Artefaktrepository verfügbar ist.
• Überprüfen Sie, ob für das Repository mehrere Versionen derselben Abhängigkeit erforderlich sind. CodeQL kann nur eine Version verwenden und wählt in der Regel die neuere Version aus, in der mehrere Versionen vorhanden sind. Dieser Ansatz funktioniert möglicherweise nicht für alle Repositories.
• Überprüfen Sie, ob mehrere Versionen der JDK-API von verschiedenen Quelldateien Java benötigt werden. Bei mehreren Versionen nutzt CodeQL die höchste Version, die von einem Buildskript benötigt wird. Das kann bedeuten, dass einige Dateien, die eine niedrigere Version des JDK benötigen, teilweise analysiert werden. Wenn beispielsweise einige Dateien JDK 8 benötigen, in einem oder mehreren Buildskripts jedoch eine JDK 17-Anforderung gefunden wird, nutzt CodeQL JDK 17. Dateien, die JDK 8 benötigen und nicht mit JDK 17 erstellt werden konnten, werden teilweise analysiert.
• Vermeiden Sie kollidierende Klassennamen (zum Beispiel mehrere Dateien, die org.myproject.Test definieren). Andernfalls kann dies zu fehlenden Methodenaufrufzielen führen, was Auswirkungen auf die Dataflow-Analyse hat.

AutoBuild-Zusammenfassung für Java

Unterstütztes System	Systemname
Betriebssystem	Windows, macOS und Linux (keine Einschränkung)
Buildsystem	Gradle, Maven und Ant

AutoDetection für Java

Der prozess autobuild versucht, das Buildsystem für Java Codebases durch Anwenden dieser Strategie zu ermitteln:

1. Im Stammverzeichnis wird nach einer Builddatei gesucht. Eine Prüfung auf Gradle-, dann Maven-, dann Ant-Builddateien erfolgt.
2. Die erste gefundene Builddatei wird ausgeführt. Wenn sowohl Gradle- als auch Maven-Dateien vorhanden sind, wird die Gradle-Datei verwendet.
3. Andernfalls wird in direkten Unterverzeichnissen des Stammverzeichnisses nach Builddateien gesucht. Wenn nur ein Unterverzeichnis Builddateien enthält, wird die erste Datei ausgeführt, die in diesem Unterverzeichnis ermittelt wurde (mit derselben Einstellung wie für 1). Wenn mehrere Unterverzeichnisse Builddateien enthalten, wird ein Fehler gemeldet.

Runner-Anforderungen für Java

Wenn Sie selbst gehostete Läufer verwenden, sollten die erforderlichen Versionen von Java vorhanden sein:

• Wenn der Runner zum Analysieren von Repositorys verwendet wird, die eine einzelne Version von Java benötigen, muss die entsprechende JDK-Version installiert werden und muss in der PATH-Variablen vorhanden sein (sodass java und javac gefunden werden können).

• Wenn der Runner zum Analysieren von Repositorys verwendet wird, die mehrere Versionen von Java benötigen, müssen die entsprechenden JDK-Versionen installiert werden und können über die Datei toolchains.xml angegeben werden. Dies ist eine Konfigurationsdatei, die in der Regel von Apache Maven verwendet wird, mit der Sie den Speicherort der Tools, die Version der Tools und alle zusätzlichen Konfigurationen angeben können, die für die Verwendung der Tools erforderlich sind. Weitere Informationen finden Sie in der Apache Maven-Dokumentation unter Guide to Using Toolchains (Leitfaden zur Verwendung von Toolchains).

Die folgenden ausführbaren Dateien sind wahrscheinlich für einen Bereich von Java Projekten erforderlich und sollten in der PATH-Variablen vorhanden sein, sind aber in allen Fällen nicht unbedingt erforderlich:

•         `mvn` (Apache Maven)
  

•         `gradle` (Gradle)
  

•         `ant` (Apache Ant)
  

Außerdem müssen Sie das Buildsystem (z. B. make, cmake, bazel) und Dienstprogramme (z. B. python, perl, lex und yacc) installieren, von denen die Projekte abhängen.

Windows Runner müssen powershell.exe auf dem PATH sein.

Erstellen von Swift

CodeQL unterstützt die Buildmodi autobuild oder manual für Swift-Code.

Autobuild-Zusammenfassung für Swift

Unterstütztes System	Systemname
Betriebssystem	macOS
Buildsystem	Xcode

Der Prozess autobuild versucht, das größte Ziel aus einem Xcode-Projekt oder -Arbeitsbereich zu kompilieren.

Bei der Codeüberprüfung von Swift-Code werden standardmäßig macOS-Runner verwendet.

Code scanning von Swift-Code werden für Runner, die Teil einerActions Runner Controller (ARC) sind, nicht unterstützt, da ARC-Runner nur Linux verwenden und Swift macOS-Runner erfordert. Sie können jedoch eine Mischung aus ARC-Runnern und selbst gehosteten macOS-Runnern haben. Weitere Informationen finden Sie unter Actions Runner Controller.

Anpassen der Swift-Kompilierung in einem CodeQL-Analyseworkflow

          Sowohl `xcodebuild` als auch `swift build` werden für Swift-Builds unterstützt. Es wird empfohlen, während des Builds nur eine Architektur als Ziel zu verwenden. Beispiel: `ARCH=arm64` für `xcodebuild` oder `--arch arm64` für `swift build`.

Sie können die Optionen archive und test an xcodebuild übergeben. Es wird jedoch die Verwendung des Standardbefehls xcodebuild empfohlen, da dieser am schnellsten ist und CodeQL für eine erfolgreiche Überprüfung nichts weiter erfordert.

Für die Swift-Analyse müssen Sie über CocoaPods oder Carthage verwaltete Abhängigkeiten immer explizit installieren, bevor Sie die CodeQL-Datenbank generieren.