Vorbereiten des Codes für die CodeQL-Analyse

Informationen zum Vorbereiten von Code für die Analyse

Bevor du deinen Code mit CodeQL analysierst, musst du eine CodeQL-Datenbank erstellen, die alle zum Ausführen von Abfragen für deinen Code erforderlichen Daten enthält. Du kannst CodeQL-Datenbanken selbst erstellen, indem du CodeQL CLI verwendest.

Bei der CodeQL-Analyse werden relationale Daten aus deinem Code extrahiert und zum Erstellen einer CodeQL-Datenbank verwendet. CodeQL-Datenbanken enthalten alle wichtigen Informationen zu einer Codebasis, die analysiert werden können, indem CodeQL-Abfragen dafür ausgeführt werden.

Bevor du eine CodeQL-Datenbank erstellst, musst du Folgendes tun:

1. Installiere und teste die CodeQL CLI. Weitere Informationen findest du unter Einrichten der CodeQL-CLI.
2. Checke den Code aus, den du analysieren möchtest:
   • Für einen Branch: Checke den Kopfteil des Branchs aus, den du analysieren möchtest.
   • Für einen Pull Request: Checke entweder den Headcommit des Pull Requests oder den von GitHub generierten Mergecommit aus.
3. Richte die Umgebung für die Codebasis ein, und stelle sicher, dass alle Abhängigkeiten verfügbar sind. Weitere Informationen findest du unter Erstellen von Datenbanken für nicht kompilierte Sprachen und Erstellen von Datenbanken für kompilierte Sprachen.
4. Suche ggf. den Buildbefehl für die Codebasis. Üblicherweise ist dieser in der Konfigurationsdatei des CI-Systems verfügbar.

Sobald die Codebasis bereit ist, kannst du codeql database create ausführen, um die Datenbank zu erstellen.

Wird ausgeführt codeql database create

CodeQL-Datenbanken werden erstellt, indem der folgende Befehl über den Check-Out-Stamm deines Projekts ausgeführt wird:

codeql database create <database> --language=<language-identifier>

Dabei musst du Folgendes festlegen:

• <database>: Dies ist ein Pfad zur neuen Datenbank, die erstellt werden soll. Dieses Verzeichnis wird erstellt, wenn du den Befehl ausführst. Du kannst kein vorhandenes Verzeichnis angeben.
• --language: Dies ist der Bezeichner für die Sprache, die zum Erstellen der Datenbank verwendet wird. Wenn dieser mit --db-cluster verwendet wird, akzeptiert die Option eine durch Kommas getrennte Liste oder kann mehrfach angegeben werden. CodeQL unterstützt das Erstellen von Datenbanken für die folgenden Sprachen:

Sprache	Bezeichner
C/C++	cpp
C#	csharp
Go	go
Java	java
JavaScript/TypeScript	javascript
Python	python
Ruby	ruby

Wenn deine Codebasis über einen Buildbefehl oder ein Skript verfügt, der den Buildprozess aufruft, wird empfohlen, ihn auch anzugeben:

   codeql database create <database> --command <build> \
         --language=<language-identifier>

Du kannst je nach Speicherort deiner Quelldatei mehrere Optionen angeben, wenn der Code kompiliert werden muss und wenn du CodeQL-Datenbanken für mehrere Sprachen erstellen möchtest.

