Skip to content

Commit 2e4e118

Browse files
GrahamDumpletonGrahamDumpleton
committed
Add changes notes and new documentation related to operation of trusted proxy feature.
1 parent af3c0c2 commit 2e4e118

File tree

3 files changed

+334
-0
lines changed

3 files changed

+334
-0
lines changed

‎docs/configuration-directives/WSGITrustedProxies.rst

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
==================
2+
WSGITrustedProxies
3+
==================
4+
5+
:Description: Specify a list of trusted proxies.
6+
:Syntax: ``WSGITrustedProxies`` *ipaddr|(ipaddr-1 ipaddr-2 ...)*
7+
:Context: server config, virtual host, directory, .htaccess
8+
:Override: ``FileInfo``
9+
10+
Used to specify a list of IP addresses for proxies placed in front of the
11+
Apache instance which are trusted.
12+
13+
This directive only has effect when used in conjunction with the
14+
``WSGITrustedProxyHeaders`` directive. For more details see the documentation
15+
for the ``WSGITrustedProxyHeaders`` directive.

‎docs/configuration-directives/WSGITrustedProxyHeaders.rst

+231
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
=======================
2+
WSGITrustedProxyHeaders
3+
=======================
4+
5+
:Description: Specify a list of trusted proxy headers.
6+
:Syntax: ``WSGITrustedProxyHeaders`` *header|(header-1 header-2 ...)*
7+
:Context: server config, virtual host, directory, .htaccess
8+
:Override: ``FileInfo``
9+
10+
When trusted proxies are designated, this is used to specify the headers
11+
which are used to convey information from a proxy to a web server behind the
12+
proxy that are to be trusted.
13+
14+
The IP addresses of the proxies to be trusted should be specified using the
15+
``WSGITrustedProxies`` directive.
16+
17+
As there are multiple conventions for what headers are used to convey
18+
information from the proxy to the web server you need to specify the specific
19+
header from a supported list of headers for a particular purpose that you want
20+
to trust using the ``WSGITrustedProxyHeaders`` directive.
21+
22+
When a request is then received from a trusted proxy, only the header from
23+
the set of headers for that particular purpose is passed through to the WSGI
24+
application and all others will be dropped. If a request was instead from an
25+
IP address which isn't a trusted proxy, then all headers in that set of headers
26+
will be dropped and not passed through.
27+
28+
Depending on the purpose of the header, modifications will be made to other
29+
special variables passed through to the WSGI application. It is these other
30+
variables which is what the WSGI application should consult and the original
31+
header should never be consulted, with it only being provided as an indication
32+
of which header was used to set the special variable.
33+
34+
The different sets of supported headers used by proxies are as follows.
35+
36+
For passing through the IP address of the remote HTTP client the supported
37+
headers are:
38+
39+
* X-Forwarded-For
40+
* X-Client-IP
41+
* X-Real-IP
42+
43+
You should select only one of these headers as the authoritative source for
44+
the IP address of the remote HTTP client as sent by the proxy. Never select
45+
multiple headers because if you do which will be used is indeterminate.
46+
47+
The de-facto standard for this type of header is ``X-Forwarded-For`` and it
48+
is recommended that it be used if your proxy supports it.
49+
50+
The configuration might therefore be::
51+
52+
WSGITrustedProxies 1.2.3.4
53+
WSGITrustedProxyHeaders X-Forwarded-For
54+
55+
With this configuration, when a request is received from the trusted proxy only
56+
the ``X-Forwarded-For`` header will be passed through to the WSGI application.
57+
This will be done following CGI convention as used by WSGI, namely in the
58+
``HTTP_X_FORWARDED_FOR`` variable.
59+
60+
For this set of headers, the ``REMOTE_ADDR`` CGI variable as used by WSGI will
61+
be modified and set to the IP address of the remote HTTP client. A WSGI
62+
application in this case should always use ``REMOTE_ADDR`` and never consult
63+
the original header files.
64+
65+
For passing through the protocol of the original request received by the
66+
trusted proxy the supported headers are:
67+
68+
* X-Forwarded-HTTPS
69+
* X-Forwarded-Proto
70+
* X-Forwarded-Scheme
71+
* X-Forwarded-SSL
72+
* X-HTTPS
73+
* X-Scheme
74+
75+
You should select only one of these headers as the authoritative source for what
76+
protocol was used by the remote HTTP client as sent by the proxy. Never select
77+
multiple headers because if you do which will be used is indeterminate.
78+
79+
The de-facto standard for this type of header is ``X-Forwarded-Proto`` and it
80+
is recommended that it be used if your proxy supports it.
81+
82+
The configuration might therefore be::
83+
84+
WSGITrustedProxies 1.2.3.4
85+
WSGITrustedProxyHeaders X-Forwarded-Proto
86+
87+
With this configuration, when a request is received from the trusted proxy only
88+
the ``X-Forwarded-Proto`` header will be passed through to the WSGI application.
89+
This will be done following CGI convention as used by WSGI, namely in the
90+
``HTTP_X_FORWARDED_PROTO`` variable.
91+
92+
For this set of headers, the ``wsgi.url_scheme`` variable passed to the WSGI
93+
application will be modified to indicate whether the original request used the
94+
``https`` protocol. Note that although it is a convention when using CGI
95+
scripts with Apache, the mod_wsgi module removes the ``HTTPS`` variable from
96+
the set of variables passed to the WSGI application. You should always use
97+
the ``wsgi.url_scheme`` variable in a WSGI application.
98+
99+
For passing through the host name targeted by the original request received by
100+
the trusted proxy the supported headers are:
101+
102+
* X-Forwarded-Host
103+
* X-Host
104+
105+
You should select only one of these headers as the authoritative source for the
106+
host targeted by the original request as sent by the proxy. Never select
107+
multiple headers because if you do which will be used is indeterminate.
108+
109+
The de-facto standard for this type of header is ``X-Forwarded-Host`` and it
110+
is recommended that it be used if your proxy supports it.
111+
112+
The configuration might therefore be::
113+
114+
WSGITrustedProxies 1.2.3.4
115+
WSGITrustedProxyHeaders X-Forwarded-Host
116+
117+
With this configuration, when a request is received from the trusted proxy only
118+
the ``X-Forwarded-Host`` header will be passed through to the WSGI application.
119+
This will be done following CGI convention as used by WSGI, namely in the
120+
``HTTP_X_FORWARDED_HOST`` variable.
121+
122+
For this set of headers, the ``HTTP_HOST`` variable passed to the WSGI
123+
application will be overridden with the value from the header supplied by the
124+
proxy. That is, the value from the proxy for the original request will even
125+
override any explicit ``Host`` header supplied in the request from the proxy,
126+
which in normal cases would be the host of the web server. A WSGI application
127+
should always consult the ``HTTP_HOST`` variable and not the separate header
128+
supplied by the proxy.
129+
130+
For passing through the port targeted by the original request received by the
131+
trusted proxy, the only supported header is:
132+
133+
* X-Forwarded-Port
134+
135+
Although it is the only supported header, you still must select if as a trusted
136+
header to have it processed in the same way as other trusted headers.
137+
138+
The configuration might therefore be::
139+
140+
WSGITrustedProxies 1.2.3.4
141+
WSGITrustedProxyHeaders X-Forwarded-Port
142+
143+
With this configuration, when a request is received from the trusted proxy only
144+
the ``X-Forwarded-Port`` header will be passed through to the WSGI application.
145+
This will be done following CGI convention as used by WSGI, namely in the
146+
``HTTP_X_FORWARDED_PORT`` variable.
147+
148+
For this header, the ``SERVER_PORT`` variable passed to the WSGI application
149+
will be overridden with the value from the header supplied by the proxy. A WSGI
150+
application should always consult the ``SERVER_PORT`` variable and not the
151+
separate header supplied by the proxy.
152+
153+
For passing through the host name of any proxy, to use in overriding the host
154+
name of the web server, the only supported header is:
155+
156+
* X-Forwarded-Server
157+
158+
Although it is the only supported header, you still must select if as a trusted
159+
header to have it processed in the same way as other trusted headers.
160+
161+
The configuration might therefore be::
162+
163+
WSGITrustedProxies 1.2.3.4
164+
WSGITrustedProxyHeaders X-Forwarded-Server
165+
166+
With this configuration, when a request is received from the trusted proxy only
167+
the ``X-Forwarded-Server`` header will be passed through to the WSGI application.
168+
This will be done following CGI convention as used by WSGI, namely in the
169+
``HTTP_X_FORWARDED_SERVER`` variable.
170+
171+
For this header, the ``SERVER_NAME`` variable passed to the WSGI application
172+
will be overridden with the value from the header supplied by the proxy. A WSGI
173+
application should always consult the ``SERVER_NAME`` variable and not the
174+
separate header supplied by the proxy.
175+
176+
For passing through the apparent URL sub path of a web application, as mapped
177+
by the trusted proxy, the supported headers are:
178+
179+
* X-Script-Name
180+
* X-Forwarded-Script-Name
181+
182+
You should select only one of these headers as the authoritative source for the
183+
host targeted by the original request as sent by the proxy. Never select
184+
multiple headers because if you do which will be used is indeterminate.
185+
186+
The configuration might therefore be::
187+
188+
WSGITrustedProxies 1.2.3.4
189+
WSGITrustedProxyHeaders X-Script-Name
190+
191+
With this configuration, when a request is received from the trusted proxy only
192+
the ``X-Script-Name`` header will be passed through to the WSGI application.
193+
This will be done following CGI convention as used by WSGI, namely in the
194+
``HTTP_X_SCRIPT_NAME`` variable.
195+
196+
For this header, the ``SCRIPT_NAME`` variable passed to the WSGI application
197+
will be overridden with the value from the header supplied by the proxy. A WSGI
198+
application should always consult the ``SCRIPT_NAME`` variable and not the
199+
separate header supplied by the proxy.
200+
201+
Examples above show using a single header of a specific purpose at one time.
202+
When you need to trust multiple headers for different purposes, you can list
203+
them separated by spaces using one instance of ``WSGITrustedProxyHeaders``::
204+
205+
WSGITrustedProxyHeaders X-Forwarded-For X-Forwarded-Host X-Forwarded-Port
206+
207+
or in separate directives::
208+
209+
WSGITrustedProxyHeaders X-Forwarded-For
210+
WSGITrustedProxyHeaders X-Forwarded-Host
211+
WSGITrustedProxyHeaders X-Forwarded-Port
212+
213+
As already highlighted you should only list one header for a specific purpose
214+
when there are multiple conventions for what header to use. Which you use will
215+
depend on the configuration of your proxy. You should only trust headers which
216+
are always set by the proxy, never trust headers which are optionally set by
217+
proxies because if not overridden by a proxy, a remote client could still
218+
supply the header.
219+
220+
Also remember that in general you should not consult the proxied headers
221+
themselves, but instead consult the special variables set from those headers
222+
which are passed to the WSGI application and which are defined as being special
223+
to WSGI. As illustration of how such special variables are used, consider
224+
for example the notes in the WSGI specification around URL reconstruction.
225+
226+
* https://peps.python.org/pep-3333/#url-reconstruction
227+
228+
Finally, if using this feature to trust proxies and designated headers, do not
229+
enable in any WSGI framework or application separate functionality it may have
230+
for also processing the proxy headers. You should only rely on what mod_wsgi
231+
has done to update variables special to WSGI.

