Update docs for barriers and barrier guards

Author: owen-mc

docs/codeql/codeql-language-guides/customizing-library-models-for-cpp.rst

@@ -178,6 +178,88 @@ The remaining values are used to define the input and output specifications, the
 - The ninth value ``"taint"`` is the kind of the flow. ``taint`` means that taint is propagated through the call.
 - The tenth value ``"manual"`` is the provenance of the summary, which is used to identify the origin of the summary model.
 
+Example: Taint barrier using the ``mysql_real_escape_string`` function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example shows how the CPP query pack models the ``mysql_real_escape_string`` function as a barrier for SQL injection.
+This function escapes special characters in a string for use in an SQL statement, which prevents SQL injection attacks.
+
+.. code-block:: cpp
+
+   char *query = "SELECT * FROM users WHERE name = '%s'";
+   char *name = get_untrusted_input();
+   char *escaped_name = new char[2 * strlen(name) + 1];
+   mysql_real_escape_string(mysql, escaped_name, name, strlen(name)); // The escaped_name is safe for SQL injection.
+   sprintf(query_buffer, query, escaped_name);
+
+We need to add a tuple to the ``barrierModel``\(namespace, type, subtypes, name, signature, ext, output, kind, provenance) extensible predicate by updating a data extension file.
+
+.. code-block:: yaml
+
+   extensions:
+     - addsTo:
+         pack: codeql/cpp-all
+         extensible: barrierModel
+       data:
+         - ["", "", False, "mysql_real_escape_string", "", "", "Argument[*1]", "sql-injection", "manual"]
+
+Since we are adding a barrier, we need to add a tuple to the ``barrierModel`` extensible predicate.
+The first five values identify the callable (in this case a free function) to be modeled as a barrier.
+
+- The first value ``""`` is the namespace name.
+- The second value ``""`` is the name of the type (class) that contains the method. Because we're modelling a free function, the type is left blank.
+- The third value ``False`` is a flag that indicates whether or not the barrier also applies to all overrides of the method. For a free function, this should be ``False``.
+- The fourth value ``"mysql_real_escape_string"`` is the function name.
+- The fifth value is the function input type signature, which can be used to narrow down between functions that have the same name.
+
+The sixth value should be left empty and is out of scope for this documentation.
+The remaining values are used to define the output specification, the ``kind``, and the ``provenance`` (origin) of the barrier.
+
+- The seventh value ``"Argument[*1]"`` is the output specification, which means in this case that the barrier is the first indirection (or pointed-to value, ``*``) of the second argument (``Argument[1]``) passed to the function.
+- The eighth value ``"sql-injection"`` is the kind of the barrier. The barrier kind is used to define the queries where the barrier is in scope.
+- The ninth value ``"manual"`` is the provenance of the barrier, which is used to identify the origin of the barrier model.
+
+Example: Add a barrier guard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example shows how to model a barrier guard that stops the flow of taint when a conditional check is performed on data.
+A barrier guard model is used when a function returns a boolean that indicates whether the data is safe to use.
+Consider a function called ``is_safe`` which returns ``true`` when the data is considered safe.
+
+.. code-block:: cpp
+
+   if (is_safe(user_input)) { // The check guards the use, so the input is safe.
+       mysql_query(user_input); // This is safe.
+   }
+
+We need to add a tuple to the ``barrierGuardModel``\(namespace, type, subtypes, name, signature, ext, input, acceptingvalue, kind, provenance) extensible predicate by updating a data extension file.
+
+.. code-block:: yaml
+
+   extensions:
+     - addsTo:
+         pack: codeql/cpp-all
+         extensible: barrierGuardModel
+       data:
+         - ["", "", False, "is_safe", "", "", "Argument[*0]", "true", "sql-injection", "manual"]
+
+Since we are adding a barrier guard, we need to add a tuple to the ``barrierGuardModel`` extensible predicate.
+The first five values identify the callable (in this case a free function) to be modeled as a barrier guard.
+
+- The first value ``""`` is the namespace name.
+- The second value ``""`` is the name of the type (class) that contains the method. Because we're modelling a free function, the type is left blank.
+- The third value ``False`` is a flag that indicates whether or not the barrier guard also applies to all overrides of the method. For a free function, this should be ``False``.
+- The fourth value ``"is_safe"`` is the function name.
+- The fifth value is the function input type signature, which can be used to narrow down between functions that have the same name.
+
+The sixth value should be left empty and is out of scope for this documentation.
+The remaining values are used to define the input specification, the ``accepting value``, the ``kind``, and the ``provenance`` (origin) of the barrier guard.
+
+- The seventh value ``Argument[*0]`` is the input specification (the value being validated). In this case, the first indirection (or pointed-to value, ``*``) of the first argument (``Argument[0]``) passed to the function.
+- The eighth value ``true`` is the accepting value of the barrier guard. This is the value that the conditional check must return for the barrier to apply.
+- The ninth value ``sql-injection`` is the kind of the barrier guard. The barrier guard kind is used to define the queries where the barrier guard is in scope.
+- The tenth value ``manual`` is the provenance of the barrier guard, which is used to identify the origin of the barrier guard.
+
 .. _threat-models-cpp:
 
 Threat models

