Base de Dados de Consultas Joern ("Joern-Scan")

Esta é a base de dados central de consultas para a plataforma de análise de código aberto Joern. Ela tem dois objetivos:

• Fornece as baterias necessárias para transformar o Joern numa ferramenta de verificação de código pronta para uso.
• Suas consultas servem como exemplos úteis para quem deseja escrever as suas próprias consultas.
• construído no JDK11 mas executa em JRE >= 1.8

A base de dados de consultas é distribuída como uma biblioteca independente que inclui o Joern como dependência. Isso significa que não é necessário instalar o Joern para utilizar as consultas da base de dados.

Ao mesmo tempo, a base de dados é uma extensão do Joern, ou seja, quando carregada dinamicamente na inicialização, sua funcionalidade fica disponível no shell interativo do Joern e em scripts Joern.

Você pode bifurcar este projeto para criar suas próprias consultas e scanners personalizados ou enviar um PR para este repositório para que sejam considerados para inclusão na distribuição padrão.

Instalação e execução

O script de instalação faz download do joern e o instala num subdiretório. A base de dados de consultas é instalada como uma extensão.

./install.sh

Pode executar todas as consultas da seguinte forma:

./joern-scan path/to/code

Por exemplo,

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

executa todas as consultas no código de exemplo no diretório foo, determinando que a função foo tem demasiados parâmetros.

Adicionar as suas próprias consultas

Siga as regras abaixo para uma experiência de escrita de consultas sem sobressaltos:

• As consultas no pacote io.joern.scanners são detectadas automaticamente em tempo de execução, por favor coloque as suas consultas lá.
• Cada consulta deve começar com a anotação @q e ser colocada num pacote de consultas. Um pacote de consultas é simplesmente um object que deriva de QueryBundle
• As consultas podem ter parâmetros, mas deve fornecer um valor predefinido para cada parâmetro
• Adicione testes unitários para as consultas. Estes também servem como especificação do que a sua consulta faz.
• Formate o código antes de enviar um PR usando sbt scalafmt Test/scalafmt

Veja o pacote de consultas Metrics em src/main/scala/io/joern/scanners/c/Metrics.scala como exemplo:

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

Os testes correspondentes para as consultas estão localizados em src/test/scala/io/joern/scanners. Por exemplo, os testes para as consultas de métricas estão em 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
    }
  }
  ...
}

Estes testes podem ser executados individualmente a partir do IntelliJ IDE durante o desenvolvimento de consultas.

Compilação/Teste da base de dados

Usamos a Scala Build Tool (sbt). Certifique-se de ter o sbt instalado. A versão não importa, pois o sbt irá buscar a versão necessária com base no ficheiro de compilação (build.sbt).

Uma vez instalado o sbt, pode compilar e testar a base de dados da seguinte forma:

sbt test

Pode testar consultas recentemente desenvolvidas

Se quiser testar consultas recém-criadas com joern-scan da seguinte forma:

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

Exportar a base de dados para JSON

Depois de executar install.sh, pode lançar

./joern-scan --dump

para criar um ficheiro chamado querydb.json que contém a lista de todas as consultas disponíveis juntamente com as suas meta-informações.