database init

Übersicht

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>

Beschreibung

[Sanitär] Erstellt 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.)

Optionen

Primäre Optionen

<database>

[Obligatorisch] Pfad zu der CodeQL-Datenbank, die erstellt werden soll. 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>

[Obligatorisch] Das Stammquellcode-Verzeichnis. 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 vorhanden ist, lösche sie, und fahre mit diesem Befehl fort, bevor der Vorgang fehlschlägt. Diese Option sollte mit Vorsicht verwendet werden, da sie das gesamte Datenbankverzeichnis rekursiv löschen kann.

--codescanning-config=<file>

[Erweitert] Liest eine Konfigurationsdatei für die Codeüberprüfung, die Optionen zum Erstellen der CodeQL-Datenbanken und die in späteren Schritten auszuführenden Abfragen angibt. Weitere Informationen zum Format dieser Konfigurationsdatei finden Sie unter Anpassen des erweiterten Setups für das Codescanning. Um Abfragen aus dieser Datei in einem späteren Schritt auszuführen, rufe codeql 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 dass dabei der Quellstamm erstellt wird. Verfügbar für JavaScript/TypeScript, Python und Ruby. Auch in der Betaversion für C# und Java verfügbar.

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

manual: Die Datenbank wird erstellt, indem der Quellstamm mithilfe eines manuell angegebenen Buildbefehls 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] Fährt auch dann fort, wenn das angegebene Quellstammverzeichnis nicht vorhanden ist.

--[no-]begin-tracing

[Erweitert] Erstellt einige Skripts, die zum Einrichten der „indirekten Buildablaufverfolgung“ verwendet werden können, die die Integration in vorhandene Buildworkflows ermöglicht, wenn kein expliziter Buildbefehl verfügbar ist. Informationen zur Verwendung dieses Features findest du in unserer Dokumentation unter Vorbereiten des Codes für die CodeQL-Analyse.

Baselineberechnungsoptionen

--[no-]calculate-baseline

[Erweitert] Berechnet Baselineinformationen zum analysierten Code, und fügt 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+] Verwenden Sie Informationen zur Dateiabdeckung in Untersprache. 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] Fügt beim Initialisieren der Ablaufverfolgung den Ablaufverfolgungsvorgang in einen übergeordneten Prozess der CodeQL-CLI ein, dessen Name mit diesem Argument übereinstimmt. 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] Wenn du die Ablaufverfolgung initialisierst, füge die Ablaufverfolgung so viele übergeordnete Elemente über den aktuellen Prozess ein, wobei 0 dem Prozess entspricht, der die 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] Verfolgt den angegebenen Befehl nicht, sondern lässt alle erforderlichen Daten direkt durch ihn erzeugen.

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

[Erweitert] Der Pfad zu einer Konfigurationsdatei für die Ablaufverfolgung. 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 muss im Format „Extraktorname.Gruppe1.Gruppe2.Optionsname“ oder im Format „Gruppe1.Gruppe2.Optionsname“ angegeben werden. Wenn extractor_option_name mit einem Extraktornamen beginnt, muss der angegebene Extraktor die Option „Gruppe1.Gruppe2.Optionsname“ deklarieren. Andernfalls wird die Option für jeden Extraktor festgelegt, der die Option „Gruppe1.Gruppe2.Optionsname“ deklariert. value kann eine beliebige Zeichenfolge ohne Zeilenumbruch sein.

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 Übergabe an codeql database init oder codeql database begin-tracing werden die Optionen nur 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 findest du unter https://codeql.github.com/docs/codeql-cli/extractor-options. Dort erfährst du 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.

Bei Übergabe an codeql database init oder codeql database begin-tracing werden die Optionen nur 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.

Allgemeine Optionen

-h, --help

Zeigt diesen Hilfetext an.

-J=<opt>

[Erweitert] Dient zum Angeben einer Option für die JVM-Instanz, die den Befehl ausführt.

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

-v, --verbose

Ermöglicht die inkrementelle Erhöhung der Anzahl ausgegebener Statusmeldungen.

-q, --quiet

Ermöglicht die inkrementelle Verringerung der Anzahl ausgegebener Statusmeldungen.

--verbosity=<level>

[Erweitert] Dient zum expliziten Festlegen des Ausführlichkeitsgrads auf „errors“, „warnings“, „progress“, „progress+“, „progress++“ oder „progress+++“. Überschreibt -v und -q:

--logdir=<dir>

[Erweitert] Ermöglicht das Schreiben detaillierter Protokolle in eine oder mehrere Dateien im angegebenen Verzeichnis 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 Speicherort zwischengespeicherter Daten auf dem Datenträger, der zwischen mehreren Ausführungsvorgängen der CLI beibehalten wird, 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.