Skip to main content
Wir veröffentlichen regelmäßig Aktualisierungen unserer Dokumentation, und die Übersetzung dieser Seite ist möglicherweise noch nicht abgeschlossen. Aktuelle Informationen findest du in der englischsprachigen Dokumentation.
GitHub AE ist derzeit begrenzt freigegeben.

Konfigurieren der CodeQL-CLI in deinem CI-System

Du kannst dein Continuous Integration-System so konfigurieren, dass die CodeQL CLI ausgeführt, CodeQL-Analysen durchgeführt und die Ergebnisse in GitHub AE als code scanning-Warnungen hochgeladen werden.

Code scanning ist für organisationseigene Repositorys in GitHub AE verfügbar. Dies ist ein GitHub Advanced Security-Feature (kostenlos während der Betaphase). Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Informationen zum Generieren von Codeüberprüfungsergebnissen mit CodeQL CLI

Nachdem du die CodeQL CLI für Server in deinem CI-System verfügbar gemacht und sichergestellt hast, dass sie sich mit GitHub AE authentifizieren können, kannst du Daten generieren.

Du verwendest drei unterschiedliche Befehle, um Ergebnisse zu generieren und diese auf GitHub AE hochzuladen:

  1. database create: Mit diesem Befehl erstellst du eine CodeQL-Datenbank, die die hierarchische Struktur aller unterstützten Programmiersprachen im Repository darstellt.
  2. database analyze: Mit diesem Befehl führst du Abfragen aus, um jede CodeQL-Datenbank zu analysieren und die Ergebnisse in einer SARIF-Datei zusammenzufassen.
  3. github upload-results: Mit diesem Befehl lädst du die SARIF-Dateien auf GitHub AE hoch, wo die Ergebnisse mit einem Branch oder Pull Request abgeglichen und als Warnungen der Codeüberprüfung ( code scanning) angezeigt werden.

Du kannst die Befehlszeilenhilfe über die Option --help für jeden Befehl anzeigen.

Hinweis: Das Hochladen von SARIF-Daten zur Anzeige von code scanning-Ergebnissen in GitHub AE wird für organisationseigene Repositorys mit aktivierter GitHub Advanced Security unterstützt. Weitere Informationen findest du unter Verwalten von Sicherheits- und Analyseeinstellungen für dein Repository.

Erstellen von CodeQL-Datenbanken zur Analyse

  1. 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.
  2. 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 CodeQL-Datenbanken und unter Erstellen von CodeQL-Datenbanken.

  3. Suche ggf. den Buildbefehl für die Codebasis. Üblicherweise ist dieser in der Konfigurationsdatei des CI-Systems verfügbar.

  4. Führe codeql database create im Check-Out-Stamm deines Repositorys aus, und erstelle die Codebasis.

    # Single supported language - create one CodeQL database
    codeql database create <database> --command<build> --language=<language-identifier>
    
    # Multiple supported languages - create one CodeQL database per language
    codeql database create <database> --command<build> \
          --db-cluster --language=<language-identifier>,<language-identifier>

    Hinweis: Wenn du einen Containerbuild verwendest, musst du die CodeQL CLI innerhalb des Containers ausführen, in dem die Buildaufgabe ausgeführt wird.

OptionErforderlichVerwendung
<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.
--languageGib den Bezeichner für die Sprache an, für die eine 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.
--commandEmpfohlen. 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-clusterVerwende diese Option für Codebasen mit mehreren Sprachen, um eine Datenbank für jede durch --language angegebene Sprache zu generieren.
--no-run-unnecessary-buildsEmpfohlen. 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-rootVerwende 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-configErweitert. 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 findest du unter Anpassen der Codeüberprüfung und unter database create.

Weitere Informationen findest du unter Erstellen von CodeQL-Datenbanken.

Beispiel für eine einzelne Sprache

In diesem Beispiel wird eine 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.
$

Analysieren einer CodeQL-Datenbank

  1. Erstelle eine CodeQL-Datenbank (siehe oben).
  2. Führe codeql database analyze in der Datenbank aus, und gib an, welche Abfragen verwendet werden sollen.
    codeql database analyze <database> --format=<format> \
        --output=<output>  <queries>

