Datenbankinit

Hinweis

In diesem Inhalt wird die neueste Version von CodeQL CLI beschrieben. Weitere Informationen zu diesem Thema findest du unter https://github.com/github/codeql-cli-binaries/releases.

Um Details zu den Optionen anzuzeigen, die für diesen Befehl in früheren Releases verfügbar sind, führe den Befehl mit der Option --help im Terminal aus.

Zusammenfassung

Shell

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Description

          \[Plumbing] Erstelle eine leere CodeQL-Datenbank.

Erstellt eine Grundstruktur für eine CodeQL-Datenbank, die noch keine QL-Rohdaten enthält, aber für die Ausführung von Extraktorschritten genutzt werden kann. Führt nach Abschluss dieses Befehls mindestens einen codeql database trace-command-Befehl gefolgt von codeql database finalize aus, um die Datenbank für Abfragen vorzubereiten.

(Dabei wird unter anderem der Speicherort des entsprechenden Sprachpakets ermittelt und in den Metadaten der Datenbank gespeichert, sodass dies nicht bei jedem Extraktionsbefehl wiederholt werden muss. Es ist ohnehin nicht zulässig, die Extraktoren mitten in einem Extraktionsvorgang zu wechseln.)

Options

Primäre Optionen

`<database>`

          \[Erforderlich] Pfad zur zu erstellenden CodeQL-Datenbank. Dieses Verzeichnis wird erstellt und _darf noch nicht_ vorhanden sein (aber das übergeordnete Verzeichnis muss vorhanden sein).

Wenn die Option --db-cluster angegeben ist, handelt es sich nicht um eine Datenbank als solches, sondern um ein Verzeichnis, das Datenbanken für mehrere Sprachen enthält, die aus demselben Quellstammverzeichnis erstellt wurden.

Es ist wichtig, dass sich dieses Verzeichnis nicht an einem Speicherort befindet, an dem der Buildprozess beeinträchtigt wird. Das Verzeichnis target eines Maven-Projekts wäre zum Beispiel keine geeignete Wahl.

`-s, --source-root=<dir>`

          \[Erforderlich] Das Stammverzeichnis für den Quellcode. In vielen Fällen ist dies das Check-Out-Stammverzeichnis. Die darin enthaltenen Dateien gelten als primäre Quelldateien für diese Datenbank. In einigen Ausgabeformaten wird auf Dateien durch den relativen Pfad aus diesem Verzeichnis verwiesen.

`--[no-]overwrite`

          \[Erweitert] Wenn die Datenbank bereits existiert, lösche sie und fahre mit diesem Befehl fort, anstatt fehlzuschlagen. Wenn das Verzeichnis zwar existiert, aber nicht wie eine Datenbank aussieht, wird ein Fehler ausgelöst.

`--[no-]force-overwrite`

          \[Erweitert] Wenn die Datenbank bereits existiert, lösche sie, auch wenn sie nicht wie eine Datenbank aussieht, und fahre mit diesem Befehl fort, anstatt fehlzuschlagen. Diese Option sollte mit Vorsicht verwendet werden, da sie das gesamte Datenbankverzeichnis rekursiv löschen kann.

`--codescanning-config=<file>`

          \[Erweitert] Lies eine Code-Scanning-Konfigurationsdatei, in der du festlegst, wie die CodeQL-Datenbanken erstellt werden und welche Abfragen in späteren Schritten ausgeführt werden sollen. Weitere Informationen zum Format dieser Konfigurationsdatei findest du unter [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). Um Abfragen aus dieser Datei in einem späteren Schritt auszuführen, rufe [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) ohne weitere Abfragen auf.

`--[no-]db-cluster`

Anstatt eine einzige Datenbank zu erstellen, erstelle einen „Cluster“ aus Datenbanken für verschiedene Sprachen, die jeweils ein Unterverzeichnis des in der Befehlszeile angegebenen Verzeichnisses sind.

`-l, --language=<lang>[,<lang>...]`

Die Sprache, die von der neuen Datenbank analysiert wird.

Verwende codeql resolve languages, um eine Liste der austauschbaren Sprachextraktoren abzurufen, die im Suchpfad gefunden wurden.

