Ausführung von CodeQL-Abfragen in großem Maßstab mit der Analyse von Varianten über mehrere Repositories

Mit der Multirepository-Variantenanalyse (MRVA) können Sie Abfragen in einer Liste von bis zu 1.000 Repositorys auf GitHub von Visual Studio Code ausführen.

Voraussetzungen

• Sie müssen code scanning mithilfe von CodeQL auf GitHub aktivieren, entweder durch das Standardsetup oder das erweiterte Setup, bevor Sie Ihr Repository zu einer Liste für die Analyse hinzufügen. Informationen zum Aktivieren von code scanning unter Verwendung von CodeQL finden Sie unter Konfigurieren des Standardsetups für das Code-Scanning.

• Sie müssen ein Controller-Repository definieren, bevor Sie die erste Multi-Repository-Variantenanalyse ausführen können.

• Controllerrepositorys können leer sein, müssen jedoch mindestens einen Commit haben.

• Das Controllerrepository muss auf derselben Website gehostet werden wie die Repositorys, die Sie mithilfe von MRVA analysieren möchten, d. h.: GitHub.com oder SUBDOMAIN.ghe.com. Wenn Sie MRVA GitHub Enterprise-Cloud mit Datenresidenz ausführen möchten, sehen Sie Ändern der von der Erweiterung verwendeten URL GitHub.

• Auf GitHub.com kann die Sichtbarkeit der Controller-Repositories auf "öffentlich" gesetzt werden, wenn Sie nur öffentliche Repositorys analysieren möchten. Die Variantenanalyse ist frei.

• Die Sichtbarkeit des Controller-Repositorys muss "privat" sein, wenn Sie private oder interne Repositorys auf GitHub.com analysieren müssen.

Alle Aktionsminuten über dem kostenlosen Grenzwert, die du zum Ausführen einer Variantenanalyse für private oder interne Repositorys verbrauchst, werden dem Repositorybesitzer in Rechnung gestellt. Weitere Informationen zu kostenlosen Minuten und Abrechnungen finden Sie unter Abrechnung für GitHub Actions.

Einrichten eines Controller-Repositorys für MRVA

1. Klicken Sie in der Ansicht „Variantenanalyse-Repositorys“ auf Controller-Repository einrichten, um ein Feld für das Controller-Repository anzuzeigen.

   

2. Geben Sie den Besitzer und Namen des Repositorys ein, das Sie als Controller-Repository verwenden möchten, und drücken Sie die GitHub EINGABETASTE. Dieses Repository muss sich in derselben Instanz wie GitHub die Zu analysierenden Repositorys befinden, siehe Ändern der GitHub von der Erweiterung verwendeten URL.

3. Wenn Sie aufgefordert werden, die Authentifizierung mit GitHub vorzunehmen, folgen Sie den Anweisungen und melden Sie sich bei Ihrem Konto an. Wenn Sie fertig sind, kann eine Aufforderung von GitHub zur Authentifizierung um Erlaubnis bitten, in Visual Studio Code zu öffnen, klicken Sie auf Öffnen.

Der Name des Controller-Repositorys wird in Ihren Einstellungen für die CodeQL Erweiterung gespeichert. Informationen zum Bearbeiten des Controller-Repositorys findest du unter Anpassen von Einstellungen.

Ausführen einer Abfrage im großen Stil mithilfe von MRVA

1. Standardmäßig werden in der Ansicht "Variantenanalyserepositorys" die Standardlisten der öffentlichen Repositorys GitHub.com "Top 10", "Top 100" und "Top 1000" für die zu analysierende Sprache angezeigt. Wenn Ihr Controller-Repository auf SUBDOMAIN.ghe.com gehostet wird, sind diese Listen nicht verfügbar.

2. Optional können Sie ein neues Repository, eine neue Organisation oder Liste hinzufügen.

   1. Klicken Sie + in der Ansicht „Variantenanalyse-Repositories“, um eine neue Datenbank hinzuzufügen.

   2. Wählen Sie im Dropdownmenü "Aus einem GitHub Repository " oder "Alle Repositorys von GitHub Organisation oder Besitzer" aus.

   3. Geben Sie den Bezeichner des Repositorys oder der Organisation ein, den Sie in dem Feld verwenden möchten.

3. Wählen Sie aus, für welches Repository oder welche GitHub Repositorys Sie Ihre Abfrage ausführen möchten.

   

4. Öffnen Sie die Abfrage, die Sie ausführen möchten, klicken Sie mit der rechten Maustaste in die Abfragedatei, und wählen Sie :CodeQLVariant-Analyse ausführen, um die Variantenanalyse zu starten.

Auswählen eines einzelnen Repositorys oder einer Organisation GitHub für die Analyse