docs/codeql/codeql-language-guides/customizing-library-models-for-csharp.rst

@@ -309,6 +309,90 @@ For the remaining values for both rows:
 
 That is, the first row specifies that values can flow from the elements of the qualifier enumerable into the first argument of the function provided to ``Select``.  The second row specifies that values can flow from the return value of the function to the elements of the enumerable returned from ``Select``.
 
+Example: Add a barrier for the ``RawUrl`` property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This example shows how we can model a property as a barrier for a specific kind of query.
+A barrier model is used to define that the flow of taint stops at the modeled element for the specified kind of query.
+Here we model the getter of the ``RawUrl`` property of the ``HttpRequest`` class as a barrier for URL redirection queries.
+The ``RawUrl`` property returns the raw URL of the current request, which is considered safe for URL redirects because it is the URL of the current request and cannot be manipulated by an attacker.
+
+.. code-block:: csharp
+
+   public static void TaintBarrier(HttpRequest request) {
+       string url = request.RawUrl; // The return value of this property is considered safe for URL redirects.
+       Response.Redirect(url); // This is not a URL redirection vulnerability.
+   }
+
+We need to add a tuple to the ``barrierModel``\(namespace, type, subtypes, name, signature, ext, output, kind, provenance) extensible predicate by updating a data extension file.
+
+.. code-block:: yaml
+
+   extensions:
+     - addsTo:
+         pack: codeql/csharp-all
+         extensible: barrierModel
+       data:
+         - ["System.Web", "HttpRequest", False, "get_RawUrl", "()", "", "ReturnValue", "url-redirection", "manual"]
+
+Since we are adding a barrier, we need to add a tuple to the ``barrierModel`` extensible predicate.
+The first five values identify the callable (in this case the getter of a property) to be modeled as a barrier.
+
+- The first value ``System.Web`` is the namespace name.
+- The second value ``HttpRequest`` is the class (type) name.
+- The third value ``False`` is a flag that indicates whether or not the barrier also applies to all overrides of the method.
+- The fourth value ``get_RawUrl`` is the method name. Getter and setter methods are named ``get_<name>`` and ``set_<name>`` respectively.
+- The fifth value ``()`` is the method input type signature.
+
+The sixth value should be left empty and is out of scope for this documentation.
+The remaining values are used to define the ``access path``, the ``kind``, and the ``provenance`` (origin) of the barrier.
+
+- The seventh value ``ReturnValue`` is the access path to the return value of the property getter, which means that the return value is considered safe.
+- The eighth value ``url-redirection`` is the kind of the barrier. The barrier kind is used to define the queries where the barrier is in scope. In this case - the URL redirection queries.
+- The ninth value ``manual`` is the provenance of the barrier, which is used to identify the origin of the barrier.
+
+Example: Add a barrier guard for the ``IsAbsoluteUri`` property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This example shows how we can model a property as a barrier guard for a specific kind of query.
+A barrier guard model is used to stop the flow of taint when a conditional check is performed on data.
+Here we model the getter of the ``IsAbsoluteUri`` property of the ``Uri`` class as a barrier guard for URL redirection queries.
+When the ``IsAbsoluteUri`` property returns ``false``, the URL is relative and therefore safe for URL redirects because it cannot redirect to an external site controlled by an attacker.
+
+.. code-block:: csharp
+
+   public static void TaintBarrierGuard(Uri uri) {
+       if (!uri.IsAbsoluteUri) { // The check guards the redirect, so the URL is safe.
+           Response.Redirect(uri.ToString()); // This is not a URL redirection vulnerability.
+       }
+   }
+
+We need to add a tuple to the ``barrierGuardModel``\(namespace, type, subtypes, name, signature, ext, input, acceptingvalue, kind, provenance) extensible predicate by updating a data extension file.
+
+.. code-block:: yaml
+
+   extensions:
+     - addsTo:
+         pack: codeql/csharp-all
+         extensible: barrierGuardModel
+       data:
+         - ["System", "Uri", False, "get_IsAbsoluteUri", "()", "", "Argument[this]", "false", "url-redirection", "manual"]
+
+Since we are adding a barrier guard, we need to add a tuple to the ``barrierGuardModel`` extensible predicate.
+The first five values identify the callable (in this case the getter of a property) to be modeled as a barrier guard.
+
+- The first value ``System`` is the namespace name.
+- The second value ``Uri`` is the class (type) name.
+- The third value ``False`` is a flag that indicates whether or not the barrier guard also applies to all overrides of the method.
+- The fourth value ``get_IsAbsoluteUri`` is the method name. Getter and setter methods are named ``get_<name>`` and ``set_<name>`` respectively.
+- The fifth value ``()`` is the method input type signature.
+
+The sixth value should be left empty and is out of scope for this documentation.
+The remaining values are used to define the ``access path``, the ``accepting value``, the ``kind``, and the ``provenance`` (origin) of the barrier guard.
+
+- The seventh value ``Argument[this]`` is the access path to the input whose flow is blocked. In this case, the qualifier of the property access (``uri`` in the example).
+- The eighth value ``false`` is the accepting value of the barrier guard. This is the value that the conditional check must return for the barrier to apply. In this case, when ``IsAbsoluteUri`` is ``false``, the URL is relative and considered safe.
+- The ninth value ``url-redirection`` is the kind of the barrier guard. The barrier guard kind is used to define the queries where the barrier guard is in scope. In this case - the URL redirection queries.
+- The tenth value ``manual`` is the provenance of the barrier guard, which is used to identify the origin of the barrier guard.
+
 Example: Add a ``neutral`` method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This example shows how we can model a method as being neutral with respect to flow. We will also cover how to model a property by modeling the getter of the ``Now`` property of the ``DateTime`` class as neutral.