Wenn die Option --db-cluster angegeben ist, kann dies mehrmals angezeigt werden, oder der Wert kann eine durch Trennzeichen getrennte Liste von Sprachen sein.

Wenn diese Option weggelassen wird und das zu analysierende Quellstammverzeichnis ein Check-Out eines GitHub-Repositorys ist, ruft die CodeQL-CLI die GitHub-API auf, um automatisch zu ermitteln, welche Sprachen analysiert werden sollen. Beachte, dass dazu ein GitHub PAT-Token entweder in der Umgebungsvariablen GITHUB_TOKEN oder über die Standardeingabe mit der Option --github-auth-stdin bereitgestellt werden muss.

`--build-mode=<mode>`

Der Buildmodus, der zum Erstellen der Datenbank verwendet wird.

Wählen Sie Ihren Buildmodus basierend auf der Sprache aus, die Sie analysieren:

          `none`: Die Datenbank wird erstellt, ohne den Quellcode zu erstellen.

Verfügbar für C#, Java, JavaScript/TypeScript, Python und Ruby.

          `autobuild`: Die Datenbank wird erstellt, indem versucht wird, den Quellcode automatisch zu erstellen. Verfügbar für C/C++, C#, Go, Java/Kotlin und Swift.

          `manual`: Die Datenbank wird erstellt, indem der Source Root mit einem manuell festgelegten Build-Befehl erstellt wird. Verfügbar für C/C++, C#, Go, Java/Kotlin und Swift.

Beim Erstellen einer Datenbank mit --command muss nicht zusätzlich „--build-mode none“ angegeben werden.

Verfügbar seit v2.16.4.

`--[no-]allow-missing-source-root`

          \[Erweitert] Fortfahren, auch wenn der angegebene Quellstamm nicht existiert.

`--[no-]begin-tracing`

          \[Erweitert] Erstelle einige Skripte, mit denen du ein „indirektes Tracing“ einrichten kannst, das die Integration in bestehende Workflows bietet, wenn kein expliziter Build-Befehl verfügbar ist. Informationen zur Verwendung dieses Features findest du in unserer Dokumentation unter [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis).

Baselineberechnungsoptionen

`--[no-]calculate-baseline`

          \[Erweitert] Berechne Baseline-Informationen über den zu analysierenden Code und füge sie der Datenbank hinzu. Standardmäßig ist dies aktiviert, es sei denn, der Quellstamm ist das Stammverzeichnis eines Dateisystems. Dieses Flag kann verwendet werden, um das Verhalten auch im Stammverzeichnis des Dateisystems zu deaktivieren oder zu erzwingen.

`--[no-]sublanguage-file-coverage`

          \[Nur GitHub.com und GitHub Enterprise Server v3.12.0+] Verwende Informationen zur Dateiabdeckung in Untersprachen. Dadurch werden separate Dateiabdeckungsinformationen für Sprachen berechnet, angezeigt und exportiert, die einen CodeQL-Extraktor wie C und C++, Java und Kotlin sowie JavaScript und TypeScript gemeinsam nutzen.

Verfügbar seit v2.15.2.

Optionen zur Extraktorauswahl

`--search-path=<dir>[:<dir>...]`

Eine Liste der Verzeichnisse, in denen Extraktorpakete gefunden werden können. Bei den Verzeichnissen handelt es sich entweder um die Extraktorpakete selbst oder um Verzeichnisse, die Extraktoren als unmittelbare Unterverzeichnisse enthalten.

Enthält der Pfad mehrere Verzeichnisstrukturen, bestimmt ihre Reihenfolge den Vorrang zwischen ihnen: Wenn die Zielsprache in mehr als einer der Verzeichnisstrukturen vorkommt, gilt die zuerst angegebene.

Die Extraktoren, die mit der CodeQL-Toolkette selbst gebündelt sind, werden immer gefunden. Wenn du jedoch separat verteilte Extraktoren verwenden musst, musst du diese Option angeben (oder, noch besser, --search-path in einer Konfigurationsdatei pro Benutzer*in einrichten).

