Verwenden des CodeQL-Modell-Editors

Informationen zum CodeQL Modell-Editor

Mit CodeQL Modellpaketen können Sie Ihre CodeQLcode scanning Analyse erweitern, um benutzerdefinierte Bibliotheken und Frameworks zu erkennen, die von Ihrer Codebasis verwendet werden, die standardmäßig nicht unterstützt werden. Mit dem CodeQL Modell-Editor können Sie eigene Modellpakete erstellen. Der Modell-Editor führt Sie durch die Modellierung der Aufrufe externer Abhängigkeiten in Ihrer Anwendung oder die vollständige Modellierung aller öffentlichen Einstiegs- und Ausgangspunkte in einer externen Abhängigkeit.

Weitere Informationen zum Anpassen code scanning der Analyse mit Modellpaketen finden Sie unter Bearbeiten der Konfiguration des Standardsetups und Workflowkonfigurationsoptionen für die Codeüberprüfung.

Wenn Sie den Modell-Editor öffnen, analysiert er die aktuell ausgewählte CodeQL Datenbank und identifiziert, wo die Anwendung externe APIs und alle öffentlichen Methoden verwendet. Eine externe (oder Drittanbieter)-API ist eine beliebige API, die nicht Teil der CodeQL ausgewählten Datenbank ist.

Der Modell-Editor verfügt über zwei verschiedene Modi:

•         **Anwendungsmodus (Standardansicht):** Der Editor listet jedes externe Framework auf, das von der ausgewählten CodeQL Datenbank verwendet wird. Wenn Sie ein Framework erweitern, wird eine Liste aller Aufrufe an und aus der externen API mit den Optionen angezeigt, die zum Modellieren von Datenflüssen über jeden Aufruf verfügbar sind. Dieser Modus ist am nützlichsten, um die CodeQL Ergebnisse für eine bestimmte Codebasis zu verbessern.
  

•         **Abhängigkeitsmodus:** Der Editor identifiziert alle öffentlich zugänglichen APIs in der ausgewählten CodeQL Datenbank. Diese Ansicht führt Sie durch die Modellierung jeder öffentlichen API, die von der Codebasis zur Verfügung gestellt wird. Wenn Sie mit der Modellierung der gesamten API fertig sind, können Sie das Modell speichern und verwenden, um die CodeQL Analyse für alle Codebasen zu verbessern, die die Abhängigkeit verwenden.
  

Der Rest dieses Artikels behandelt die praktischen Aspekte der Modellierungsabhängigkeiten mithilfe des CodeQL Modell-Editors. Technische Informationen finden Sie unter Anpassen von Bibliotheksmodellen für Java und Kotlin, Anpassen von Bibliotheksmodellen für Python, Anpassen von Bibliotheksmodellen für Ruby und Anpassen von Bibliotheksmodellen für C# in der CodeQL Sprachdokumentation.

Anzeigen des CodeQL Modell-Editors

1. Öffnen Sie Ihren CodeQL Arbeitsbereich in VS Code. Beispielsweise der vscode-codeql-starter Arbeitsbereich. Wenn Sie den Startarbeitsbereich verwenden, aktualisieren Sie das ql Untermodul, main um sicherzustellen, dass die Abfragen zum Sammeln von Daten für den Modell-Editor verwendet werden.

2.        Visual Studio CodeKlicken Sie in , klicken Sie in der linken Randleiste auf **QL**, um die CodeQL Erweiterung anzuzeigen.
   

3. Wählen Sie in der Ansicht "Datenbanken" die Datenbank aus, aus der CodeQL Sie modellieren möchten.

4. Klicken Sie in der CodeQL Ansicht "Methodenmodellierung" auf " Modellierung starten ", um den Modell-Editor anzuzeigen. Alternativ können Sie den VS Code Command PaletteCodeQLBefehl ": Modell-Editor (Beta) öffnen" ausführen.

5. Der CodeQL Modell-Editor führt eine Reihe von Telemetrieabfragen aus, um APIs im Code zu identifizieren, und der Editor wird auf einer neuen Registerkarte angezeigt.

6. Nach Abschluss der Telemetrie-Abfragen werden die identifizierten APIs im Editor angezeigt.

Modellieren der Aufrufe Ihrer Codebasis an externe APIs

