ExternalAPIs.qll

/**
 * Definitions for reasoning about untrusted data used in APIs defined outside the
 * user-written code.
 */

private import python
import semmle.python.dataflow.new.DataFlow
private import semmle.python.dataflow.new.TaintTracking
private import semmle.python.dataflow.new.RemoteFlowSources
private import semmle.python.ApiGraphs
private import semmle.python.dataflow.new.internal.DataFlowPrivate as DataFlowPrivate
private import semmle.python.dataflow.new.internal.TaintTrackingPrivate as TaintTrackingPrivate

/**
 * An external API that is considered a "safe" from a security perspective.
 */
class SafeExternalApi extends Unit {
  /**
   * Gets a call that is considered "safe" from a security perspective. You can use API
   * graphs to find calls to functions you know are safe.
   *
   * Which works even when the external library isn't extracted.
   */
  abstract DataFlow::CallCfgNode getSafeCall();

  /**
   * Gets a callable that is considered a "safe" external API from a security
   * perspective.
   *
   * You probably want to define this as `none()` and use `getSafeCall` instead, since
   * that can handle the external library not being extracted.
   */
  DataFlowPrivate::DataFlowCallable getSafeCallable() { none() }
}

/** DEPRECATED: Alias for SafeExternalApi */
deprecated class SafeExternalAPI = SafeExternalApi;

/** The default set of "safe" external APIs. */
private class DefaultSafeExternalApi extends SafeExternalApi {
  override DataFlow::CallCfgNode getSafeCall() {
    result = API::builtin(["len", "isinstance", "getattr", "hasattr"]).getACall()
  }
}

/** Gets a human readable representation of `node`. */
string apiNodeToStringRepr(API::Node node) {
  node = API::builtin(result)
  or
  node = API::moduleImport(result)
  or
  exists(API::Node base, string basename |
    base.getDepth() < node.getDepth() and
    basename = apiNodeToStringRepr(base)
  |
    exists(string m | node = base.getMember(m) | result = basename + "." + m)
    or
    node = base.getReturn() and
    result = basename + "()"
    or
    node = base.getAwaited() and
    result = basename
  )
}

newtype TInterestingExternalApiCall =
  TUnresolvedCall(DataFlow::CallCfgNode call) {
    exists(call.getLocation().getFile().getRelativePath()) and
    not exists(DataFlowPrivate::DataFlowCall dfCall | dfCall.getNode() = call.getNode()) and
    not call = any(SafeExternalApi safe).getSafeCall()
  } or
  TResolvedCall(DataFlowPrivate::DataFlowCall call) {
    exists(call.getLocation().getFile().getRelativePath()) and
    not call.getCallable() = any(SafeExternalApi safe).getSafeCallable() and
    not exists(call.getCallable().getLocation().getFile().getRelativePath())
  }

abstract class InterestingExternalApiCall extends TInterestingExternalApiCall {
  /** Gets the argument at position `apos`, if any */
  abstract DataFlow::Node getArgument(DataFlowPrivate::ArgumentPosition apos);

  /** Gets a textual representation of this element. */
  abstract string toString();

  /**
   * Gets a human-readable name for the external API.
   */
  abstract string getApiName();
}

class ResolvedCall extends InterestingExternalApiCall, TResolvedCall {
  DataFlowPrivate::DataFlowCall dfCall;

  ResolvedCall() { this = TResolvedCall(dfCall) }

  override DataFlow::Node getArgument(DataFlowPrivate::ArgumentPosition apos) {
    result = dfCall.getArgument(apos)
  }

  override string toString() { result = "ExternalAPI:ResolvedCall" }

  override string getApiName() {
    exists(DataFlow::CallCfgNode call, API::Node apiNode | dfCall.getNode() = call.getNode() |
      result = apiNodeToStringRepr(apiNode) and
      apiNode.getACall() = call
    )
  }
}

class UnresolvedCall extends InterestingExternalApiCall, TUnresolvedCall {
  DataFlow::CallCfgNode call;

  UnresolvedCall() { this = TUnresolvedCall(call) }

