Twig в контенте¶

Grav может обрабатывать Twig внутри Markdown-контента страницы, поэтому в теле страницы можно писать выражения вроде {{ ... }} и теги вроде {% ... %}. В Grav 2.0 это поведение изменилось по соображениям безопасности: Twig в контенте теперь по умолчанию отключён, а когда вы его включаете, контент выполняется в песочнице безопасности.

Что изменилось в 2.0¶

В Grav 1.7 любая страница с process.twig: true в метаданных выполняла свой контент через Twig без ограничений. Поскольку контент страниц пишет любой, у кого есть доступ на редактирование, редактор страницы мог написать Twig, который читал секреты конфигурации, обращался к файловой системе или, в худшем случае, выполнял код на сервере. Этот класс уязвимостей называется инъекцией шаблонов на стороне сервера (SSTI).

Grav 2.0 закрывает эту дыру двумя независимыми уровнями защиты:

1. Разрешающий механизм. Twig в контенте вообще не выполняется, пока администратор явно не включит его в настройках безопасности.
2. Песочница. Когда Twig в контенте всё-таки выполняется, разрешён только список безопасных тегов, фильтров, функций, методов и свойств. Всё остальное блокируется.

Эти уровни независимы. Разрешающий механизм решает, будет ли выполняться Twig в контенте, а песочница — что он сможет делать, если запустится. Включение разрешающего механизма не отключает песочницу.

Включение Twig в контенте¶

1. Выберите профиль¶

В админке перейдите в Конфигурация → Безопасность. В верхней части страницы находится единый селектор профиля Twig в контенте, который охватывает типичные случаи:

Выбор профиля записывает за вас два базовых ключа, поэтому напрямую их трогать почти никогда не нужно. Они остаются доступны ниже селектора в расширенном виде:

Эквивалентные настройки в user/config/security.yaml:

twig_content:
  process_enabled: true
  editor_enabled: true

Профили сопоставляются с этими ключами так: Выкл. — оба выключены; Только доверенные роли — process_enabled: true и editor_enabled: false; Все редакторы — оба включены.

2. Понимайте, что включает разрешающий механизм¶

Когда Обработка включена, разрешающий механизм становится единственным источником истины для Twig в контенте, и каждая страница по умолчанию обрабатывает Twig в своём контенте. Это изменение по сравнению с 1.7, где каждая страница подключалась индивидуально через свои метаданные. Больше не нужно отмечать страницы по одной.

Если нужно, чтобы конкретная страница не выполняла Twig в своём контенте, исключите эту страницу в её метаданных:

---
title: My Page
process:
    twig: false
---

Явное значение process.twig на странице (true или false) всегда важнее разрешающего механизма, поэтому Twig по-прежнему можно принудительно включить для одной страницы, но делать это приходится редко. Поскольку переключатель включает Twig в контенте на всём сайте, включайте его осознанно.

Сохранение литеральных {{ }} в контенте¶

Когда Twig в контенте включён, Grav вычисляет каждое {{ ... }} и {% ... %} в контенте страницы. Это проблема, если двойные фигурные скобки предназначены не для Grav, например для поля формы Formspree или для шаблона Vue, Handlebars или Angular, который вы встраиваете. Grav пытается вычислить выражение, ничего не находит, и фигурные скобки исчезают из вывода.

Есть два способа сохранить литеральные фигурные скобки:

1. Исключить всю страницу из Twig в контенте с помощью process.twig: false в её метаданных (показано выше).
2. Обернуть только затронутую разметку в тег verbatim, чтобы Grav не трогал её, пока остальная часть страницы по-прежнему обрабатывает Twig:

{% verbatim %}
<input type="hidden" name="subject" value="Feedback: {{ user_subject }} {{ topic }}" />
{% endverbatim %}

При установке по умолчанию Twig в контенте выключен, поэтому эти фигурные скобки и так проходят без изменений, и экранирование не требуется.

3. Очистите кэш¶

После изменения настроек безопасности или параметра process страницы очистите кэш, чтобы страницы перерендерились:

bin/grav cache

Песочница¶

Когда Twig в контенте выполняется, он работает в песочнице, определённой в twig_sandbox файла system/config/security.yaml. Из коробки песочница разрешает широкий набор безопасных Twig-конструкций только для чтения, что покрывает большинство реальных задач:

• Теги для управления потоком и композиции: if, for, set, block, include, embed, macro, apply, with, verbatim и другие.
• Фильтры, такие как date, upper, lower, default, markdown, json_encode, number_format, nicetime, slug, length, join, sort и многие другие.
• Функции, такие как url, authorize, t, media_directory, theme_var, nicetime, dump, а также стандартные помощники Twig вроде range, min, max и cycle.
• Методы и свойства только для чтения обычных объектов: текущий page (title, header, media, children, collection, taxonomy и т. д.), его media, uri, активный user и активный language.

Полные списки по умолчанию находятся в system/config/security.yaml в разделе twig_sandbox; их можно просмотреть в админке в разделе Конфигурация → Безопасность → Песочница Twig.

Что происходит при блокировке¶

Песочница завершается мягко, не выбрасывая фатальную ошибку:

• Заблокированное выражение выводится как литеральный текст, поэтому видно, что именно было остановлено.
• В logs/security.log записывается строка с именем заблокированного тега, фильтра, функции, метода или свойства, маршрутом страницы и подсказкой, как его разрешить.
• То же событие фиксируется для отчёта Twig в контенте (см. ниже), поэтому не нужно читать файл журнала, чтобы узнать, что было заблокировано.
• Если вы вошли как суперпользователь-администратор и включён admin_hint, Grav добавляет HTML-комментарий рядом с заблокированным выражением, указывающий на журнал.

Так что если после включения разрешающего механизма страница показывает сырое {{ something() }}, значит, песочница заблокировала something(). Отчёт назовёт точный нераспознанный элемент и способ его разрешить.

Проверка XSS в контенте¶

Валидатор XSS в схеме проверяет необработанный контент, который вы сохраняете, поэтому полезная нагрузка, собранная во время рендеринга (например, {{ "on" ~ "error" }}, которая становится onerror только после выполнения Twig), проскальзывает мимо него. Grav закрывает этот пробел при сохранении страницы: он изолированно рендерит собственный Twig редактора через тот же проход с песочницей, описанный выше, запускает по результату детектор XSS и отклоняет сохранение, если отрендеренная разметка опасна. Отказ записывается в logs/security.log.

Поскольку проверка выполняется при сохранении и видит только собственный вывод редактора, разметка шорткодов, плагинов или темы никогда не проверяется, а просмотр страницы не требует дополнительных затрат. Учётные записи, покрытые security.xss_whitelist (по умолчанию суперпользователи-администраторы), освобождены от проверки, как и при валидаторе исходного кода.

Сопоставляемые шаблоны — это те, что указаны в security.xss_enabled и security.xss_dangerous_tags в system/config/security.yaml, тот же список, который использует bin/grav security.

Отчёт Twig в контенте¶

Каждый тихий сбой на этой странице (страница с выключенным разрешающим механизмом, блокировка песочницей, утечка сырого Twig) собирается в одном месте админки: Инструменты → Отчёты → Twig в контенте. Это избавляет от ручного чтения logs/security.log. Отчёт показывает:

• Текущее состояние с первого взгляда: включены ли разрешающий механизм и песочница.
• Страницы, отдающие сырой Twig. Любая страница, контент которой содержит {{ ... }} или {% ... %} и не будет отрендерен (потому что разрешающий механизм выключен или на этой странице Twig отключён), перечисляется с понятной причиной и прямой ссылкой на редактор страницы.
• Недавние блокировки. Последние блокировки разрешающего механизма и песочницы, каждая с маршрутом страницы и той же подсказкой, что попадает в журнал. Блокировка песочницы сопровождается кнопкой Добавить в список разрешённых, которая добавляет заблокированный элемент в нужный список за вас, сохраняя полный существующий список (см. Настройка песочницы).
• Сканировать контент. Кнопка, которая сканирует контент каждой страницы на теги, фильтры и функции, не разрешённые песочницей в данный момент, чтобы вы увидели, что нужно вашему контенту, до включения разрешающего механизма, а не обнаруживали это страница за страницей.

Когда вы открываете страницу в редакторе, та же информация появляется встроенным баннером в верхней части страницы, если её контент отдаёт сырой Twig или недавно столкнулся с блокировкой, со ссылкой на полный отчёт.

Настройка песочницы¶

Если вы решили, что конкретный элемент Twig безопасно выполнять против контента, который могут писать ваши авторы, его можно добавить в список разрешённых. Сначала важное предупреждение о том, как объединяются эти списки.

Списки разрешённых песочницы не складываются при ручном редактировании. Плоские списки (allowed_functions, allowed_filters, allowed_tags) полностью заменяются тем, что вы укажете под этим ключом в user/config/security.yaml, а списки по классам (allowed_methods, allowed_properties) объединяются по позиции, поэтому частичный список молча перезаписывает существующие записи. Если написать так:

twig_sandbox:
  allowed_functions:
    - my_safe_function

то будут удалены все встроенные безопасные функции (url, t и остальные), и останется только my_safe_function, что сломает гораздо больше, чем исправит. Есть три безопасных способа добавить элемент:

• Использовать отчёт (самый простой). Когда элемент заблокирован, отчёт Twig в контенте (в разделе Инструменты → Отчёты) показывает его с кнопкой Добавить в список разрешённых. Один клик добавляет его в нужный список с сохранением всех существующих записей. Это самый быстрый безопасный путь, потому что вы действуете с точным элементом, который только что заблокировал Grav.
• Использовать админку. В разделе Конфигурация → Безопасность → Песочница Twig каждое поле предварительно заполнено текущим полным списком. Добавьте свою запись и сохраните — Grav запишет обратно полный список, поэтому значения по умолчанию не потеряются.
• Редактировать вручную с полным списком. Скопируйте весь список по умолчанию для нужного ключа из system/config/security.yaml в свой user/config/security.yaml, затем добавьте новую запись, сохранив все существующие.

То же правило действует для списков методов и свойств по классам: включайте все существующие строки class/methods (или class/properties) вместе с добавляемыми.

twig_sandbox:
  allowed_methods:
    - class: 'Grav\Plugin\MyGallery\Gallery'
      methods: 'render, thumbnail'
    # ...плюс все строки по умолчанию, скопированные из system/config/security.yaml

Разработчики плагинов могут программно регистрировать собственные безопасные элементы через событие onBuildTwigSandboxPolicy, поэтому плагин работает в контенте с песочницей без необходимости каждому сайту редактировать security.yaml. Это надёжное решение для элементов, предоставляемых плагинами, и оно полностью избавляет от необходимости поддерживать полные списки. Сигнатуру события и рабочий пример см. в руководстве по обновлению для разработчиков.

Переменная config¶

По умолчанию переменная Twig config пуста внутри контента с песочницей, поэтому авторы страниц не могут читать конфигурацию вашего сайта (которая может содержать секреты). Если нужен доступ на чтение к неконфиденциальной конфигурации из контента, включите Доступ к конфигурации в разделе Twig в контенте или задайте twig_content.config_access: true. При включении config становится отфильтрованным фасадом, который всё равно скрывает конфиденциальные поддеревья, перечисленные в twig_sandbox.config_denied_paths (по умолчанию: plugins, streams, security, backups, scheduler).

Отключение песочницы¶

Песочницу можно полностью отключить с помощью twig_sandbox.enabled: false, что снимает всю защиту от SSTI для контента, написанного редакторами. Это настоятельно не рекомендуется на любом сайте, где страницы могут редактировать несколько полностью доверенных людей. Почти всегда существует более узкая настройка (добавление конкретного элемента в список разрешённых), которая решает реальную задачу, не снимая защиту.

Лучший путь: вынести Twig из контента¶

Песочница существует для случаев, когда Twig в контенте действительно необходим, но рекомендуемый подход в Grav 2.0 — по возможности избегать Twig в контенте. Он смешивает логику представления с обычным текстом, затрудняет безопасное редактирование для нетехнических авторов и привязывает контент к внутренностям шаблонов. Почти все случаи покрывают два подхода.

Использовать шаблон страницы¶

Если одной странице нужна логика шаблона, создайте для неё отдельный шаблон в теме и укажите его через template: в метаданных. Шаблоны доверенные и не помещаются в песочницу, и логика шаблона должна находиться именно там. Тело страницы снова становится чистым Markdown.

Использовать шорткод¶

Для повторяемых, удобных для авторов фрагментов обычно лучше подходит собственный шорткод. Вместо того чтобы учить авторов фрагменту Twig (и добавлять в список разрешённых всё, что ему нужно), вы даёте им один короткий читаемый тег, а вся логика живёт в PHP вашего плагина. В контенте Twig не выполняется, поэтому песочнице нечего блокировать.

Пошаговое руководство «сначала Twig, потом шорткод» см. в разделе Создание шорткода. Плагин сообщества Shortcode Core также предоставляет большой набор готовых шорткодов.