Hinweis: Wenn du mehrere CodeQL-Datenbanken für einen einzelnen Commit analysierst, musst du für alle von diesem Befehl generierten Ergebnisse eine SARIF-Kategorie angeben. Wenn du die Ergebnisse auf GitHub AE hochlädst, wird diese Kategorie bei der code scanning verwendet, um die Ergebnisse separat für jede Sprache zu speichern. Wenn du dies vergisst, überschreibt jeder Upload die alten Ergebnisse.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <queries>
OptionErforderlichVerwendung
<database>Gib den Pfad des Verzeichnisses an, das die zu analysierende CodeQL-Datenbank enthält.
<packs,queries>Gib CodeQL-Pakete oder -Abfragen an, die ausgeführt werden sollen. Lass diesen Parameter aus, um die Standardabfragen zur code scanning auszuführen. Die anderen Abfragesammlungen, die im CodeQL CLI-Paket enthalten sind, findest du unter /<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites. Weitere Informationen zum Erstellen einer eigenen Abfragesammlung findest du unter Erstellen von CodeQL-Abfragesammlungen in der Dokumentation für die CodeQL CLI.
--formatGib das Format der vom Befehl generierten Ergebnisdatei an. Für den Upload in GitHub sollte dies sein: sarif-latest. Weitere Informationen findest du unter SARIF-Unterstützung für die Codeüberprüfung.
--outputGib an, wo die SARIF-Ergebnisdatei gespeichert werden soll.
--sarif-categoryDiese Option kann optional bei der Analyse einer einzelnen Datenbank verwendet werden. Diese Option ist erforderlich, um die Sprache zu definieren, wenn du mehrere Datenbanken für einen einzelnen Commit in einem Repository analysierst.

Gib eine Kategorie an, die in die SARIF-Ergebnisdatei für diese Analyse aufgenommen werden soll. Eine Kategorie wird verwendet, um mehrere Analysen für dasselbe Tool und denselben Commit zu unterscheiden, die jedoch für verschiedene Sprachen oder Teile des Codes ausgeführt werden.
--sarif-add-query-helpVerwende diese Option, wenn du alle verfügbaren, mit Markdown gerenderten Abfragen, die in deiner Analyse verwendet werden, einschließen möchtest. Alle Abfragehilfen für benutzerdefinierte Abfragen, die in der SARIF enthalten sind, werden auf der Benutzeroberfläche für die Codeüberprüfung angezeigt, wenn die entsprechende Abfrage eine Warnung generiert. Weitere Informationen findest du unter Analysieren von Datenbanken mit der CodeQL-CLI.
--threadsVerwende diese Option, wenn du mehrere Threads zum Ausführen von Abfragen verwenden möchtest. Der Standardwert ist 1. Du kannst weitere Threads angeben, um die Abfrageausführung zu beschleunigen. Gib 0 an, um die Anzahl der Threads auf die Anzahl der logischen Prozessoren festzulegen.
--verboseVerwende diese Option, um weitere Informationen zum Analyseprozess und Diagnosedaten zum Prozess der Datenbankerstellung zu erhalten.

Weitere Informationen findest du unter Analysieren von Datenbanken mit der CodeQL CLI.

Einfaches Beispiel für die Analyse einer CodeQL-Datenbank

In diesem Beispiel wird eine CodeQL-Datenbank analysiert, die unter /codeql-dbs/example-repo gespeichert ist und die Ergebnisse als SARIF-Datei speichert: /temp/example-repo-js.sarif. Dabei wird --sarif-category verwendet, um zusätzliche Informationen in die SARIF-Datei einzuschließen, die die Ergebnisse als JavaScript kennzeichnen. Dies ist wichtig, wenn du über mehrere CodeQL-Datenbanken verfügst und einen einzelnen Commit in einem Repository analysieren möchtest.

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Hochladen von Ergebnissen in GitHub AE

Du kannst überprüfen, ob die SARIF-Eigenschaften die unterstützte Größe für den Upload aufweisen und ob die Datei mit der Codeüberprüfung kompatibel ist. Weitere Informationen findest du unter SARIF-Unterstützung für die Codeüberprüfung.

Bevor du Ergebnisse auf GitHub AE hochladen kannst, musst du bestimmen, wie du die GitHub App oder das zuvor erstellte personal access token am besten an die CodeQL CLI übergibst (siehe Installieren von CodeQL CLI in deinem CI-System). Es wird empfohlen, den Leitfaden deines CI-Systems zur sicheren Verwendung eines Geheimnisspeichers zu lesen. Die CodeQL CLI unterstützt:

  • Das Übergeben des Tokens an die CLI über die Standardeingabe mithilfe der Option --github-auth-stdin (empfohlen)
  • Das Speichern des Geheimnisses in der Umgebungsvariablen GITHUB_TOKEN und das Ausführen der CLI ohne die Option --github-auth-stdin