(Hinweis: Unter Windows wird ; als Pfadtrennzeichen verwendet.)

Optionen zum Konfigurieren des Aufrufs der GitHub-API zur automatischen Spracherkennung.

`-a, --github-auth-stdin`

Akzeptiert ein GitHub Apps-Token oder ein persönliches Zugriffstoken über die Standardeingabe.

Dadurch wird die GITHUB_TOKEN-Umgebungsvariable überschrieben.

`-g, --github-url=<url>`

URL der zu verwendenden GitHub-Instanz. Wenn nicht angegeben, versucht die CLI, diese automatisch über den Check-Out-Pfad zu ermitteln. Wenn dies nicht möglich ist, wird diese standardmäßig auf https://github.com/ gesetzt.

Optionen zum Konfigurieren des Paket-Managers.

`--registries-auth-stdin`

Führt eine Authentifizierung bei GitHub Enterprise Server-Containerregistrierungen durch, indem eine durch Trennzeichen getrennte Liste von <registry_url>=<token>-Paaren übergeben wird.

Du kannst https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 übergeben, um dich bei zwei GitHub Enterprise Server-Instanzen zu authentifizieren.

Dadurch werden die Umgebungsvariablen CODEQL_REGISTRIES_AUTH und GITHUB_TOKEN überschrieben. Wenn du dich nur bei der Containerregistrierung von github.com authentifizieren musst, kannst du dich stattdessen mit der einfacheren Option --github-auth-stdin authentifizieren.

Optionen zum Konfigurieren der Windows-Ablaufverfolgung

`--trace-process-name=<process-name>`

          \[Nur Windows] Beim Initialisieren des Tracings injiziere den Tracer in einen übergeordneten Prozess des CodeQL CLI, dessen Name diesem Argument entspricht. Wenn mehr als ein übergeordneter Prozess diesen Namen hat, wird der niedrigste in der Prozessstruktur ausgewählt. Diese Option überschreibt `--trace-process-level`. Wenn also beide übergeben werden, wird nur diese Option verwendet.

`--trace-process-level=<process-level>`

          \[Nur Windows] Bei der Initialisierung des Tracings injiziere den Tracer so viele übergeordnete Prozesse über dem aktuellen Prozess, wobei 0 dem Prozess entspricht, der das CodeQL CLI aufruft. Das Standardverhalten der CLI, wenn keine Argumente übergeben werden, besteht darin, das übergeordnete Element des Aufrufvorgangs mit einigen Sonderfällen für GitHub Actions und Azure-Pipelines einzufügen.

Optionen zum Konfigurieren der indirekten Buildablaufverfolgung

`--no-tracing`

          \[Erweitert] Verfolge das angegebene Kommando nicht, sondern verlasse dich darauf, dass es alle notwendigen Daten direkt erzeugt.

`--extra-tracing-config=<tracing-config.lua>`

          \[Erweitert] Der Pfad zu einer Tracer-Konfigurationsdatei. Er kann verwendet werden, um das Verhalten der Buildablaufverfolgung zu ändern. Er kann verwendet werden, um Compilerprozesse zu ermitteln, die als Teil des Buildbefehls ausgeführt werden, und um die Ausführung anderer Tools auszulösen. Die Extraktoren stellen standardmäßige Konfigurationsdateien für die Ablaufverfolgung bereit, die in den meisten Situationen funktionieren sollten.

Optionen zum Steuern des Extraktorverhaltens: Nur zur Anwendung auf die indirekte Ablaufverfolgungsumgebung

`-O, --extractor-option=<extractor-option-name=value>`

Legt Optionen für CodeQL-Extraktoren fest. extractor-option-name sollte die Form extractor_name.group1.group2.option_name oder group1.group2.option_name haben. Wenn extractor_option_name mit einem Extraktornamen beginnt, muss der angegebene Extraktor die Option group1.group2.option_name deklarieren. Andernfalls wird in jedem Extraktor, der die Option group1.group2.option_name deklariert, die Option festgelegt. value kann eine beliebige Zeichenfolge sein, die keinen Zeilenumbruch enthält.

