Ловушка add_header

Если про add_header_inherit merge уже знаешь - листай до «Теперь сам».

Сначала ответь сам

server {
    server_name shop.local;
    root /var/www/shop;

    add_header X-Frame-Options DENY always;
    add_header Strict-Transport-Security "max-age=31536000" always;

    location /api/ {
        add_header X-Request-Id $request_id always;
        proxy_pass http://127.0.0.1:8080;
    }
}

Какие заголовки получит клиент в ответе на GET /api/cart?

Инстинктивный ответ - все три. Правильный - только X-Request-Id. Защита от кликджекинга и HSTSРазбирается в разделе 9, глава «HSTS, протоколы, шифры»: HSTS и цена необратимости (заголовок, требующий ходить только по https) не отправятся вообще, и именно на том адресе, где принимают деньги.

На что это похоже

Представь стопку распоряжений на столе у сотрудника.

Сверху лежит распоряжение отдела: «к каждой посылке класть чек и гарантийный талон». Начальник участка кладёт сверху своё: «к каждой посылке класть наклейку». Ты ждёшь, что теперь кладут три вещи.

А сотрудник читает только верхний лист. Не потому что ленив - потому что так устроена инструкция: действует ближайшее распоряжение, остальные не складываются с ним, а перестают действовать.

Наклейку положат. Чек и гарантийный талон - нет. И никто об этом не узнает, пока клиент не спросит про гарантию.

Механизм: почему выключается весь список

add_header - директива-список из прошлого урока. При сборке конфига nginx идёт от location вверх и ищет первый уровень, где есть хоть один add_header. Найденный список и становится итоговым; поиск на этом останавливается.

Правило

Заголовки берутся с ближайшего уровня, где есть хоть один add_header. Всё, что задано выше, при этом выключается целиком. Чтобы уровни складывались, нужна директива add_header_inherit merge; - она появилась в nginx 1.29.3.

Разбор: одна строка чинит всё

Проверено на nginx 1.31.5. Ставим merge на уровень http и смотрим, что получит клиент на четырёх уровнях вложенности:

add_header_inherit merge;
add_header X-Http "http" always;

server {
    add_header X-Server "server" always;

    location /deep/ {
        add_header X-Loc "loc" always;

        location /deep/deeper/ {
            add_header X-Deep "deep" always;
        }
    }
}

Две первые строки стоят прямо в файле из conf.d, вне server, - то есть на уровне http, как и обещает шапка.

curl -sI localhost/deep/deeper/ | grep '^X-'

X-Deep: deep
X-Loc: loc
X-Server: server
X-Http: http

Все четыре уровня сложились, от самого глубокого к http - в таком порядке их собирает merge, а браузеру порядок заголовков безразличен. Причём сама директива add_header_inherit наследуется обычным способом, поэтому написанная один раз в http она действует на весь сервер - в том числе на блоки, которые допишут потом.

У директивы три значения:

off нужен там, где вложенный блок обязан отдавать только своё: отдача чужого файла, редирект на партнёрский домен, health-check (служебный адрес, который опрашивает мониторинг, чтобы понять, жив ли сервер) без лишних подробностей о сервере.

Разбор: где наивное правило подводит

Наивное правило после этого урока звучит так: «поставил merge - заголовки на месте». Оно верно ровно наполовину, и вторая половина ломается на страницах ошибок.

add_header X-Frame-Options DENY;

Без always заголовок добавляется только к «успешным» ответам: 200, 201, 204, 301, 302, 303, 304, 307, 308. Ответ 404, 502 или 429 уедет клиенту без него.

curl -I https://свой-сайт/ | grep -ci x-frame-options
curl -I https://свой-сайт/этой-страницы-нет | grep -ci x-frame-options

grep -ci считает строки с этим словом без учёта регистра: 1 - заголовок есть, 0 - нет. Если второе число меньше первого - ты только что нашёл это у себя. Лечится одним словом в конце каждой строки:

add_header X-Frame-Options DENY always;

Почему так вообще сделано: add_header задумывался для заголовков про содержимое (Cache-Control, Expires), а их на странице ошибки быть и не должно. Заголовки безопасности пришли позже, и для них появился always.

Что ломается без этого

• Заголовков меньше на части адресов. Сравни curl -I на главную и на /api/. Разница - след add_header во вложенном блоке.
• Заголовков меньше на ошибках. Сравни главную и несуществующую страницу. Разница - отсутствующий always.
• Внешний сканер безопасности ругается через полгода после настройки. Классическая история: заголовки поставили, проверили, всё хорошо; через полгода кто-то добавил в один location add_header X-Request-Id для отладки и забыл убрать.

Зачем это в работе

Эта ловушка почти никогда не срабатывает в день настройки. Она срабатывает позже и от чужой руки: заголовки безопасности пишет один человек, а X-Request-Id для отладки добавляет другой, через год, в один location, и уверенно проверяет nginx -t.

Поэтому лечение выбирается не по красоте, а по тому, переживёт ли оно следующего человека:

1. add_header_inherit merge; в http - одна строка на весь сервер, действует и на блоки, которых ещё нет. Лучший вариант, если у тебя nginx 1.29.3 или новее.
2. Сниппет с заголовками и include в каждом блоке - работает на любой версии, но требует помнить про include при заведении нового location.
3. Не добавлять add_header во вложенные блоки вообще - надёжнее всего, но держится на договорённости, а договорённости не переживают год.

add_header X-Frame-Options DENY always;
add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Content-Type-Options nosniff always;

Подключается он строкой в каждом server и location, где есть свои add_header:

include snippets/security-headers.conf;

Путь без / в начале nginx считает от /etc/nginx. В пакете Debian каталог snippets уже есть, в официальном образе Docker его создают сами: sudo mkdir -p /etc/nginx/snippets.

Теперь сам

1. На сервере nginx 1.26. Что выбрать из трёх способов и почему?