Hinweis: Dieser Artikel wurde im Januar 2023 von der CodeQL-Dokumentationswebsite migriert.
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.
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.