Vorbereiten einer Datenbank für CodeQL

Abgeschlossen

CodeQL behandelt Code wie Daten. Sie erstellen eine Datenbank mithilfe von abfragefähigen Daten, die Sie aus Ihrer Codebasis extrahieren. Anschließend können Sie CodeQL-Abfragen für diese Datenbank ausführen, um Sicherheitsrisiken, Fehler und andere Fehler zu identifizieren. Sie können eigene Abfragen schreiben oder standardmäßige CodeQL-Abfragen ausführen, die von GitHub-Forschern und Communitymitwirkenden geschrieben wurden.

In dieser Lektion erfahren Sie, wie Sie eine Datenbank erstellen. Dieser Schritt ist erforderlich, bevor Sie Ihren Code analysieren können. Sie müssen eine CodeQL-Datenbank erstellen, die alle Daten enthält, die zum Ausführen von Abfragen in Ihrem Code erforderlich sind.

Die CodeQL-Analyse basiert darauf, relationale Daten aus Ihrem Code zu extrahieren und zum Erstellen einer CodeQL-Datenbank zu verwenden. Diese Datenbanken enthalten alle wichtigen Informationen zu einer Codebasis.

Sie können das eigenständige CodeQL CLI-Produkt verwenden, um Code zu analysieren und eine Datenbankdarstellung einer Codebasis zu generieren. Nachdem die Datenbank fertig ist, können Sie die Datenbank abfragen oder eine Reihe von Abfragen ausführen, um eine Reihe von Ergebnissen im SARIF -Format (Static Analysis Results Interchange Format) zu generieren.

Datenbankvorbereitung für CodeQL

Bevor Sie eine CodeQL-Datenbank generieren, müssen Sie die CodeQL CLI installieren und einrichten. Anschließend müssen Sie die Version Ihrer Codebasis auschecken, die Sie analysieren möchten.

Für kompilierte Sprachen sollte das Verzeichnis zum Erstellen bereit sein, wobei alle Abhängigkeiten bereits installiert sind. CodeQL beginnt mit dem Extrahieren einer einzelnen relationalen Darstellung jeder Quelldatei in der Codebasis zum Erstellen einer Datenbank. Sie verwenden diese Datenbank, um Ihren Code zu analysieren.

Bei interpretierten Sprachen wird der Extraktor direkt im Quellcode ausgeführt. Diese Funktion bietet Ihnen eine genaue Darstellung der Codebasis und löst alle Abhängigkeiten auf.

Die Quelldateiextraktion aus der Codebasis funktioniert, indem der normale Buildprozess für kompilierte Sprachen überwacht wird. CodeQL erstellt jedes Mal eine Kopie der Quelldatei, wenn Sie einen Compiler aufrufen, um eine Quelldatei zu verarbeiten. Es sammelt alle relevanten Informationen zum Quellcode mit jeder Quelldatei.

CLI-Setup

Führen Sie die folgenden Schritte aus, um die CodeQL CLI einzurichten.

1. Laden Sie das .zip Paket des CodeQL CLI-Bundles herunter.

Es wird empfohlen, die CodeQL CLI und Abfragen zu installieren, indem Sie das gebündelte Paket herunterladen. Diese Methode trägt dazu bei, kompatibilitäts- und leistungsverbesserungen zu gewährleisten, anstatt die CLI und Abfragen separat herunterzuladen.

Das CodeQL CLI-Downloadpaket ist ein .zip Archiv mit Tools, Skripts und verschiedenen CodeQL-spezifischen Dateien. Das Bundle umfasst: codeQL CLI, kompatible Versionen der Abfragen und Bibliotheken aus dem CodeQL GitHub-Repository und die vorkompilierten Versionen der enthaltenen Abfragen.

1. Wechseln Sie zur Releases-Seite des öffentlichen CodeQL–Repositorys.
2. Laden Sie das plattformspezifische Bundle unter "Assets" herunter.

Auf der Seite Releases können Sie auch die Änderungsprotokolle für Releases sowie Downloads für frühere Versionen des CodeQL-Pakets anzeigen. Bei Bedarf können Sie codeql-bundle.tar.gz herunterladen, die die CLI für alle unterstützten Plattformen enthält.

2. Extrahiere das .zip-Archiv

Wenn Sie Linux, Windows oder macOS verwenden, können Sie das .zip Archiv in das Verzeichnis Ihrer Wahl extrahieren.

Benutzer von macOS Catalina (oder neuer) müssen weitere Schritte unternehmen. Weitere Informationen finden Sie in der CodeQL-Dokumentation zu den ersten Schritten mit der CLI.

3. Ausführen von CodeQL-Prozessen

