Merge pull request #16250 from owen-mc/go/rename-untrusted-flow-source

Go: Rename `UntrustedFlowSource` to `RemoteFlowSource` to match other language libraries

Author: owen-mc

docs/codeql/codeql-language-guides/modeling-data-flow-in-go-libraries.rst

@@ -15,14 +15,14 @@ Sources
 -------
 
 To mark a source of data that is controlled by an untrusted user, we
-create a class extending ``UntrustedFlowSource::Range``. Inheritance and
+create a class extending ``RemoteFlowSource::Range``. Inheritance and
 the characteristic predicate of the class should be used to specify
 exactly the dataflow node that introduces the data. Here is a short
 example from ``Mux.qll``.
 
 .. code-block:: ql
 
-   class RequestVars extends DataFlow::UntrustedFlowSource::Range, DataFlow::CallNode {
+   class RequestVars extends DataFlow::RemoteFlowSource::Range, DataFlow::CallNode {
      RequestVars() { this.getTarget().hasQualifiedName("github.com/gorilla/mux", "Vars") }
    }
 

go/docs/language/learn-ql/go/library-modeling-go.rst

@@ -13,14 +13,14 @@ Sources
 -------
 
 To mark a source of data that is controlled by an untrusted user, we
-create a class extending ``UntrustedFlowSource::Range``. Inheritance and
+create a class extending ``RemoteFlowSource::Range``. Inheritance and
 the characteristic predicate of the class should be used to specify
 exactly the dataflow node that introduces the data. Here is a short
 example from ``Mux.qll``.
 
 .. code-block:: ql
 
-   class RequestVars extends DataFlow::UntrustedFlowSource::Range, DataFlow::CallNode {
+   class RequestVars extends DataFlow::RemoteFlowSource::Range, DataFlow::CallNode {
      RequestVars() { this.getTarget().hasQualifiedName("github.com/gorilla/mux", "Vars") }
    }
 
@@ -119,4 +119,4 @@ Here is a short example from ``Stdlib.qll``, which has been slightly simplified.
 This has the effect that any call to ``Print``, ``Printf``, or
 ``Println`` in the package ``fmt`` is recognized as a logger call.
 Any query that uses logger calls as a sink will then identify when tainted data 
-has been passed as an argument to ``Print``, ``Printf``, or ``Println``.
+has been passed as an argument to ``Print``, ``Printf``, or ``Println``.

go/ql/lib/change-notes/2024-04-18-untrustedflowsource-renamed-remoteflowsource.md

@@ -0,0 +1,5 @@
+---
+category: deprecated
+---
+* To make Go consistent with other language libraries, the `UntrustedFlowSource` name has been deprecated throughout. Use `RemoteFlowSource` instead, which replaces it. 
+* Where modules have classes named `UntrustedFlowAsSource`, these are also deprecated and the `Source` class in the same module or the `RemoteFlowSource` class should be used instead.

go/ql/lib/semmle/go/frameworks/AwsLambda.qll

@@ -1,12 +1,12 @@
 /**
- * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * Provides classes for working with remote flow sources, sinks and taint propagators
  * from the `github.com/aws/aws-lambda-go/lambda` package.
  */
 
 import go
 
 /** A source of input data in an AWS Lambda. */
-private class LambdaInput extends UntrustedFlowSource::Range {
+private class LambdaInput extends RemoteFlowSource::Range {
   LambdaInput() {
     exists(Parameter p | p = this.asParameter() |
       p = any(HandlerFunction hf).getAParameter() and

go/ql/lib/semmle/go/frameworks/Beego.qll

@@ -1,5 +1,5 @@
 /**
- * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * Provides classes for working with remote flow sources, sinks and taint propagators
  * from the `github.com/beego/beego` package.
  */
 
@@ -9,7 +9,7 @@ private import semmle.go.security.SafeUrlFlowCustomizations
 
 // Some TaintTracking::FunctionModel subclasses remain because varargs functions don't work with Models-as-Data sumamries yet.
 /**
- * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * Provides classes for working with remote flow sources, sinks and taint propagators
  * from the [Beego](https://github.com/beego/beego) package.
  */
 module Beego {
@@ -50,7 +50,7 @@ module Beego {
   /**
    * `BeegoInput` sources of untrusted data.
    */
-  private class BeegoInputSource extends UntrustedFlowSource::Range {
+  private class BeegoInputSource extends RemoteFlowSource::Range {
     string methodName;
 
     BeegoInputSource() {
@@ -81,7 +81,7 @@ module Beego {
   /**
    * `beego.Controller` sources of untrusted data.
    */
-  private class BeegoControllerSource extends UntrustedFlowSource::Range {
+  private class BeegoControllerSource extends RemoteFlowSource::Range {
     BeegoControllerSource() {
       exists(string methodName, FunctionOutput output |
         methodName = "ParseForm" and
@@ -105,7 +105,7 @@ module Beego {
   /**
    * `BeegoInputRequestBody` sources of untrusted data.
    */
-  private class BeegoInputRequestBodySource extends UntrustedFlowSource::Range {
+  private class BeegoInputRequestBodySource extends RemoteFlowSource::Range {
     BeegoInputRequestBodySource() {
       exists(DataFlow::FieldReadNode frn | this = frn |
         frn.getField().hasQualifiedName(contextPackagePath(), "BeegoInput", "RequestBody")
@@ -116,7 +116,7 @@ module Beego {
   /**
    * `beego/context.Context` sources of untrusted data.
    */
-  private class BeegoContextSource extends UntrustedFlowSource::Range {
+  private class BeegoContextSource extends RemoteFlowSource::Range {
     BeegoContextSource() {
       exists(Method m | m.hasQualifiedName(contextPackagePath(), "Context", "GetCookie") |
         this = m.getACall().getResult()

go/ql/lib/semmle/go/frameworks/BeegoOrm.qll

@@ -1,13 +1,13 @@
 /**
- * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * Provides classes for working with remote flow sources, sinks and taint propagators
  * from the `github.com/astaxie/beego/orm` subpackage.
  */
 
 import go
 private import semmle.go.security.StoredXssCustomizations
 
 /**
- * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * Provides classes for working with remote flow sources, sinks and taint propagators
  * from the [Beego ORM](https://github.com/astaxie/beego/orm) subpackage.
  */
 module BeegoOrm {

go/ql/lib/semmle/go/frameworks/Chi.qll

@@ -1,5 +1,5 @@
 /**
- * Provides classes for working with untrusted flow sources from the `github.com/go-chi/chi` package.
+ * Provides classes for working with remote flow sources from the `github.com/go-chi/chi` package.
  */
 
 import go
@@ -9,18 +9,18 @@ private module Chi {
   string packagePath() { result = package("github.com/go-chi/chi", "") }
 
   /**
-   * Functions that extract URL parameters, considered as a source of untrusted flow.
+   * Functions that extract URL parameters, considered as a source of remote flow.
    */
-  private class UserControlledFunction extends UntrustedFlowSource::Range, DataFlow::CallNode {
+  private class UserControlledFunction extends RemoteFlowSource::Range, DataFlow::CallNode {
     UserControlledFunction() {
       this.getTarget().hasQualifiedName(packagePath(), ["URLParam", "URLParamFromCtx"])
     }
   }
 
   /**
-   * Methods that extract URL parameters, considered as a source of untrusted flow.
+   * Methods that extract URL parameters, considered as a source of remote flow.
    */
-  private class UserControlledRequestMethod extends UntrustedFlowSource::Range,
+  private class UserControlledRequestMethod extends RemoteFlowSource::Range,
     DataFlow::MethodCallNode
   {
     UserControlledRequestMethod() {

go/ql/lib/semmle/go/frameworks/Echo.qll

@@ -1,5 +1,5 @@
 /**
- * Provides classes for working with untrusted flow sources, taint propagators, and HTTP sinks
+ * Provides classes for working with remote flow sources, taint propagators, and HTTP sinks
  * from the `github.com/labstack/echo` package.
  */
 
@@ -10,9 +10,9 @@ private module Echo {
   private string packagePath() { result = package("github.com/labstack/echo", "") }
 
   /**
-   * Data from a `Context` interface method, considered as a source of untrusted flow.
+   * Data from a `Context` interface method, considered as a source of remote flow.
    */
-  private class EchoContextSource extends UntrustedFlowSource::Range {
+  private class EchoContextSource extends RemoteFlowSource::Range {
     EchoContextSource() {
       exists(DataFlow::MethodCallNode call, string methodName |
         methodName =
@@ -42,7 +42,7 @@ private module Echo {
   /**
    * A call to a method on `Context` struct that unmarshals data into a target.
    */
-  private class EchoContextBinder extends UntrustedFlowSource::Range {
+  private class EchoContextBinder extends RemoteFlowSource::Range {
     EchoContextBinder() {
       exists(DataFlow::MethodCallNode call |
         call.getTarget().hasQualifiedName(packagePath(), "Context", "Bind")

go/ql/lib/semmle/go/frameworks/ElazarlGoproxy.qll

@@ -95,7 +95,7 @@ module ElazarlGoproxy {
     }
   }
 
-  private class UserControlledRequestData extends UntrustedFlowSource::Range {
+  private class UserControlledRequestData extends RemoteFlowSource::Range {
     UserControlledRequestData() {
       exists(DataFlow::FieldReadNode frn | this = frn |
         // liberally consider ProxyCtx.UserData to be untrusted; it's a data field set by a request handler

go/ql/lib/semmle/go/frameworks/Fasthttp.qll

@@ -1,5 +1,5 @@
 /**
- * Provides classes for working with untrusted flow sources, sinks and taint propagators
+ * Provides classes for working with remote flow sources, sinks and taint propagators
  * from the `github.com/valyala/fasthttp` package.
  */
 
@@ -255,11 +255,16 @@ module Fasthttp {
    * Provide modeling for fasthttp.URI Type.
    */
   module URI {
+    /**
+     * DEPRECATED: Use `RemoteFlowSource` instead.
+     */
+    deprecated class UntrustedFlowSource = RemoteFlowSource;
+
     /**
      * The methods as Remote user controllable source which are part of the incoming URL.
      */
-    class UntrustedFlowSource extends UntrustedFlowSource::Range instanceof DataFlow::Node {
-      UntrustedFlowSource() {
+    class RemoteFlowSource extends RemoteFlowSource::Range instanceof DataFlow::Node {
+      RemoteFlowSource() {
         exists(Method m |
           m.hasQualifiedName(packagePath(), "URI",
             ["FullURI", "LastPathSegment", "Path", "PathOriginal", "QueryString", "String"]) and
@@ -273,13 +278,18 @@ module Fasthttp {
    * Provide modeling for fasthttp.Args Type.
    */
   module Args {
+    /**
+     * DEPRECATED: Use `RemoteFlowSource` instead.
+     */
+    deprecated class UntrustedFlowSource = RemoteFlowSource;
+
     /**
      * The methods as Remote user controllable source which are part of the incoming URL Parameters.
      *
      * When support for lambdas has been implemented we should model "VisitAll".
      */
-    class UntrustedFlowSource extends UntrustedFlowSource::Range instanceof DataFlow::Node {
-      UntrustedFlowSource() {
+    class RemoteFlowSource extends RemoteFlowSource::Range instanceof DataFlow::Node {
+      RemoteFlowSource() {
         exists(Method m |
           m.hasQualifiedName(packagePath(), "Args",
             ["Peek", "PeekBytes", "PeekMulti", "PeekMultiBytes", "QueryString", "String"]) and
@@ -386,11 +396,16 @@ module Fasthttp {
    * Provide modeling for fasthttp.Request Type.
    */
   module Request {
+    /**
+     * DEPRECATED: Use `RemoteFlowSource` instead.
+     */
+    deprecated class UntrustedFlowSource = RemoteFlowSource;
+
     /**
      * The methods as Remote user controllable source which can be many part of request.
      */
-    class UntrustedFlowSource extends UntrustedFlowSource::Range instanceof DataFlow::Node {
-      UntrustedFlowSource() {
+    class RemoteFlowSource extends RemoteFlowSource::Range instanceof DataFlow::Node {
+      RemoteFlowSource() {
         exists(Method m |
           m.hasQualifiedName(packagePath(), "Request",
             [
@@ -463,13 +478,18 @@ module Fasthttp {
       override Http::ResponseWriter getResponseWriter() { none() }
     }
 
+    /**
+     * DEPRECATED: Use `RemoteFlowSource` instead.
+     */
+    deprecated class UntrustedFlowSource = RemoteFlowSource;
+
     /**
      * The methods as Remote user controllable source which are generally related to HTTP request.
      *
      * When support for lambdas has been implemented we should model "VisitAll", "VisitAllCookie", "VisitAllInOrder", "VisitAllTrailer".
      */
-    class UntrustedFlowSource extends UntrustedFlowSource::Range instanceof DataFlow::Node {
-      UntrustedFlowSource() {
+    class RemoteFlowSource extends RemoteFlowSource::Range instanceof DataFlow::Node {
+      RemoteFlowSource() {
         exists(Method m |
           m.hasQualifiedName(packagePath(), "RequestCtx",
             [
@@ -486,13 +506,18 @@ module Fasthttp {
    * Provide Methods of fasthttp.RequestHeader which mostly used as remote user controlled sources.
    */
   module RequestHeader {
+    /**
+     * DEPRECATED: Use `RemoteFlowSource` instead.
+     */
+    deprecated class UntrustedFlowSource = RemoteFlowSource;
+
     /**
      * The methods as Remote user controllable source which are mostly related to HTTP Request Headers.
      *
      * When support for lambdas has been implemented we should model "VisitAll", "VisitAllCookie", "VisitAllInOrder", "VisitAllTrailer".
      */
-    class UntrustedFlowSource extends UntrustedFlowSource::Range instanceof DataFlow::Node {
-      UntrustedFlowSource() {
+    class RemoteFlowSource extends RemoteFlowSource::Range instanceof DataFlow::Node {
+      RemoteFlowSource() {
         exists(Method m |
           m.hasQualifiedName(packagePath(), "RequestHeader",
             [

go/ql/lib/semmle/go/frameworks/Gin.qll

@@ -10,9 +10,9 @@ private module Gin {
   string packagePath() { result = package("github.com/gin-gonic/gin", "") }
 
   /**
-   * Data from a `Context` struct, considered as a source of untrusted flow.
+   * Data from a `Context` struct, considered as a source of remote flow.
    */
-  private class GithubComGinGonicGinContextSource extends UntrustedFlowSource::Range {
+  private class GithubComGinGonicGinContextSource extends RemoteFlowSource::Range {
     GithubComGinGonicGinContextSource() {
       // Method calls:
       exists(DataFlow::MethodCallNode call, string methodName |
@@ -39,7 +39,7 @@ private module Gin {
   /**
    * A call to a method on `Context` struct that unmarshals data into a target.
    */
-  private class GithubComGinGonicGinContextBindSource extends UntrustedFlowSource::Range {
+  private class GithubComGinGonicGinContextBindSource extends RemoteFlowSource::Range {
     GithubComGinGonicGinContextBindSource() {
       exists(DataFlow::MethodCallNode call, string methodName |
         call.getTarget().hasQualifiedName(packagePath(), "Context", methodName) and

go/ql/lib/semmle/go/frameworks/GoKit.qll

@@ -35,7 +35,7 @@ module GoKit {
       DataFlow::exprNode(result.(FuncLit)) = getAnEndpointFactoryResult()
     }
 
-    private class EndpointRequest extends UntrustedFlowSource::Range {
+    private class EndpointRequest extends RemoteFlowSource::Range {
       EndpointRequest() { this = DataFlow::parameterNode(getAnEndpointFunction().getParameter(1)) }
     }
   }

go/ql/lib/semmle/go/frameworks/GoMicro.qll

@@ -142,7 +142,7 @@ module GoMicro {
   /**
    * A set of remote requests from a service handler.
    */
-  class Request extends UntrustedFlowSource::Range instanceof DataFlow::ParameterNode {
+  class Request extends RemoteFlowSource::Range instanceof DataFlow::ParameterNode {
     Request() {
       exists(ServiceHandler handler |
         this.asParameter().isParameterOf(handler.getFuncDecl(), 1) and

go/ql/lib/semmle/go/frameworks/GoRestfulHttp.qll

@@ -27,14 +27,14 @@ private module GoRestfulHttp {
   /**
    * A model of go-restful's `Request` object as a source of user-controlled data.
    */
-  private class GoRestfulSource extends UntrustedFlowSource::Range {
+  private class GoRestfulSource extends RemoteFlowSource::Range {
     GoRestfulSource() { this = any(GoRestfulSourceMethod g).getACall() }
   }
 
   /**
    * A model of go-restful's `Request.ReadEntity` method as a source of user-controlled data.
    */
-  private class GoRestfulReadEntitySource extends UntrustedFlowSource::Range {
+  private class GoRestfulReadEntitySource extends RemoteFlowSource::Range {
     GoRestfulReadEntitySource() {
       exists(DataFlow::MethodCallNode call |
         call.getTarget().hasQualifiedName(packagePath(), "Request", "ReadEntity")

go/ql/lib/semmle/go/frameworks/Gqlgen.qll

@@ -39,7 +39,7 @@ module Gqlgen {
   }
 
   /** A parameter of a resolver method which receives untrusted input. */
-  class ResolverParameter extends UntrustedFlowSource::Range instanceof DataFlow::ParameterNode {
+  class ResolverParameter extends RemoteFlowSource::Range instanceof DataFlow::ParameterNode {
     ResolverParameter() {
       this.asParameter() = any(ResolverImplementationMethod h).getAnUntrustedParameter()
     }

go/ql/lib/semmle/go/frameworks/Mux.qll

@@ -9,7 +9,7 @@ import go
  */
 module Mux {
   /** An access to a Mux middleware variable. */
-  class RequestVars extends DataFlow::UntrustedFlowSource::Range, DataFlow::CallNode {
+  class RequestVars extends DataFlow::RemoteFlowSource::Range, DataFlow::CallNode {
     RequestVars() {
       this.getTarget().hasQualifiedName(package("github.com/gorilla/mux", ""), "Vars")
     }