Interactive and Non-Interactive Modes

ShiftLeft Ocular lets you perform code analysis on CPGs and Security Profiles, both interactively using a REPL or with non-interactive scripts.

Using a REPL

A REPL is an interactive shell with support for the Ocular Query Language (OQL). Among other features, a REPL offers utilities for exporting security analysis results as plain text or in JSON format, readline support and tab-completion (included in the ShiftLeft Ocular trial version).

The ShiftLeft Ocular underlying shell is an interactive Scala shell which includes useful things like:

  • \<TAB> for autocomplete.

  • \<UP> and for moving through the command history.

  • \<CTRL-r> to search the command history.

  • helpMsg and status.

Using Non-Interactive Scripts

ShiftLeft Ocular can be used in non-interactive mode, to execute commands and operations without typing them after the prompt. The commands are stored in a file which can be specified as an argument. ShiftLeft Ocular runs those commands and then exits. For example, include in

@main def exec(cpgFile: String, outFile: String) = {
loadCpg(cpgFile) |> outFile

You can include arbitrary Scala code in and use the |> operator to pipe output into files. The script is run as

./ --script --params cpgFile=/fullpath/to/,outFile=out.log

Importing Additional Scripts

If your script depends on code from one or more additional scripts, you can use the --import parameter, which accepts a comma-separated list of input scripts

echo 'def hello(name: String) = println(s"hello, $name")' > scripts/
echo '@main def exec(name: String) = hello(name)' > scripts/
./ --script scripts/ --params name=shiftleft --import scripts/
# prints:
# hello, shiftleft
# script finished successfully

Writing JSON and Pretty-Printed JSON

To write JSON

ocular> cpg.method.toJson |> "/tmp/foo"

To write Pretty-Printed JSON

ocular> cpg.method.toPrettyJson |> "/tmp/foo"

Appending to Files

To append to a JSON file

ocular> cpg.method.toJson ||> "/tmp/foo"

To append to a Pretty-Printed JSON file

ocular> cpg.method.toPrettyJson ||> "/tmp/foo"