config defaults: PATH_NAME and ::1 for proxy

* PATH_NAME is used like SCRIPT_NAME: include both * replicate changed forwarded-allow-ips default to proxy_allow_ips
benoitc · Aug 8, 2024 · 687b78d · 687b78d
1 parent 5bbf373
commit 687b78d
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 38 deletions.
diff --git a/docs/source/news.rst b/docs/source/news.rst
@@ -13,18 +13,20 @@ Changelog
 - sdist generation now explicitly excludes sphinx build folder (:pr:`3257`)
 - decode bytes-typed status (as can be passed by gevent) as utf-8 instead of raising `TypeError` (:pr:`2336`)
 - raise correct Exception when encounting invalid chunked requests (:pr:`3258`)
-- the SCRIPT_NAME header when received from allowed forwarders is no longer restricted for containing an underscore (:pr:`3192`)
+- the SCRIPT_NAME and PATH_INFO headers, when received from allowed forwarders, are no longer restricted for containing an underscore (:pr:`3192`)
+- include IPv6 loopback address ``[::1]`` in default for :ref:`forwarded-allow-ips` and :ref:`proxy-allow-ips` (:pr:`3192`)
 
 ** NOTE **
 
 - The SCRIPT_NAME change mitigates a regression that appeared first in the 22.0.0 release
-- Review your ``forwarded-allow-ips`` setting if you are still not seeing the SCRIPT_NAME transmitted
+- Review your :ref:`forwarded-allow-ips` setting if you are still not seeing the SCRIPT_NAME transmitted
+- Review your :ref:`forwarder-headers` setting if you are missing headers after upgrading from a version prior to 22.0.0
 
 ** Breaking changes **
 
 - refuse requests where the uri field is empty (:pr:`3255`)
 - refuse requests with invalid CR/LR/NUL in heade field values (:pr:`3253`)
-- remove temporary `--tolerate-dangerous-framing` switch from 22.0 (:pr:`3260`)
+- remove temporary ``--tolerate-dangerous-framing`` switch from 22.0 (:pr:`3260`)
 - If any of the breaking changes affect you, be aware that now refused requests can post a security problem, especially so in setups involving request pipe-lining and/or proxies.
 
 22.0.0 - 2024-04-17

diff --git a/docs/source/settings.rst b/docs/source/settings.rst
@@ -1208,7 +1208,7 @@ temporary directory.
 
 A dictionary containing headers and values that the front-end proxy
 uses to indicate HTTPS requests. If the source IP is permitted by
-``forwarded-allow-ips`` (below), *and* at least one request header matches
+:ref:`forwarded-allow-ips` (below), *and* at least one request header matches
 a key-value pair listed in this dictionary, then Gunicorn will set
 ``wsgi.url_scheme`` to ``https``, so your application can tell that the
 request is secure.
@@ -1235,16 +1235,21 @@ the headers defined here can not be passed directly from the client.
 **Default:** ``'127.0.0.1,::1'``
 
 Front-end's IPs from which allowed to handle set secure headers.
-(comma separate).
+(comma separated).
 
-Set to ``*`` to disable checking of Front-end IPs. This is useful for setups
-where you don't know in advance the IP address of Front-end, but
-instead have ensured via other means that none other than your
-authorized Front-ends can access gunicorn.
+Set to ``*`` to disable checking of front-end IPs. This is useful for setups
+where you don't know in advance the IP address of front-end, but
+instead have ensured via other means that only your
+authorized front-ends can access Gunicorn.
 
 By default, the value of the ``FORWARDED_ALLOW_IPS`` environment
 variable. If it is not defined, the default is ``"127.0.0.1,::1"``.
 
+.. note::
+
+    This option does not affect UNIX socket connections. Connections not associated with
+    an IP address are treated as allowed, unconditionally.
+
 .. note::
 
     The interplay between the request headers, the value of ``forwarded_allow_ips``, and the value of
@@ -1370,13 +1375,19 @@ Example for stunnel config::
 
 **Command line:** ``--proxy-allow-from``
 
-**Default:** ``'127.0.0.1'``
+**Default:** ``'127.0.0.1,::1'``
 
-Front-end's IPs from which allowed accept proxy requests (comma separate).
+Front-end's IPs from which allowed accept proxy requests (comma separated).
+
+Set to ``*`` to disable checking of front-end IPs. This is useful for setups
+where you don't know in advance the IP address of front-end, but
+instead have ensured via other means that only your
+authorized front-ends can access Gunicorn.
+
+.. note::
 
-Set to ``*`` to disable checking of Front-end IPs (useful for setups
-where you don't know in advance the IP address of Front-end, but
-you still trust the environment)
+    This option does not affect UNIX socket connections. Connections not associated with
+    an IP address are treated as allowed, unconditionally.
 
 .. _raw-paste-global-conf:
 
@@ -1486,14 +1497,15 @@ Use with care and only if necessary. Deprecated; scheduled for removal in 24.0.0
 
 **Command line:** ``--forwarder-headers``
 
-**Default:** ``'SCRIPT_NAME'``
+**Default:** ``'SCRIPT_NAME,PATH_INFO'``
 
 A list containing upper-case header field names that the front-end proxy
-sets, to be used in WSGI environment.
+(see :ref:`forwarded-allow-ips`) sets, to be used in WSGI environment.
 
