crackercat / joern

Open-source code analysis platform for C/C++ based on code property graphs

Joern - The Bug Hunter's Workbench

Joern is a platform for analyzing source code, bytecode, and binary executables. It generates code property graphs (CPGs), a graph representation of code for cross-language code analysis. Code property graphs are stored in a custom graph database. This allows code to be mined using search queries formulated in a Scala-based domain-specific query language. Joern is developed with the goal of providing a useful tool for vulnerability discovery and research in static program analysis.

Website: https://joern.io

Documentation: https://docs.joern.io/

Specification: https://cpg.joern.io

News / Changelog

• Joern v2.0.0 upgrades from Scala2 to Scala3
• Joern v1.2.0 removes the overflowdb.traversal.Traversal class. This change is not completely backwards compatible. See here for a detailed writeup.

Requirements

• JDK 19 (other versions might work, but have not been properly tested)
• optional: gcc and g++ (for auto-discovery of C/C++ system header files if included/used in your C/C++ code)

Development Requirements

• mvn https://maven.apache.org/install.html

Quick Installation

wget https://github.com/joernio/joern/releases/latest/download/joern-install.sh
chmod +x ./joern-install.sh
sudo ./joern-install.sh
joern

     ██╗ ██████╗ ███████╗██████╗ ███╗   ██╗
     ██║██╔═══██╗██╔════╝██╔══██╗████╗  ██║
     ██║██║   ██║█████╗  ██████╔╝██╔██╗ ██║
██   ██║██║   ██║██╔══╝  ██╔══██╗██║╚██╗██║
╚█████╔╝╚██████╔╝███████╗██║  ██║██║ ╚████║
 ╚════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝
Version: 2.0.1
Type `help` to begin

joern>

If the installation script fails for any reason, try

./joern-install --interactive

Docker based execution

docker run --rm -it -v /tmp:/tmp -v $(pwd):/app:rw -w /app -t ghcr.io/joernio/joern joern

To run joern in server mode:

docker run --rm -it -v /tmp:/tmp -v $(pwd):/app:rw -w /app -t ghcr.io/joernio/joern joern --server

Almalinux 9 requires the CPU to support SSE4.2. For kvm64 VM use the Almalinux 8 version instead.

docker run --rm -it -v /tmp:/tmp -v $(pwd):/app:rw -w /app -t ghcr.io/joernio/joern-alma8 joern

Releases

A new release is created automatically once per day. Contributers can also manually run the release workflow if they need the release sooner.

Developers: IDE setup

Intellij IDEA

• Download Intellij Community
• Install and run it
• Install the Scala Plugin - just search and install from within Intellij
• Important: run sbt in your local joern clone and keep it open - this will allow us to use the BSP build in the next step
• Back to Intellij: open project: select your local joern clone: select to open as BSP project (i.e. not sbt project!)
• Await the import and indexing to complete, then you can start, e.g. Build -> build project or run a test

VSCode

• Install VSCode and Docker
• Install the plugin ms-vscode-remote.remote-containers
• Open Joern project folder in VSCode Visual Studio Code detects the new files and opens a message box saying: Folder contains a Dev Container configuration file. Reopen to folder to develop in a container.
• Select the Reopen in Container button to reopen the folder in the container created by the .devcontainer/Dockerfile file
• Switch to scalameta.metals sidebar in VSCode, and select import build in BUILD COMMANDS
• After import build succeeds, you are ready to start writing code for Joern

QueryDB (queries plugin)

Quick way to develop and test QueryDB:

sbt stage
./querydb-install.sh
./joern-scan --list-query-names

The last command prints all available queries - add your own in querydb, run the above commands again to see that your query got deployed. More details in the separate querydb readme

Benchmarks

Various static analysis benchmarks that measure Joern are contained under the benchmarks. The benchmarks are implemented in ScalaTest and can be run using the joern-benchmarks script. The benchmark results can be found on the benchmarks subproject's README. The currently implemented benchmarks along with the language frontends tested are:

• Securibench Micro [javasrc2cpg, jimple2cpg]
• IFSpec (paper) [javasrc2cpg, jimple2cpg]
• JInfoFlow (paper) [javasrc2cpg, jimple2cpg]

For more instructions on how to run benchmarks individually head over to the benchmarks subproject. If you would like the benchmark results to be written to a file instead of printed to STDOUT, set the path to the environment variable JOERN_BENCHMARK_RESULT_FILE.