قاعدة بيانات استعلامات Joern ("Joern-Scan")

هذه هي قاعدة بيانات الاستعلامات المركزية لمنصة تحليل الكود مفتوحة المصدر Joern. لها غرضان:

• توفير البطاريات اللازمة لتحويل Joern إلى أداة مسح كود جاهزة للاستخدام.
• تعمل استعلاماتها كأمثلة مفيدة لمن يرغبون في كتابة استعلاماتهم الخاصة.
• مبنية على JDK11 ولكنها تعمل على JRE >= 1.8

يتم توزيع قاعدة بيانات الاستعلامات كمكتبة مستقلة تتضمن Joern كاعتمادية. وهذا يعني أنه ليس من الضروري تثبيت Joern للاستفادة من الاستعلامات في قاعدة البيانات.

في الوقت نفسه، قاعدة البيانات هي امتداد لـ Joern، أي أنه عند تحميلها ديناميكيًا عند بدء التشغيل، تصبح وظائفها متاحة على شل Joern التفاعلية وفي نصوص Joern.

يمكنك عمل fork لهذا المشروع لبناء استعلامات وماسحات ضوئية مخصصة لك، أو إرسال PR بأدب إلى هذا المستودع لدراسة إدراجها في التوزيعة الافتراضية.

التثبيت والتشغيل

يقوم نص التثبيت بتحميل 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 (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 يحتوي على قائمة بجميع الاستعلامات المتاحة بالإضافة إلى معلوماتها الوصفية.