1. Klicken Sie + in der Ansicht „Variantenanalyse-Repositories“, um eine neue Datenbank hinzuzufügen.

2. Wählen Sie im Dropdownmenü "Aus einem GitHub Repository " oder "Alle Repositorys von GitHub Organisation oder Besitzer" aus.

3. Geben Sie den Bezeichner des Repositorys oder der Organisation ein, den Sie in dem Feld verwenden möchten.

Fehler und Warnungen

Wenn Sie MRVA ausführen, gibt es zwei Schlüsselstellen, an denen Fehler und Warnungen angezeigt werden:

•         Visual Studio Code Fehler: Alle Probleme beim Erstellen eines CodeQL Pakets und beim Senden der Analyse GitHub werden als Visual Studio Code Fehler in der unteren rechten Ecke der Anwendung gemeldet. Informationen sind auch in der Ansicht „Probleme“ verfügbar.
  

• „Variantenanalyseergebnisse“: Alle Probleme mit der Variantenanalyse werden in dieser Ansicht gemeldet.

Erkunden Ihrer Ergebnisse

Sobald ein Workflow ausgeführt wird, um Ihre Variantenanalyse auf GitHub durchzuführen, öffnet sich eine Ansicht „Ergebnisse der Variantenanalyse“, die die Ergebnisse anzeigt, sobald sie verfügbar sind. Sie können diese Ansicht verwenden, um den Fortschritt zu überwachen, alle Fehler anzuzeigen und auf die Workflowprotokolle in Ihrem Controller-Repository zuzugreifen.

Wenn die Ausführung der Variantenanalyse geplant ist, wird die Ansicht „Ergebnisse“ automatisch geöffnet. Zunächst zeigt die Ansicht eine Liste aller Repositorys an, die für die Analyse geplant wurden. Da jedes Repository analysiert wird, wird die Ansicht aktualisiert, um eine Zusammenfassung der Anzahl der Ergebnisse anzuzeigen. Um die detaillierten Ergebnisse für ein Repository (einschließlich Ergebnispfaden) anzuzeigen, klicken Sie auf den Repositorynamen.

Für jedes Repository sehen Sie:

• Anzahl der von der Abfrage gefundenen Ergebnisse

• Sichtbarkeit des Repositorys

• Gibt an, ob die Analyse noch ausgeführt wird oder abgeschlossen ist.

• Anzahl der Sterne, auf die das Repository verfügt GitHub

Anzeigen der Ergebnisse für ein Repository

1. Klicken Sie auf den Repositorynamen, um eine Zusammenfassung der einzelnen Ergebnisse anzuzeigen.

2. Erkunden Sie die für jedes Ergebnis verfügbaren Informationen mithilfe von Links zu den Quelldateien auf GitHub. Für Datenflussabfragen gibt es einen zusätzlichen „Pfade anzeigen“-Link.

   

Exportieren Ihrer Ergebnisse

Sie können Ihre Ergebnisse zur weiteren Analyse exportieren oder mit Mitarbeitern besprechen. Klicken Sie in der Ansicht "Ergebnisse" auf " Ergebnisse exportieren", um die Ergebnisse in einen geheimen Gist GitHub oder in eine Markdown-Datei in Ihrem Arbeitsbereich zu exportieren.

Erstellen einer benutzerdefinierten Liste von Repositorys

          CodeQL Für die Analyse ist immer eine CodeQL Datenbank erforderlich, um Abfragen auszuführen. Wenn Sie eine Variantenanalyse für eine Liste von Repositorys ausführen, wird Ihre Abfrage nur für die Repositorys ausgeführt, für die derzeit eine CodeQL Datenbank zum Herunterladen verfügbar ist. Die beste Möglichkeit, ein Repository für die Variantenanalyse verfügbar zu machen, ist die Aktivierung code scanning mit CodeQL. Informationen zum Aktivieren von code scanning mit CodeQL finden Sie unter [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning).

1. Klicken Sie in der Ansicht „Variantenanalyse-Repositorys“ auf das Symbol „Liste hinzufügen“.

   

2. Geben Sie einen Namen für die neue Liste ein, und drücken Sie dann die Eingabetaste.

3. Wählen Sie Ihre Liste in der Ansicht aus, und klicken Sie dann auf +, um Ihrer Liste ein Repository hinzuzufügen.

Verwalten ihrer benutzerdefinierten Repositorylisten

Sie können Ihre benutzerdefinierten Listen verwalten und bearbeiten, indem Sie mit der rechten Maustaste auf den Listennamen oder einen Repositorynamen in der Liste klicken und im Kontextmenü eine Option auswählen.

Die benutzerdefinierten Listen werden in Ihrem Arbeitsbereich in einer databases.json-Datei gespeichert. Wenn Sie die Datei direkt in Visual Studio Code bearbeiten möchten, können Sie sie öffnen, indem Sie im Ansichtsheader auf {} klicken.

