Extending the Ocular Schema

Ocular ships with a utility called schema-extender that allows you to extend any of the default Code Property Graph schemas.

You can define additional nodes, edges, and properties in a specific JSON file, then run schema-extender so that the schema is ready for use in Ocular immediately. The schema-extender is useful for tasks like defining your own passes, and it can be used in conjunction with an enhanced version of the Code Property Graph Query Language.

Usage

1. Add your new schema (in a JSON file) to schema-extender/schemas; you can use an existing schema as a template

2. Run ./schema-extender.sh

The next time you start Ocular, your added nodes, edges, and properties are equal members of the io.shiftleft.codepropertygraph.generated package.

Example: additional Foo edge from File -> Method

First, navigate into schema-extender using cd schema-extender.

Create a new file in that directory (e.g., schemas/foo.json) with the following contents:

{
  "edgeTypes" : [
    {"id" : 9000, "name": "FOO", "comment" : "Foo edge", "keys": []}
  ],

  "nodeTypes" : [
    { "name" : "FILE", "outEdges" : [{"edgeName": "FOO", "inNodes": ["METHOD"]}] }
  ]
}

In the terminal, run:

./schema-extender.sh
./ocular.sh

Finally, open a CPG using importCode(<path-to-code-directory>), and create a FOO edge from a file to a method:

val file = cpg.file.head
val method = cpg.method.head
file --- "FOO" --> method

Idempotency

The schema-enhancer automatically backs up the original jar, which means that you can run the process described above repeatedly.