Informationen zur CodeQL-CLI

Informationen zur CodeQL CLI

Softwareentwickler*innen und Sicherheitsfachkräfte können ihren Code mithilfe der CodeQL-Analyse sichern. Weitere Informationen zu CodeQL findest du unter Informationen zu Codescans mit CodeQL.

Die CodeQL CLI ist ein eigenständiges Befehlszeilentool, mit dem du Code analysieren kannst. Ihr Hauptzweck besteht darin, eine Datenbankdarstellung einer Codebasis zu generieren: eine CodeQL-Datenbank. Wenn die Datenbank bereit ist, kannst du sie interaktiv abfragen oder eine Reihe von Abfragen ausführen, um Ergebnissets im SARIF-Format zu generieren und auf Ihre GitHub Enterprise Server-Instance hochzuladen.

Du kannst die CodeQL CLI verwenden, um Folgendes zu tun:

• Ausführen von CodeQL-Analysen mithilfe von Abfragen, die von GitHub-Entwickler*innen und der Open-Source-Community bereitgestellt werden
• Generieren von Codescanwarnungen, um diese für die Anzeige in GitHub Enterprise Server hochzuladen
• Erstellen von CodeQL-Datenbanken zur Verwendung in der CodeQL für die Visual Studio Code-Erweiterung
• Entwickeln und Testen von benutzerdefinierten CodeQL-Abfragen für die Verwendung in eigenen Analysen

Die CodeQL CLI kann Folgendes analysieren:

• Dynamische Sprachen, z. B. JavaScript und Python.
• Kompilierte Sprachen wie C/C++, C#, Go und Java.
• Codebases, die in einer Mischung aus Sprachen geschrieben wurden.

Weitere Informationen zur Einrichtung der CodeQL CLI findest du unter Einrichten der CodeQL-CLI.

Informationen zur Verwendung der CodeQL CLI für das code scanning

Du kannst die CodeQL CLI zum Ausführen von code scanning von Code verwenden, den du in einem CI-System (Continuous Integration) eines Drittanbieters verarbeitest. Code scanning ist ein Feature, das du zum Analysieren des Codes in einem GitHub-Repository verwendest, um Sicherheitsrisiken und Codefehler zu finden. Alle von der Analyse ermittelten Probleme werden im Repository angezeigt. Eine Übersicht über die Verwendung der Codeüberprüfung bei externen CI-Systemen (Continuous Integration) findest du unter Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System. Die empfohlenen Spezifikationen (RAM, CPU-Kerne und Festplatte) zum Ausführen von CodeQL-Analysen findest du unter Empfohlene Hardwareressourcen zum Ausführen von CodeQL.

Du kannst alternativ GitHub Actions oder Azure DevOps-Pipelines verwenden, um Code mithilfe der CodeQL CLI zu überprüfen. Weitere Informationen finden Sie unter "Konfigurieren des Codescanning" oder unter Konfigurieren von GitHub Advanced Security for Azure DevOps in Microsoft Learn.

Eine Übersicht über alle Optionen zur Verwendung der CodeQL-Analyse für die Codeüberprüfung findest du unter Informationen zu Codescans mit CodeQL.

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

Wenn du die CodeQL CLI direkt ausführen möchtest, musst du zuerst die CodeQL CLI loak installieren. Wenn du die CodeQL CLI mit einem externen CI-System (Continuous Integration) verwenden möchtest, musst du die CodeQL CLI für alle Server in deinem CI-System verfügbar machen. Weitere Informationen findest du unter Einrichten der CodeQL-CLI.

Sobald die CodeQL CLI eingerichtet ist, kannst du drei verschiedene Befehle verwenden, um Ergebnisse zu generieren oder 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. Weitere Informationen findest du unter Vorbereiten des Codes für die CodeQL-Analyse.
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. Weitere Informationen findest du unter Analysieren des Codes mit CodeQL-Abfragen.
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. Weitere Informationen findest du unter Hochladen von CodeQL-Analyseergebnissen auf GitHub.

CI-Beispielkonfiguration für CodeQL-Analyse

Dies ist ein Beispiel für die gesamte Reihe von Befehlen für CodeQL CLI, 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'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

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

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

Informationen zur GitHub CodeQL-Lizenz

Lizenzhinweis: Wenn du keine GitHub Enterprise-Lizenz besitzt, stimmst du mit dem Installieren dieses Produkts den GitHub CodeQL-Geschäftsbedingungen zu.

GitHub CodeQL wird auf Benutzerbasis lizenziert. Im Rahmen der Lizenzbeschränkungen kannst du CodeQL verwenden, um die folgenden Aufgaben auszuführen:

• Durchführen wissenschaftlicher Forschung
• Vorstellen der Software
• Testen der CodeQL-Abfragen, die unter einer von der OSI genehmigten Lizenz veröffentlicht werden, um zu bestätigen, dass neue Versionen dieser Abfragen weiterhin die richtigen Sicherheitsrisiken ermitteln

„Von der OSI genehmigte Lizenz“ meint dabei eine von der Open Source Initiative (OSI) genehmigte Open-Source-Softwarelizenz.

Wenn du mit einer Open-Source-Codebasis arbeitest (d. h. einer Codebasis, die unter einer von der OSI genehmigten Lizenz veröffentlicht wurde), kannst du CodeQL auch für die folgenden Aufgaben verwenden:

• Durchführen der Analyse der Open-Source-Codebasis
• Wenn die Open-Source-Codebasis auf GitHub.com gehostet und verwaltet wird: Generieren von CodeQL-Datenbanken für oder während Continuous Integration, Continuous Delivery oder der automatisierten Analyse

CodeQL kann außer in den hier ausdrücklich genannten Fällen ohne eine Lizenz für GitHub Advanced Security weder als Teil normaler Softwareentwicklungsprozesse noch anderweitig für automatisierte Analysen, Continuous Integration oder Continuous Delivery verwendet werden.