docs/codeql/codeql-language-guides/customizing-library-models-for-go.rst

@@ -341,6 +341,88 @@ The remaining values are used to define the ``access path``, the ``kind``, and t
 - The ninth value ``taint`` is the kind of the flow. ``taint`` means that taint is propagated through the call.
 - The tenth value ``manual`` is the provenance of the summary, which is used to identify the origin of the summary.
 
+Example: Add a barrier using the ``Htmlquote`` function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This example shows how the Go query pack models a barrier that stops the flow of taint.
+The ``Htmlquote`` function from the beego framework HTML-escapes a string, which prevents HTML injection attacks.
+
+.. code-block:: go
+
+    func Render(w http.ResponseWriter, r *http.Request) {
+        name := r.FormValue("name")
+        safe := beego.Htmlquote(name) // The return value of this function is safe to use in HTML.
+        ...
+    }
+
+We need to add a tuple to the ``barrierModel``\(package, type, subtypes, name, signature, ext, output, kind, provenance) extensible predicate by updating a data extension file.
+
+.. code-block:: yaml
+
+   extensions:
+     - addsTo:
+         pack: codeql/go-all
+         extensible: barrierModel
+       data:
+         - ["group:beego", "", True, "Htmlquote", "", "", "ReturnValue", "html-injection", "manual"]
+
+Since we are adding a barrier, we need to add a tuple to the ``barrierModel`` extensible predicate.
+The first five values identify the function to be modeled as a barrier.
+
+- The first value ``group:beego`` is the package group name. The ``group:`` prefix indicates that this is a package group, which is used to match multiple package paths that refer to the same package.
+- The second value ``""`` is left blank since the function is not a method of a type.
+- The third value ``True`` is a flag that indicates whether or not the barrier also applies to subtypes. This has no effect for non-method functions.
+- The fourth value ``Htmlquote`` is the function name.
+- The fifth value ``""`` is the input type signature. For Go it should always be an empty string.
+
+The sixth value should be left empty and is out of scope for this documentation.
+The remaining values are used to define the ``access path``, the ``kind``, and the ``provenance`` (origin) of the barrier.
+
+- The seventh value ``ReturnValue`` is the access path to the output of the barrier, which means that the return value is considered sanitized.
+- The eighth value ``html-injection`` is the kind of the barrier. The barrier kind must match the kind used in the query where the barrier should take effect. In this case, it matches the ``html-injection`` sink kind used by XSS queries.
+- The ninth value ``manual`` is the provenance of the barrier, which is used to identify the origin of the barrier.
+
+Example: Add a barrier guard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This example shows how to model a barrier guard that stops the flow of taint when a conditional check is performed on data.
+A barrier guard model is used when a function returns a boolean that indicates whether the data is safe to use.
+Consider a function called ``IsSafe`` which returns ``true`` when the data is considered safe for SQL injection.
+
+.. code-block:: go
+
+    func Query(db *sql.DB, input string) {
+        if example.IsSafe(input) { // The check guards the query, so the input is safe.
+            db.Query(input) // This is not a SQL injection vulnerability.
+        }
+    }
+
+We need to add a tuple to the ``barrierGuardModel``\(package, type, subtypes, name, signature, ext, input, acceptingvalue, kind, provenance) extensible predicate by updating a data extension file.
+
+.. code-block:: yaml
+
+   extensions:
+     - addsTo:
+         pack: codeql/go-all
+         extensible: barrierGuardModel
+       data:
+         - ["example.com/example", "", False, "IsSafe", "", "", "Argument[0]", "true", "sql-injection", "manual"]
+
+Since we are adding a barrier guard, we need to add a tuple to the ``barrierGuardModel`` extensible predicate.
+The first five values identify the function to be modeled as a barrier guard.
+
+- The first value ``example.com/example`` is the package name.
+- The second value ``""`` is left blank since the function is not a method of a type.
+- The third value ``False`` is a flag that indicates whether or not the barrier guard also applies to subtypes. This has no effect for non-method functions.
+- The fourth value ``IsSafe`` is the function name.
+- The fifth value ``""`` is the input type signature. For Go it should always be an empty string.
+
+The sixth value should be left empty and is out of scope for this documentation.
+The remaining values are used to define the ``access path``, the ``accepting value``, the ``kind``, and the ``provenance`` (origin) of the barrier guard.
+
+- The seventh value ``Argument[0]`` is the access path to the input whose flow is blocked. In this case, the first argument to the function (``input`` in the example).
+- The eighth value ``true`` is the accepting value of the barrier guard. This is the value that the conditional check must return for the barrier to apply. In this case, when ``IsSafe`` returns ``true``, the input is considered safe.
+- The ninth value ``sql-injection`` is the kind of the barrier guard. The barrier guard kind is used to define the queries where the barrier guard is in scope. In this case - the SQL injection queries.
+- The tenth value ``manual`` is the provenance of the barrier guard, which is used to identify the origin of the barrier guard.
+
 Example: Accessing the ``Body`` field of an HTTP request
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This example shows how we can model a field read as a source of tainted data.