Fixed #36778 -- Extended advice to sanitize input before using in query expressions.

Thanks Clifford Gama and Simon Charette for reviews.

3 files changed, 17 insertions, 4 deletions

diff --git a/docs/internals/security.txt b/docs/internals/security.txt
index 745f26f5f5..4eee394759 100644
--- a/docs/internals/security.txt
+++ b/docs/internals/security.txt
@@ -111,9 +111,11 @@ validated::
             return JsonResponse(status=200)
         return JsonResponse(form.errors, status=400)
 
-Similarly, as Django's raw SQL constructs (such as :meth:`~.QuerySet.extra` and
-:class:`.RawSQL` expression) provide developers with full control over the
-query, they are insecure if user input is not properly handled. As explained in
+Similarly, as Django's raw SQL constructs (such as :meth:`~.QuerySet.extra`,
+:class:`.RawSQL`, and :ref:`keyword arguments to database functions
+<avoiding-sql-injection-in-query-expressions>`) provide developers with full
+control over the query, they are insecure if user input is not properly
+handled. As explained in
 our :ref:`security documentation <sql-injection-protection>`, it is the
 developer's responsibility to safely process user input for these functions.
 
diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt
index 42bbb09956..76c6362da9 100644
--- a/docs/ref/models/database-functions.txt
+++ b/docs/ref/models/database-functions.txt
@@ -9,7 +9,8 @@ The classes documented below provide a way for users to use functions provided
 by the underlying database as annotations, aggregations, or filters in Django.
 Functions are also :doc:`expressions </ref/models/expressions>`, so they can be
 used and combined with other expressions like :ref:`aggregate functions
-<aggregation-functions>`.
+<aggregation-functions>`. See the :class:`~django.db.models.Func` documentation
+for security considerations.
 
 We'll be using the following model in examples of each function::
 
diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index 098feeb0e1..3238207c5b 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -434,6 +434,16 @@ replace the attributes of the same name without having to define your own
 class. :ref:`output_field<output-field>` can be used to define the expected
 return type.
 
+.. admonition:: Sanitize input used to configure a query expression
+
+    Built-in database functions (such as
+    :class:`~django.db.models.functions.Cast`) vary in whether arguments such
+    as ``output_field`` can be supplied positionally or only by keyword. For
+    ``output_field`` and several other cases, the input ultimately reaches
+    ``Func()`` as a keyword argument, so the advice to avoid constructing
+    keyword arguments from untrusted user input applies as equally to these
+    arguments as it does to ``**extra``.
+
 ``Aggregate()`` expressions
 ---------------------------