Wenn du dich für die sicherste und zuverlässigste Methode für deinen CI-Server entschieden hast, führe codeql github upload-results in jeder SARIF-Ergebnisdatei aus, und schließe --github-auth-stdin ein (es sei denn, das Token ist in der Umgebungsvariablen GITHUB_TOKEN verfügbar).

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-url=<URL> --github-auth-stdin
OptionErforderlichVerwendung
--repositoryGib OWNER/NAME (dendie Besitzerin/den Namen) des Repositorys an, in das Daten hochgeladen werden. Der Besitzer muss eine Organisation innerhalb eines Unternehmens sein, die über eine Lizenz für GitHub Advanced Security verfügt. GitHub Advanced Security muss für das Repository aktiviert sein. Weitere Informationen findest du unter Verwalten von Sicherheits- und Analyseeinstellungen für dein Repository.
--refGib den Namen des von dir ausgecheckten und analysierten Verweises (ref) an, damit die Ergebnisse dem richtigen Code zugeordnet werden können. Verwende für einen Branch refs/heads/BRANCH-NAME. Verwende für einen Headcommit eines Pull Requests refs/pull/NUMBER/head oder für den von GitHub generierten Mergecommit eines Pull Requests refs/pull/NUMBER/merge.
--commitGib die vollständigen SHA des analysierten Commits an.
--sarifGib die SARIF-Datei an, die geladen werden soll.
--github-urlGib die URL für GitHub AE an.
--github-auth-stdinVerwende diese Option, um die CLI an die GitHub App oder das personal access token weiterzugeben, das zur Authentifizierung mit der REST-API von GitHub über die Standardeingabe erstellt wurde. Dies ist nicht erforderlich, wenn der Befehl über Zugriff auf GITHUB_TOKEN-Umgebungsvariablen verfügt, die mit diesem Token festgelegt wurden.

Weitere Informationen findest du unter github upload-results in der Dokumentation für die CodeQL CLI.

Einfaches Beispiel für das Hochladen von Ergebnissen in GitHub AE

In diesem Beispiel werden Ergebnisse aus der SARIF-Datei temp/example-repo-js.sarif in das Repository my-org/example-repo hochgeladen. Es teilt der code scanning-API mit, dass die Ergebnisse für den Commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 für den Branch main gelten.

$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-url=https://github.example.com \
    --github-auth-stdin

Es gibt keine Ausgabe aus diesem Befehl, sofern der Upload nicht erfolgreich war. Die Eingabeaufforderung kehrt zurück, wenn der Upload abgeschlossen ist und die Datenverarbeitung begonnen hat. Auf kleineren Codebasen solltest du die code scanning-Warnungen in GitHub AE kurz danach untersuchen können. Je nach ausgechecktem Code kannst du Warnungen direkt im Pull Request oder auf der Registerkarte Sicherheit für Branches anzeigen. Weitere Informationen findest du unter Filtern von Codescanbenachrichtigungen in Pull-Anforderungen und Verwalten von Codescanwarnungen für dein Repository.

CI-Beispielkonfiguration für CodeQL-Analyse

Dies ist ein Beispiel für die Reihe von Befehlen, die du verwenden kannst, um eine Codebasis mit zwei unterstützten Sprachen zu analysieren und dann die Ergebnisse in GitHub AE hochzuladen.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

# Upload the SARIF file with the Python results: 'python-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

Problembehandlung der CodeQL CLI im CI-System

Anzeigen von Protokoll- und Diagnoseinformationen

Wenn du eine CodeQL-Datenbank mithilfe einer code scanning-Abfragesuite analysierst, generiert die CLI detaillierte Informationen zu Warnungen und meldet zusätzlich Diagnosedaten aus dem Schritt für die Datenbankgenerierung und Zusammenfassungsmetriken. Für Repositorys mit wenigen Warnungen sind diese Informationen möglicherweise für dich hilfreich, um festzustellen, ob es wirklich wenige Probleme im Code gibt, oder wenn Fehler beim Generieren der CodeQL-Datenbank aufgetreten sind. Wenn du eine ausführlichere codeql database analyze-Ausgabe wünschst, verwende die Option --verbose.

Weitere Informationen zum Typ der verfügbaren Diagnoseinformationen findest du unter Anzeigen von Codescanprotokollen.

Code scanning zeigt nur Analyseergebnisse aus einer der analysierten Sprachen an.

Standardmäßig erwartet code scanning eine SARIF-Ergebnisdatei pro Analyse für ein Repository. Wenn du daher eine zweite SARIF-Ergebnisdatei für einen Commit hochlädst, wird sie als Ersatz für den ursprünglichen Datensatz behandelt.

Wenn du mehrere Ergebnisse in die code scanning-API für einen Commit in einem Repository hochladen möchtest, musst du jede Gruppe von Ergebnissen als eindeutige Gruppe identifizieren. Für Repositorys, in denen du mehrere CodeQL-Datenbanken zur Analyse für jeden Commit erstellst, verwende die Option --sarif-category, um eine Sprache oder eine andere eindeutige Kategorie für jede SARIF-Datei anzugeben, die du für dieses Repository generierst.

Weitere Informationsquellen