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

Class API::Node

A node in the API graph, representing a value that has crossed the boundary between this codebase and an external library (or in general, any external codebase).

Basic usage

API graphs are typically used to identify “API calls”, that is, calls to an external function whose implementation is not necessarily part of the current codebase.

The most basic use of API graphs is typically as follows:

  1. Start with API::moduleImport for the relevant library.
  2. Follow up with a chain of accessors such as getMember describing how to get to the relevant API function.
  3. Map the resulting API graph nodes to data-flow nodes, using asSource or asSink.

For example, a simplified way to get the first argument of a call to json.dumps would be

API::moduleImport("json").getMember("dumps").getParameter(0).asSink()

The most commonly used accessors are getMember, getParameter, and getReturn.

API graph nodes

There are two kinds of nodes in the API graphs, distinguished by who is “holding” the value:

  • Use-nodes represent values held by the current codebase, which came from an external library. (The current codebase is “using” a value that came from the library).
  • Def-nodes represent values held by the external library, which came from this codebase. (The current codebase “defines” the value seen by the library).

API graph nodes are associated with data-flow nodes in the current codebase. (API graphs are designed to work when external libraries are not part of the database, so we do not associate with concrete data-flow nodes from the external library).

  • Use-nodes are associated with data-flow nodes where a value enters the current codebase, such as the return value of a call to an external function.
  • Def-nodes are associated with data-flow nodes where a value leaves the current codebase, such as an argument passed in a call to an external function.

Access paths and edge labels

Nodes in the API graph are associated with a set of access paths, describing a series of operations that may be performed to obtain that value.

For example, the access path API::moduleImport("json").getMember("dumps") represents the action of importing json and then accessing the member dumps on the resulting object.

Each edge in the graph is labelled by such an “operation”. For an edge A->B, the type of the A node determines who is performing the operation, and the type of the B node determines who ends up holding the result:

  • An edge starting from a use-node describes what the current codebase is doing to a value that came from a library.
  • An edge starting from a def-node describes what the external library might do to a value that came from the current codebase.
  • An edge ending in a use-node means the result ends up in the current codebase (at its associated data-flow node).
  • An edge ending in a def-node means the result ends up in external code (its associated data-flow node is the place where it was “last seen” in the current codebase before flowing out)

Because the implementation of the external library is not visible, it is not known exactly what operations it will perform on values that flow there. Instead, the edges starting from a def-node are operations that would lead to an observable effect within the current codebase; without knowing for certain if the library will actually perform those operations. (When constructing these edges, we assume the library is somewhat well-behaved).

For example, given this snippet:

import foo
foo.bar(lambda x: doSomething(x))

A callback is passed to the external function foo.bar. We can’t know if foo.bar will actually invoke this callback. But if the library should decide to invoke the callback, then a value will flow into the current codebase via the x parameter. For that reason, an edge is generated representing the argument-passing operation that might be performed by foo.bar. This edge is going from the def-node associated with the callback to the use-node associated with the parameter x.

Import path

import semmle.python.ApiGraphs

Direct supertypes

Known direct subtypes

Predicates

asSink

Gets a data-flow node where this value leaves the current codebase and flows into an external library (or in general, any external codebase).

asSource

Gets a data-flow node where this value enters the current codebase.

getACall

Gets a call to the function represented by this API component.

getAMember

Gets a node representing a member of this API component where the name of the member may or may not be known statically.

getAPredecessor

Gets a node such that there is an edge in the API graph between that other node and this one, and that edge is labeled with lbl

getAPredecessor

Gets a node such that there is an edge in the API graph between this node and the other one.

getARhs

DEPRECATED. This predicate has been renamed to asSink().

getASubclass

Gets a node representing a subclass of the class represented by this node.

getASubscript

Gets a node representing a subscript of this node. For example obj[x] is a subscript of obj.

getASuccessor

Gets a node such that there is an edge in the API graph between this node and the other one, and that edge is labeled with lbl.

getASuccessor

Gets a node such that there is an edge in the API graph between that other node and this one.

getAUse

DEPRECATED. This predicate has been renamed to getAValueReachableFromSource().

getAValueReachableFromSource

Gets a data-flow node where this value may flow after entering the current codebase.

getAValueReachingRhs

DEPRECATED. This predicate has been renamed to getAValueReachingSink().

getAValueReachingSink

Gets a data-flow node that transitively flows to an external library (or in general, any external codebase).

getAnImmediateUse

DEPRECATED. This predicate has been renamed to asSource().

getAwaited

Gets a node representing the result from awaiting this node.

getDepth

Gets the shortest distance from the root to this node in the API graph.

getIndex

Gets a node representing an index of a subscript of this node. For example, in obj[x], x is an index of obj.

getInducingNode

Gets the data-flow node that gives rise to this node, if any.

getKeywordParameter

Gets the node representing the keyword parameter name of the function represented by this node.

getMember

Gets a node representing member m of this API component.

getNumParameter

Gets the number of parameters of the function represented by this node.

getParameter

Gets a node representing the ith parameter of the function represented by this node.

getPath

Gets a string representation of the lexicographically least among all shortest access paths from the root to this node.

getReturn

Gets a node representing the result of the function represented by this node.

getSelfParameter

Gets the node representing the self parameter

getSubscript

Gets a node representing a subscript of this node at (string) index key. This requires that the index can be statically determined.

getSubscriptAt

Gets a node representing a subscript of this node at index index.

getUnknownMember

Gets a node representing a member of this API component where the name of the member is not known statically.

hasLocationInfo

Holds if this element is at the specified location. The location spans column startcolumn of line startline to column endcolumn of line endline in file filepath. For more information, see Locations.

toString

Gets a textual representation of this element.