CodeQL library for Python
codeql/python-all 0.6.4 (changelog, source)
Search

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 CSV format.

The CSV specification has the following columns:

  • Sources: package; type; path; kind
  • Sinks: package; type; path; kind
  • Summaries: package; type; path; input; output; kind
  • Types: package1; type1; package2; type2; path

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

  1. The package column selects a package name, as it would be referenced in the source code, such as an NPM package, PIP package, or Ruby gem. (See ModelsAsData.qll for language-specific details). It may also be a synthetic package used for a type definition (see type definitions below).

  2. The type column selects all instances of a named type originating from that package, or the empty string if referring to the package itself. It can also be a synthetic type name defined by a type definition (see type definitions below).

  3. The path column is a .-separated list of “access path tokens” to resolve, starting at the node selected by package and 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.

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

  5. 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 package1; type1; package2; type2; path indicates that package2; type2; path should be seen as an instance of the type package1; type1.

A (package,type) pair 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 packages and static type names.

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

Import path

import semmle.python.frameworks.data.internal.ApiGraphModels

Predicates

getAPackageAlias

Gets a package that should be seen as an alias for the given other package, or the package itself.

getSuccessorFromInvoke

Gets an API-graph successor for the given invocation.

getSuccessorFromNode

Gets a successor of node in the API graph.

isRelevantFullPath

Holds if package,type,path is used in some CSV row.

sourceModel

Holds if a source model exists for the given parameters.

Classes

TestAllModels

An empty class, except in specific tests.

Modules

ModelInput

Module containing hooks for providing input data to be interpreted as a model.

ModelOutput

Module providing access to the imported models in terms of API graph nodes.