Base de données de requêtes Joern ("Joern-Scan")

Ceci est la base de données centrale de requêtes pour la plateforme d'analyse de code open source Joern. Elle a deux objectifs :

• Elle fournit les batteries nécessaires pour transformer Joern en un outil de scan de code prêt à l'emploi.
• Ses requêtes servent d'exemples utiles à ceux qui souhaitent écrire leurs propres requêtes.
• construit sur JDK11 mais s'exécute sur JRE >= 1.8

La base de données de requêtes est distribuée comme une bibliothèque autonome qui inclut Joern comme dépendance. Cela signifie qu'il n'est pas nécessaire d'installer Joern pour utiliser les requêtes de la base de données.

En même temps, la base de données est une extension de Joern, c'est-à-dire que lorsqu'elle est chargée dynamiquement au démarrage, ses fonctionnalités deviennent disponibles sur le shell interactif de Joern et dans les scripts Joern.

Vous pouvez forker ce projet pour construire vos propres requêtes et scanners personnalisés, ou envoyer gentiment une PR à ce dépôt pour qu'elles soient considérées pour inclusion dans la distribution par défaut.

Installation et exécution

Le script d'installation télécharge joern et l'installe dans un sous-répertoire. La base de données de requêtes est installée en tant qu'extension.

./install.sh

Vous pouvez exécuter toutes les requêtes comme suit :

./joern-scan path/to/code

Par exemple,

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

exécute toutes les requêtes sur l'exemple de code dans le répertoire foo, déterminant que la fonction foo a trop de paramètres.

Ajouter vos propres requêtes

Veuillez suivre les règles ci-dessous pour une expérience d'écriture de requêtes sans larmes :

• Les requêtes dans le package io.joern.scanners sont détectées automatiquement à l'exécution, veuillez donc y placer vos requêtes.
• Chaque requête doit commencer par l'annotation @q et doit être placée dans un bundle de requêtes. Un bundle de requêtes est simplement un object qui dérive de QueryBundle.
• Les requêtes peuvent avoir des paramètres, mais vous devez fournir une valeur par défaut pour chaque paramètre.
• Veuillez ajouter des tests unitaires pour les requêtes. Ceux-ci servent également de spécification pour ce que fait votre requête.
• Veuillez formater le code avant d'envoyer une PR en utilisant sbt scalafmt Test/scalafmt.

Jetez un œil au bundle de requêtes Metrics dans src/main/scala/io/joern/scanners/c/Metrics.scala comme exemple :

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

Les tests correspondants pour les requêtes se trouvent dans src/test/scala/io/joern/scanners. Par exemple, les tests pour les requêtes de métriques se trouvent dans 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
    }
  }
  ...
}

Ces tests peuvent être exécutés individuellement depuis l'IDE IntelliJ pendant le développement des requêtes.

Construction/Test de la base de données

Nous utilisons l'outil de construction Scala (sbt). Assurez-vous d'avoir sbt installé. La version n'a pas d'importance car sbt récupérera la version requise en fonction du fichier de construction (build.sbt).

Une fois sbt installé, vous pouvez construire et tester la base de données comme suit :

sbt test

Vous pouvez tester les requêtes nouvellement développées

Si vous voulez tester les requêtes nouvellement créées avec joern-scan comme suit :

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

Exportation de la base de données en JSON

Après avoir exécuté install.sh, vous pouvez lancer

./joern-scan --dump

pour créer un fichier nommé querydb.json qui contient la liste de toutes les requêtes disponibles ainsi que leurs méta-informations.