Module ApiGraphModels

INTERNAL use only. This is an experimental API subject to change without notice.

Provides classes and predicates for dealing with flow models specified in extensible predicates.

The extensible predicates have the following columns:

• Sources: type, path, kind
• Sinks: type, path, kind
• Summaries: type, path, input, output, kind
• Types: type1, type2, path

The interpretation of a row is similar to API-graphs with a left-to-right reading.

1. The type column selects all instances of a named type. The syntax of this column is language-specific. The language defines some type names that the analysis knows how to identify without models. It can also be a synthetic type name defined by a type definition (see type definitions below).

2. The path column is a .-separated list of “access path tokens” to resolve, starting at the node selected by type.

   Every language supports the following tokens:

   • Argument[n]: the n-th argument to a call. May be a range of form x..y (inclusive) and/or a comma-separated list. Additionally, N-1 refers to the last argument, N-2 refers to the second-last, and so on.
   • Parameter[n]: the n-th parameter of a callback. May be a range of form x..y (inclusive) and/or a comma-separated list.
   • ReturnValue: the value returned by a function call
   • WithArity[n]: match a call with the given arity. May be a range of form x..y (inclusive) and/or a comma-separated list.

   The following tokens are common and should be implemented for languages where it makes sense:

   • Member[x]: a member named x; exactly what a “member” is depends on the language. May be a comma-separated list of names.
   • Instance: an instance of a class
   • Subclass: a subclass of a class
   • ArrayElement: an element of array
   • Element: an element of a collection-like object
   • MapKey: a key in map-like object
   • MapValue: a value in a map-like object
   • Awaited: the value from a resolved promise/future-like object

   For the time being, please consult ApiGraphModelsSpecific.qll to see which language-specific tokens are currently supported.

3. The input and output columns specify how data enters and leaves the element selected by the first (type, path) tuple. Both strings are .-separated access paths of the same syntax as the path column.

4. The kind column is a tag that can be referenced from QL to determine to which classes the interpreted elements should be added. For example, for sources "remote" indicates a default remote flow source, and for summaries "taint" indicates a default additional taint step and "value" indicates a globally applicable value-preserving step.

Types

A type row of form type1; type2; path indicates that type2; path should be seen as an instance of the type type1.

A type may refer to a static type or a synthetic type name used internally in the model. Synthetic type names can be used to reuse intermediate sub-paths, when there are multiple ways to access the same element. See ModelsAsData.qll for the language-specific interpretation of type names.

By convention, if one wants to avoid clashes with static types, the type name should be prefixed with a tilde character (~). For example, ~Bar can be used to indicate that the type is not intended to match a static type.