Python: Add SSRF queries

docs/codeql/support/reusables/frameworks.rst

@@ -171,6 +171,7 @@ Python built-in support
    Twisted, Web framework
    Flask-Admin, Web framework
    starlette, Asynchronous Server Gateway Interface (ASGI)
+   requests, HTTP client
    dill, Serialization
    PyYAML, Serialization
    ruamel.yaml, Serialization

python/change-notes/2021-12-17-add-SSRF-queries.md

@@ -0,0 +1,3 @@
+lgtm,codescanning
+* Two new queries have been added for detecting Server-side request forgery (SSRF). _Full server-side request forgery_ (`py/full-ssrf`) will only alert when the URL is fully user-controlled, and _Partial server-side request forgery_ (`py/partial-ssrf`) will alert when any part of the URL is user-controlled. Only `py/full-ssrf` will be run by default.
+* To support the new SSRF queries, the PyPI package `requests` have been modeled, along with `http.client.HTTP[S]Connection` from the standard library.

python/ql/lib/semmle/python/Concepts.qll

@@ -812,6 +812,72 @@ module HTTP {
       }
     }
   }
+
+  /** Provides classes for modeling HTTP clients. */
+  module Client {
+    /**
+     * A data-flow node that makes an outgoing HTTP request.
+     *
+     * Extend this class to refine existing API models. If you want to model new APIs,
+     * extend `HTTP::Client::Request::Range` instead.
+     */
+    class Request extends DataFlow::Node instanceof Request::Range {
+      /**
+       * Gets a data-flow node that contributes to the URL of the request.
+       * Depending on the framework, a request may have multiple nodes which contribute to the URL.
+       */
+      DataFlow::Node getAUrlPart() { result = super.getAUrlPart() }
+
+      /** Gets a string that identifies the framework used for this request. */
+      string getFramework() { result = super.getFramework() }
+
+      /**
+       * Holds if this request is made using a mode that disables SSL/TLS
+       * certificate validation, where `disablingNode` represents the point at
+       * which the validation was disabled, and `argumentOrigin` represents the origin
+       * of the argument that disabled the validation (which could be the same node as
+       * `disablingNode`).
+       */
+      predicate disablesCertificateValidation(
+        DataFlow::Node disablingNode, DataFlow::Node argumentOrigin
+      ) {
+        super.disablesCertificateValidation(disablingNode, argumentOrigin)
+      }
+    }
+
+    /** Provides a class for modeling new HTTP requests. */
+    module Request {
+      /**
+       * A data-flow node that makes an outgoing HTTP request.
+       *
+       * Extend this class to model new APIs. If you want to refine existing API models,
+       * extend `HTTP::Client::Request` instead.
+       */
+      abstract class Range extends DataFlow::Node {
+        /**
+         * Gets a data-flow node that contributes to the URL of the request.
+         * Depending on the framework, a request may have multiple nodes which contribute to the URL.
+         */
+        abstract DataFlow::Node getAUrlPart();
+
+        /** Gets a string that identifies the framework used for this request. */
+        abstract string getFramework();
+
+        /**
+         * Holds if this request is made using a mode that disables SSL/TLS
+         * certificate validation, where `disablingNode` represents the point at
+         * which the validation was disabled, and `argumentOrigin` represents the origin
+         * of the argument that disabled the validation (which could be the same node as
+         * `disablingNode`).
+         */
+        abstract predicate disablesCertificateValidation(
+          DataFlow::Node disablingNode, DataFlow::Node argumentOrigin
+        );
+      }
+    }
+    // TODO: investigate whether we should treat responses to client requests as
+    // remote-flow-sources in general.
+  }
 }
 
 /**

python/ql/lib/semmle/python/Frameworks.qll

@@ -30,6 +30,7 @@ private import semmle.python.frameworks.Peewee
 private import semmle.python.frameworks.Psycopg2
 private import semmle.python.frameworks.Pydantic
 private import semmle.python.frameworks.PyMySQL
+private import semmle.python.frameworks.Requests
 private import semmle.python.frameworks.RestFramework
 private import semmle.python.frameworks.Rsa
 private import semmle.python.frameworks.RuamelYaml

python/ql/lib/semmle/python/frameworks/Requests.qll

@@ -0,0 +1,171 @@
+/**
+ * Provides classes modeling security-relevant aspects of the `requests` PyPI package.
+ *
+ * See
+ * - https://pypi.org/project/requests/
+ * - https://docs.python-requests.org/en/latest/
+ */
+
+private import python
+private import semmle.python.Concepts
+private import semmle.python.ApiGraphs
+private import semmle.python.dataflow.new.DataFlow
+private import semmle.python.dataflow.new.TaintTracking
+private import semmle.python.frameworks.internal.InstanceTaintStepsHelper
+private import semmle.python.frameworks.Stdlib
+
+/**
+ * INTERNAL: Do not use.
+ *
+ * Provides models for the `requests` PyPI package.
+ *
+ * See
+ * - https://pypi.org/project/requests/
+ * - https://docs.python-requests.org/en/latest/
+ */
+private module Requests {
+  private class OutgoingRequestCall extends HTTP::Client::Request::Range, DataFlow::CallCfgNode {
+    string methodName;
+
+    OutgoingRequestCall() {
+      methodName in [HTTP::httpVerbLower(), "request"] and
+      (
+        this = API::moduleImport("requests").getMember(methodName).getACall()
+        or
+        exists(API::Node moduleExporting, API::Node sessionInstance |
+          moduleExporting in [
+              API::moduleImport("requests"), //
+              API::moduleImport("requests").getMember("sessions")
+            ] and
+          sessionInstance = moduleExporting.getMember(["Session", "session"]).getReturn()
+        |
+          this = sessionInstance.getMember(methodName).getACall()
+        )
+      )
+    }
+
+    override DataFlow::Node getAUrlPart() {
+      result = this.getArgByName("url")
+      or
+      not methodName = "request" and
+      result = this.getArg(0)
+      or
+      methodName = "request" and
+      result = this.getArg(1)
+    }
+
+    /** Gets the `verify` argument to this outgoing requests call. */
+    DataFlow::Node getVerifyArg() { result = this.getArgByName("verify") }
+
+    override predicate disablesCertificateValidation(
+      DataFlow::Node disablingNode, DataFlow::Node argumentOrigin
+    ) {
+      disablingNode = this.getVerifyArg() and
+      argumentOrigin = verifyArgBacktracker(disablingNode) and
+      argumentOrigin.asExpr().(ImmutableLiteral).booleanValue() = false and
+      not argumentOrigin.asExpr() instanceof None
+    }
+
+    override string getFramework() { result = "requests" }
+  }
+
+  /**
+   * Extra taint propagation for outgoing requests calls,
+   * to ensure that responses to user-controlled URL are tainted.
+   */
+  private class OutgoingRequestCallTaintStep extends TaintTracking::AdditionalTaintStep {
+    override predicate step(DataFlow::Node nodeFrom, DataFlow::Node nodeTo) {
+      nodeFrom = nodeTo.(OutgoingRequestCall).getAUrlPart()
+    }
+  }
+
+  /** Gets a back-reference to the verify argument `arg`. */
+  private DataFlow::TypeTrackingNode verifyArgBacktracker(
+    DataFlow::TypeBackTracker t, DataFlow::Node arg
+  ) {
+    t.start() and
+    arg = any(OutgoingRequestCall c).getVerifyArg() and
+    result = arg.getALocalSource()
+    or
+    exists(DataFlow::TypeBackTracker t2 | result = verifyArgBacktracker(t2, arg).backtrack(t2, t))
+  }
+
+  /** Gets a back-reference to the verify argument `arg`. */
+  private DataFlow::LocalSourceNode verifyArgBacktracker(DataFlow::Node arg) {
+    result = verifyArgBacktracker(DataFlow::TypeBackTracker::end(), arg)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Response
+  // ---------------------------------------------------------------------------
+  /**
+   * Provides models for the `requests.models.Response` class
+   *
+   * See https://docs.python-requests.org/en/latest/api/#requests.Response.
+   */
+  module Response {
+    /** Gets a reference to the `requests.models.Response` class. */
+    private API::Node classRef() {
+      result = API::moduleImport("requests").getMember("models").getMember("Response")
+      or
+      result = API::moduleImport("requests").getMember("Response")
+    }
+
+    /**
+     * A source of instances of `requests.models.Response`, extend this class to model new instances.
+     *
+     * This can include instantiations of the class, return values from function
+     * calls, or a special parameter that will be set when functions are called by an external
+     * library.
+     *
+     * Use the predicate `Response::instance()` to get references to instances of `requests.models.Response`.
+     */
+    abstract class InstanceSource extends DataFlow::LocalSourceNode { }
+
+    /** A direct instantiation of `requests.models.Response`. */
+    private class ClassInstantiation extends InstanceSource, DataFlow::CallCfgNode {
+      ClassInstantiation() { this = classRef().getACall() }
+    }
+
+    /** Return value from making a reuqest. */
+    private class RequestReturnValue extends InstanceSource, DataFlow::Node {
+      RequestReturnValue() { this = any(OutgoingRequestCall c) }
+    }
+
+    /** Gets a reference to an instance of `requests.models.Response`. */
+    private DataFlow::TypeTrackingNode instance(DataFlow::TypeTracker t) {
+      t.start() and
+      result instanceof InstanceSource
+      or
+      exists(DataFlow::TypeTracker t2 | result = instance(t2).track(t2, t))
+    }
+
+    /** Gets a reference to an instance of `requests.models.Response`. */
+    DataFlow::Node instance() { instance(DataFlow::TypeTracker::end()).flowsTo(result) }
+
+    /**
+     * Taint propagation for `requests.models.Response`.
+     */
+    private class InstanceTaintSteps extends InstanceTaintStepsHelper {
+      InstanceTaintSteps() { this = "requests.models.Response" }
+
+      override DataFlow::Node getInstance() { result = instance() }
+
+      override string getAttributeName() {
+        result in ["text", "content", "raw", "links", "cookies", "headers"]
+      }
+
+      override string getMethodName() { result in ["json", "iter_content", "iter_lines"] }
+
+      override string getAsyncMethodName() { none() }
+    }
+
+    /** An attribute read that is a file-like instance. */
+    private class FileLikeInstances extends Stdlib::FileLikeObject::InstanceSource {
+      FileLikeInstances() {
+        this.(DataFlow::AttrRead).getObject() = instance() and
+        this.(DataFlow::AttrRead).getAttributeName() = "raw"
+      }
+    }
+  }
+}