[lua2cpg] Add Lua 5.1 bytecode analysis frontend

.gitignore

@@ -102,3 +102,4 @@ flake.lock
 ##############
 user.bazelrc
 bazel-*
+/joern-cli/frontends/lua2cpg/src/test/resources/openwrt-derived-firmware-lua-report/

build.sbt

@@ -25,6 +25,7 @@ lazy val swiftsrc2cpg      = Projects.swiftsrc2cpg
 lazy val csharpsrc2cpg     = Projects.csharpsrc2cpg
 lazy val abap2cpg          = Projects.abap2cpg
 lazy val rust2cpg          = Projects.rust2cpg
+lazy val lua2cpg           = Projects.lua2cpg
 lazy val linterRules       = Projects.linterRules
 
 lazy val root = project
@@ -51,6 +52,7 @@ lazy val root = project
     csharpsrc2cpg,
     abap2cpg,
     rust2cpg,
+    lua2cpg,
     linterRules
   )
   .dependsOn(linterRules % ScalafixConfig)

joern-cli/build.sbt

@@ -48,6 +48,7 @@ lazy val rubysrc2cpg   = project.in(file("frontends/rubysrc2cpg"))
 lazy val gosrc2cpg     = project.in(file("frontends/gosrc2cpg"))
 lazy val csharpsrc2cpg = project.in(file("frontends/csharpsrc2cpg"))
 lazy val rust2cpg      = project.in(file("frontends/rust2cpg"))
+lazy val lua2cpg       = project.in(file("frontends/lua2cpg"))
 
 Universal / mappings ++= frontendMappings("kotlin2cpg", (kotlin2cpg / stage).value)
 Universal / mappings ++= frontendMappings("abap2cpg", (abap2cpg / stage).value)