Option	Erforderlich	Verwendung
<database>		Gib den Namen und den Speicherort eines Verzeichnisses an, das für die CodeQL-Datenbank erstellt werden soll. Der Befehl schlägt fehl, wenn du versuchst, ein vorhandenes Verzeichnis zu überschreiben. Wenn du außerdem --db-cluster angibst, ist dies das übergeordnete Verzeichnis, und für jede analysierte Sprache wird ein Unterverzeichnis erstellt.
--language		Gib den Bezeichner für die Sprache an, für die die Datenbank erstellt werden soll: cpp, csharp, go, java, javascript, python, und ruby (verwende javascript zum Analysieren von TypeScript-Code ). Wenn dieser mit --db-cluster verwendet wird, akzeptiert die Option eine durch Kommas getrennte Liste oder kann mehrfach angegeben werden.
--command		Empfohlen. Verwende diese Option, um den Buildbefehl oder das Skript anzugeben, der bzw. das den Buildprozess für die Codebasis aufruft. Befehle werden aus dem aktuellen Ordner oder (falls definiert) aus --source-root ausgeführt. Diese Option ist für Python- und JavaScript- bzw. TypeScript-Analysen nicht erforderlich.
--db-cluster		Verwende diese Option für Codebasen mit mehreren Sprachen, um eine Datenbank für jede durch --language angegebene Sprache zu generieren.
--no-run-unnecessary-builds		Empfohlen. Verwende diese Option, um den Buildbefehl für Sprachen zu unterdrücken, in denen die CodeQL CLI den Build nicht überwachen muss (z. B. Python und JavaScript bzw. TypeScript).
--source-root		Verwende diese Option, wenn du die CLI außerhalb des Check-Out-Stamms des Repositorys ausführst. Beim Befehl zum Erstellen von Datenbanken (database create) wird standardmäßig davon ausgegangen, dass das aktuelle Verzeichnis das Stammverzeichnis der Quelldateien ist. Verwende diese Option, um einen anderen Speicherort anzugeben.
--codescanning-config		Erweitert. Verwende diese Option, wenn du über eine Konfigurationsdatei verfügst, die angibt, wie die CodeQL-Datenbanken erstellt werden und welche Abfragen in späteren Schritten ausgeführt werden sollen. Weitere Informationen finden Sie unter Anpassen Codeüberprüfung und unter database create.

Du kannst Extraktoroptionen angeben, um das Verhalten von Extraktoren anzupassen, die CodeQL-Datenbanken erstellen. Weitere Informationen findest du unter Extraktoroptionen.

Ausführliche Informationen zu allen Optionen, die du beim Erstellen von Datenbanken verwenden kannst, findest du unter database create.

Beispiel für eine einzelne Sprache

In diesem Beispiel wird eine einzelne CodeQL-Datenbank für das Repository erstellt, das unter /checkouts/example-repo ausgecheckt ist. Dabei wird der JavaScript-Extraktor verwendet, um eine hierarchische Darstellung des JavaScript- und TypeScript-Codes im Repository zu erstellen. Die resultierende Datenbank wird unter /codeql-dbs/example-repo gespeichert.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Beispiel für mehrere Sprachen

In diesem Beispiel werden zwei CodeQL-Datenbanken für das Repository erstellt, das unter /checkouts/example-repo-multi ausgecheckt ist. Er verwendet Folgendes:

• --db-cluster: Wird verwendet, um die Analyse mehrerer Sprachen anzufordern
• --language: Wird verwendet, um anzugeben, für welche Sprachen Datenbanken erstellt werden sollen
• --command: Wird verwendet, um dem Tool den Buildbefehl für die Codebasis weiterzugeben, hier make.
• --no-run-unnecessary-builds: Wird verwendet, um das Tool anzuweisen, den Buildbefehl für Sprachen zu überspringen, in denen er nicht benötigt wird (z. B. für Python)

Die resultierenden Datenbanken werden in den Unterverzeichnissen python und cpp von /codeql-dbs/example-repo-multi gespeichert.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Fortschritte und Ergebnisse

Fehler werden gemeldet, wenn Probleme mit den von dir angegebenen Optionen auftreten. Bei interpretierten Sprachen wird der Extraktionsfortschritt in der Konsole angezeigt. Für jede Quelldatei zeigt die Konsole an, ob die Extraktion erfolgreich war oder ob sie fehlgeschlagen ist. Für kompilierte Sprachen zeigt die Konsole die Ausgabe des Buildsystems an.

Wenn die Datenbank erfolgreich erstellt wurde, findest du das neue Verzeichnis unter dem Pfad, der im Befehl angegeben ist. Wenn du die Option --db-cluster zum Erstellen von mehr als einer Datenbank verwendet hast, wird für jede Sprache ein Unterverzeichnis erstellt. Jedes CodeQL-Datenbankverzeichnis enthält mehrere Unterverzeichnisse, darunter die (für die Analyse erforderlichen) relationalen Daten und ein Quellarchiv (eine Kopie der Quelldateien, die zum Zeitpunkt der Datenbankerstellung erstellt wurden), das zum Anzeigen von Analyseergebnissen verwendet wird.

