Benutzerdefinierte CodeQL-Abfragen

Benutzerdefinierte Abfragen erweitern CodeQL's integrierte Sicherheitsanalyse, um Sicherheitsrisiken zu erkennen und Codierungsstandards zu erzwingen, die für Ihre Codebasis spezifisch sind.

Wer kann dieses Feature verwenden?

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

In diesem Artikel

Was sind benutzerdefinierte CodeQL Abfragen?

Benutzerdefinierte Abfragen erweitern die integrierte Sicherheitsanalyse von CodeQL, um Schwachstellen, Codierungsstandards und Muster zu erkennen, die für Ihre Codebasis spezifisch sind.

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:

  • Abfragen in der Datenbank ausführen: Gibt nicht interpretierte Ergebnisse in einem binären Zwischenformat namens BQRS aus.
  • Abfrageausführung: 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 dekodieren verarbeiten. Daher ist es in den meisten Anwendungsfällen am einfachsten, die Datenbankanalyse zu verwenden, um interpretierte Ergebnisse direkt zu generieren.

Wann benutzerdefinierte Abfragen verwendet werden sollten

Verwenden Sie benutzerdefinierte Abfragen, um:

  • Erkennen von Sicherheitsrisiken, die für die Architektur oder Frameworks Ihrer Anwendung spezifisch sind
  • Erzwingen von organisationsspezifischen Codierungsstandards oder bewährten Methoden
  • Finden Sie Muster, die nicht von den Standard-CodeQL-Abfragepaketen abgedeckt werden
  • Analysieren Sie CodeQL-Datenbanken unter Verwendung des Befehls database analyze mithilfe der CodeQL CLI, um interpretierte Ergebnisse zu erzeugen.

Abfragestruktur

Benutzerdefinierte Abfragen werden in Abfragedateien geschrieben, die mit der .ql Erweiterung gespeichert werden. Diese Dateien enthalten auch wichtige Metadaten, die Informationen über den Zweck der Abfrage bereitstellen und den CodeQL CLI mitteilen, wie Ergebnisse verarbeitet werden. Zu den erforderlichen Eigenschaften gehören:

  •         **Abfragebezeichner (`@id`)**: Kleinbuchstaben oder Ziffern, begrenzt durch `/` oder `-`

  •         **Abfragetyp (`@kind`)**: Einer von:
    * problem - Einfache Warnung * path-problem – Warnung mit Codestandortsequenz * diagnostic – Problembehandlung bei Extraktoren * metric - Zusammenfassungsmetrik (erfordert @tags summary)

Hinweis

Die Anforderungen an die Metadaten können abweichen, wenn du deine Abfrage mit anderen Anwendungen verwenden willst. Weitere Informationen findest du unter Metadaten für CodeQL Abfragen.

Weitere Informationen zu Abfragemetadaten finden Sie unter Metadaten für CodeQL Abfragen und dem Leitfaden für Abfragemetadaten.

Abfragedokumentation

Die Abfragedokumentation hilft Benutzern zu verstehen, was eine Abfrage erkennt und wie identifizierte Probleme behoben werden. Sie können dokumentationen für Ihre benutzerdefinierten Abfragen in zwei Formaten einschließen:

  •         **Markdown-Dateien**: Werden zusammen mit der Abfrage gespeichert, können in SARIF-Dateien eingebunden und in der Benutzeroberfläche von code scanning angezeigt werden.

  •         **
        `.qhelp` Dateien**: Konsistent mit Standard-CodeQL Abfragen, müssen jedoch für die Verwendung mit code scanning in Markdown konvertiert werden.

Wenn SARIF-Dateien, die Abfragehilfe enthalten, in GitHub hochgeladen werden, wird die Dokumentation in der UI von code scanning für alle Warnungen angezeigt, die von der Abfrage generiert werden.

Weitere Informationen finden Sie unter Abfragehilfedateien.

Freigeben benutzerdefinierter Abfragen

Sie können benutzerdefinierte Abfragen für die Community freigeben, indem Sie Ihre eigenen Abfragepakete veröffentlichen. Weitere Informationen findest du unter Veröffentlichen und Verwenden von CodeQL-Paketen.

Weiterführende Lektüre

  •         [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)

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