@@ -63,6 +64,7 @@ Universal / mappings ++= frontendMappings("rubysrc2cpg", (rubysrc2cpg / stage).v
 Universal / mappings ++= frontendMappings("gosrc2cpg", (gosrc2cpg / stage).value)
 Universal / mappings ++= frontendMappings("csharpsrc2cpg", (csharpsrc2cpg / stage).value)
 Universal / mappings ++= frontendMappings("rust2cpg", (rust2cpg / stage).value)
+Universal / mappings ++= frontendMappings("lua2cpg", (lua2cpg / stage).value)
 
 lazy val cpgVersionFile = taskKey[File]("persist cpg version in file (e.g. for schema-extender)")
 cpgVersionFile := {

joern-cli/frontends/lua2cpg/README.md

@@ -0,0 +1,218 @@
+# lua2cpg
+
+`lua2cpg` is a Lua 5.1 analyzer for Joern. It builds Code Property
+Graphs for Lua programs through a bytecode-based pipeline and emits
+taint-analysis evidence for Lua code, including interprocedural flow,
+source/sink matches, sanitizer classifications, and vulnerability reports.
+
+The analysis core operates on Lua 5.1 bytecode. To analyze Lua source files,
+compile them with `luac5.1` and pass the generated `.luac` files to
+`lua2cpg`. Source files placed in the input tree are also recorded in the CPG
+file inventory.
+
+## Prerequisites
+
+- Use JDK 21 and `sbt` 1.12.5, matching the Joern repository configuration.
+- Run the commands below from the Joern repository root.
+- Install `luac5.1` when starting from Lua source files.
+
+## Build
+
+Build the staged frontend command:
+
+```bash
+sbt 'lua2cpg/stage'
+```
+
+The staged command is written to:
+
+```bash
+joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg
+```
+
+Check the available options:
+
+```bash
+joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg --help
+```
+
+## Quickstart
+
+Analyze an existing Lua 5.1 bytecode directory:
+
+```bash
+LUA2CPG=joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg
+INPUT=/path/to/lua-bytecode
+OUTPUT=/tmp/lua.cpg.bin
+
+"$LUA2CPG" "$INPUT" --output "$OUTPUT"
+```
+
+Analyze a Lua source file by compiling it to Lua 5.1 bytecode first:
+
+```bash
+mkdir -p /tmp/lua-bytecode
+luac5.1 -o /tmp/lua-bytecode/app.luac /path/to/app.lua
+
+joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg \
+  /tmp/lua-bytecode \
+  --output /tmp/lua.cpg.bin
+```
+
+For a source tree, preserve the directory layout while compiling:
+
+```bash
+SRC_ROOT=/path/to/lua-source
+BC_ROOT=/tmp/lua-bytecode
+
+mkdir -p "$BC_ROOT"
+find "$SRC_ROOT" -name '*.lua' -print0 |
+  while IFS= read -r -d '' file; do
+    rel="${file#$SRC_ROOT/}"
+    out="$BC_ROOT/${rel%.lua}.luac"
+    mkdir -p "$(dirname "$out")"
+    luac5.1 -o "$out" "$file"
+  done
+
+joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg \
+  "$BC_ROOT" \
+  --output /tmp/lua.cpg.bin
+```
+
+## Inspecting The CPG
+
+Open the generated CPG with Joern and inspect the Lua-specific evidence:
+
+```bash
+joern /tmp/lua.cpg.bin
+```
+
+Useful traversals:
+
+```scala
+cpg.metaData.language.l
+cpg.file.name.l
+cpg.method.fullName.l
+cpg.call.nameExact("lua.module.resolution").code.l
+cpg.call.nameExact("lua.calltarget.candidate").code.l
+cpg.call.nameExact("lua.source.endpoint").code.l
+cpg.call.nameExact("lua.sink.endpoint").code.l
+cpg.call.nameExact("lua.sanitizer.classification").code.l
+cpg.call.nameExact("lua.report.vulnerability").code.l
+```
+
+## Taint Evidence Export
+
+`lua2cpg` can also write reviewer-visible JSON evidence for benchmark and
+debugging workflows:
+
+```bash
+joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg \
+  /path/to/lua-bytecode \
+  --output /tmp/lua.cpg.bin \
+  --lua-real-firmware-output-dir /tmp/lua2cpg-evidence
+```
+
+The evidence directory contains:
+
+- `decoder-summary.json`: input, decode, prototype, instruction, callsite, and
+  local-flow totals.
+- `path-search-profile.json`: taint path-search counters and retained pair
+  profiles.
+- `run-summary.json`: native run status and decode totals.
+- `run-errors.json`: native run errors.
+- `staging/*.json`: per-artifact decode, flow, module-resolution, source/sink,
+  sanitizer, and path-evidence rows.
+
+This export is optional. The primary `lua2cpg` output is the CPG written by
+`--output`.
+
+## Self-Contained Reviewer Corpus
+
+The test resources include a self-contained OpenWrt-derived Lua corpus for
+review and regression checks:
+
+```text
+joern-cli/frontends/lua2cpg/src/test/resources/openwrt-derived-firmware-lua/usr/lib/lua
+```
+
+The corpus preserves the original `usr/lib/lua` layout and contains:
+
+- 42 `.lua` source files recorded in the CPG file inventory.
+- 42 Lua 5.1 `.luac` bytecode files analyzed by the bytecode pipeline.
+
+To generate a native JSON analysis report from the Joern repository root:
+
+```bash
+joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg \
+  joern-cli/frontends/lua2cpg/src/test/resources/openwrt-derived-firmware-lua/usr/lib/lua \
+  --output /tmp/openwrt-derived-firmware-lua.cpg.bin \
+  --lua-real-firmware-output-dir /tmp/openwrt-derived-firmware-lua-report
+```
+
+The generated report and CPG are reproducible outputs and are intentionally not
+tracked by Git. A successful corpus run decodes all 42 bytecode inputs with no
+diagnostics and emits 164 source endpoints, 94 sink endpoints, 20 taint paths,
+and 20 reports.
+
+## Supported Analysis
+
+- Lua version: Lua 5.1.
+- Inputs: Lua 5.1 `.luac` bytecode; Lua source after compilation with
+  `luac5.1`.
+- CPG content: file inventory, bytecode artifacts, prototypes, constants,
+  instructions, methods, identifiers, calls, and reaching definitions.
+- Program analysis: intraprocedural value flow, module require/return-table
+  linkage, cross-module call targets, interprocedural argument and return flow,
+  source/sink matching, sanitizer classification, and vulnerability reports.
+- Distribution boundary: this frontend does not ship QueryDB queries as part
+  of this README. Reviewer-visible results are exposed through CPG nodes and
+  optional JSON evidence.
+
+## Architecture
+
+The frontend is organized around a bytecode-first analysis pipeline:
+
+- `LuaFileInventoryPass` records `.lua` source files in the CPG file inventory.
+- `LuaBytecodeDecoder` decodes Lua 5.1 bytecode artifacts into profiles,
+  prototypes, constants, instructions, and diagnostics.
+- `LuaBytecodeModelPass` emits the decoded bytecode model into the CPG.
+- `LuaInstructionSemantics` computes prototype-local value, call, table,
+  global, upvalue, and boundary facts.
+- `LuaProgramSemantics` normalizes module-level and interprocedural flow,
+  source/sink, sanitizer, and report evidence across decoded artifacts.
+- `LuaRealFirmwareEvidenceExporter` writes the optional JSON evidence directory
+  requested by `--lua-real-firmware-output-dir`.
+
+## Tests
+
+Use the smallest tier that answers the review question first.
+
+Quick smoke:
+
+```bash
+sbt 'lua2cpg/testOnly io.joern.lua2cpg.RulesSanitizerReportSmokeTest'
+sbt 'lua2cpg/stage'
+joern-cli/frontends/lua2cpg/target/universal/stage/bin/lua2cpg --help
+git status --short
+```
+
+Focused capability tests:
+
+```bash
+sbt 'lua2cpg/testOnly io.joern.lua2cpg.BytecodeModelSmokeTest'
+sbt 'lua2cpg/testOnly io.joern.lua2cpg.IntraproceduralSemanticsSmokeTest'
+sbt 'lua2cpg/testOnly io.joern.lua2cpg.InterproceduralModuleTaintSmokeTest'
+sbt 'lua2cpg/testOnly io.joern.lua2cpg.RulesSanitizerReportSmokeTest'
+sbt 'lua2cpg/testOnly io.joern.lua2cpg.OpenWrtDerivedFirmwareCorpusSmokeTest'
+sbt 'lua2cpg/testOnly io.joern.lua2cpg.RealFirmwareEvidenceExportSmokeTest'
+```
+
+Full frontend test suite:
+
+```bash
+sbt 'lua2cpg/test'
+```
+
+The full suite covers the decoder, CPG modeling, program semantics, evidence
+export, and self-contained corpus regression tests.

joern-cli/frontends/lua2cpg/build.sbt

@@ -0,0 +1,13 @@
+name := "lua2cpg"
+
+dependsOn(
+  Projects.x2cpg        % "compile->compile;test->test",
+  Projects.linterRules  % ScalafixConfig
+)
+
+libraryDependencies ++= Seq(
+  "com.lihaoyi"   %% "ujson"     % Versions.upickle,
+  "org.scalatest" %% "scalatest" % Versions.scalatest % Test
+)
+
+enablePlugins(JavaAppPackaging, LauncherJarPlugin)

joern-cli/frontends/lua2cpg/src/main/scala/io/joern/lua2cpg/Lua2Cpg.scala

@@ -0,0 +1,26 @@
+package io.joern.lua2cpg
+
+import io.joern.lua2cpg.bytecode.{LuaProgramSemantics, LuaRealFirmwareEvidenceExporter}
+import io.joern.lua2cpg.passes.{LuaBytecodeModelPass, LuaFileInventoryPass}
+import io.joern.x2cpg.X2Cpg.withNewEmptyCpg
+import io.joern.x2cpg.X2CpgFrontend
+import io.joern.x2cpg.passes.frontend.MetaDataPass
+import io.shiftleft.codepropertygraph.generated.Cpg
+
+import scala.util.Try
+
+class Lua2Cpg extends X2CpgFrontend {
+  override type ConfigType = Config
+  override val defaultConfig: Config = Config()
+
+  override def createCpg(config: Config): Try[Cpg] = {
+    val decoded          = LuaBytecodeModelPass.decodeInputs(config)
+    val programSemantics = LuaProgramSemantics.normalize(decoded.map(item => item.relativeName -> item.result))
+    withNewEmptyCpg(config.outputPath, config) { (cpg, config) =>
+      new MetaDataPass(cpg, "LUA", config.inputPath).createAndApply()
+      new LuaFileInventoryPass(cpg, config).createAndApply()
+      new LuaBytecodeModelPass(cpg, config, Some(decoded)).createAndApply()
+      LuaRealFirmwareEvidenceExporter.write(config, decoded, programSemantics)
+    }
+  }
+}

joern-cli/frontends/lua2cpg/src/main/scala/io/joern/lua2cpg/Main.scala

@@ -0,0 +1,31 @@
+package io.joern.lua2cpg
+
+import io.joern.lua2cpg.Frontend.cmdLineParser
+import io.joern.x2cpg.{X2CpgConfig, X2CpgMain}
+import scopt.OParser
+
+final case class Config(
+  realFirmwareOutputDir: Option[String] = None,
+  override val genericConfig: X2CpgConfig.GenericConfig = X2CpgConfig.GenericConfig()
+) extends X2CpgConfig[Config] {
+  override def withGenericConfig(value: X2CpgConfig.GenericConfig): Config =
+    copy(genericConfig = value)
+
+  def withRealFirmwareOutputDir(value: String): Config =
+    copy(realFirmwareOutputDir = Some(value))
+}
+
+private object Frontend {
+  val cmdLineParser: OParser[Unit, Config] = {
+    val builder = OParser.builder[Config]
+    import builder.*
+    OParser.sequence(
+      programName("lua2cpg"),
+      opt[String]("lua-real-firmware-output-dir")
+        .text("write Lua real-firmware benchmark evidence JSON to the given directory")
+        .action((value, config) => config.withRealFirmwareOutputDir(value))
+    )
+  }
+}
+
+object Main extends X2CpgMain(new Lua2Cpg(), cmdLineParser)