Konfigurieren der CodeQL-CLI in deinem CI-System

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 Enterprise Server authentifizieren können, kannst du Daten generieren.

Du verwendest drei unterschiedliche Befehle, um Ergebnisse zu generieren und diese auf GitHub Enterprise Server 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 Enterprise Server 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.

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.

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 -Pakete und/oder Abfragen verwendet werden sollen.

   codeql database analyze <database> --format=<format> \
       --output=<output>  --download <packs,queries>

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

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=sarifv2.1.0 --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 Enterprise Server

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 Enterprise Server 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

Weitere Informationen findest du unter github upload-results.

Einfaches Beispiel für das Hochladen von Ergebnissen in GitHub Enterprise Server

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 Enterprise Server 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.

Herunterladen und Verwenden von CodeQL-Abfragepaketen

Das CodeQL CLI-Paket enthält Abfragen, die von GitHub-Experten, Sicherheitsforschern und Community-Mitwirkenden verwaltet werden. Wenn du Abfragen ausführen möchtest, die von anderen Organisationen entwickelt wurden, bieten CodeQL-Abfragepakete eine effiziente und zuverlässige Möglichkeit zum Herunterladen und Ausführen von Abfragen. Weitere Informationen findest du unter Informationen zu Codescans mit CodeQL.

Bevor du ein CodeQL-Paket verwenden kannst, um eine Datenbank zu analysieren, müssen alle Pakete heruntergeladen werden, die du aus der GitHub Container registry benötigst. Dies kann durch Verwendung des Flags --download als Teil des Befehls codeql database analyze erfolgen. Wenn ein Paket nicht öffentlich verfügbar ist, musst du eine GitHub App oder ein personal access token zum Authentifizieren verwenden. Weitere Informationen und ein Beispiel findest du unter Hochladen von Ergebnissen in GitHub Enterprise Server oben.

Einfaches Beispiel für das Herunterladen und Verwenden von Abfragepaketen

In diesem Beispiel wird der Befehl codeql database analyze mit der Option --download für folgende Zwecke ausgeführt:

1. Herunterladen der neuesten Version des Pakets octo-org/security-queries
2. Herunterladen einer Version des Pakets octo-org/optional-security-queries, die mit Version 1.0.1 kompatibel ist (in diesem Fall Version 1.0.2) Weitere Informationen zur SemVer-Kompatibilität findest du in der npm-Dokumentation zur semantischen Versionierung unter „Ranges“.
3. Ausführen aller Standardabfragen in octo-org/security-queries
4. Ausschließliches Ausführen der Abfrage queries/csrf.ql in octo-org/optional-security-queries

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Direktes Herunterladen von CodeQL-Paketen

Wenn du ein CodeQL-Paket herunterladen möchtest, ohne es sofort auszuführen, kannst du den Befehl codeql pack download verwenden. Dies ist nützlich, wenn du bei der Ausführung von CodeQL-Abfragen den Zugriff auf das Internet vermeiden möchtest. Wenn du die CodeQL-Analyse ausführst, kannst du Pakete, Versionen und Pfade auf die gleiche Weise wie im vorherigen Beispiel angeben:

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Herunterladen von CodeQL-Paketen aus mehreren GitHub-Containerregistrierungen

Wenn sich deine CodeQL-Pakete in mehreren Containerregistrierungen befinden, musst du der CodeQL CLI mitteilen, wo jedes Paket zu finden ist. Weitere Informationen findest du unter Anpassen der Codeüberprüfung.

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 Enterprise Server 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

• Erstellen von CodeQL-Datenbanken
• Analysieren von Datenbanken mit der CodeQL-CLI
• Veröffentlichen und Verwenden von CodeQL-Paketen