Packages

  • package root
    Definition Classes
    root
  • package io
    Definition Classes
    root
  • package shiftleft
    Definition Classes
    io
  • package semanticcpg

    Domain specific language for querying code property graphs

    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 language

    Language for traversing the code property graph

    Language for traversing the code property graph

    Implicit conversions to specific steps, based on the node at hand. Automatically in scope when using anything in the steps package, e.g. Steps

    Definition Classes
    semanticcpg
  • package types
    Definition Classes
    language
  • package expressions
    Definition Classes
    types
  • package generalizations
    Definition Classes
    expressions
  • AstNodeTraversal
  • CfgNodeTraversal
  • ExpressionTraversal

final class AstNodeTraversal[A <: AstNode] extends AnyVal

Annotations
@Traversal()
Linear Supertypes
AnyVal, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. AstNodeTraversal
  2. AnyVal
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Instance Constructors

  1. new AstNodeTraversal(traversal: Traversal[A])

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    Any
  2. final def ##: Int
    Definition Classes
    Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def ast(predicate: (AstNode) => Boolean): Traversal[AstNode]

    All nodes of the abstract syntax tree rooted in this node, which match predicate.

    All nodes of the abstract syntax tree rooted in this node, which match predicate. Equivalent of match in the original CPG paper.

  6. def ast: Traversal[AstNode]

    Nodes of the AST rooted in this node, including the node itself.

    Nodes of the AST rooted in this node, including the node itself.

    Annotations
    @Doc()
  7. def astChildren: Traversal[AstNode]

    Direct children of node in the AST.

    Direct children of node in the AST. Siblings are ordered by their order fields

  8. def astMinusRoot: Traversal[AstNode]

    Nodes of the AST rooted in this node, minus the node itself

  9. def astParent: Traversal[AstNode]

    Parent AST node

  10. def containsCallTo(regex: String): Traversal[A]
  11. def depth(p: (AstNode) => Boolean): Traversal[Int]
  12. def depth: Traversal[Int]
    Annotations
    @Doc()
  13. def getClass(): Class[_ <: AnyVal]
    Definition Classes
    AnyVal → Any
  14. def inAst(root: AstNode): Traversal[AstNode]

    Nodes of the AST obtained by expanding AST edges backwards until root or the method root is reached

  15. def inAst: Traversal[AstNode]

    Nodes of the AST obtained by expanding AST edges backwards until the method root is reached

  16. def inAstMinusLeaf(root: AstNode): Traversal[AstNode]

    Nodes of the AST obtained by expanding AST edges backwards until root or the method root is reached, minus this node

  17. def inAstMinusLeaf: Traversal[AstNode]

    Nodes of the AST obtained by expanding AST edges backwards until the method root is reached, minus this node

  18. def isBlock: Traversal[Block]

    Traverse only to those AST nodes that are blocks

  19. def isCall(calleeRegex: String): Traversal[Call]

    Cast to call if applicable and filter on call code calleeRegex

  20. def isCall: Traversal[Call]

    Traverse only to AST nodes that are calls

  21. def isCallTo(regex: String): Traversal[Call]
  22. def isCfgNode: Traversal[CfgNode]

    Traverse only to those AST nodes that are also control flow graph nodes

  23. def isControlStructure: Traversal[ControlStructure]

    Traverse only to those AST nodes that are control structures

  24. def isExpression: Traversal[Expression]

    Traverse only to AST nodes that are expressions

  25. def isFieldIdentifier: Traversal[FieldIdentifier]

    Traverse only to AST nodes that are field identifier

  26. def isFile: Traversal[File]

    Traverse only to FILE AST nodes

  27. def isIdentifier: Traversal[Identifier]

    Traverse only to AST nodes that are identifier

  28. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  29. def isLiteral: Traversal[Literal]

    Traverse only to AST nodes that are literals

  30. def isLocal: Traversal[Local]
  31. def isMember: Traversal[Member]

    Traverse only to AST nodes that are MEMBER

  32. def isMethod: Traversal[Method]

    Traverse only to AST nodes that are METHOD

  33. def isMethodRef: Traversal[MethodRef]

    Traverse only to AST nodes that are method reference

  34. def isModifier: Traversal[Modifier]

    Traverse only to AST nodes that are MODIFIER

  35. def isNamespaceBlock: Traversal[NamespaceBlock]

    Traverse only to AST nodes that are NAMESPACE_BLOCK

  36. def isParameter: Traversal[MethodParameterIn]

    Traverse only to AST nodes that are METHOD_PARAMETER_IN

  37. def isReturn: Traversal[Return]

    Traverse only to AST nodes that are return nodes

  38. def isTypeDecl: Traversal[TypeDecl]

    Traverse only to AST nodes that are TYPE_DECL

  39. def isTypeRef: Traversal[TypeRef]

    Traverse only to AST nodes that are type reference

  40. def parentBlock: Traversal[Block]

    Traverses up the AST and returns the first block node.

  41. def toString(): String
    Definition Classes
    Any
  42. val traversal: Traversal[A]
  43. def walkAstUntilReaching(labels: List[String]): Traversal[StoredNode]

Inherited from AnyVal

Inherited from Any

Ungrouped