Joern Query Database ("Joern-Scan")

Dies ist die zentrale Abfragedatenbank für die Open-Source-Codeanalyseplattform Joern. Sie hat zwei Zwecke:

• Sie liefert die erforderlichen Grundlagen, um Joern in ein einsatzbereites Code-Scanning-Tool zu verwandeln.
• Ihre Abfragen dienen als nützliche Beispiele für diejenigen, die eigene Abfragen schreiben möchten.
• erstellt mit JDK11, läuft aber auf JRE >= 1.8

Die Abfragedatenbank wird als eigenständige Bibliothek verteilt, die Joern als Abhängigkeit enthält. Das bedeutet, dass es nicht notwendig ist, Joern zu installieren, um die Abfragen in der Datenbank nutzen zu können.

Gleichzeitig ist die Datenbank eine Joern-Erweiterung, das heißt, wenn sie beim Start dynamisch geladen wird, wird ihre Funktionalität in der interaktiven Joern-Shell und in Joern-Skripten verfügbar.

Sie können dieses Projekt forken, um eigene benutzerdefinierte Abfragen und Scanner zu erstellen, oder freundlicherweise einen PR an dieses Repository senden, um sie für die Aufnahme in die Standardverteilung in Betracht ziehen zu lassen.

Installation und Ausführung

Das Installationsskript lädt Joern herunter und installiert es in einem Unterverzeichnis. Die Abfragedatenbank wird als Erweiterung installiert.

./install.sh

Sie können alle Abfragen wie folgt ausführen:

./joern-scan path/to/code

Zum Beispiel:

mkdir foo
echo "int foo(int a, int b, int c, int d, int e, int f) {}" > foo/foo.c
./joern-scan foo

führt alle Abfragen auf dem Beispielcode im Verzeichnis foo aus und stellt fest, dass die Funktion foo zu viele Parameter hat.

Eigene Abfragen hinzufügen

Bitte befolgen Sie die folgenden Regeln für eine tränenfreie Abfragenerstellung:

• Abfragen im Paket io.joern.scanners werden zur Laufzeit automatisch erkannt. Bitte legen Sie Ihre Abfragen dort ab.
• Jede Abfrage muss mit der Annotation @q beginnen und in einem Query-Bundle platziert werden. Ein Query-Bundle ist einfach ein object, das von QueryBundle abgeleitet ist.
• Abfragen können Parameter haben, aber Sie müssen für jeden Parameter einen Standardwert angeben.
• Bitte fügen Sie Komponententests für Abfragen hinzu. Diese dienen auch als Spezifikation für das, was Ihre Abfrage tut.
• Bitte formatieren Sie den Code vor dem Senden eines PR mit sbt scalafmt Test/scalafmt

Werfen Sie einen Blick auf das Query-Bundle Metrics unter src/main/scala/io/joern/scanners/c/Metrics.scala als Beispiel:

object Metrics extends QueryBundle {

  @q
  def tooManyParameters(n: Int = 4): Query =
    Query.make(
      name = "too-many-params",
      author = Crew.fabs,
      title = s"Number of parameters larger than $n",
      description = s"This query identifies functions with more than $n formal parameters",
      score = 1.0,
      withStrRep({ cpg =>
        cpg.method.internal.filter(_.parameter.size > n)
      }),
      tags = List(QueryTags.metrics)
    )

  @q
  def tooHighComplexity(n: Int = 4): Query =
    Query.make(
      name = "too-high-complexity",
      author = Crew.fabs,
      title = s"Cyclomatic complexity higher than $n",
      description = s"This query identifies functions with a cyclomatic complexity higher than $n",
      score = 1.0,
      withStrRep({ cpg =>
        cpg.method.internal.filter(_.controlStructure.size > n)
      }),
      tags = List(QueryTags.metrics)
    )
  ...
}

Die entsprechenden Tests für Abfragen befinden sich in src/test/scala/io/joern/scanners. Zum Beispiel befinden sich Tests für die Metrikabfragen in src/test/scala/io/joern/scanners/c/MetricsTests.scala:

class MetricsTests extends Suite {

  override val code = """
    int too_many_params(int a, int b, int c, int d, int e) {
    }
	...
	"""

  "find functions with too many parameters" in {
    Metrics.tooManyParameters(4)(cpg).map(_.evidence) match {
      case List(List(method: nodes.Method)) =>
        method.name shouldBe "too_many_params"
      case _ => fail
    }
  }
  ...
}

Diese Tests können während der Abfrageentwicklung einzeln aus der IntelliJ IDE ausgeführt werden.

Erstellen/Testen der Datenbank

Wir verwenden das Scala Build Tool (sbt). Bitte stellen Sie sicher, dass sbt installiert ist. Die Version spielt keine Rolle, da sbt die erforderliche Version basierend auf der Build-Datei (build.sbt) abruft.

Sobald sbt installiert ist, können Sie die Datenbank wie folgt erstellen und testen:

sbt test

Sie können neu entwickelte Abfragen testen

Wenn Sie neu erstellte Abfragen mit joern-scan wie folgt testen möchten:

sbt joerncli/stage
./querydb-install.sh && ./joern-scan <src>

Exportieren der Datenbank nach JSON

Nach dem Ausführen von install.sh können Sie

./joern-scan --dump

starten, um eine Datei namens querydb.json zu erstellen, die die Liste aller verfügbaren Abfragen zusammen mit ihren Metainformationen enthält.