{"meta":{"title":"Verwenden benutzerdefinierter Abfragen mit der CodeQL-CLI","intro":"Du kannst deine eigenen CodeQL-Abfragen schreiben, um bestimmte Sicherheitsrisiken und Fehler zu finden.","product":"Sicherheit und Codequalität","breadcrumbs":[{"href":"/de/code-security","title":"Sicherheit und Codequalität"},{"href":"/de/code-security/codeql-cli","title":"CodeQL CLI"},{"href":"/de/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli","title":"Erweiterte Funktionen"},{"href":"/de/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli","title":"Verwenden benutzerdefinierter Abfragen mit der CodeQL-CLI"}]},"body":"## Informationen zu benutzerdefinierten Abfragen und der CodeQL CLI\n\n<!-- tweaked title to fit \"About\" styling of conceptual intro section -->\n\nDu kannst deine CodeQL-Analysen anpassen, indem du eigene Abfragen schreibst, um bestimmte Sicherheitsrisiken oder Fehler zu ermitteln.\n\nIn diesem Artikel geht es insbesondere um das Schreiben von Abfragen, die mit dem Befehl [Datenbankanalyse](/de/code-security/codeql-cli/codeql-cli-manual/database-analyze) verwendet werden sollen, um [interpretierte Ergebnisse](https://codeql.github.com/docs/codeql-overview/about-codeql/#interpret-query-results) zu erzeugen.\n\n> \\[!NOTE]\n> Abfragen, die mit `database analyze` ausgeführt werden, weisen strenge [Metadatenanforderungen](https://codeql.github.com/docs/codeql-cli/using-custom-queries-with-the-codeql-cli/#including-query-metadata) auf. Du kannst Abfragen auch mit den folgenden Unterbefehlen auf plumbing-Ebene ausführen:\n>\n> * [Abfragen in der Datenbank ausführen](/de/code-security/codeql-cli/codeql-cli-manual/database-run-queries): Gibt nicht interpretierte Ergebnisse in einem binären Zwischenformat namens [BQRS](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#bqrs-file) aus.\n> * [Abfrageausführung](/de/code-security/codeql-cli/codeql-cli-manual/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.\n>\n> 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](/de/code-security/codeql-cli/codeql-cli-manual/bqrs-decode) verarbeiten. Daher ist es in den meisten Anwendungsfällen am einfachsten, die Datenbankanalyse zu verwenden, um interpretierte Ergebnisse direkt zu generieren.\n\n<!-- created a reusable since it's a reusable on the microsite -->\n\n## Schreiben einer gültigen Abfrage\n\nVor 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](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries).\n\n## Einschließen von Abfragemetadaten\n\nAbfragemetadaten sind oben in jeder Abfragedatei enthalten. Sie liefert Benutzern Informationen zur Abfrage und teilt der CodeQL CLI mit, wie die Abfrageergebnisse verarbeitet werden sollen.\n\nWenn 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:\n\n* Abfragebezeichner (`@id`): Eine Sequenz von Wörtern aus Kleinbuchstaben oder Ziffern, die durch `/` oder `-` getrennt sind und die Abfrage identifizieren und klassifizieren.\n\n* 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`).\n\nWeitere Informationen zu diesen Metadateneigenschaften findest du unter [Metadaten für CodeQL-Abfragen](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries) und [Styleguide zum Abfragen von Metadaten](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md).\n\n> \\[!NOTE]\n> 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](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).\n\n## Verpacken von benutzerdefinierten QL-Abfragen\n\nWenn 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 finden Sie unter [Anpassen der Analyse mit CodeQL-Paketen](/de/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs).\n\n<!-- tweaked to \"For more information, see X\" to match our style guide -->\n\nCodeQL-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.\n\nFü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](/de/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#codeqlpack-yml-properties).\n\n## Einschließen von Abfragehilfen für benutzerdefinierte CodeQL-Abfragen in SARIF-Dateien\n\nWenn 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.\nNach 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.\n\nAb 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.\n\nDu 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](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files) und [Testen von Abfragehilfedateien](/de/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files).\n\n## Mitwirken am CodeQL-Repository\n\nWenn du deine Abfrage für andere CodeQL-Benutzer freigeben möchtest, kannst du einen Pull Request im [CodeQL-Repository](https://github.com/github/codeql) erstellen. Weitere Informationen findest du unter [Mitwirken an CodeQL](https://github.com/github/codeql/blob/main/CONTRIBUTING.md).\n\n<!-- tweaked to \"For more information, see X\" to match our style guide -->\n\n## Weiterführende Themen\n\n* [CodeQL-Abfragen](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)"}