Schreiben und Freigeben von benutzerdefinierten Abfragen für die CodeQL CLI

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

Wer kann dieses Feature verwenden?

CodeQL ist für die folgenden Repositorytypen verfügbar:

In diesem Artikel

Dieser Artikel befasst sich speziell mit dem Schreiben von Abfragen, die mit dem Befehl AUTOTITLE verwendet werden, um interpretierte Ergebnisse zu erzeugen. Konzeptionelle Informationen zu benutzerdefinierten Abfragen finden Sie unter Benutzerdefinierte CodeQL-Abfragen.

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

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 in der Anleitung Query metadata style guide.

Packen benutzerdefinierter Abfragen

Wenn Sie Abfragen schreiben, die für andere Personen freigegeben werden sollen, speichern Sie sie in einem benutzerdefinierten CodeQL Paket.

So packen Sie Ihre benutzerdefinierten Abfragen:

  1. Erstellen Sie ein CodeQL Paket mit einer qlpack.yml Datei im Stammverzeichnis.
  2. Speichern Sie Ihre benutzerdefinierten Abfragen (.ql Dateien) im Paketstamm oder in den Unterverzeichnissen.
  3. Konfigurieren Sie die qlpack.yml Datei so, dass Folgendes angegeben wird:
    • Kompilieren der Abfragen
    • Abhängigkeiten von anderen CodeQL Packs und Bibliotheken
    • Abfragesuitedefinitionen Weitere Informationen zu qlpack.yml Eigenschaften finden Sie unter Anpassen der Analyse mit CodeQL-Paketen.
  4. Veröffentlichen Sie Ihr Paket in GitHub Packages - der GitHub Container registry. Weitere Informationen finden Sie unter Anpassen der Analyse mit CodeQL-Paketen.

Einschließen von Abfragehilfen für benutzerdefinierte CodeQL-Abfragen in SARIF-Dateien

Informationen zu Abfragehilfe- und Dokumentationsformaten finden Sie unter Benutzerdefinierte CodeQL-Abfragen.

So fügen Sie beim Ausführen von Codescananalysen Abfragehilfe in SARIF-Dateien ein:

  1. Schreiben Sie Ihre Abfragehilfe in einem der unten aufgeführten Formate. * Markdown-Datei: Speichern Sie eine Markdown-Datei zusammen mit Ihrer Abfrage mit demselben Namen (z. B my-query.md . für my-query.ql) * ** .qhelp Datei**: Schreiben Sie die Abfragehilfe im .qhelp Format und konvertieren Sie sie dann in Markdown, bevor Sie die Analyse durchführen. Weitere Informationen findest du unter Abfrage-Hilfedateien und Testen von Abfragehilfedateien.

  2. Führen Sie codeql database analyze mit der Option --sarif-add-query-help aus:

    codeql database analyze <database> --format=sarif-latest --output=results.sarif --sarif-add-query-help

    Hinweis

    Die Option --sarif-add-query-help ist verfügbar ab CodeQL CLI v2.7.1.

  3. Laden Sie die SARIF-Datei in GitHubhoch.

Weiterführende Lektüre

  •         [CodeQL Abfragen](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)