Skip to main content

GitHub AE ist derzeit begrenzt freigegeben.

Verwenden benutzerdefinierter Abfragen mit der CodeQL-CLI

Du kannst deine eigenen CodeQL-Abfragen schreiben, um bestimmte Sicherheitsrisiken und Fehler zu finden.

GitHub CodeQL wird nach der Installation auf Benutzerbasis lizenziert. Du kannst CodeQL nur für bestimmte Aufgaben unter den Lizenzeinschränkungen verwenden. Weitere Informationen findest du unter Informationen zur CodeQL-CLI.

Wenn du über eine GitHub Advanced Security-Lizenz verfügst, kannst du CodeQL für eine automatisierte Analyse sowie für Continuous Integration und Continuous Delivery verwenden. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

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 metric und @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.

Weiterführende Themen