How to Enhance the Ocular Query Language (OQL)

The Ocular Query Language is used to query Code Property Graphs and Security Profiles. The results can be integrated into your security tools and used to share data across the software development lifecycle. Because it is based on Scala, you can easily enhance it by defining implicit extensions.

If you find yourself in need of combining multiple Ocular Queries into one, or simply want to save an Ocular Query you use frequently, you can add your own custom Ocular Query Component. For example, you could define an Ocular Query Component publicExampleOrg on Node-Type Steps for METHOD nodes that filters for those nodes whose FULL_NAME property matches the .*org.example.* regular expression, and have the public modifier, like so:

implicit class MyMethodTraversals(method: NodeSteps[nodes.Method]){
def publicExampleOrg = method.fullName(".*org.example.*").isPublic
}

Usage: cpg.method.publicExampleOrg.l

note

Notes:

  • tab completion works, i.e. if you type cpg.method.pu<TAB> it will auto-complete
  • unless we add additional extensions, this step is not available for other types, e.g. cpg.namespace.publicExampleOrg does not compile (or autocomplete)
  • you can store it in a script, e.g. myext.sc and import it on startup of your ocular session, e.g. sl ocular -- --import myext.sc