Skip to content
Browse files

[1.5.x] Added a new required ALLOWED_HOSTS setting for HTTP host head…

…er validation.

This is a security fix; disclosure and advisory coming shortly.
  • Loading branch information
carljm committed Feb 9, 2013
1 parent 5d853db commit a7e33c5bf3a5d854a088c6e56f2684952b1cd2b6
@@ -29,6 +29,10 @@
# * Receive x-headers

# Hosts/domain names that are valid for this site.
# "*" matches anything, "" matches and all subdomains

# Local time zone for this installation. All choices can be found here:
# (although not all
# systems may support all possibilities). When USE_TZ is True, this is
@@ -21,6 +21,10 @@

# Hosts/domain names that are valid for this site; required if DEBUG is False
# See{{ docs_version }}/ref/settings/#allowed-hosts

# Local time zone for this installation. Choices can be found here:
# although not all choices may be available on all operating systems.
@@ -105,6 +105,7 @@ def test_email_found_custom_from(self):
self.assertEqual(len(mail.outbox), 1)
self.assertEqual("", mail.outbox[0].from_email)

def test_admin_reset(self):
"If the reset view is marked as being for admin, the HTTP_HOST header is used for a domain override."
response ='/admin_password_reset/',
@@ -6,6 +6,7 @@
from django.contrib.sites.models import Site, get_current_site
from django.http import HttpRequest, Http404
from django.test import TestCase
from django.test.utils import override_settings
from django.utils.http import urlquote
from django.utils import six
from django.utils.encoding import python_2_unicode_compatible
@@ -203,6 +204,7 @@ def test_get_for_concrete_models(self):