In der Regel verwenden Sie diesen Ansatz, wenn Sie sich eine bestimmte Codebasis ansehen, in der Sie die Genauigkeit der CodeQL Ergebnisse verbessern möchten. Dies ist nützlich, wenn die Codebasis Frameworks oder Bibliotheken verwendet, die nicht unterstützt CodeQLwerden, und wenn der Quellcode des Frameworks oder der Bibliothek nicht in der Analyse enthalten ist.

In diesem Abschnitt wird ein open source Java Projekt namens "sofa-jraft" als Beispiel verwendet. Die Erfahrung der Modellierung von Aufrufen externer APIs, die in anderen kompilierten Sprachen geschrieben wurden, ist ähnlich.

1. Wählen Sie in Visual Studio Codeder Datei die Datenbank aus, für die Sie die CodeQL Abdeckung verbessern CodeQL möchten.

2. Zeigen Sie den CodeQL Modell-Editor an. Standardmäßig wird der Editor im Anwendungsmodus ausgeführt, sodass die Liste der externen APIs, die von der ausgewählten Codebasis verwendet werden, angezeigt wird.

   

3. Klicken Sie hier, um eine externe API zu erweitern und die Liste der Aufrufe aus der Codebasis auf die externe Abhängigkeit anzuzeigen.

   

4. Klicken Sie auf Ansicht, die mit einem API-Aufruf oder einer Methode verknüpft ist, um anzuzeigen, wo diese in Ihrer Codebasis verwendet wird.

5. Die Datei, die den ersten Aufruf ihrer Codebasis an die API enthält, wird geöffnet, und eine CodeQL Ansicht "Methodenverwendung" wird in VS Code der Ansicht "Probleme" und "Terminal" angezeigt (in der Regel werden die Ansichten "Probleme" und "Terminal" angezeigt). In CodeQL der Ansicht "Methodenverwendung" werden alle Aufrufe von Ihrem Code an die API aufgelistet, gruppiert nach Methode. Sie können durch die einzelnen Nutzungen klicken, um zu entscheiden, wie Sie die Nutzung der Methode modellieren.

6. Wenn Sie bestimmt haben, wie Sie die Nutzung der Methode modellieren, können Sie einen anderen Modelltyp auswählen. Klicken Sie in der Ansicht "Methodenmodellierung" der CodeQL Erweiterung auf das CodeQL Dropdown unter "Modelltyp". Diese Änderung wird automatisch in den Standard-Modell-Editor übernommen.

7. Die restlichen Felder in dieser Zeile werden mit den für den gewählten Modelltyp verfügbaren Optionen aktualisiert:

   • „Source“: Wählen Sie das zu modellierende „Output“-Element.
   • „Sink“: Wählen Sie das zu modellierende „Input“-Element.
   • „Flow summary“: Wählen Sie die zu modellierenden „Input“- und „Output“-Elemente.

8. Definieren Sie die „Variante“ des Datenflusses für das Modell.

9. Wenn Sie mit der Modellierung fertig sind, rufen Sie den Standard-Modell-Editor auf und klicken Sie auf Alles speichern oder Speichern (unten rechts in jeder erweiterten Methodenliste). Der Prozentsatz der im Editor modellierten Methoden wird aktualisiert.

Die Modelle werden in Ihrem Arbeitsbereich unter .github/codeql/extensions/CODEQL-MODEl-PACKdem CODEQL-MODEL-PACK Namen der CodeQL ausgewählten Datenbank gespeichert. Das heißt, der Name des Repositorys, Bindestriche, die sprache analysiert nach CodeQL. Weitere Informationen findest du unter Erstellen und Arbeiten mit CodeQL-Paketen.

Die Modelle werden in einer Reihe von YAML-Datenerweiterungsdateien gespeichert, eine für jede externe API. Beispiel:

.github/codeql/extensions/sofa-jraft-java # the model pack directory
    models
        jmh-core.model.yml                  # models calls to [email protected]
        rocksdbjni.model.yml                # models calls to [email protected]

Modellieren der öffentlichen API einer Codebasis

In der Regel verwenden Sie diese Methode, wenn Sie ein Framework oder eine Bibliothek modellieren möchten, das Ihre Organisation in mehr als einer Codebasis verwendet. Nachdem Sie das Erstellen und Testen des Modells abgeschlossen haben, können Sie das CodeQL Modellpaket für GitHubContainer registry ihre gesamte Organisation veröffentlichen.

In diesem Abschnitt wird ein open source Java Projekt namens "sofa-jraft" als Beispiel verwendet. Die Erfahrung der Modellierung von Aufrufen externer APIs, die in anderen kompilierten Sprachen geschrieben wurden, ist ähnlich.

