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 data extensions and CSV format.

The CSV specification has the following columns:

• Sources: package; type; subtypes; name; signature; ext; output; kind; provenance
• Sinks: package; type; subtypes; name; signature; ext; input; kind; provenance
• Summaries: package; type; subtypes; name; signature; ext; input; output; kind; provenance
• Neutrals: package; type; name; signature; kind; provenance A neutral is used to indicate that a callable is neutral with respect to flow (no summary), source (is not a source) or sink (is not a sink).

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

1. The package column selects a package. Note that if the package does not contain a major version suffix (like “/v2”) then we will match all major versions. This can be disabled by putting fixed-version: at the start of the package path. Also, instead of a package path, if this column is “group:” then it indicates that the row applies to all packages in the group <groupname> according to the packageGrouping predicate.

2. The type column selects a type within that package.

3. The subtypes column is a boolean that controls what restrictions we place on the type t of the selector base when accessing a field or calling a method. When it is false, t must be the exact type specified by this row. When it is true, t may be a type which embeds the specified type, and for interface methods t may be a type which implements the interface.

4. The name column optionally selects a specific named member of the type.

5. The signature column is always empty.

6. The ext column is always empty.

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 "", “Argument[n]”, or “Argument[n1..n2]”:

   • "": Selects a write to the selected element in case this is a field or package-level variable.
   • “Argument[n]”: Selects an argument in a call to the selected element. The arguments are zero-indexed, and receiver specifies the receiver.
   • “Argument[n1..n2]”: Similar to “Argument[n]” but selects any argument in the given range. The range is inclusive at both ends.

   An output can be either "", “Argument[n]”, “Argument[n1..n2]”, “Parameter”, “Parameter[n]”, “Parameter[n1..n2]”, , “ReturnValue”, “ReturnValue[n]”, or “ReturnValue[n1..n2]”:

   • "": Selects a read of a selected field or package-level variable.
   • “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 receiver specifies the receiver.
   • “Argument[n1..n2]”: Similar to “Argument[n]” but select any argument in the given range. The range is inclusive at both ends.
   • “Parameter”: Selects the value of a parameter of the selected element.
   • “Parameter[n]”: Similar to “Parameter” but restricted to a specific numbered parameter (zero-indexed, and receiver specifies the receiver).
   • “Parameter[n1..n2]”: Similar to “Parameter[n]” but selects any parameter in the given range. The range is inclusive at both ends.
   • “ReturnValue”: Selects the first value being returned by the selected element. This requires that the selected element is a method with a body.
   • “ReturnValue[n]”: Similar to “ReturnValue” but selects the specified return value. The return values are zero-indexed
   • “ReturnValue[n1..n2]”: Similar to “ReturnValue[n]” but selects any return value in the given range. The range is inclusive at both ends.

   For summaries, input and output may be suffixed by any number of the following, separated by “.”:

   • “Field[pkg.className.fieldname]”: Selects the contents of the field f which satisfies f.hasQualifiedName(pkg, className, fieldname).
   • “SyntheticField[f]”: Selects the contents of the synthetic field f.
   • “ArrayElement”: Selects an element in an array or slice.
   • “Element”: Selects an element in a collection.
   • “MapKey”: Selects a key in a map.
   • “MapValue”: Selects a value in a map.
   • “Dereference”: Selects the value referenced by a pointer.

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.