База запросов Joern ("Joern-Scan")

Это центральная база запросов для платформы анализа открытого исходного кода Joern. Она имеет две цели:

• Она предоставляет необходимые компоненты для превращения Joern в готовый к использованию инструмент сканирования кода.
• Её запросы служат примерами, полезными для тех, кто хочет писать собственные запросы.
• собрано на JDK11, но работает на JRE >= 1.8

База запросов распространяется как отдельная библиотека, включающая Joern в качестве зависимости. Это означает, что для использования запросов из базы не требуется устанавливать Joern.

В то же время база данных является расширением Joern, то есть при динамической загрузке во время запуска её функциональность становится доступной в интерактивной оболочке Joern и в скриптах Joern.

Вы можете форкнуть этот проект, чтобы создать собственные запросы и сканеры, или отправить пул-реквест в этот репозиторий, чтобы они были рассмотрены для включения в стандартную поставку.

Установка и запуск

Скрипт установки загружает joern и устанавливает его в поддиректорию. База запросов устанавливается как расширение.

./install.sh

Вы можете запустить все запросы следующим образом:

./joern-scan path/to/code

Например,

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

запускает все запросы на образце кода в директории foo, определяя, что функция foo имеет слишком много параметров.

Добавление собственных запросов

Пожалуйста, следуйте приведённым ниже правилам для безболезненного написания запросов:

• Запросы в пакете io.joern.scanners автоматически обнаруживаются во время выполнения, поэтому помещайте туда свои запросы.
• Каждый запрос должен начинаться с аннотации @q и должен быть помещён в набор запросов (query bundle). Набор запросов — это просто object, наследующий от QueryBundle.
• Запросы могут иметь параметры, но для каждого параметра необходимо указать значение по умолчанию.
• Пожалуйста, добавляйте модульные тесты для запросов. Они также служат спецификацией того, что делает ваш запрос.
• Пожалуйста, форматируйте код перед отправкой PR с помощью sbt scalafmt Test/scalafmt

Взгляните на набор запросов Metrics в файле src/main/scala/io/joern/scanners/c/Metrics.scala в качестве примера:

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

Соответствующие тесты для запросов находятся в src/test/scala/io/joern/scanners. Например, тесты для запросов метрик находятся в 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
    }
  }
  ...
}

Эти тесты можно запускать по отдельности из IntelliJ IDE во время разработки запросов.

Сборка/Тестирование базы данных

Мы используем Scala Build Tool (sbt). Убедитесь, что sbt установлен. Версия не имеет значения, так как sbt загрузит необходимую версию на основе файла сборки (build.sbt).

После установки sbt вы можете собрать и протестировать базу данных следующим образом:

sbt test

Вы можете тестировать недавно разработанные запросы

Если вы хотите протестировать недавно созданные запросы с помощью joern-scan, сделайте следующее:

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

Экспорт базы данных в JSON

После запуска install.sh вы можете выполнить

./joern-scan --dump

чтобы создать файл с именем querydb.json, содержащий список всех доступных запросов вместе с их метаинформацией.