CodeQL-Befehlszeilenschnittstelle

Softwareentwickler und Sicherheitsforscher können ihren Code mithilfe von CodeQL Analysen sichern. Weitere Informationen zu CodeQL findest du unter Codeüberprüfung mit CodeQL.

Dies CodeQL CLI ist ein eigenständiges Befehlszeilentool, mit dem Sie Code analysieren können. Der Hauptzweck besteht darin, eine Datenbankdarstellung einer Codebasis, einer CodeQL Datenbank zu generieren. Sobald die Datenbank fertig ist, können Sie sie interaktiv abfragen oder eine Reihe von Abfragen ausführen, um eine Reihe von Ergebnissen im SARIF-Format zu generieren und die Ergebnisse hochzuladen.GitHub

Sie können das CodeQL CLI verwenden, um:

• Führen Sie CodeQL Analysen mithilfe von Abfragen aus, die von GitHub Ingenieuren und der Open-Source-Community bereitgestellt werden.
• Generieren Sie Code-Scanning-Warnungen, die Sie hochladen können, damit sie in GitHub angezeigt werden.
• Erstellen Sie CodeQL Datenbanken zur Verwendung im CodeQL für die Erweiterung Visual Studio Code.
• Entwickeln und Testen von benutzerdefinierten CodeQL Abfragen zur Verwendung in Ihren eigenen Analysen

CodeQL CLI kann analysieren:

• Dynamische Sprachen, z. B. JavaScript und Python.
• Kompilierte Sprachen, z. B. C/C++, C#, Go, Java, Kotlin, Rust (öffentliche Vorschau), and Swift
• Codebases, die in einer Mischung aus Sprachen geschrieben wurden.

Informationen zur Verwendung von CodeQL CLI für code scanning

Sie können CodeQL CLI verwenden, um code scanning für Code auszuführen, den Sie in einem CI-System eines Drittanbieters verarbeiten. 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 von Codescans mit externen CI-Systemen finden Sie unter Verwenden der Codeüberprüfung mit deinem vorhandenen CI-System. Empfohlene Spezifikationen (RAM, CPU-Kerne und Datenträger) für die laufende CodeQL Analyse finden Sie unter Empfohlene Hardwareressourcen zum Ausführen von CodeQL.

Alternativ können Sie GitHub Actions oder Azure DevOps Pipelines verwenden, um Code mithilfe der CodeQL CLI zu scannen. Weitere Informationen finden Sie unter Konfigurieren des Standardsetups für das Code-Scanning oder Configure GitHub Advanced Security for Azure DevOps in Microsoft Learn.

Eine Übersicht über alle Optionen für die Verwendung der CodeQL-Analyse für die Codeüberprüfung finden Sie unter Codeüberprüfung mit CodeQL.

Informationen zum Generieren von Codescanergebnissen mit dem CodeQL CLI

Wenn Sie CodeQL CLI direkt ausführen möchten, müssen Sie zunächst CodeQL CLI lokal installieren. Wenn Sie planen, die CodeQL CLI mit einem externen CI-System zu verwenden, müssen Sie die CodeQL CLI den Servern in Ihrem CI-System verfügbar machen.

Sobald CodeQL CLI eingerichtet ist, können Sie drei verschiedene Befehle verwenden, um Ergebnisse zu generieren und sie auf GitHub hochzuladen:

1. database create um eine CodeQL Datenbank zu erstellen, die die hierarchische Struktur jeder unterstützten Programmiersprache im Repository darstellt. Weitere Informationen findest du unter Vorbereiten des Codes für die CodeQL-Analyse.
2. database analyze um Abfragen auszuführen, um jede CodeQL Datenbank zu analysieren und die Ergebnisse in einer SARIF-Datei zusammenzufassen. Weitere Informationen findest du unter Analyzing your code with CodeQL queries.
3. github upload-results um die resultierenden SARIF-Dateien zu GitHub hochzuladen, wo die Ergebnisse einem Branch oder Pull Request zugeordnet und als code scanning Warnungen angezeigt werden. Weitere Informationen findest du unter Hochladen von CodeQL-Analyseergebnissen in GitHub.

Beispiel einer CI-Konfiguration für die CodeQL-Analyse

Dies ist ein Beispiel für die vollständige Befehlsfolge für CodeQL CLI, die Sie verwenden können, um eine Codebasis mit zwei unterstützten Sprachen zu analysieren und die Ergebnisse anschließend auf GitHub 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

Datenbankextraktion

Die CodeQL CLI verwendet spezielle Programme, sogenannte Extraktoren, um Informationen aus dem Quellcode eines Softwaresystems in eine abfragbare Datenbank zu extrahieren. Sie können das Verhalten von Extraktoren anpassen, indem Sie Konfigurationsoptionen von Extraktoren über CodeQL CLI festlegen. Siehe Extraktoroptionen.

Informationen zur GitHub CodeQL-Lizenz

Lizenzhinweis: Wenn du über keine Lizenz für GitHub Code Security verfügst, stimmst du bei der Installation dieses Produkts den Geschäftsbedingungen für GitHub CodeQL zu.

Informationen zu CodeQL CLI Datenbankbündeln

Der CodeQL CLI Befehl "Datenbankbundle" kann verwendet werden, um ein wiederverwendbares Archiv einer CodeQL Datenbank zu erstellen.

Eine Kopie eines Datenbankbundles kann verwendet werden, um Informationen zur Problembehandlung mit Ihren Teammitgliedern oder mit GitHub-Supportihnen zu teilen. Siehe Erstellen von CodeQL CLI-Datenbankpaketen.

Erste Schritte

Die einfachste Möglichkeit für die ersten Schritte finden Sie unter Einrichten der CodeQL-CLI.

Erweiterte Setup-Optionen sind verfügbar, wenn Sie sie benötigen. Beispielsweise, wenn Sie:

• Möchten Sie zu Open Source freigegebenen CodeQL-Abfragen beitragen und lieber direkt mit dem Quellcode CodeQL arbeiten. Siehe Auschecken des CodeQL CLI-Quellcodes.
• Mehrere Versionen von CodeQL CLI müssen parallel installiert werden. Wenn z. B. eine Codebasis eine bestimmte Version erfordert, während eine andere die neueste Version verwendet. Sie können jede Version herunterladen und beide CLI-Archive im selben übergeordneten Verzeichnis entpacken.
• Sie recherchieren oder entwickeln Abfragen und möchten Datenbanken von GitHub.com herunterladen. Siehe Herunterladen von CodeQL-Datenbanken aus GitHub.