Erstellen von Datenbanken für nicht kompilierte Sprachen

Die CodeQL CLI enthält Extraktoren zum Erstellen von Datenbanken für nicht kompilierte Sprachen, nämlich JavaScript (und TypeScript), Python und Ruby. Diese Extraktoren werden automatisch aufgerufen, wenn du JavaScript, Python oder Ruby beim Ausführen von database create als --language-Option angibst. Beim Erstellen von Datenbanken für diese Sprachen musst du sicherstellen, dass alle zusätzlichen Abhängigkeiten verfügbar sind.

JavaScript und TypeScript

Zum Erstellen von Datenbanken für JavaScript sind keine zusätzlichen Abhängigkeiten erforderlich. Wenn das Projekt jedoch TypeScript-Dateien enthält, musst du Node.js (Version 6.x oder höher) installieren. In der Befehlszeile kannst du --language=javascript angeben, um sowohl JavaScript- als auch TypeScript-Dateien zu extrahieren:

codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database

Hier wurde ein --source-root-Pfad angegeben, der den Speicherort darstellt, an dem die Datenbankerstellung ausgeführt wird, aber nicht zwangsläufig der Check-Out-Stamm der Codebasis ist.

Standardmäßig werden Dateien in node_modules- und bower_components-Verzeichnissen nicht extrahiert.

Python

Beim Erstellen von Datenbanken für Python musst du Folgendes sicherstellen:

• Python 3 wurde installiert und ist für den CodeQL-Extraktor verfügbar.
• Du hast die Version von Python installiert, die von deinem Code verwendet wird.
• Du hast Zugriff auf das pip-Paketverwaltungssystem und kannst alle Pakete installieren, von denen die Codebasis abhängt.
• Du hast das pip-Modul virtualenv installiert.

In der Befehlszeile musst du --language=python angeben. Beispiel:

codeql database create --language=python <output-folder>/python-database

Dadurch wird der Unterbefehl database create aus dem Check-Out-Stamm des Codes ausgeführt und eine neue Python-Datenbank unter <output-folder>/python-databasegeneriert.

Ruby

Für das Erstellen von Datenbanken für Ruby sind keine weiteren Abhängigkeiten erforderlich. In der Befehlszeile musst du --language=ruby angeben. Beispiel:

codeql database create --language=ruby --source-root <folder-to-extract> <output-folder>/ruby-database

Hier wurde ein --source-root-Pfad angegeben, der den Speicherort darstellt, an dem die Datenbankerstellung ausgeführt wird, aber nicht zwangsläufig der Check-Out-Stamm der Codebasis ist.

Erstellen von Datenbanken für kompilierte Sprachen

Für kompilierte Sprachen muss CodeQL das erforderliche Buildsystem aufrufen, um eine Datenbank zu generieren. Daher muss die Buildmethode für die CLI verfügbar sein.

Ermitteln des Buildsystems

Die CodeQL CLI enthält Autobuilder für C/C++, C#, Go, und Java-Code. Mit CodeQL-Autobuildern kannst du Projekte für kompilierte Sprachen erstellen, ohne Buildbefehle anzugeben. Wenn ein Autobuilder aufgerufen wird, untersucht CodeQL die Quelle auf Nachweise für ein Buildsystem und versucht, die optimalen Befehle auszuführen, die zum Extrahieren einer Datenbank erforderlich sind. Weitere Informationen findest du unter CodeQL-Codeüberprüfung für kompilierte Sprachen.

Ein Autobuilder wird automatisch aufgerufen, wenn du codeql database create für eine kompilierte --language ausführst und keine --command-Option einschließt. Für eine Java-Codebasis könntest du einfach Folgendes ausführen:

codeql database create --language=java <output-folder>/java-database