‎docs/release-notes/version-4.9.3.rst

+88
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,91 @@ Version 4.9.3
55
Version 4.9.3 of mod_wsgi can be obtained from:
66

77
https://codeload.github.com/GrahamDumpleton/mod_wsgi/tar.gz/4.9.3
8+
9+
Bugs Fixed
10+
----------
11+
12+
* When using ``WSGITrustedProxies`` and ``WSGITrustedProxyHeaders`` in the
13+
Apache configuration, or ``--trust-proxy`` and ``--trust-proxy-header``
14+
options with ``mod_wsgi-express``, if you trusted the ``X-Client-IP``
15+
header and a request was received from an untrusted client, the header
16+
was not being correctly removed from the set of headers passed through to
17+
the WSGI application.
18+
19+
This only occurred with the ``X-Client-IP`` header and the same problem was
20+
not present if trusting the ``X-Real-IP`` or ``X-Forwarded-For`` headers.
21+
22+
The purpose of this feature for trusting a front end proxy was in this
23+
case for the headers:
24+
25+
* ``X-Client-IP``
26+
* ``X-Real-IP``
27+
* ``X-Forwarded-For``
28+
29+
and was designed to allow the value of ``REMOTE_ADDR`` passed to the WSGI
30+
application to be rewritten to the IP address that a trusted proxy said
31+
was the real remote address of the client.
32+
33+
In other words, if a request was received from a proxy the IP address
34+
of which was trusted, ``REMOTE_ADDR`` would be set to the value of the
35+
single designated header out of those listed above which was to be
36+
trusted.
37+
38+
In the case where the proxy was trusted, in addition to ``REMOTE_ADDR``
39+
being rewritten, only the trusted header would be passed through. That is,
40+
if ``X-Real-IP`` was the trusted header, then ``HTTP_X_REAL_IP`` would
41+
be passed to the WSGI application, but ``HTTP_X_CLIENT_IP`` and
42+
``HTTP_X_FORWARDED_FOR`` would be dropped if corresponding headers had
43+
also been supplied. That the header used to rewrite ``REMOTE_ADDR`` was
44+
passed through still was only intended for the purpose of documenting
45+
where the value of ``REMOTE_ADDR`` came from. A WSGI application when
46+
relying on this feature should only ever use the value of ``REMOTE_ADDR``
47+
and should ignore the header passed through.
48+
49+
The behaviour as described was therefore based on a WSGI application
50+
not at the same time enabling any WSGI or web framework middleware to
51+
try and process any proxy headers a second time and ``REMOTE_ADDR``
52+
should be the single source of truth. Albeit the headers which were
53+
passed through should have resulted in the same result for ``REMOTE_ADDR``
54+
if the proxy headers were processed a second time.
55+
56+
Now in the case of the client a request was received from not being a
57+
trusted proxy, then ``REMOTE_ADDR`` would not be rewritten, and would
58+
be left as the IP of the client, and none of the headers listed above
59+
were supposed to be passed through.
60+
61+
That ``REMOTE_ADDR`` is not rewritten is implemented correctly when the
62+
client is not a trusted proxy, but of the three headers listed above,
63+
``HTTP_X_CLIENT_ID`` was not being dropped if the corresponding header
64+
was supplied.
65+
66+
If the WSGI application followed best practice and only relied on the
67+
value of ``REMOTE_ADDR`` as the source of truth for the remote client
68+
address, then that ``HTTP_X_CLIENT_ID`` was not being dropped should
69+
pose no security risk. There would however be a problem if a WSGI
70+
application was still enabling a WSGI or web framework specific middleware
71+
to process the proxy headers a second time even though not required. In this
72+
case, the middleware used by the WSGI application may still trust the
73+
``X-Client-IP`` header and rewrite ``REMOTE_ADDR`` allowing a malicious
74+
client to pretend to have a different IP address.
75+
76+
In addition to the WSGI application having redundant checks for the proxy
77+
headers, to take advantage of this, a client would also need direct access
78+
to the Apache/mod_wsgi server instance.
79+
80+
In the case that only clients on your private network behind your proxy
81+
could access the Apache/mod_wsgi server instance, that would imply any
82+
malicious actor already had access to your private network and had access
83+
to hosts in that private network or could attach their own device to that
84+
private network.
85+
86+
In the case where your Apache/mod_wsgi server instance could be accessed
87+
from the same external networks as a proxy forwarding requests to it, such
88+
as may occur if making use of a CDN proxy cache, a client would still need
89+
to know the direct address used by the Apache/mod_wsgi server instance.
90+
91+
Note that only one proxy header for designating the IP of a client should
92+
ever be trusted. If you trust more than one, then which will be used if
93+
both are present is undefined as it is dependent on the order that Apache
94+
processes headers. This hasn't changed and as before to avoid ambiguity you
95+
should only trust one of the proxy headers recognised for this purpose.

0 commit comments

Comments
 (0)