Host Header Validation

## What the setting is for Every HTTP/1.1 request carries a **`Host` header**, and the client chooses its value. Django uses the host to build absolute URLs: redirects, `build_absolute_uri()`, links in emails, the current site. If an attacker can put any host there, those URLs can point at the attacker. **`ALLOWED_HOSTS`** is the allow-list that stops it: a list of strings naming the host/domain names this Django site may serve. Its default in `django/conf/global_settings.py` is an empty list, `[]`. ## How a host is matched The check lives in **`HttpRequest.get_host()`**. It takes the raw host (from `Host`, or from `X-Forwarded-Host` only when `USE_X_FORWARDED_HOST = True`), splits off the port, lowercases the domain and strips a trailing dot, then compares it with each entry: | Entry | Matches | |---|---| | `'www.example.com'` | exactly that name, case-insensitive, any port | | `'.example.com'` | `example.com` and every subdomain such as `api.example.com` | | `'*'` | anything, so you must validate the host yourself | A few details interviewers probe: - Ports are **not** part of the match, so `'example.com'` accepts `example.com:8000`. - There is no glob syntax: `'*.example.com'` is treated as an exact string and matches nothing useful. - A host that is not a syntactically valid domain fails even before the list is consulted. ## What happens on a miss `get_host()` raises **`DisallowedHost`**, a subclass of **`SuspiciousOperation`**. Django's exception handler converts any `SuspiciousOperation` into a **400 Bad Request** and logs it to the `django.security.DisallowedHost` logger rather than `django.request`. With `DEBUG = True` you see the technical error page with status 400 and a hint such as "You may need to add 'shop.example.com' to ALLOWED_HOSTS". ## Why DEBUG=False suddenly breaks the site The surprise comes from a **debug-only fallback**. When `DEBUG = True` and `ALLOWED_HOSTS` is empty, `get_host()` validates against `['.localhost', '127.0.0.1', '[::1]']`, so local development works with the setting untouched. Setting `DEBUG = False` removes that fallback, and an empty list then matches nothing. The typical sequence: 1. A developer deploys with `DEBUG = False` and leaves `ALLOWED_HOSTS = []`. 2. A request arrives with `Host: shop.example.com`. 3. `CommonMiddleware.process_request()`, which is in the default `MIDDLEWARE` list, calls `request.get_host()` for its `PREPEND_WWW` check. 4. `DisallowedHost` is raised and the client gets a 400 for every page. Two related behaviours help diagnose it: - **`manage.py runserver`** refuses to start with `CommandError: You must set settings.ALLOWED_HOSTS if DEBUG is False.` A WSGI or ASGI server starts normally and fails request by request, which is why the bug shows up only in production. - The **test runner** appends `'testserver'` to `ALLOWED_HOSTS` during tests, so a test suite passes even when the production list is wrong. ## Diagnosing the 400 in production When a freshly deployed site answers 400 to everything, work through these checks: - **Read the security log.** The message on the `django.security.DisallowedHost` logger quotes the rejected host and suggests the entry to add. - **Compare what the proxy sends.** If a reverse proxy rewrites `Host` to an internal name such as `app:8000`, that internal name is what Django validates, not the public domain. - **Check the environment variable.** A typo or an unset variable leaves the list empty, which behaves exactly like forgetting the setting. - **Check `DEBUG` itself.** A site that worked on staging with `DEBUG = True` and an empty list was relying on the localhost fallback all along. The fix is almost never `'*'`; it is naming the host Django actually receives. ## Getting it right - List the real public names: `ALLOWED_HOSTS = ['www.example.com', 'example.com']`, usually read from an environment variable per deployment. - Use a leading dot only when every subdomain really belongs to this app. - Avoid `'*'`. The documentation says that if you use it you are responsible for validating the host yourself, for example in a middleware listed first in `MIDDLEWARE`. - Remember health checks: a probe that sends an IP address as its `Host` needs that IP listed, or it gets 400s. The setting is a guard, not a routing feature: Django does not serve different URLconfs per host because of it.