Quickstart

This article will show you how to get started with Ocular. More specifically, you will learn how to:

  • Download, install, and start Ocular

  • Create your first CPG and load it into memory for use

Prerequisites

Before proceeding, you must:

  • Have the Java Runtime Environment v.1.8 (or later) installed on the machine on which you plan to run Ocular.

  • Have installed and authenticated with ShiftLeft. This step makes it possible for you to use the ShiftLeft command line tools (note: you do not have to run Inspect before using Ocular)

Installing Ocular

Once you have installed and authenticated with installed and authenticated with ShiftLeft, you will have access to the ShiftLeft command line tools.

To download Ocular, run:

sl ocular

ShiftLeft automatically creates the .shiftleft/ocular directory, which is where Ocular is installed.

Starting Ocular

Once you've downloaded Ocular, run sl ocular again to start the program.

When Ocular is ready, you'll see:

██████╗ ██████╗██╗ ██╗██╗ █████╗ ██████╗
██╔═══██╗██╔════╝██║ ██║██║ ██╔══██╗██╔══██╗
██║ ██║██║ ██║ ██║██║ ███████║██████╔╝
██║ ██║██║ ██║ ██║██║ ██╔══██║██╔══██╗
╚██████╔╝╚██████╗╚██████╔╝███████╗██║ ██║██║ ██║
╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝
Version: 0.3.96
Commands:
loadCpg("name-of-input-file", ["overlay-name", ...])
Welcome to ShiftLeft Ocular/Joern
ocular>

Creating Your Code Property Graph (CPG)

Once you've started Ocular, you can create a CPG for your application by running createCpg("<inputPath>") where <inputPath> is the path to the application for which you want a CPG created.

Example: createCpg("/Users/john-doe/HelloShiftLeft/target/hello-shiftleft-0.0.1.jar")

You can run the workspace command to see all of your CPGs (note that overlays simple refers to the layers of your CPG):

workspace
res0: Workspace =
_________________________________________________________________
| name | overlays | loaded|
|================================================================|
| hello-shiftleft-0.0.1.jar| semanticcpg,dataflow,tagging| false |

Loading a CPG into Memory

Loading a CPG into memory makes it the active CPG and therefore to CPG against which your operations are executed. To do so, run:

loadCpg("<nameOfCpg>")

You can load as many CPGs into your workspace as long as you have sufficient memory allocated.

At this point, you are ready to start exploring your CPG with queries.