Once you've started ShiftLeft Ocular, you can create a CPG for a new application or for a new version of an application. When a CPG is created, it's
base and default layers are also automatically generated, and all are saved to your workspace and loaded into memory. However you must intentionally generate and load the Security Profile.
By default, all operations are executed on the CPG that was last loaded into memory; this is the active CPG.
Working with existing CPGs involves:
For additional information about the CPG, refer to:
The command, with all available functions, to create a CPG is
createCpg(inputPaths: List[String], namespaces: List[String], overlayCreators: List[String])
ShiftLeft Ocular provides several simpler versions of
createCpg for convenience.
<inputPaths> is the path of the target application; multiple applications are separated by a comma. The format of the CPG is automatically inferred by ShiftLeft Ocular.
When you create a CPG, a file named
cpg.bin.zip containing the CPG in a binary format, is created in your workspace and automatically loaded into memory; it becomes the active CPG.
For Java applications, 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. Before creating the CPG you should identify your application code and dependencies; so that you know which parts of your application will be modelled. You can then decide whether to include specific objects in the CPG.
The easiest way to create a CPG is to use the following command
You can create a single CPG from multiple applications, for example for an application and several of its dependencies, or for multiple microservices. To do so, use the command
createCpg("subjects/hello-shiftleft-0.0.1-SNAPSHOT.jar", "linux/driver", "linux/cryto").
To create a CPG and its Security Profile at the same time, use
Both the CPG and the
securityprofile layer are created in your workspace and automatically loaded into memory. The sp.bin.zip file contains the SP in a binary format.
If your application uses namespaces (e.g. Java packages) to organize objects, you can specify which namespaces contain code you want represented in the CPG. The command is
ocular> createCpg(<inputPath>, <namespace>)
<namespace> is one or more namespaces you want to include in the CPG; multiple namespaces are separated by a comma. For example
createCpg("subjects/hello-shiftleft-0.0.1-SNAPSHOT.jar", List("io.shiftleft", "org.foo")).
You work with the CPGs, and their associated layers, which are in your workspace and loaded into memory. By default, all operations are executed on the CPG that was last loaded into memory; this is the active CPG.
<names> is the name of one or more CPGs you want to work with; multiple names are separated by a comma. For example
"hello-shiftleft-0.0.1-SNAPSHOT.jar". The format of the CPG is automatically inferred by ShiftLeft Ocular.
When you load an existing CPG into memory, all default layers and the
securityprofile layer (if it already exists), are also automatically loaded. To load a CPG, use the command
The number and size of CPGs that can be loaded into your workspace at any one time is limited by the amount of available memory.
Unloading a CPG (and its associated layers) removes it from memory, but not from disk. When you unload a CPG, the most recently loaded CPG becomes the active CPG.
To unload the active CPG, use the command
To unload a specific CPG, use the command
Deleting a CPG (and its associated layers) from disk also deletes it from your workspace. When you delete a CPG, the most recently loaded CPG become the active CPG.
To delete the active CPG, use the command
To delete a specific CPG, use the command