1. Wählen Sie die CodeQL Datenbank aus, die Sie modellieren möchten.

2. Zeigen Sie den CodeQL Modell-Editor an. Standardmäßig wird der Editor im Anwendungsmodus ausgeführt. Klicken Sie auf Als Abhängigkeit modellieren, um den Abhängigkeitsmodus anzuzeigen. Der Bildschirm ändert sich, um die öffentliche API des Frameworks oder der Bibliothek anzuzeigen.

   

3. Klicken Sie, um ein Paket zu erweitern und die Liste der verfügbaren Methoden anzuzeigen.

4. Klicken Sie auf „Mit einer Methode verknüpft anzeigen“, um ihre Definition anzuzeigen.

   

5. Wenn Sie bestimmt haben, wie die Methode modellieren soll, definieren Sie den „Modelltyp“.

6. Die restlichen Felder in dieser Zeile werden mit den für den gewählten Modelltyp verfügbaren Optionen aktualisiert:

   • „Source“: Wählen Sie das zu modellierende „Output“-Element.
   • „Sink“: Wählen Sie das zu modellierende „Input“-Element.
   • „Flow summary“: Wählen Sie die zu modellierenden „Input“- und „Output“-Elemente.

7. Definieren Sie die „Variante“ des Datenflusses für das Modell.

8. Wenn Sie mit der Modellierung fertig sind, klicken Sie auf Alles speichern oder Speichern (unten rechts in jeder erweiterten Liste von Aufrufen). Der Prozentsatz der im Editor modellierten Aufrufe wird aktualisiert.

Die Modelle werden in Ihrem Arbeitsbereich unter .github/codeql/extensions/CODEQL-MODEL-PACKdem CODEQL-MODEL-PACK Namen der CodeQL ausgewählten Datenbank gespeichert. Das heißt, der Name des Repositorys, Bindestriche, die sprache analysiert nach CodeQL. Weitere Informationen findest du unter Erstellen und Arbeiten mit CodeQL-Paketen.

Die Modelle werden in einer Reihe von YAML-Datenerweiterungsdateien gespeichert, eine für jede öffentliche Methode. Beispiel:

.github/codeql/extensions/sofa-jraft-java          # the model pack directory
    models
        com.alipay.sofa.jraft.option.model.yml # models public methods in package
        com.alipay.sofa.jraft.rhea.options.model.yml

Der Editor erstellt eine separate Modelldatei für jedes Paket, das Sie modellieren.

Modellieren von Methoden mit mehreren potenziellen Flüssen

Einige Methoden unterstützen mehr als einen Datenfluss. Es ist wichtig, alle Datenflüsse für eine Methode zu modellieren, andernfalls können Sie nicht alle potenziellen Probleme erkennen, die mit der Verwendung der Methode verbunden sind. Sie modellieren zunächst einen Datenfluss für die Methode und verwenden dann die +-Taste in der Methodenzeile, um ein zweites Datenflussmodell anzugeben.

Testen von CodeQL Modellpaketen in VS Code

Sie können alle CodeQL Modellpakete testen, die VS Code Sie mit der Einstellung "Ausführen von Abfragen: Erweiterungspakete verwenden" erstellen. Weitere Informationen findest du unter Anpassen von Einstellungen. Diese Methode funktioniert sowohl für Datenbanken als auch für Variantenanalyse-Repositorys.

• Wenn Sie Abfragen für eine CodeQL Datenbank mit allen Modellpaketen ausführen möchten, die .github/codeql/extensions im Verzeichnis des Arbeitsbereichs gespeichert sind, aktualisieren Sie Ihre settings.json Datei mit: "codeQL.runningQueries.useExtensionPacks": "all",

• Wenn Sie Abfragen für eine CodeQL Datenbank ausführen möchten, ohne Modellpakete zu verwenden, aktualisieren Sie Ihre settings.json Datei mit: "codeQL.runningQueries.useExtensionPacks": "none",

Wenn Ihr Modell gut funktioniert, sollten Sie einen Unterschied in den Ergebnissen der beiden verschiedenen Ausführungen sehen. Wenn keine Unterschiede in den Ergebnissen auftreten, müssen Sie möglicherweise einen bekannten Bug einführen, um zu bestätigen, ob sich das Modell wie erwartet verhält.

Weiterführende Lektüre

•         [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup)
  

•         [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#codeql-model-packs)[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies).