Как использовать trusted types для защиты веб-приложений от уязвимостей

Q: Что делать с легаси-кодом, который невозможно быстро переписать

Включите Trusted Types в отчетном режиме и постепенно закрывайте самые критичные точки. Для остаточного легаси можно ввести отдельную узкую политику с жесткими фильтрами и четким сроком жизни.

Q: Можно ли временно отключить Trusted Types для одной страницы

Если конфигурация сервера позволяет, задайте более мягкий CSP только для этой страницы или поддомена. Обязательно зафиксируйте это в документации и поставьте задачу на обратную интеграцию.

Q: Как организовать trusted types обучение разработчиков

Создайте короткий внутренний гайд с примерами до и после, добавьте пункты проверки в code review и проведите практические сессии, где участники сами мигрируют небольшой модуль.

Q: Как тестировать Trusted Types в CI без поддержки в некоторых браузерах

Запускайте e2e в современных браузерах с включенной политикой и отдельный набор тестов в старых браузерах с fallback логикой. В unit тестах можно замокать trustedTypes для проверки правильности вызовов.

Trusted Types добавляет в браузер уровень проверок, который блокирует динамический HTML, если он не создан доверенной политикой. Чтобы использовать Trusted Types для защиты от XSS, включите заголовок CSP, опишите безопасные фабрики строк, поэтапно оберните опасные DOM-операции и включите строгий режим только после прохождения тестов.

Краткий обзор принципов Trusted Types

Trusted Types переводит опасные операции с DOM с произвольных строк на строго типизированные объекты, снижая риск XSS.
Базовая стратегия: запретить прямое использование innerHTML и подобных API, разрешая только значения, прошедшие через доверенные политики.
Поэтапное trusted types внедрение в приложении безопаснее: сначала отчётный режим, затем частичное покрытие, потом строгий режим.
Trusted Types тесно связан с CSP, но не заменяет остальные меры web security trusted types, такие как валидация входных данных и кодирование в шаблонах.
Успех зависит от процесса и культуры: важны code review и trusted types обучение разработчиков, а не только технические настройки.

Подготовка окружения и подключение полиси

Trusted Types имеет смысл включать в браузере для одностраничных приложений, панелей администрирования, сложных виджетов и любых интерфейсов, где много динамического HTML и пользовательских данных.

Не стоит начинать с Trusted Types, если:

кодовая база маленькая, почти нет innerHTML, insertAdjacentHTML и динамических скриптов;
нет возможности менять HTTP-заголовки (например, только статический хостинг без конфигурации);
приложение всё равно будет работать в старых браузерах без поддержки Trusted Types и нет полифиллов в вашем стеке.

Базовые шаги включения:

Добавьте CSP с Trusted Types. На сервере настройте заголовок примерно так:
```
Content-Security-Policy:
  trusted-types default myAppPolicy;
  require-trusted-types-for 'script';
```
Начните без require-trusted-types-for, чтобы сначала собрать отчёты.

Создайте политику в JavaScript. Пример минимальной политики:

if (window.trustedTypes) {
  window.myAppPolicy = trustedTypes.createPolicy('myAppPolicy', {
    createHTML(input) {
      // здесь вы очищаете/проверяете HTML
      return DOMPurify.sanitize(input);
    },
    createScriptURL(url) {
      // белый список или строгая проверка URL
      return url;
    }
  });
}

Проверьте поддержку и trusted types настройка в браузере. В dev-инструментах убедитесь, что заголовок CSP применился, а объект trustedTypes существует в window.

Проектирование политик: правило минимальной доверенности

Как использовать Trusted Types для защиты от уязвимостей - иллюстрация

Для безопасного проектирования политик понадобится:

доступ к конфигурации сервера или CDN, чтобы управлять CSP и включать отчётный режим;
инструменты статического поиска по коду (например, встроенный поиск IDE) для нахождения всех innerHTML, outerHTML, insertAdjacentHTML, document.write и использования new Function;
библиотека для очистки HTML, если вы пропускаете пользовательский HTML (DOMPurify или встроенный в ваш фреймворк механизм);
набор unit- и e2e-тестов, чтобы отловить регрессии после включения строгого режима;
возможность логировать нарушения CSP/Trusted Types (report-uri или report-to, плюс бэкенд для сбора отчётов).

Применяйте правило минимальной доверенности:

Создавайте несколько узких политик вместо одной глобальной, если приложение большое (например, policy для шаблонов, policy для URL).
Каждая политика должна чётко документировать, какие данные принимает и какие проверки выполняет.
Запрещайте в политике всё, что не можете обосновать: никакого «сквозного» пропуска строк без фильтрации.

Интеграция Trusted Types с уязвимыми точками DOM

Найдите все опасные операции с DOM. Просканируйте код на:
- element.innerHTML, outerHTML, insertAdjacentHTML;
- document.write, dangerouslySetInnerHTML (в React) и аналогичные паттерны;
- создание script через innerHTML, new Function, setTimeout/setInterval со строкой.
Составьте список мест, где потенциально нужна trusted types защита от xss.

Оберните генерацию HTML в фабрику политики. Вместо:

container.innerHTML = htmlFromServer;

используйте:

const safeHtml = window.myAppPolicy
  ? window.myAppPolicy.createHTML(htmlFromServer)
  : htmlFromServer; // fallback для старых браузеров

container.innerHTML = safeHtml;

Так вы централизуете фильтрацию и облегчаете аудит.

Замените опасные места c добавлением скриптов. Для script src:
```
const safeUrl = window.myAppPolicy
  ? window.myAppPolicy.createScriptURL(untrustedUrl)
  : untrustedUrl;

const script = document.createElement('script');
script.src = safeUrl;
document.body.appendChild(script);
```
Избегайте inline-скриптов; если без них нельзя, используйте отдельный файл и строгую политику URL.
Используйте безопасные альтернативы там, где можно. Вместо innerHTML применяйте:
- textContent/innerText для вывода текста;
- createElement + appendChild для структурирования DOM;
- шаблонизаторы с автоэкранированием (например, в фреймворке).
Каждый такой переход уменьшает количество мест, где нужна политика.
Включите строгий режим поэтапно. Сначала добавьте:
```
Content-Security-Policy:
  trusted-types default myAppPolicy;
  report-uri /csp-report-endpoint;
```
Проанализируйте отчёты, закройте нарушения, только потом добавляйте require-trusted-types-for ‘script’. Это ядро безопасного процесса trusted types внедрения в приложении.

Быстрый режим: минимальный набор шагов

Включите CSP с trusted-types в отчётном режиме и убедитесь, что браузер поддерживает API.
Создайте одну базовую политику с DOMPurify и фабриками createHTML/createScriptURL.
Замените все innerHTML и динамические script.src на вызовы политики.
Закройте нарушения из отчётов, затем включите require-trusted-types-for ‘script’.

Пошаговая миграция существующего кода

Используйте чек-лист, чтобы контролировать прогресс миграции:

Все найденные innerHTML, outerHTML, insertAdjacentHTML либо заменены на безопасные API, либо обёрнуты в политику Trusted Types.
Все места динамического подключения скриптов используют createScriptURL из политики.
Inline-скрипты по возможности удалены или перенесены в отдельные файлы с жёстко прописанными путями.
Критические пользовательские данные (комментарии, сообщения, поля формы) выводятся только через автоэкранирующий шаблонизатор или через createHTML с очисткой.
В отчётах CSP/Trusted Types нет новых нарушений после каждой итерации рефакторинга.
Тесты покрывают сценарии, где раньше использовался динамический HTML или script, и успешно проходят с включённым строгим режимом.
Code review чек-лист обновлён: новые изменения не могут добавлять прямые обращения к опасным DOM-API без участия политики.
Документация по политике и правилам работы с DOM доступна всей команде.

Совместимость с CSP, фреймворками и сторонними скриптами

Частые ошибки, мешающие внедрению:

Несогласованность настроек CSP: в одном месте включён require-trusted-types-for, в другом старый фрагмент CSP его перетирает.
Фреймворк (React, Angular, Vue) уже выполняет экранирование, но вы дополнительно вставляете HTML через innerHTML, обходя его механизмы.
Сторонние виджеты (чат, аналитика, A/B-тесты) используют innerHTML или inline-скрипты и ломаются при включении строгого режима.
Использование dangerouslySetInnerHTML в React без централизованной обёртки вокруг Trusted Types политики.
Отсутствие согласованного подхода к загрузке скриптов: часть через data-атрибуты, часть через document.write, часть через динамический import.
Игнорирование trusted types настройка в браузере у пользователей: старые браузеры не поддерживают Trusted Types, а код не предусматривает fallback.
Разные команды на одном домене меняют CSP независимо друг от друга, ломая политику соседних приложений.

Тестирование, логирование и отладка политик

Trusted Types эффективны, но иногда целесообразно дополнить или временно заменить их другими подходами:

Только CSP без Trusted Types. Подходит для простых сайтов, где мало динамического контента. Меньше кода, но нет типобезопасности на уровне API браузера.
Шаблоны с жёстким автоэкранированием. Если вы можете полностью запретить динамический HTML, используйте шаблонизатор, который по умолчанию экранирует всё, и не давайте разработчикам прямой доступ к DOM.
Фреймворки с декларативным рендерингом. Современные фреймворки сильно снижают потребность в innerHTML. В простых приложениях одного их соблюдения может быть достаточно.
Комбинация логирования и ручного аудита. Там, где Trusted Types сложно включить (много легаси и стороннего кода), настройте агрессивное логирование операций с DOM и регулярно проводите аудиты безопасности.

В любом случае полезно сохранять отчёты CSP, чтобы видеть реальные попытки обхода защиты и подстраивать политику под угрозы.

Решения для частых сложных кейсов внедрения

Как быть, если сторонний виджет ломается из-за Trusted Types

Поместите виджет в изолированный iframe с более мягкой политикой CSP и без require-trusted-types-for. Так вы сохраните защиту основного приложения и минимизируете риск от стороннего кода.

Что делать с легаси-кодом, который невозможно быстро переписать

Включите Trusted Types в отчётном режиме и постепенно закрывайте самые критичные точки. Для остаточного легаси можно ввести отдельную узкую политику с жёсткими фильтрами и чётким сроком жизни.

Можно ли временно отключить Trusted Types для одной страницы

Да, если конфигурация сервера позволяет, задайте более мягкий CSP только для этой страницы или поддомена. Но обязательно зафиксируйте это в документации и поставьте задачу на обратную интеграцию.

Как организовать trusted types обучение разработчиков

Создайте короткий внутренний гайд с примерами до/после, добавьте пункты проверки в code review и проведите пару практических сессий, где участники сами мигрируют небольшой модуль.

Как тестировать Trusted Types в CI без поддержки в некоторых браузерах

Запускайте e2e в современных браузерах с включённой политикой и отдельный набор тестов в старых браузерах с fallback-логикой. В unit-тестах можете замокать trustedTypes, чтобы проверять правильность вызовов.

Нужно ли включать Trusted Types на публичном маркетинговом сайте

Если там почти нет пользовательского ввода и динамики, достаточно строгого CSP и аккуратного шаблонизатора. Trusted Types разумнее приберечь для сложных приложений и административных панелей.

Как совместить web security trusted types и существующую XSS-защиту на бэкенде

Не отключайте серверное кодирование и фильтрацию. Рассматривайте Trusted Types как дополнительный слой защиты в браузере, который срабатывает даже при ошибках в бэкенде или во фронтенд-фреймворке.