Base de datos de consultas de Joern ("Joern-Scan")

Esta es la base de datos central de consultas para la plataforma de análisis de código abierto Joern. Tiene dos propósitos:

• Proporciona las baterías necesarias para convertir Joern en una herramienta de escaneo de código lista para usar.
• Sus consultas sirven como ejemplos útiles para aquellos que buscan escribir sus propias consultas.
• construido sobre JDK11 pero se ejecuta en JRE >= 1.8

La base de datos de consultas se distribuye como una biblioteca independiente que incluye Joern como dependencia. Esto significa que no es necesario instalar Joern para hacer uso de las consultas en la base de datos.

Al mismo tiempo, la base de datos es una extensión de Joern, es decir, cuando se carga dinámicamente al iniciar, su funcionalidad está disponible en el shell interactivo de Joern y en los scripts de Joern.

Puedes bifurcar (fork) este proyecto para construir tus propias consultas y escáneres personalizados o enviar amablemente un PR a este repositorio para que sean considerados para su inclusión en la distribución predeterminada.

Instalación y ejecución

El script de instalación descarga joern y lo instala en un subdirectorio. La base de datos de consultas se instala como una extensión.

./install.sh

Puedes ejecutar todas las consultas de la siguiente manera:

./joern-scan path/to/code

Por ejemplo,

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

ejecuta todas las consultas en el código de muestra en el directorio foo, determinando que la función foo tiene demasiados parámetros.

Añadir tus propias consultas

Por favor, sigue las reglas a continuación para una experiencia de escritura de consultas sin contratiempos:

• Las consultas en el paquete io.joern.scanners se recogen automáticamente en tiempo de ejecución, así que por favor coloca tus consultas allí.
• Cada consulta debe comenzar con la anotación @q y debe colocarse en un paquete de consultas. Un paquete de consultas es simplemente un object que deriva de QueryBundle
• Las consultas pueden tener parámetros, pero debes proporcionar un valor predeterminado para cada parámetro
• Por favor, añade pruebas unitarias para las consultas. Estas también sirven como especificación de lo que hace tu consulta.
• Por favor, formatea el código antes de enviar un PR usando sbt scalafmt Test/scalafmt

Echa un vistazo al paquete de consultas Metrics en src/main/scala/io/joern/scanners/c/Metrics.scala como ejemplo:

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

Las pruebas correspondientes para las consultas se encuentran en src/test/scala/io/joern/scanners. Por ejemplo, las pruebas para las consultas de métricas se encuentran en 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
    }
  }
  ...
}

Estas pruebas se pueden ejecutar individualmente desde el IDE IntelliJ durante el desarrollo de consultas.

Construir/Probar la base de datos

Usamos Scala Build Tool (sbt). Asegúrate de tener sbt instalado. La versión no importa, ya que sbt obtendrá la versión requerida según el archivo de construcción (build.sbt).

Una vez que sbt esté instalado, puedes construir y probar la base de datos de la siguiente manera:

sbt test

Puedes probar las consultas recién desarrolladas

Si quieres probar las consultas recién creadas con joern-scan de la siguiente manera:

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

Exportar la base de datos a JSON

Después de ejecutar install.sh, puedes lanzar

./joern-scan --dump

para crear un archivo llamado querydb.json que contiene la lista de todas las consultas disponibles junto con su metainformación.