Wenn eine Codebasis ein Standardbuildsystem verwendet, ist die Verwendung eines Autobuilders häufig die einfachste Möglichkeit, eine Datenbank zu erstellen. Für Quellen, die vom Standard abweichende Buildschritte erfordern, musst du möglicherweise jeden Schritt in der Befehlszeile explizit definieren.

Angeben von Buildbefehlen

Die folgenden Beispiele bieten einen Überblick über einige der Buildbefehle, die du für kompilierte Sprachen angeben kannst.

• C- bzw. C++-Projekt, das mit make erstellt wurde:

  codeql database create cpp-database --language=cpp --command=make
  

• C#-Projekt, das mit dotnet build erstellt wurde:

  Du solltest /t:rebuild hinzufügen, um sicherzustellen, dass der gesamte Code erstellt wird, oder zuvor einen dotnet clean ausführen (Code, der nicht erstellt wird, wird nicht in die CodeQL-Datenbank aufgenommen):

  codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
  

• Go-Projekt, das mit der Umgebungsvariablen CODEQL_EXTRACTOR_GO_BUILD_TRACING=on erstellt wurde:

  CODEQL_EXTRACTOR_GO_BUILD_TRACING=on codeql database create go-database --language=go
  

• Go-Projekt, das mit einem benutzerdefinierten Buildskript erstellt wurde:

  codeql database create go-database --language=go --command='./scripts/build.sh'
  

• Java-Projekt, das mit Gradle erstellt wurde:

  # Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL.
  # To ensure isolated builds without caching, add `--no-build-cache` on persistent machines.
  codeql database create java-database --language=java --command='gradle --no-daemon clean test'
  

• Java-Projekt, das mit Maven erstellt wurde:

  codeql database create java-database --language=java --command='mvn clean install'
  

• Java-Projekt, das mit Ant erstellt wurde:

  codeql database create java-database --language=java --command='ant -f build.xml'
  

• Mit Bazel erstelltes Projekt:

  # Navigate to the Bazel workspace.
  
  # Before building, remove cached objects
  # and stop all running Bazel server processes.
  bazel clean --expunge
  
  # Build using the following Bazel flags, to help CodeQL detect the build:
  # `--spawn_strategy=local`: build locally, instead of using a distributed build
  # `--nouse_action_cache`: turn off build caching, which might prevent recompilation of source code
  # `--noremote_accept_cached`, `--noremote_upload_local_results`: avoid using a remote cache
  codeql database create new-database --language=<language> \
  --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results //path/to/package:target'
  
  # After building, stop all running Bazel server processes.
  # This ensures future build commands start in a clean Bazel server process
  # without CodeQL attached.
  bazel shutdown
  

• Mit einem benutzerdefinierten Buildskript erstelltes Projekt:

  codeql database create new-database --language=<language> --command='./scripts/build.sh'
  

Dieser Befehl führt ein benutzerdefiniertes Skript aus, das alle Befehle enthält, die zum Erstellen des Projekts erforderlich sind.

Verwenden der indirekten Buildablaufverfolgung

Wenn die CodeQL CLI-Autobuilder für kompilierte Sprachen nicht mit deinem CI-Workflow funktionieren und du Aufrufe von Buildbefehlen nicht mit codeql database trace-command umschließen kannst, kannst du die indirekte Buildablaufverfolgung verwenden, um eine CodeQL-Datenbank zu erstellen. Um die indirekte Buildablaufverfolgung verwenden zu können, muss dein CI-System in der Lage sein, benutzerdefinierte Umgebungsvariablen für jede Buildaktion festzulegen.

Um eine CodeQL-Datenbank mit indirekter Buildablaufverfolgung zu erstellen, führe den folgenden Befehl im Check-Out-Stamm deines Projekts aus:

codeql database init ... --begin-tracing <database>

Dabei musst du Folgendes festlegen:

• <database>: Dies ist ein Pfad zur neuen Datenbank, die erstellt werden soll. Dieses Verzeichnis wird erstellt, wenn du den Befehl ausführst. Du kannst kein vorhandenes Verzeichnis angeben.
• --begin-tracing: Dieser Befehl erstellt Skripts, die zum Einrichten einer Umgebung verwendet werden können, in der Buildbefehle nachverfolgt werden.