Wenn Sie z. B. weiterhin eine Reihe von Repositorys analysieren möchten, die Ergebnisse für Ihre Abfrage hatten, klicken Sie in der Ansicht „Variantenanalyseergebnisse“ auf Repositoryliste kopieren, um nur eine Liste der Repositorys hinzuzufügen, die Ergebnisse in der Zwischenablage als JSON enthalten.

Im folgenden Beispiel wurden für eine Abfrage Ergebnisse in my-organization/my-repository angezeigt:

{
    "name": "new-repo-list",
    "repositories": [
        "my-organization/my-repository"
    ]
}

Sie können dann das new-repo-list der Repositorys in databases.json einfügen, um in der Ansicht „ Variantenanalyse-Repositorys“ leicht darauf zugreifen zu können.

Verwenden der GitHub Codesuche zum Hinzufügen von Repositorys zu einer benutzerdefinierten Liste

Sie können die Codesuche direkt in der CodeQL Erweiterung verwenden, um einer benutzerdefinierten Liste eine Teilmenge von Repositorys GitHub hinzuzufügen.

Wenn Sie beispielsweise alle Repositories in der rails-Organisation auf GitHub hinzufügen möchten, suchen Sie nach org:rails.

Sie können einer benutzerdefinierten Liste pro Suche maximal 1.000 Repositorys hinzufügen.

1. Wählen Sie in der Ansicht „Variantenanalyse-Repositorys“ die Liste aus, der Sie Repositorys hinzufügen möchten. Sie können eine neue Liste erstellen oder eine vorhandene Liste auswählen, die bereits Repositorys enthält.

2. Klicken Sie mit der rechten Maustaste auf die ausgewählte Liste, und klicken Sie dann auf " Repositorys mit GitHub Codesuche hinzufügen".

3. Wählen Sie im Popup, das oben in der Anwendung angezeigt wird, unter der Suchleiste eine Sprache für Ihre Suche aus den Optionen in der Dropdownliste aus.

4. Geben Sie in der Suchleiste die Suchabfrage ein, die Sie verwenden möchten, und drücken Sie die Eingabetaste.

Sie können den Fortschritt Ihrer Suche in der unteren rechten Ecke der Anwendung in einem Feld mit dem Text Searching for repositories... anzeigen. Wenn Sie auf Abbrechen klicken, werden Ihrer Liste keine Repositorys hinzugefügt. Nach Abschluss des Vorgangs werden die resultierenden Repositorys in der Ansicht "Variantenanalyse-Repositorys" in der Dropdownliste unter Ihrer benutzerdefinierten Liste angezeigt.

Einige der resultierenden Repositorys verfügen nicht über CodeQL Datenbanken, und einige erlauben möglicherweise keinen Zugriff durch die CodeQL Erweiterung für Visual Studio Code. Wenn Sie eine Analyse in der Liste ausführen, zeigt die Ansicht "Variant Analysis Results" an, welche Repositorys analysiert wurden, welche den Zugriff verweigert haben und welche keine CodeQL Datenbank hatten.

Ausführen von CodeQL-Abfragen mit der Analyse von Varianten in mehreren Repositorien auf selbstgehosteten Runnern

Um CodeQL Abfragen mit einer Multi-Repository-Variantenanalyse auf selbst gehosteten Läufern auszuführen, müssen Sie zuerst sicherstellen, dass Sie Ihrem Controller-Repository einen selbst gehosteten Läufer hinzugefügt haben, oder sicherstellen, dass das Controller-Repository Zugriff auf einen Läufer auf Organisations- oder Unternehmensebene hat.

Anschließend musst du eine neue „Actions“-Repositoryvariable in deinem Controllerrepository mit dem Namen MRVA_RUNNER_OS hinzufügen. Dieses enthält eine JSON-formatierte Liste der Bezeichnungen des selbstgehosteten Runners, den du verwenden möchtest. Beispiel:

["self-hosted", "macOS", "ARM64"]

Weitere Informationen findest du unter Selbst-gehostete Runner hinzufügen und Verwalten des Zugriffs auf selbstgehostete Runner mithilfe von Gruppen.

Wenn du eine Abfrage mit Multi-Repository-Variantenanalyse auf einem selbst gehosteten Runner ausführst, wird die Analyse vollständig darauf ausgeführt. Sie müssen keine neuen Workflows erstellen, aber Sie müssen angeben, welches Repository für die CodeQLVisual Studio Code Erweiterung als Controller-Repository verwendet werden soll. Wenn die Analyse der einzelnen Repositorys abgeschlossen ist, werden die Ergebnisse an Sie gesendet VS Code , damit Sie sie anzeigen können.