Erstellen von CodeQL-Datenbanken

Informationen zum Erstellen von CodeQL-Datenbanken

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 mit der CodeQL CLI erstellen oder sie von GitHub.com herunterladen.

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. GitHub erstellt und speichert CodeQL-Datenbanken für eine große Anzahl von Open-Source-Projekten. Weitere Informationen findest du unter Herunterladen von CodeQL-Datenbanken auf der GitHub.com-Website.

Du kannst CodeQL-Datenbanken auch selbst erstellen, indem du CodeQL CLI verwendest. Bevor du eine CodeQL-Datenbank erstellst, musst du Folgendes tun:

• Installiere und teste die CodeQL CLI. Weitere Informationen findest du unter Erste Schritte mit der CodeQL CLI.
• Checke die Version deiner Codebasis aus, die du analysieren möchtest. Das Verzeichnis sollte für die Erstellung bereit sein, wobei alle Abhängigkeiten bereits installiert sind.

Informationen zum Verwenden der CodeQL CLI in einem CI-System eines Drittanbieters, um Ergebnisse zu erstellen, die in GitHub als Codeüberprüfungswarnungen angezeigt werden, findest du unter Konfigurieren von CodeQL CLI in deinem CI-System. Weitere Informationen zum Aktivieren der CodeQL-Codeüberprüfung mit GitHub Actions findest du unter Einrichten der Codeüberprüfung für ein Repository.

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

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:

• --source-root: Dies ist der Stammordner für die primären Quelldateien, die bei der Datenbankerstellung verwendet werden. Bei dem Befehl wird standardmäßig davon ausgegangen, dass das aktuelle Verzeichnis der Quellstamm ist. Verwende diese Option, um einen anderen Speicherort anzugeben.
• --db-cluster: Dieser wird für mehrsprachige Codebasen verwendet, wenn du Datenbanken für mehrere Sprachen erstellen möchtest.
• --command: Dieser Befehl wird verwendet, wenn du eine Datenbank für eine oder mehrere kompilierte Sprachen erstellst. Verwende ihn nicht, wenn die einzigen angeforderten Sprachen Python und JavaScript sind. Dies gibt die Buildbefehle an, die zum Aufrufen des Compilers erforderlich sind. Befehle werden im aktuellen Ordner oder im --source-root ausgeführt (falls angegeben). Wenn du keinen --command einschließt, versucht CodeQL, das Buildsystem mithilfe eines integrierten Autobuilders automatisch zu erkennen.
• --no-run-unnecessary-builds: Wird mit --db-cluster verwendet, 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).

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 in der Referenzdokumentation zum Erstellen von Datenbanken.

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 wird gemeldet, ob die Extraktion erfolgreich war oder ein Fehler aufgetreten 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.

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: 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` ...

Herunterladen von Datenbanken von GitHub.com

GitHub speichert CodeQL-Datenbanken für über 200.000 Repositorys auf GitHub.com, die du mithilfe der REST-API herunterladen kannst. Die Liste der Repositorys wird ständig erweitert und aktualisiert, damit die interessantesten Codebasen für die Sicherheitsforschung enthalten sind.

Du kannst überprüfen, ob ein Repository über CodeQL-Datenbanken verfügt, die über den /repos/<owner>/<repo>/code-scanning/codeql/databases-Endpunkt heruntergeladen werden können. Wenn du beispielsweise mithilfe der GitHub CLI nach CodeQL-Datenbanken suchen möchtest, musst die Folgendes ausführen:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/

Dieser Befehl gibt Informationen zu allen CodeQL-Datenbanken zurück, die für ein Repository verfügbar sind, einschließlich der Sprache, in der die Datenbank vorliegt, und dem Zeitpunkt, an dem die Datenbank zuletzt aktualisiert wurde. Wenn keine CodeQL-Datenbanken verfügbar sind, ist die Antwort leer.

Wenn du überprüft hast, ob eine CodeQL-Datenbank für die gewünschte Sprache vorhanden ist, kannst du sie mit dem folgenden Befehl herunterladen:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

Weitere Informationen findest du in der Dokumentation zum CodeQL-Datenbankendpunkt.

Bevor du eine Analyse mit der CodeQL CLI durchführst, musst du die Datenbanken entzippen.

Weiterführende Themen

• Analysieren deiner Projekte in CodeQL für VS Code