Packages

Definition Classes: root

package io

Definition Classes: root

Definition Classes: io

Domain specific language for querying code property graphs

This is the API reference for the CPG query language, a language to mine code for defects and vulnerabilities both interactively on a code analysis shell (REPL), or using non-interactive scripts.

Queries written in the CPG query language express graph traversals (see https://en.wikipedia.org/wiki/Graph_traversal). Similar to the standard graph traversal language "Gremlin" (see https://en.wikipedia.org/wiki/Gremlin_(programming_language))) these traversals are formulated as sequences of primitive language elements referred to as "steps". You can think of a step as a small program, similar to a unix shell utility, however, instead of processing lines one by one, the step processes nodes of the graph.

Starting a traversal

All traversals begin by selecting a set of start nodes, e.g.,

cpg.method

will start the traversal at all methods, while

cpg.local

will start at all local variables. The complete list of starting points can be found at

io.shiftleft.codepropertygraph.Cpg

Lazy evaluation

Queries are lazily evaluated, e.g., cpg.method creates a traversal which you can add more steps to. You can, for example, evaluate the traversal by converting it to a list:

cpg.method.toList

Since toList is such a common operation, we provide the shorthand l, meaning that

cpg.method.l

provides the same result as the former query.

Properties

Nodes have "properties", key-value pairs where keys are strings and values are primitive data types such as strings, integers, or Booleans. Properties of nodes can be selected based on their key, e.g.,

cpg.method.name

traverses to all method names. Nodes can also be filtered based on properties, e.g.,

cpg.method.name(".*exec.*")

traverse to all methods where name matches the regular expression ".*exec.*". You can see a complete list of properties by browsing to the API documentation of the corresponding step. For example, you can find the properties of method nodes at io.shiftleft.semanticcpg.language.types.structure.MethodTraversal.

Side effects

Useful if you want to mutate something outside the traversal, or simply debug it: This prints all typeDecl names as it traverses the graph and increments i for each one.

var i = 0
cpg.typeDecl.sideEffect{typeTemplate => println(typeTemplate.name); i = i + 1}.exec

[advanced] Selecting multiple things from your traversal

If you are interested in multiple things along the way of your traversal, you label anything using the as modulator, and use select at the end. Note that the compiler automatically derived the correct return type as a tuple of the labelled steps, in this case with two elements.

cpg.method.as("method").definingTypeDecl.as("classDef").select.toList
// return type: List[(Method, TypeDecl)]

[advanced] For comprehensions

You can always start a new traversal from a node, e.g.,

val someMethod = cpg.method.head
someMethod.start.parameter.toList

You can use this e.g. in a for comprehension, which is (in this context) essentially an alternative way to select multiple intermediate things. It is more expressive, but more computationally expensive.

val query = for {
  method <- cpg.method
  param <- method.start.parameter
} yield (method.name, param.name)

query.toList

Definition Classes: shiftleft

package passes

Definition Classes: semanticcpg

package cfgcreation

Definition Classes: passes

Cfg

CfgCreator

CfgEdge

package cfgdominator

Definition Classes: passes

package codepencegraph

Definition Classes: passes

package compat

Definition Classes: passes

package containsedges

Definition Classes: passes

package languagespecific

Definition Classes: passes

package linking

Definition Classes: passes

package metadata

Definition Classes: passes

package methoddecorations

Definition Classes: passes

package methodexternaldecorator

Definition Classes: passes

package namespacecreator

Definition Classes: passes

package receiveredges

Definition Classes: passes

package trim

Definition Classes: passes

package typenodes

Definition Classes: passes

io.shiftleft.semanticcpg.passes

cfgcreation

package cfgcreation

Ordering

Alphabetic

Visibility

Public
Protected

Type Members

case class Cfg(entryNode: Option[CfgNode] = None, edges: List[CfgEdge] = List(), fringe: List[(CfgNode, CfgEdgeType)] = List(), labeledNodes: Map[String, CfgNode] = Map(), breaks: List[CfgNode] = List(), continues: List[CfgNode] = List(), caseLabels: List[CfgNode] = List(), gotos: List[(CfgNode, String)] = List()) extends Product with Serializable
A control flow graph that is under construction, consisting of:
A control flow graph that is under construction, consisting of:
entryNode
the control flow graph's first node, that is, the node to which a CFG that appends this CFG should attach itself to.
edges
control flow edges between nodes of the code property graph.
fringe
nodes of the CFG for which an outgoing edge type is already known but the destination node is not. These nodes are connected when another CFG is appended to this CFG. In addition to these three core building blocks, we store labels and jump statements that have not been resolved and may be resolvable as parent sub trees or sibblings are translated.
labeledNodes
labels contained in the abstract syntax tree from which this CPG was generated
breaks
unresolved breaks collected along the way
continues
unresolved continues collected along the way
caseLabels
labels beginning with "case"
gotos
unresolved gotos collected along the way
class CfgCreator extends AnyRef
Translation of abstract syntax trees into control flow graphs
Translation of abstract syntax trees into control flow graphs
The problem of translating an abstract syntax tree into a corresponding control flow graph can be formulated as a recursive problem in which sub trees of the syntax tree are translated and their corresponding control flow graphs are connected according to the control flow semantics of the root node. For example, consider the abstract syntax tree for an if-statement:
( if ) / \ (x < 10) (x += 1) / \ / \ x 10 x 1
This tree can be translated into a control flow graph, by translating the sub tree rooted in x < 10 and that of x += 1 and connecting their control flow graphs according to the semantics of if:
[x < 10]---- |t f| [x +=1 ] | | The semantics of if dictate that the first sub tree to the left is a condition, which is connected to the CFG of the second sub tree - the body of the if statement - via a control flow edge with the true label (indicated in the illustration by t), and to the CFG of any follow-up code via a false edge (indicated by f).
A problem that becomes immediately apparent in the illustration is that the result of translating a sub tree may leave us with edges for which a source node is known but the destination node depends on parents or siblings that were not considered in the translation. For example, we know that an outgoing edge from [x<10] must exist, but we do not yet know where it should lead. We refer to the set of nodes of the control flow graph with outgoing edges for which the destination node is yet to be determined as the "fringe" of the control flow graph.
case class CfgEdge(src: CfgNode, dst: CfgNode, edgeType: CfgEdgeType) extends Product with Serializable

Value Members

object Cfg extends Serializable
object CfgCreator

Packages

Starting a traversal

Lazy evaluation

Properties

Side effects

[advanced] Selecting multiple things from your traversal

[advanced] For comprehensions

cfgcreation

package cfgcreation

Type Members

Value Members

Ungrouped

cfgcreation