Top-Level Commands

CommandDescription
helpInteractive help
workspaceAccess to the workspace directory
importCodeCreate new project from code
importCpgCreate new project from existing CPG
cpgCPG of the active project
projectCurrently active project
openOpen project
closeClose project by name
deleteClose and remove project from disk
reloadPolicyreload policy
runRun analyzer on active CPG
saveWrite all changes to disk
undoUndo effects of analyzer
configThe Ocular configuration object
versionPrints the version of Ocular
bannerPrints 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 ShiftLeft NG SAST|
| 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

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