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 structure
    Definition Classes
    types
  • BlockTraversal
  • FileTraversal
  • LocalTraversal
  • MemberTraversal
  • MethodParameterOutTraversal
  • MethodParameterTraversal
  • MethodReturnTraversal
  • MethodTraversal
  • NamespaceBlockTraversal
  • NamespaceTraversal
  • TypeDeclTraversal
  • TypeTraversal

final class MethodTraversal extends AnyVal

A method, function, or procedure

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

Instance Constructors

  1. new MethodTraversal(traversal: Traversal[Method])

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 block: Traversal[Block]

    Traverse to block

    Traverse to block

    Annotations
    @Doc("Root of the abstract syntax tree", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  6. def body: Traversal[Block]

    Traverse to method body (alias for block)

    Traverse to method body (alias for block)

    Annotations
    @Doc("Alias for `block`", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  7. def break: Traversal[ControlStructure]
    Annotations
    @Doc("All breaks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  8. def cfgFirst: Traversal[Expression]

    Traverse to first expression in CFG.

    Traverse to first expression in CFG.

    Annotations
    @Doc("First control flow graph node", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  9. def cfgLast: Traversal[Expression]

    Traverse to last expression in CFG.

    Traverse to last expression in CFG.

    Annotations
    @Doc("Last control flow graph node", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  10. def cfgNode: Traversal[CfgNode]
    Annotations
    @Doc("Control flow graph nodes", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  11. def continue: Traversal[ControlStructure]
    Annotations
    @Doc("All continues (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  12. def controlStructure(regex: String): Traversal[ControlStructure]

    Shorthand to traverse to control structures where condition matches regex

  13. def controlStructure: Traversal[ControlStructure]

    All control structures of this method

    All control structures of this method

    Annotations
    @Doc("Control structures (source frontends only)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  14. def definingMethod: Traversal[Method]

    The method in which this method is defined

    The method in which this method is defined

    Annotations
    @Doc("Method this method is defined in", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  15. def definingTypeDecl: Traversal[TypeDecl]

    The type declaration associated with this method, e.g., the class it is defined in.

    The type declaration associated with this method, e.g., the class it is defined in.

    Annotations
    @Doc("Type this method is defined in", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  16. def doBlock: Traversal[ControlStructure]
    Annotations
    @Doc("All do blocks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  17. def elseBlock: Traversal[ControlStructure]
    Annotations
    @Doc("All else blocks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  18. def external: Traversal[Method]

    Traverse to external methods, that is, methods not present but only referenced in the CPG.

    Traverse to external methods, that is, methods not present but only referenced in the CPG.

    Annotations
    @Doc("External methods (called, but no body available)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  19. def forBlock: Traversal[ControlStructure]
    Annotations
    @Doc("All for blocks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  20. def getClass(): Class[_ <: AnyVal]
    Definition Classes
    AnyVal → Any
  21. def goto: Traversal[ControlStructure]
    Annotations
    @Doc("All gotos (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  22. def ifBlock: Traversal[ControlStructure]
    Annotations
    @Doc("All if blocks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  23. def internal: Traversal[Method]

    Traverse to internal methods, that is, methods for which code is included in this CPG.

    Traverse to internal methods, that is, methods for which code is included in this CPG.

    Annotations
    @Doc("Internal methods, i.e., a body is available", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  24. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  25. def isNotStub: Traversal[Method]

    Traverse only to methods that are not stubs.

  26. def isStub: Traversal[Method]

    Traverse only to methods that are stubs, e.g., their code is not available or the method body is empty.

  27. def isVariadic: Traversal[Method]

    Traverse only to methods that accept variadic arguments.

  28. def literal: Traversal[Literal]

    Traverse to literals of method

    Traverse to literals of method

    Annotations
    @Doc("Literals used in the method", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  29. def local: Traversal[Local]

    Traverse to the methods local variables

    Traverse to the methods local variables

    Annotations
    @Doc("Local variables declared in the method", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  30. def methodReturn: Traversal[MethodReturn]

    Traverse to formal return parameter

    Traverse to formal return parameter

    Annotations
    @Doc("All formal return parameters", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  31. def namespace: Traversal[Namespace]

    Traverse to namespace

    Traverse to namespace

    Annotations
    @Doc("Namespace this method is declared in", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  32. def numberOfLines: Traversal[Int]
  33. def parameter: Traversal[MethodParameterIn]

    Traverse to parameters of the method

    Traverse to parameters of the method

    Annotations
    @Doc("All parameters", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  34. def switchBlock: Traversal[ControlStructure]
    Annotations
    @Doc("All switch blocks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  35. def toString(): String
    Definition Classes
    Any
  36. def topLevelExpressions: Traversal[Expression]
    Annotations
    @Doc("Top level expressions (\"Statements\")", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  37. val traversal: Traversal[Method]
  38. def tryBlock: Traversal[ControlStructure]
    Annotations
    @Doc("All try blocks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)
  39. def whileBlock: Traversal[ControlStructure]
    Annotations
    @Doc("All while blocks (`ControlStructure` nodes)", help.this.Doc.<init>$default$2, help.this.Doc.<init>$default$3)

Inherited from AnyVal

Inherited from Any

Ungrouped