Module ExternalFlow

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

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

The CSV specification has the following columns:

• Sources: namespace; type; subtypes; name; signature; ext; output; kind
• Sinks: namespace; type; subtypes; name; signature; ext; input; kind
• Summaries: namespace; type; subtypes; name; signature; ext; input; output; kind

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

1. The namespace column selects a namespace.

2. The type column selects a type within that namespace. This column can introduce template names that can be mentioned in the signature column. For example, vector<T,Allocator> introduces the template names T and Allocator.

3. The subtypes is a boolean that indicates whether to jump to an arbitrary subtype of that type. Set this to false if leaving the type blank (for example, a free function).

4. The name column optionally selects a specific named member of the type. Like the type column, this column can introduce template names that can be mentioned in the signature column. For example, insert<InputIt> introduces the template name InputIt.

5. The signature column optionally restricts the named member. If signature is blank then no such filtering is done. The format of the signature is a comma-separated list of types enclosed in parentheses. The types must be stripped of template names. That is, write const vector & instead of const vector<T> &.

6. The ext column specifies additional API-graph-like edges. Currently there is only one valid value: "".

7. The input column specifies how data enters the element selected by the first 6 columns, and the output column specifies how data leaves the element selected by the first 6 columns. An input can be either:

   • "": Selects a write to the selected element in case this is a field.
   • “Argument[n]”: Selects an argument in a call to the selected element. The arguments are zero-indexed, and -1 specifies the qualifier object, that is, *this.
     • one or more “*” can be added in front of the argument index to indicate indirection, for example, Argument[*0] indicates the first indirection of the 0th argument.
     • n1..n2 syntax can be used to indicate a range of arguments, inclusive at both ends. One or more "*"s can be added in front of the whole range to indicate that every argument in the range is indirect, for example *0..1 is the first indirection of both arguments 0 and 1.
   • “ReturnValue”: Selects a value being returned by the selected element. One or more “*” can be added as an argument to indicate indirection, for example, “ReturnValue[*]” indicates the first indirection of the return value. The special symbol @ can be used to specify an arbitrary (but fixed) number of indirections. For example, the input column Argument[*@0] indicates one or more indirections of the 0th argument.

   An output can be either:

   • "": Selects a read of a selected field.
   • “Argument[n]”: Selects the post-update value of an argument in a call to the selected element. That is, the value of the argument after the call returns. The arguments are zero-indexed, and -1 specifies the qualifier object, that is, *this.
     • one or more “*” can be added in front of the argument index to indicate indirection, for example, Argument[*0] indicates the first indirection of the 0th argument.
     • n1..n2 syntax can be used to indicate a range of arguments, inclusive at both ends. One or more "*"s can be added in front of the whole range to indicate that every argument in the range is indirect, for example *0..1 is the first indirection of both arguments 0 and 1.
   • “Parameter[n]”: Selects the value of a parameter of the selected element. The syntax is the same as for “Argument”, for example “Parameter[0]”, “Parameter[*0]”, “Parameter[0..2]” etc.
   • “ReturnValue”: Selects a value being returned by the selected element. One or more “*” can be added as an argument to indicate indirection, for example, “ReturnValue[*]” indicates the first indirection of the return value. The special symbol @ can be used to specify an arbitrary (but fixed) number of indirections. For example, the output column ReturnValue[*@0] indicates one or more indirections of the return value. Note: The symbol @ only ever takes a single value across a row. Thus, the (input, output) pair ("Argument[*@0]", "ReturnValue[@]") represents:
   • flow from the first indirection of the 0th argument to the return value, and
   • flow from the second indirection of the 0th argument to the first indirection of the return value, etc.

8. 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.