Top-Level Commands

Command	Description
help	Interactive help
workspace	Access to the workspace directory
importCode	Create new project from code
importCpg	Create new project from existing CPG
cpg	CPG of the active project
project	Currently active project
open	Open project
close	Close project by name
delete	Close and remove project from disk
reloadPolicy	reload policy
run	Run analyzer on active CPG
save	Write all changes to disk
undo	Undo effects of analyzer
config	The Ocular configuration object
version	Prints the version of Ocular
banner	Prints the Ocular banner

help

• Interactive help

ocular> help 
res33: Helper = Welcome to the interactive help system. Below you find a table of all available
top-level commands. To get more detailed help on a specific command, just type

`help.<command>`.

Try `help.importCode` to begin with.
_______________________________________________________________________________
 command     | description                         | example                  |
==============================================================================|
 close       | Close project by name               | close(projectName)       |
 cpg         | CPG of the active project           | cpg.method.l             |
 delete      | Close and remove project from disk  | delete(projectName)      |
 importCode  | Create new project from code        | importCode("example.jar")|
 importCpg   | Create new project from existing CPG| importCpg("cpg.bin.zip") |
 open        | Open project                        | open("projectName")      |
 project     | Currently active project            | project                  |
 reloadPolicy| reload policy                       | reloadPolicy             |
 run         | Run analyzer on active CPG          | run.securityprofile      |
 save        | Write all changes to disk           | save                     |
 undo        | undo effects of analyzer            | undo                     |
 workspace   | Access to the workspace directory   | workspace                |

workspace

The Workspace object - see Organizing Projects

• List available projects in workspace and see which one is open

ocular> workspace 
res0: io.shiftleft.console.workspacehandling.WorkspaceManager[io.shiftleft.repl.OcularProject] = 
_______________________________________________________________________________
| name    | overlays                    | inputPath                      | open|
|==============================================================================|
| x42-c   | semanticcpg,dataflow,tagging| /home/user/x42/c           | true|
| x42-java| semanticcpg,dataflow,tagging| /home/user/x42/java/X42.jar| true|

• Reset workspace and delete all projects and CPGs

// warning, highly destructive action
ocular> workspace.reset

importCode

Create code property graph from code and create a new project in the workspace for it.

• List available language frontends

ocular> importCode
______________________________________________________
| name      | description                  | available|
|=====================================================|
| c         | Fuzzy Parser for C/C++       | true     |
| csharp    | C# Source Frontend (Roslyn)  | false    |
| golang    | Golang Source Frontend       | false    |
| java      | Java/Dalvik Bytecode Frontend| false    |
| javascript| Javascript Source Frontend   | false    |
| llvm      | LLVM Bitcode Frontend        | false    |

• Import code - guessing programming language

ocular> importCode("/path/to/vlc-3.0.8")

• Import code using a specific language frontend

ocular> importCode.c("/path/to/vlc-3.0.8")
ocular> importCode.java("/path/to/a.jar")
...

• Import code from string

ocular> importCode.c.fromString("int main() { return 0; } ")

importCpg

• Import Code Property Graph for analysis

ocular> importCpg("/path/to/cpg.bin.zip")

cpg

• Cpg of the active project

ocular> cpg

project

• Currently active project

ocular> project

open

• Open project by name

ocular> open("project-name")

close

• Close project by name

ocular> close("project-name")

save

• Write all changes to disk

ocular> save

delete

• Close project and remove it from disk

ocular> delete("x42-java") 
res26: Option[Unit] = Some(())

run

• List available layer creators that can be run to enhance the graph. The command run.$name executes the layer creator named $name. run($query) runs the $query as a custom layer creator, e.g., run(cpg.method.newTagNode("foo")) applies the tag "foo" to all methods.

ocular> run 

________________________________________________________________________
| name           | description                                          |
|=======================================================================|
| semanticcpg    | linked code property graph                           |
| securityprofile| vulnerability analysis performed by Qwiet preZero|
| dataflow       | graph enhancements required for data flow engine     |
| tagging        | applies tags based on policy                         |

undo

• Undo effects of analyzer

ocular> undo 
res2: better.files.File = /home/user/.shiftleft/ocular/workspace/x42-java/overlays/tagging

ocular> undo 
res3: better.files.File = /home/user/.shiftleft/ocular/workspace/x42-java/overlays/dataflow

regenerateCacheOnNextLoad

Applies to Ocular only

• create new policy cache on next load/import
• use e.g. if you edited the policy text files - on first usage they are being converted to an efficient binary format, which is being cached

ocular> regenerateCacheOnNextLoad 

reloadPolicy

Applies to Ocular only

• Reload policies

ocular> reloadPolicy 
Loading dynamic policies from /home/user/.shiftleft/ocular/policy/dynamic/jvm
Loading static policies from /home/user/.shiftleft/ocular/policy/static

config

• Print the Ocular installation path

ocular> config.install.rootPath 
res0: better.files.File = /home/user/.shiftleft/ocular

version

• Print the Ocular version

ocular> version 
res0: String = "0.3.114"

banner

• Print the 1337 Ocular banner

ocular> banner 

 ██████╗  ██████╗██╗   ██╗██╗      █████╗ ██████╗
██╔═══██╗██╔════╝██║   ██║██║     ██╔══██╗██╔══██╗
██║   ██║██║     ██║   ██║██║     ███████║██████╔╝
██║   ██║██║     ██║   ██║██║     ██╔══██║██╔══██╗
╚██████╔╝╚██████╗╚██████╔╝███████╗██║  ██║██║  ██║
 ╚═════╝  ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝ 
Version: 0.3.114
Type `help` or `browse(help)` to begin