ShiftLeft Ocular uses workspaces to help you manage Code Property Graphs (CPGs) and their overlays, simultaneously work with multiple CPGs, and combine queries from multiple CPGs.
Within a workspace you can create CPGs, augment CPGs with overlays, load CPGs into the workspace, remove (unload) CPGs from the workspace, and delete CPGs. By default, all operations are executed on the CPG that was last loaded into the workspace.
The active, last loaded CPG is accessible through the
cpg variable; all CPGs loaded in the workspace are accessible using the
In order to create CPGs that contain the application code but do not include the code of libraries, ShiftLeft Ocular performs a smart inspection of the input file(s) to determine application code vs dependencies. Refer to the API for information on the methods used to gain visibility into this process:
ShiftLeft Ocular offers the following features to use workspaces:
There are three ways to create CPGs and Security Profiles, illustrated using the Java Vulnerable Lab benchmarking application for vulnerability discovery tools.
First creating the CPG, then creating the Security Profile.
By explicitly specifying the overlays.
createCpg("subjects/JavaVulnerableLab.war", "semanticcpg", "tagging", "securityprofile")
Managing a workspace involves loading and removing (unloading CPG and running queries. The commands to manage a workspace are illustrated using the HelloShiftLeft demo Java application.
workspace. Load all of an application's CPGs in the workspace. The last entry is the active CPG.
unloadCpg. Remove (unload) the newly created CPG from the workspace.
loadCpg("hello-shiftleft-0.0.1-SNAPSHOT.jar"). Load a specific CPG, by name, in the workspace. Once loaded, this CPG is active.
cpg.method.fullName.l. Run query on the active CPG in the workspace.
cpgs.flatMap(_.method.fullName.l). Run query on all CPGs in the workspace and join results.
You manage overlays by showing all overlay creators, loading a CPG only with a
semanticcpg overlay and adding a tagging overlay. The commands to manage overlays are illustrated using the Java Vulnerable Lab application.
overlays. Show all available overlay creators.
loadCpg("JavaVulnerableLab.war", "semanticcpg"). Load a CPG only with the
addOverlay("tagging"). Add the tagging overlay.
Java applications are distributed in Java Archives (JARs) and Web Application Archives (WARs). These archives contain both the application code and code for all dependencies.
Generally, you use ShiftLeft Ocular to analyze your application code and determine vulnerable dependencies. As part of this process, ShiftLeft Ocular creates a CPG for only the application code, and with references to the dependency code. ShiftLeft Ocular makes this distinction through the use of a built-in Smart Jar Unpacker, which heuristically determines for each namespace whether it contains application or dependency code.
The commands to identify application code and dependencies are illustrated using the HelloShiftLeft demo Java application.
namespaces("subjects/hello-shiftleft-0.0.1-SNAPSHOT.jar"). Show all namespaces of the application.
appNamespaces("subjects/hello-shiftleft-0.0.1-SNAPSHOT.jar"). Specify prior to creating the CPG, which packages the Smart Jar Unpacker treats as application packages.
depNamespaces("subjects/hello-shiftleft-0.0.1-SNAPSHOT.jar"). Show dependency namespaces.
If you want to manually choose application namespaces for CPG creation, you can pass those namespaces to the
createCpg command. For example, to specify explicitly that the application namespace is
io.shiftleft, you would use the command