Führen Sie nach der Extraktion einen der folgenden Schritte aus, um die codeql ausführbare Datei zum Ausführen der CodeQL-Prozesse zu verwenden:

• Führen Sie <extraction-root>/codeql/codeql aus, wobei <extraction-root> der Ordner ist, in dem Sie das CodeQL CLI-Paket extrahiert haben.
• Fügen Sie <extraction-root>/codeql Ihrem PATH-Eintrag hinzu, damit Sie die ausführbare Datei einfach als codeql ausführen können.

Jetzt können Sie CodeQL-Befehle ausführen.

Überprüfung Ihrer CLI-Einrichtung

Sie können CodeQL CLI-Unterbefehle ausführen, um zu überprüfen, ob Sie die CLI ordnungsgemäß eingerichtet haben und Datenbanken analysieren können:

• Führen Sie codeql resolve packs (wenn Sie hinzugefügt haben codeqlPATH) aus, um anzuzeigen, welche CodeQL-Pakete die CLI finden kann. Verwenden Sie andernfalls /<extraction-root>/codeql/codeql resolve packs. Mit diesem Befehl werden die Namen der CodeQL-Pakete angezeigt, die im CodeQL CLI-Bundle enthalten sind, wie in den vorherigen Schritten gezeigt <extraction-root>.

  Wenn die CodeQL CLI die CodeQL-Pakete für die erwarteten Sprachen nicht finden kann, überprüfen Sie, ob Sie das CodeQL-Bundle heruntergeladen haben und keine eigenständige Kopie der CodeQL CLI.

• Führen Sie die Ausführung aus codeql resolve languages , um anzuzeigen, welche Sprachen das CodeQL CLI-Paket standardmäßig unterstützt.

Datenbankerstellung

Erstellen Sie eine CodeQL-Datenbank, indem Sie diesen Befehl im Check-Out-Stamm Ihres Projekts ausführen:

codeql database create <database> --language=<language-identifier>

Im Befehl:

• Ersetzen Sie <database> mit dem Pfad zur zu erstellenden neuen Datenbank.
• Ersetzen Sie den Bezeichner <language-identifier> für die Sprache, die Sie zum Erstellen der Datenbank verwenden. Sie können diesen Bezeichner --db-cluster verwenden, um kommagetrennte Listen zu akzeptieren, oder Sie können ihn mehrmals angeben.

Sie können auch die folgenden Optionen angeben. Diese Optionen hängen vom Speicherort der Quelldatei ab, unabhängig davon, ob Der Code kompiliert werden muss oder ob Sie CodeQL-Datenbanken für mehrere Sprachen erstellen möchten.

• Verwenden Sie --source-root, um den Stammordner für die primären Quelldateien zur Datenbankerstellung zu identifizieren.
• Verwenden Sie --db-cluster, wenn Sie Datenbanken für Codebasen mit mehreren Sprachen erstellen möchten.
• Verwenden Sie --command, wenn Sie eine Datenbank für eine oder mehrere kompilierte Sprachen erstellen. Sie benötigen diese Option nicht, wenn Sie nur Python und JavaScript verwenden.
• Verwenden Sie --no-run-unnecessary-builds zusammen mit --db-cluster, um den Buildbefehl für Sprachen zu unterdrücken, in denen die CodeQL CLI den Build nicht überwachen muss.

Nachdem Sie die Datenbank erfolgreich erstellt haben, wird an dem im Befehl angegebenen Pfad ein neues Verzeichnis angezeigt. Wenn Sie die Option --db-cluster zum Erstellen mehrerer Datenbank verwendet haben, wird für jede Sprache ein Unterverzeichnis erstellt.

Jedes CodeQL-Datenbankverzeichnis enthält mehrere Unterverzeichnisse, einschließlich der relationalen Daten, die für die Analyse und ein Quellarchiv verwendet werden. Das Quellarchiv ist eine Kopie der Quelldateien, die zum Zeitpunkt der Erstellung der Datenbank erstellt wurden. CodeQL verwendet ihn zum Anzeigen von Analyseergebnissen.

Extraktoren

Ein Extraktor ist ein Tool, das die relationalen Daten und den Quellverweis für jede Eingabedatei generiert, aus der eine CodeQL-Datenbank erstellt werden kann. Jede von CodeQL unterstützte Sprache verfügt über einen Extraktor. Diese Struktur stellt sicher, dass der Extraktionsprozess so genau wie möglich ist.

Jeder Extraktor definiert einen eigenen Satz von Konfigurationsoptionen. Das Eingeben von codeql resolve extractor --format=betterjson führt zu Daten, die wie im folgenden Beispiel formatiert sind:

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