  override DataFlow::Node getArgument(DataFlowPrivate::ArgumentPosition apos) {
    exists(int i | apos.isPositional(i) | result = call.getArg(i))
    or
    exists(string name | apos.isKeyword(name) | result = call.getArgByName(name))
  }

  override string toString() { result = "ExternalAPI:UnresolvedCall" }

  override string getApiName() {
    exists(API::Node apiNode |
      result = apiNodeToStringRepr(apiNode) and
      apiNode.getACall() = call
    )
  }
}

/** A node representing data being passed to an external API through a call. */
class ExternalApiDataNode extends DataFlow::Node {
  InterestingExternalApiCall call;
  DataFlowPrivate::ArgumentPosition apos;

  ExternalApiDataNode() {
    this = call.getArgument(apos) and
    // Not already modeled as a taint step
    not exists(DataFlow::Node next | TaintTrackingPrivate::defaultAdditionalTaintStep(this, next)) and
    // for `list.append(x)`, we have a additional taint step from x -> [post] list.
    // Since we have modeled this explicitly, I don't see any cases where we would want to report this.
    not exists(DataFlow::PostUpdateNode post |
      post.getPreUpdateNode() = this and
      TaintTrackingPrivate::defaultAdditionalTaintStep(_, post)
    )
  }
}

/** DEPRECATED: Alias for ExternalApiDataNode */
deprecated class ExternalAPIDataNode = ExternalApiDataNode;

/** A configuration for tracking flow from `RemoteFlowSource`s to `ExternalApiDataNode`s. */
class UntrustedDataToExternalApiConfig extends TaintTracking::Configuration {
  UntrustedDataToExternalApiConfig() { this = "UntrustedDataToExternalAPIConfig" }

  override predicate isSource(DataFlow::Node source) { source instanceof RemoteFlowSource }

  override predicate isSink(DataFlow::Node sink) { sink instanceof ExternalApiDataNode }
}

/** DEPRECATED: Alias for UntrustedDataToExternalApiConfig */
deprecated class UntrustedDataToExternalAPIConfig = UntrustedDataToExternalApiConfig;

/** A node representing untrusted data being passed to an external API. */
class UntrustedExternalApiDataNode extends ExternalApiDataNode {
  UntrustedExternalApiDataNode() { any(UntrustedDataToExternalApiConfig c).hasFlow(_, this) }

  /** Gets a source of untrusted data which is passed to this external API data node. */
  DataFlow::Node getAnUntrustedSource() {
    any(UntrustedDataToExternalApiConfig c).hasFlow(result, this)
  }
}

/** DEPRECATED: Alias for UntrustedExternalApiDataNode */
deprecated class UntrustedExternalAPIDataNode = UntrustedExternalApiDataNode;

/** An external API which is used with untrusted data. */
private newtype TExternalApi =
  MkExternalApi(string repr, DataFlowPrivate::ArgumentPosition apos) {
    exists(UntrustedExternalApiDataNode ex, InterestingExternalApiCall call |
      ex = call.getArgument(apos) and
      repr = call.getApiName()
    )
  }

/** A argument of an external API which is used with untrusted data. */
class ExternalApiUsedWithUntrustedData extends MkExternalApi {
  string repr;
  DataFlowPrivate::ArgumentPosition apos;

  ExternalApiUsedWithUntrustedData() { this = MkExternalApi(repr, apos) }

  /** Gets a possibly untrusted use of this external API. */
  UntrustedExternalApiDataNode getUntrustedDataNode() {
    exists(InterestingExternalApiCall call |
      result = call.getArgument(apos) and
      call.getApiName() = repr
    )
  }

  /** Gets the number of untrusted sources used with this external API. */
  int getNumberOfUntrustedSources() {
    result = count(getUntrustedDataNode().getAnUntrustedSource())
  }

  /** Gets a textual representation of this element. */
  string toString() { result = repr + " [" + apos + "]" }
}

/** DEPRECATED: Alias for ExternalApiUsedWithUntrustedData */
deprecated class ExternalAPIUsedWithUntrustedData = ExternalApiUsedWithUntrustedData;