Diese Befehlszeilenoption kann wiederholt verwendet werden, um mehrere Extraktoroptionen festzulegen. Wenn du mehrere Werte für die gleiche Extraktoroption angibst, hängt das Verhalten von dem Typ ab, den die Extraktoroption erwartet. Bei Zeichenfolgenoptionen wird der zuletzt angegebene Wert verwendet. Bei Arrayoptionen werden alle angegebenen Werte der Reihe nach verwendet. Mit dieser Befehlszeilenoption angegebene Extraktoroptionen werden nach Extraktoroptionen verarbeitet, die über --extractor-options-file angegeben wurden.

Bei der Übergabe an „codeql database init“ oder codeql database begin-tracing werden die Optionen lediglich auf die indirekte Ablaufverfolgungsumgebung angewendet. Wenn dein Workflow auch Aufrufe an codeql database trace-command sendet, müssen die Optionen auch dorthin übergeben werden, falls gewünscht.

Weitere Informationen zu CodeQL-Extraktoroptionen finden Sie unter https://codeql.github.com/docs/codeql-cli/extractor-options. Dort erfahren Sie unter anderem, wie du die von den einzelnen Extraktoren deklarierten Optionen auflisten kannst.

`--extractor-options-file=<extractor-options-bundle-file>`

Dient zum Angeben von Paketdateien für Extraktoroptionen. Eine Paketdatei für Extraktoroptionen ist eine JSON-Datei (Erweiterung .json) oder eine YAML-Datei (Erweiterung .yaml oder .yml), die Extraktoroptionen festlegt. Die Datei muss über den Zuordnungsschlüssel „Extraktor“ der obersten Ebene und darunter über Extraktornamen als Zuordnungsschlüssel der zweiten Ebene verfügen. Weitere Zuordnungsebenen stellen geschachtelte Extraktorgruppen dar, und Zeichenfolgen- und Arrayoptionen sind Zuordnungseinträge mit Zeichenfolgen- und Arraywerten.

Paketdateien für Extraktoroptionen werden in der angegebenen Reihenfolge gelesen. Wenn verschiedene Paketdateien für Extraktoroptionen die gleiche Extraktoroption angeben, hängt das Verhalten von dem Typ ab, den die Extraktoroption erwartet. Bei Zeichenfolgenoptionen wird der zuletzt angegebene Wert verwendet. Bei Arrayoptionen werden alle angegebenen Werte der Reihe nach verwendet. Mit dieser Befehlszeilenoption angegebene Extraktoroptionen werden vor Extraktoroptionen verarbeitet, die über --extractor-option angegeben wurden.

          \[Erweitert] Option an die JVM übergeben, die den Befehl ausführt.

(Beachte, dass Optionen, die Leerzeichen enthalten, nicht ordnungsgemäß verarbeitet werden.)

          \[Erweitert] Legt den Verbosity-Level explizit auf einen der Werte errors, warnings, progress, progress+, progress++, progress+++ fest. Überschreibt `-v` und `-q`:

`--logdir=<dir>`

          \[Erweitert] Detaillierte Protokolle in eine oder mehrere Dateien im angegebenen Verzeichnis schreiben, mit generierten Namen, die Zeitstempel und den Namen des ausgeführten Unterbefehls enthalten.

(Um eine Protokolldatei mit einem Namen zu schreiben, über den du die volle Kontrolle hast, gib stattdessen --log-to-stderr an, und leite stderr wie gewünscht um.)

`--common-caches=<dir>`

          \[Erweitert] Steuert den Zwischenspeicherort von Datenträgern, die zwischen mehreren CLI-Ausführungen bestehen bleiben, wie z. B. heruntergeladene QL-Pakete und kompilierte Abfragepläne. Wenn dies nicht explizit festgelegt ist, wird dieses Verzeichnis standardmäßig auf ein Verzeichnis mit dem Namen `.codeql` festgelegt, das sich im Startverzeichnis des Benutzer. Es wird erstellt, wenn es noch nicht vorhanden ist.

Verfügbar seit v2.15.2.

Wer kann dieses Feature verwenden?

In diesem Artikel