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
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)
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:
ShiftLeft automatically creates the
.shiftleft/ocular directory, which is where Ocular is installed.
Once you've downloaded Ocular, run
sl ocular again to start the program.
When Ocular is ready, you'll see:
██████╗ ██████╗██╗ ██╗██╗ █████╗ ██████╗██╔═══██╗██╔════╝██║ ██║██║ ██╔══██╗██╔══██╗██║ ██║██║ ██║ ██║██║ ███████║██████╔╝██║ ██║██║ ██║ ██║██║ ██╔══██║██╔══██╗╚██████╔╝╚██████╗╚██████╔╝███████╗██║ ██║██║ ██║╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝Version: 0.3.96Commands:loadCpg("name-of-input-file", ["overlay-name", ...])Welcome to ShiftLeft Ocular/Joernocular>
Once you've started Ocular, you can create a CPG for your application by running
<inputPath> is the path to the application for which you want a CPG created.
You can run the
workspace command to see all of your CPGs (note that overlays simple refers to the layers of your CPG):
workspaceres0: Workspace =_________________________________________________________________| name | overlays | loaded||================================================================|| hello-shiftleft-0.0.1.jar| semanticcpg,dataflow,tagging| false |
Loading a CPG into memory makes it the active CPG and therefore to CPG against which your operations are executed. To do so, run:
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.