Du kannst andere Optionen für den codeql database init-Befehl wie gewohnt angeben.

Der codeql database init-Befehl gibt eine Nachricht aus:

Created skeleton <database>. This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in <database>/temp/tracingEnvironment. Please run one of these scripts before invoking your build command.

Based on your operating system, we recommend you run: ...

Der codeql database init-Befehl erstellt <database>/temp/tracingEnvironment mit Dateien, die Umgebungsvariablen und Werte enthalten, mit denen CodeQL eine Sequenz von Buildschritten nachverfolgen kann. Diese Dateien haben den Namen start-tracing.{json,sh,bat,ps1}. Verwende eine dieser Dateien mit dem Mechanismus deines CI-Systems zum Festlegen von Umgebungsvariablen für zukünftige Schritte. Du hast folgende Möglichkeiten:

• Lies die JSON-Datei, verarbeite sie, und gib die Umgebungsvariablen in dem von deinem CI-System erwarteten Format aus. Azure DevOps erwartet beispielsweise echo "##vso[task.setvariable variable=NAME]VALUE".
• Wenn dein CI-System die Umgebung endgültig gespeichert hat, binde das entsprechende start-tracing-Skript ein, um die CodeQL-Variablen in der Shellumgebung des CI-Systems festzulegen.

Schreibe deinen Code. Deaktiviere optional die Umgebungsvariablen mithilfe eines end-tracing.{json,sh,bat,ps1}-Skripts aus dem Verzeichnis, in dem die start-tracing-Skripts gespeichert sind, und führe dann den Befehl codeql database finalize <database> aus.

Nachdem du eine CodeQL-Datenbank mithilfe der indirekten Buildablaufverfolgung erstellt hast, kannst du damit wie mit jeder anderen CodeQL-Datenbank arbeiten. Analysiere beispielsweise die Datenbank, und lade die Ergebnisse in GitHub hoch, wenn du die Codeüberprüfung verwendest.

Beispiel für das Erstellen einer CodeQL-Datenbank mithilfe der indirekten Buildablaufverfolgung

Das folgende Beispiel zeigt, wie du die indirekte Buildablaufverfolgung in einer Azure DevOps-Pipeline verwenden kannst, um eine CodeQL-Datenbank zu erstellen:

steps:
    # Download the CodeQL CLI and query packs...
    # Check out the repository ...

    # Run any pre-build tasks, for example, restore NuGet dependencies...

    # Initialize the CodeQL database.
    # In this example, the CodeQL CLI has been downloaded and placed on the PATH.
    - task: CmdLine@1
       displayName: Initialize CodeQL database
      inputs:
          # Assumes the source code is checked out to the current working directory.
          # Creates a database at `<current working directory>/db`.
          # Running on Windows, so specifies a trace process level.
          script: "codeql database init --language csharp --trace-process-name Agent.Worker.exe --source-root . --begin-tracing db"

    # Read the generated environment variables and values,
    # and set them so they are available for subsequent commands
    # in the build pipeline. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Set CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    # Execute the pre-defined build step. Note the `msbuildArgs` variable.
    - task: VSBuild@1
        inputs:
          solution: '**/*.sln'
          msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory)
          platform: Any CPU
          configuration: Release
          # Execute a clean build, in order to remove any existing build artifacts prior to the build.
          clean: True
       displayName: Visual Studio Build

    # Read and set the generated environment variables to end build tracing. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Clear CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/end-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    - task: CmdLine@2
       displayName: Finalize CodeQL database
       inputs:
          script: 'codeql database finalize db'

    # Other tasks go here, for example:
    # `codeql database analyze`
    # then `codeql github upload-results` ...

Nächste Schritte

• Informationen zum Verwenden von CodeQL CLI zum Analysieren der Datenbank, die du aus deinem Code erstellt hast, findest du unter Analysieren des Codes mit CodeQL-Abfragen.