Informationen zu benutzerdefinierten Abfragen und der CodeQL CLI
Du kannst deine CodeQL-Analysen anpassen, indem du eigene Abfragen schreibst, um bestimmte Sicherheitsrisiken oder Fehler zu ermitteln.
In diesem Artikel geht es insbesondere um das Schreiben von Abfragen, die mit dem Befehl database analyze verwendet werden sollen, um interpretierte Ergebnisse zu erzeugen.
Hinweis: Abfragen, die mit database analyze ausgeführt werden, weisen strenge Metadatenanforderungen auf. Du kannst Abfragen auch mit den folgenden Unterbefehlen auf plumbing-Ebene ausführen:
- database run-queries: Gibt nicht interpretierte Ergebnisse in einem binären Zwischenformat namens BQRS aus.
- query run: Gibt die BQRS-Dateien oder Ergebnistabellen direkt in der Befehlszeile aus. Das Anzeigen von Ergebnissen direkt in der Befehlszeile kann für die iterative Abfrageentwicklung mithilfe der CLI nützlich sein.
Abfragen, die mit diesen Befehlen ausgeführt werden, haben nicht die gleichen Metadatenanforderungen. Um jedoch für Menschen lesbare Daten zu speichern, musst du jede BQRS-Ergebnisdatei mithilfe des plumbing-Unterbefehls bqrs decode verarbeiten. Daher ist es in den meisten Anwendungsfällen am einfachsten, die Datenbankanalyse zu verwenden, um interpretierte Ergebnisse direkt zu generieren.
Schreiben einer gültigen Abfrage
Vor dem Ausführen einer benutzerdefinierten Analyse musst du eine gültige Abfrage schreiben und in einer Datei mit einer .ql-Erweiterung speichern. Es gibt eine umfangreiche Dokumentation, die beim Schreiben von Abfragen hilfreich sein kann. Weitere Informationen findest du unter CodeQL-Abfragen.
Einschließen von Abfragemetadaten
Abfragemetadaten sind oben in jeder Abfragedatei enthalten. Sie liefert Benutzern Informationen zur Abfrage und teilt der CodeQL CLI mit, wie die Abfrageergebnisse verarbeitet werden sollen.
Wenn du Abfragen mit dem database analyze-Befehl ausführst, musst du die folgenden beiden Eigenschaften einschließen, um sicherzustellen, dass die Ergebnisse ordnungsgemäß interpretiert werden:
-
Abfragebezeichner (
@id): Eine Sequenz von Wörtern aus Kleinbuchstaben oder Ziffern, die durch/oder-getrennt sind und die Abfrage identifizieren und klassifizieren. -
Abfragetyp (
@kind): Kennzeichnet die Abfrage als eine einfache Warnung (@kind problem), als Warnung, die durch eine Sequenz von Codestellen dokumentiert ist (@kind path-problem), für die Problembehandlung beim Extraktor (@kind diagnostic), oder als Zusammenfassungsmetrik (@kind metricund@tags summary).
Weitere Informationen zu diesen Metadateneigenschaften findest du unter Metadaten für CodeQL-Abfragen und Styleguide zum Abfragen von Metadaten.
Hinweis: Die Metadatenanforderungen können abweichen, wenn du deine Abfrage mit anderen Anwendungen verwenden möchtest. Weitere Informationen findest du unter Metadaten für CodeQL-Abfragen.
Verpacken von benutzerdefinierten QL-Abfragen
Hinweis: Die CodeQL-Paketverwaltungsfunktionen (einschließlich der CodeQL-Pakete) sind derzeit als Betaversion verfügbar und können noch geändert werden. Während der Betaversion sind CodeQL-Pakete nur mit GitHub-Paketen verfügbar – in der Container registry. Um diese Betafunktion zu verwenden, installiere die neueste Version des CodeQL CLI-Bundles aus https://github.com/github/codeql-action/releases.
Wenn du deine eigenen Abfragen schreibst, um sie für andere freizugeben, solltest du sie in einem benutzerdefinierten CodeQL-Paket speichern. Du kannst das Paket als CodeQL-Paket in GitHub Packages veröffentlichen – der GitHub Container registry. Weitere Informationen findest du unter Anpassen der Analyse mit CodeQL-Paketen.
CodeQL-Pakete organisieren die Dateien, die in der CodeQL-Analyse verwendet werden, und können Abfragen, Bibliotheksdateien, Abfragesammlungen und wichtige Metadaten speichern. Das Stammverzeichnis muss eine Datei mit dem Namen qlpack.yml enthalten. Deine benutzerdefinierten Abfragen sollten im CodeQL-Paketstamm oder den zugehörigen Unterverzeichnissen gespeichert werden.
Für jedes CodeQL-Paket enthält die qlpack.yml-Datei Informationen, die die CodeQL CLI darüber informieren, wie die Abfragen zu kompilieren sind, von welchen anderen CodeQL}-Paketen und -Bibliotheken das Paket abhängt und wo die Definitionen der Abfragesammlung zu finden sind. Weitere Informationen dazu, was in diese Datei aufgenommen werden soll, findest du unter Anpassen der Analyse mit CodeQL-Paketen.
Einschließen von Abfragehilfen für benutzerdefinierte CodeQL-Abfragen in SARIF-Dateien
Wenn du die CodeQL CLI zum Ausführen von Codeüberprüfungsanalysen auf CI/CD-Systemen von Drittanbietern verwendest, kannst du die Abfragehilfe für deine benutzerdefinierten Abfragen in SARIF-Dateien einschließen, die während einer Analyse generiert wurden. Nach dem Hochladen der SARIF-Datei in GitHub wird die Abfragehilfe auf der Codeüberprüfungs-Benutzeroberfläche für alle Warnungen angezeigt, die von den benutzerdefinierten Abfragen generiert wurden.
Ab CodeQL CLI (Version 2.7.1) kannst du markdowngerenderte Abfragehilfen in SARIF-Dateien einschließen, indem du die --sarif-add-query-help-Option beim Ausführen von codeql database analyze bereitstellst.
Du kannst Abfragehilfen für benutzerdefinierte Abfragen direkt in eine Markdowndatei schreiben und sie zusammen mit der entsprechenden Abfrage speichern. Um die Einheitlichkeit mit den CodeQL-Standardabfragen zu gewährleisten, kannst du die Abfragehilfe auch im .qhelp-Format schreiben. In .qhelp-Dateien geschriebene Abfragehilfen können nicht in SARIF-Dateien eingefügt werden, und sie können nicht durch die Codeüberprüfung verarbeitet werden, weshalb sie vor der Ausführung der Analyse in Markdown-Dateien konvertiert werden müssen. Weitere Informationen findest du unter Abfragehilfedateien und Testen von Abfragehilfedateien.
Mitwirken am CodeQL-Repository
Wenn du deine Abfrage für andere CodeQL-Benutzer freigeben möchtest, kannst du einen Pull Request im CodeQL-Repository erstellen. Weitere Informationen findest du unter Mitwirken an CodeQL.