-If headers named in this list are not present in the request, they will be ignored.
+This option has no effect for headers not present in the request.
 
-This option can be used to transfer SCRIPT_NAME and REMOTE_USER.
+This option can be used to transfer ``SCRIPT_NAME``, ``PATH_INFO``
+and ``REMOTE_USER``.
 
 It is important that your front-end proxy configuration ensures that
 the headers defined here can not be passed directly from the client.
@@ -1518,8 +1530,8 @@ The value ``refuse`` will return an error if a request contains *any* such heade
 The value ``dangerous`` matches the previous, not advisable, behaviour of mapping different
 header field names into the same environ name.
 
-If the source IP is permitted by ``forwarded-allow-ips``, *and* the header name is
-present in ``forwarder-headers``, the header is mapped into environment regardless of
+If the source is permitted as explained in :ref:`forwarded-allow-ips`, *and* the header name is
+present in :ref:`forwarder-headers`, the header is mapped into environment regardless of
 the state of this setting.
 
 Use with care and only if necessary and after considering if your problem could

diff --git a/gunicorn/config.py b/gunicorn/config.py
@@ -1250,7 +1250,7 @@ class SecureSchemeHeader(Setting):
 
         A dictionary containing headers and values that the front-end proxy
         uses to indicate HTTPS requests. If the source IP is permitted by
-        ``forwarded-allow-ips`` (below), *and* at least one request header matches
+        :ref:`forwarded-allow-ips` (below), *and* at least one request header matches
         a key-value pair listed in this dictionary, then Gunicorn will set
         ``wsgi.url_scheme`` to ``https``, so your application can tell that the
         request is secure.
@@ -1278,16 +1278,21 @@ class ForwardedAllowIPS(Setting):
     default = os.environ.get("FORWARDED_ALLOW_IPS", "127.0.0.1,::1")
     desc = """\
         Front-end's IPs from which allowed to handle set secure headers.
-        (comma separate).
+        (comma separated).
 
-        Set to ``*`` to disable checking of Front-end IPs. This is useful for setups
-        where you don't know in advance the IP address of Front-end, but
-        instead have ensured via other means that none other than your
-        authorized Front-ends can access gunicorn.
+        Set to ``*`` to disable checking of front-end IPs. This is useful for setups
+        where you don't know in advance the IP address of front-end, but
+        instead have ensured via other means that only your
+        authorized front-ends can access Gunicorn.
 
         By default, the value of the ``FORWARDED_ALLOW_IPS`` environment
         variable. If it is not defined, the default is ``"127.0.0.1,::1"``.
 
+        .. note::
+
+            This option does not affect UNIX socket connections. Connections not associated with
+            an IP address are treated as allowed, unconditionally.
+
         .. note::
 
             The interplay between the request headers, the value of ``forwarded_allow_ips``, and the value of
@@ -2075,14 +2080,20 @@ class ProxyAllowFrom(Setting):
     name = "proxy_allow_ips"
     section = "Server Mechanics"
     cli = ["--proxy-allow-from"]
-    validator = validate_string_to_list
-    default = "127.0.0.1"
+    validator = validate_string_to_addr_list
+    default = "127.0.0.1,::1"
     desc = """\
-        Front-end's IPs from which allowed accept proxy requests (comma separate).
+        Front-end's IPs from which allowed accept proxy requests (comma separated).
+
+        Set to ``*`` to disable checking of front-end IPs. This is useful for setups
+        where you don't know in advance the IP address of front-end, but
+        instead have ensured via other means that only your
+        authorized front-ends can access Gunicorn.
+
+        .. note::
 
-        Set to ``*`` to disable checking of Front-end IPs (useful for setups
-        where you don't know in advance the IP address of Front-end, but
-        you still trust the environment)
+            This option does not affect UNIX socket connections. Connections not associated with
+            an IP address are treated as allowed, unconditionally.
         """
 
 
@@ -2365,15 +2376,16 @@ class ForwarderHeaders(Setting):
     section = "Server Mechanics"
     cli = ["--forwarder-headers"]
     validator = validate_string_to_list
-    default = "SCRIPT_NAME"
+    default = "SCRIPT_NAME,PATH_INFO"
     desc = """\
 
         A list containing upper-case header field names that the front-end proxy
-        sets, to be used in WSGI environment.
+        (see :ref:`forwarded-allow-ips`) sets, to be used in WSGI environment.
 
-        If headers named in this list are not present in the request, they will be ignored.
+        This option has no effect for headers not present in the request.
 
-        This option can be used to transfer SCRIPT_NAME and REMOTE_USER.
+        This option can be used to transfer ``SCRIPT_NAME``, ``PATH_INFO``
+        and ``REMOTE_USER``.
 
         It is important that your front-end proxy configuration ensures that
         the headers defined here can not be passed directly from the client.
@@ -2398,8 +2410,8 @@ class HeaderMap(Setting):
         The value ``dangerous`` matches the previous, not advisable, behaviour of mapping different
         header field names into the same environ name.
 
-        If the source IP is permitted by ``forwarded-allow-ips``, *and* the header name is
-        present in ``forwarder-headers``, the header is mapped into environment regardless of
+        If the source is permitted as explained in :ref:`forwarded-allow-ips`, *and* the header name is
+        present in :ref:`forwarder-headers`, the header is mapped into environment regardless of
         the state of this setting.
 
         Use with care and only if necessary and after considering if your problem could