Database delle query di Joern ("Joern-Scan")

Questo è il database centrale delle query per la piattaforma di analisi del codice open-source Joern. Ha due scopi:

• Fornisce le batterie necessarie per trasformare Joern in uno strumento di scansione del codice pronto all'uso.
• Le sue query servono come esempi utili per chi desidera scrivere le proprie query.
• costruito su JDK11 ma funziona su JRE >= 1.8

Il database delle query è distribuito come libreria autonoma che include Joern come dipendenza. Ciò significa che non è necessario installare Joern per utilizzare le query nel database.

Allo stesso tempo, il database è un'estensione di Joern, ovvero, quando caricato dinamicamente all'avvio, la sua funzionalità diventa disponibile nella shell interattiva di Joern e negli script di Joern.

Puoi fare un fork di questo progetto per creare le tue query e scanner personalizzati o inviare gentilmente una PR a questo repository per farle considerare per l'inclusione nella distribuzione predefinita.

Installazione ed esecuzione

Lo script di installazione scarica Joern e lo installa in una sottodirectory. Il database delle query viene installato come estensione.

./install.sh

Puoi eseguire tutte le query come segue:

./joern-scan path/to/code

Ad esempio,

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

esegue tutte le query sul codice di esempio nella directory foo, determinando che la funzione foo ha troppi parametri.

Aggiungere le tue query

Si prega di seguire le regole seguenti per un'esperienza di scrittura query senza problemi:

• Le query nel pacchetto io.joern.scanners vengono rilevate automaticamente a runtime, quindi si prega di inserire lì le tue query.
• Ogni query deve iniziare con l'annotazione @q e deve essere inserita in un bundle di query. Un bundle di query è semplicemente un object che deriva da QueryBundle.
• Le query possono avere parametri, ma devi fornire un valore predefinito per ciascun parametro.
• Si prega di aggiungere test unitari per le query. Questi fungono anche da specifica di ciò che la tua query fa.
• Si prega di formattare il codice prima di inviare una PR usando sbt scalafmt Test/scalafmt.

Dai un'occhiata al bundle di query Metrics in src/main/scala/io/joern/scanners/c/Metrics.scala come esempio:

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)
    )
  ...
}

I test corrispondenti per le query si trovano in src/test/scala/io/joern/scanners. Ad esempio, i test per le query sulle metriche si trovano 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
    }
  }
  ...
}

Questi test possono essere eseguiti singolarmente dall'IDE IntelliJ durante lo sviluppo delle query.

Compilazione/Test del database

Utilizziamo lo Scala Build Tool (sbt). Assicurati di avere sbt installato. La versione non ha importanza in quanto sbt recupererà la versione richiesta in base al file di build (build.sbt).

Una volta installato sbt, puoi compilare e testare il database come segue:

sbt test

Puoi testare le query appena sviluppate

Se vuoi testare le query appena create con joern-scan come segue:

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

Esportazione del database in JSON

Dopo aver eseguito install.sh, puoi avviare

./joern-scan --dump

per creare un file chiamato querydb.json che contiene l'elenco di tutte le query disponibili insieme alle relative informazioni meta.