Um herauszufinden, welche Optionen für den Extraktor Ihrer Sprache verfügbar sind, geben Sie diese eincodeql resolve languages --format=betterjson.codeql resolve extractor --format=betterjson Das betterjson Ausgabeformat bietet außerdem die Stamm- und andere sprachspezifischen Optionen des Extraktors.

Daten in einer CodeQL-Datenbank

Eine CodeQL-Datenbank ist ein einzelnes Verzeichnis, das alle daten enthält, die für die Analyse erforderlich sind. Diese Daten umfassen relationale Daten, kopierte Quelldateien und ein sprachspezifisches Datenbankschema, das die gegenseitigen Beziehungen in den Daten angibt. CodeQL importiert diese Daten nach der Extraktion.

CodeQL-Datenbanken stellen eine Momentaufnahme der abfragbaren Daten einer bestimmten Sprache bereit, die aus einer Codebasis extrahiert wurden. Diese Daten sind eine vollständige, hierarchische Darstellung des Codes. Sie enthält eine Darstellung der abstrakten Syntaxstruktur, des Datenflussdiagramms und des Steuerelementflussdiagramms.

Datenbanken werden jeweils in einer Sprache für mehrsprachige Codebasen erstellt. Jede Sprache verfügt über ein eigenes datenbankschema. Das Schema stellt eine Schnittstelle zwischen der anfänglichen lexikalischen Analyse während des Extraktionsprozesses und der komplexen Analyse über CodeQL bereit.

Eine CodeQL-Datenbank enthält zwei Haupttabellen:

• Die expressions Tabelle enthält eine Zeile für jeden Ausdruck im Quellcode, den CodeQL während des Buildvorgangs analysiert hat.
• Die statements Tabelle enthält eine Zeile für jede Anweisung im Quellcode, die CodeQL während des Buildvorgangs analysiert hat.

Die CodeQL-Bibliothek definiert Klassen, um eine Abstraktionsebene für jede dieser Tabellen bereitzustellen. Diese Ebene enthält die zugehörigen Hilfstabellen Expr und Stmt.

Potenzielle CodeQL-Schwachstellen

Die Datenbankerstellung im Code-Scan-Workflow weist einige potenzielle Schwachstellen auf. In diesem Abschnitt wird die Verwendung der GitHub CodeQL-Aktion erläutert.

Sie müssen eine Sprachmatrix autobuild verwenden, um jede der kompilierten Sprachen zu erstellen, die in der Matrix aufgeführt sind. Sie können eine Matrix verwenden, um Aufträge für mehr als eine unterstützte Version einer Programmiersprache, eines Betriebssystems oder eines Tools zu erstellen.

Wenn Sie keine Matrix verwenden, versucht autobuild, die unterstützte kompilierte Sprache mit den meisten Quelldateien im Repository zu erstellen. Die Analyse kompilierter Sprachen, außer Go, schlägt häufig fehl, es sei denn, Sie geben explizite Befehle an, um den Code zu erstellen, bevor Sie den Analyseschritt ausführen.

Das Verhalten des autobuild Schritts variiert je nach Betriebssystem, auf dem der Sprachextraktionsmodul ausgeführt wird. Der autobuild Schritt versucht, automatisch eine geeignete Buildmethode für die Sprache basierend auf dem Betriebssystem zu erkennen. Dieses Verhalten kann zu unzuverlässigen Ergebnissen für kompilierte Sprachen führen und kann häufig zu einer fehlgeschlagenen Ausführung führen.

Es wird empfohlen, einen Buildschritt in der Datei für den Codescanworkflow zu konfigurieren, die vor der Analyse ausgeführt wird, statt autobuild versuchen zu lassen, kompilierte Sprachen zu erstellen. Auf diese Weise ist die Workflowdatei auf die Buildanforderungen Ihres Systems und des Projekts für zuverlässigere Scans zugeschnitten.

Weitere Informationen zu bestimmten Sprachen und den autobuild Schritten in der CodeQL-Autobuilddokumentation finden Sie hier.

VS Code-Erweiterung

Sie können Visual Studio Code (VS Code) und die CodeQL-Erweiterung verwenden, um Abfragen zu kompilieren und auszuführen, sofern Sie VS Code 1.39 oder höher verwenden. Sie können die Erweiterung aus dem Visual Studio Code Marketplace herunterladen oder die CodeQL VSIX-Datei herunterladen.

Die Erweiterung verwendet die von Ihnen installierte CLI, sofern sie in PATH verfügbar ist. Wenn nicht, verwaltet die Erweiterung automatisch den Zugriff auf die ausführbare Datei der CLI für Sie. Die automatische Verwaltung stellt sicher, dass die CLI mit der CodeQL-Erweiterung kompatibel ist.