def test_shortcut_view(self):
Check that the shortcut view (used for the admin "view on site"
@@ -5,6 +5,7 @@
from django.core.exceptions import ObjectDoesNotExist
from django.http import HttpRequest
from django.test import TestCase
from django.test.utils import override_settings

class SitesFrameworkTests(TestCase):
@@ -41,6 +42,7 @@ def test_site_cache(self):
site = Site.objects.get_current()
self.assertEqual("Example site",

def test_get_current_site(self):
# Test that the correct Site object is returned
request = HttpRequest()
@@ -64,11 +64,12 @@ def get_host(self):
if server_port != ('443' if self.is_secure() else '80'):
host = '%s:%s' % (host, server_port)

# Disallow potentially poisoned hostnames.
if not host_validation_re.match(host.lower()):
raise SuspiciousOperation('Invalid HTTP_HOST header: %s' % host)

return host
allowed_hosts = ['*'] if settings.DEBUG else settings.ALLOWED_HOSTS
if validate_host(host, allowed_hosts):
return host
raise SuspiciousOperation(
"Invalid HTTP_HOST header (you may need to set ALLOWED_HOSTS): %s" % host)

def get_full_path(self):
# RFC 3986 requires query string arguments to be in the ASCII range.
@@ -455,3 +456,45 @@ def bytes_to_text(s, encoding):
return six.text_type(s, encoding, 'replace')
return s

def validate_host(host, allowed_hosts):
Validate the given host header value for this site.
Check that the host looks valid and matches a host or host pattern in the
given list of ``allowed_hosts``. Any pattern beginning with a period
matches a domain and all its subdomains (e.g. ```` matches
```` and any subdomain), ``*`` matches anything, and anything
else must match exactly.
Return ``True`` for a valid host, ``False`` otherwise.
# All validation is case-insensitive
host = host.lower()

# Basic sanity check
if not host_validation_re.match(host):
return False

# Validate only the domain part.
if host[-1] == ']':
# It's an IPv6 address without a port.
domain = host
domain = host.rsplit(':', 1)[0]

for pattern in allowed_hosts:
pattern = pattern.lower()
match = (
pattern == '*' or
pattern.startswith('.') and (
domain.endswith(pattern) or domain == pattern[1:]
) or
pattern == domain
if match:
return True

return False
@@ -78,6 +78,9 @@ def setup_test_environment():
mail.original_email_backend = settings.EMAIL_BACKEND
settings.EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'

settings._original_allowed_hosts = settings.ALLOWED_HOSTS
settings.ALLOWED_HOSTS = ['*']

mail.outbox = []

@@ -96,6 +99,9 @@ def teardown_test_environment():
settings.EMAIL_BACKEND = mail.original_email_backend
del mail.original_email_backend

settings.ALLOWED_HOSTS = settings._original_allowed_hosts
del settings._original_allowed_hosts

del mail.outbox

@@ -68,6 +68,42 @@ of (Full name, email address). Example::
Note that Django will email *all* of these people whenever an error happens.
See :doc:`/howto/error-reporting` for more information.

.. setting:: ALLOWED_HOSTS


Default: ``[]`` (Empty list)

A list of strings representing the host/domain names that this Django site can
serve. This is a security measure to prevent an attacker from poisoning caches
and password reset emails with links to malicious hosts by submitting requests
with a fake HTTP ``Host`` header, which is possible even under many
seemingly-safe webserver configurations.

Values in this list can be fully qualified names (e.g. ``''``),
in which case they will be matched against the request's ``Host`` header
exactly (case-insensitive, not including port). A value beginning with a period
can be used as a subdomain wildcard: ``''`` will match
````, ````, and any other subdomain of
````. A value of ``'*'`` will match anything; in this case you are
responsible to provide your own validation of the ``Host`` header (perhaps in a
middleware; if so this middleware must be listed first in

If the ``Host`` header (or ``X-Forwarded-Host`` if
:setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this
list, the :meth:`django.http.HttpRequest.get_host()` method will raise

When :setting:`DEBUG` is ``True`` or when running tests, host validation is
disabled; any host will be accepted. Thus it's usually only necessary to set it
in production.

This validation only applies via :meth:`~django.http.HttpRequest.get_host()`;
if your code accesses the ``Host`` header directly from ``request.META`` you
are bypassing this security protection.


@@ -354,6 +354,16 @@ Backwards incompatible changes in 1.5
deprecation timeline for a given feature, its removal may appear as a
backwards incompatible change.

``ALLOWED_HOSTS`` required in production

The new :setting:`ALLOWED_HOSTS` setting validates the request's ``Host``
header and protects against host-poisoning attacks. This setting is now
required whenever :setting:`DEBUG` is ``False``, or else
:meth:`django.http.HttpRequest.get_host()` will raise
:exc:`~django.core.exceptions.SuspiciousOperation`. For more details see the
:setting:`full documentation<ALLOWED_HOSTS>` for the new setting.

Managers on abstract models

@@ -167,47 +167,40 @@ server, there are some additional steps you may need:

.. _host-headers-virtual-hosting:

Host headers and virtual hosting
Host header validation

Django uses the ``Host`` header provided by the client to construct URLs
in certain cases. While these values are sanitized to prevent Cross
Site Scripting attacks, they can be used for Cross-Site Request
Forgery and cache poisoning attacks in some circumstances. We
recommend you ensure your Web server is configured such that:
Django uses the ``Host`` header provided by the client to construct URLs in
certain cases. While these values are sanitized to prevent Cross Site Scripting
attacks, a fake ``Host`` value can be used for Cross-Site Request Forgery,
cache poisoning attacks, and poisoning links in emails.

* It always validates incoming HTTP ``Host`` headers against the expected
host name.
* Disallows requests with no ``Host`` header.
* Is *not* configured with a catch-all virtual host that forwards requests
to a Django application.
Because even seemingly-secure webserver configurations are susceptible to fake
``Host`` headers, Django validates ``Host`` headers against the
:setting:`ALLOWED_HOSTS` setting in the
:meth:`django.http.HttpRequest.get_host()` method.

This validation only applies via :meth:`~django.http.HttpRequest.get_host()`;
if your code accesses the ``Host`` header directly from ``request.META`` you
are bypassing this security protection.

For more details see the full :setting:`ALLOWED_HOSTS` documentation.

.. warning::

Previous versions of this document recommended configuring your webserver to
ensure it validates incoming HTTP ``Host`` headers. While this is still
recommended, in many common webservers a configuration that seems to
validate the ``Host`` header may not in fact do so. For instance, even if
Apache is configured such that your Django site is served from a non-default
virtual host with the ``ServerName`` set, it is still possible for an HTTP
request to match this virtual host and supply a fake ``Host`` header. Thus,
Django now requires that you set :setting:`ALLOWED_HOSTS` explicitly rather
than relying on webserver configuration.

Additionally, as of 1.3.1, Django requires you to explicitly enable support for
the ``X-Forwarded-Host`` header if your configuration requires it.

Configuration for Apache

The easiest way to get the described behavior in Apache is as follows. Create
a `virtual host`_ using the ServerName_ and ServerAlias_ directives to restrict
the domains Apache reacts to. Please keep in mind that while the directives do
support ports the match is only performed against the hostname. This means that
the ``Host`` header could still contain a port pointing to another webserver on
the same machine. The next step is to make sure that your newly created virtual
host is not also the default virtual host. Apache uses the first virtual host
found in the configuration file as default virtual host. As such you have to
ensure that you have another virtual host which will act as catch-all virtual
host. Just add one if you do not have one already, there is nothing special
about it aside from ensuring it is the first virtual host in the configuration
file. Debian/Ubuntu users usually don't have to take any action, since Apache
ships with a default virtual host in ``sites-available`` which is linked into
``sites-enabled`` as ``000-default`` and included from ``apache2.conf``. Just
make sure not to name your site ``000-abc``, since files are included in
alphabetical order.

.. _virtual host:
.. _ServerName:
.. _ServerAlias:
the ``X-Forwarded-Host`` header (via the :setting:`USE_X_FORWARDED_HOST`
setting) if your configuration requires it.

.. _additional-security-topics:
@@ -7,6 +7,7 @@
from django.middleware.csrf import CsrfViewMiddleware, CSRF_KEY_LENGTH
from django.template import RequestContext, Template
from django.test import TestCase
from django.test.utils import override_settings
from django.views.decorators.csrf import csrf_exempt, requires_csrf_token, ensure_csrf_cookie

@@ -267,6 +268,7 @@ def test_token_node_with_new_csrf_cookie(self):
csrf_cookie = resp2.cookies[settings.CSRF_COOKIE_NAME]
self._check_token_present(resp, csrf_id=csrf_cookie.value)

def test_https_bad_referer(self):
Test that a POST HTTPS request with a bad referer is rejected
@@ -279,6 +281,7 @@ def test_https_bad_referer(self):
self.assertNotEqual(None, req2)
self.assertEqual(403, req2.status_code)

def test_https_good_referer(self):
Test that a POST HTTPS request with a good referer is accepted
@@ -290,6 +293,7 @@ def test_https_good_referer(self):
req2 = CsrfViewMiddleware().process_view(req, post_form_view, (), {})
self.assertEqual(None, req2)

def test_https_good_referer_2(self):
Test that a POST HTTPS request with a good referer is accepted
@@ -84,7 +84,13 @@ def test_httprequest_location(self):

'', '', '', '',
'[2001:19f0:feee::dead:beef:cafe]', '',
'', '',
def test_http_get_host(self):
# Check if X_FORWARDED_HOST is provided.
request = HttpRequest()
@@ -131,6 +137,9 @@ def test_http_get_host(self):
'', # Punnycode for öäü.com

poisoned_hosts = [
@@ -139,6 +148,7 @@ def test_http_get_host(self):
'', # not in ALLOWED_HOSTS

for host in legit_hosts:
@@ -156,7 +166,7 @@ def test_http_get_host(self):

@override_settings(USE_X_FORWARDED_HOST=True, ALLOWED_HOSTS=['*'])
def test_http_get_host_with_x_forwarded_host(self):
# Check if X_FORWARDED_HOST is provided.
request = HttpRequest()
@@ -229,6 +239,16 @@ def test_http_get_host_with_x_forwarded_host(self):

@override_settings(DEBUG=True, ALLOWED_HOSTS=[])
def test_host_validation_disabled_in_debug_mode(self):
"""If ALLOWED_HOSTS is empty and DEBUG is True, all hosts pass."""
request = HttpRequest()
request.META = {
'HTTP_HOST': '',
self.assertEqual(request.get_host(), '')

def test_near_expiration(self):
"Cookie will expire when an near expiration time is provided"
response = HttpResponse()

0 comments on commit a7e33c5

Please sign in to comment.
You can’t perform that action at this time.