# Security

## Let there be Markup: best practices for secure Drupal 8 theming

1. First and formost, put markup in a template if at all possible. That's where it belongs! Avoid writing markup in PHP. In Drupal 8, this best practice means you must avoid writing theme functions as well. Theme functions are still availabe in Drupal 8, but they circumvent important security features.
1. Use `SafeMarkup::format` or `#type => inline_template` renderable array if you deem it to much of a burden to create a new template.
1. Filter your variables through `SafeMarkup::checkAdminXss()` or `Xss::filterAdmin()` if you need a limited HTML set and for admin only.  Or `Xss::filter` to reduce the set of tags.
2. ALWAYS ensure that if you mark an unsafe tag as safe, it it stored with a closing tag. Likewise, never store an unsafe character. Either of these introduces a security vunerability.


## An important reversal between Drupal 7 and Drupal 8 security with string variables

One of the major factors in choosing Twig for Drupal 8 is Twig's autoescape security feature. This feature allows all variables to be escaped automatically at the time they are printed. As such, simply adopting Twig alleviates a bunch of concerns. It lightens the burden on the Security Team and provides better default protections for Drupal sites. In effect, adopting Twig is like writing `<?php print check_plain($variable); ?>` on each variable printed in Drupal 7.

By contrast, in Drupal 7 and prior versions we relied on developers and themers to escape variables manually. They ran every variable through `check_plain()`, `filter_xss()` or another filter function. Variables were otherwise assumed to be safe. You can see where this assumption can easily be overlooked/forgotten, resulting in a security vunerability that usually left a site exposed to an XSS attack.


## Flipping our security on it's head aka Security Thought Process

Before Drupal 8 we assumed a variable came from an unsafe source and ran it through a filtering function to ensure safe output for HTML. Now we no longer have to think about when or where to escape a variable as all variables are escaped on output in the template automatically while they are printed.

A new issue arises from this blessing of automatic safety. If you intend the variable's content to contain HTML, it will now be escaped as HTML entites or double escaped if it was previously escaped. Where before we needed to anticipate the unsafe variable, now we have to react to unintentional escaping.

Instead of thinking about which variables to escape, we now need to know which to mark as safe.


## Warning: know your source!

Knowing the origin of a variable is the only way to determine if it is truely safe. This task can be particularly difficult when a variable passes through different Drupal subsystems. For that reason, if markup indeed needs to remain unescaped we highly encourage developers to mark the variable as safe early in the pipeline.

When determining whether to mark a variable as safe, always follow it back up the pipeline. Trace from template to preprocess function to the render array that builds the template and its variables. Ensure you find the variable's origin before determining where to mark it as safe.


## Marking as Safe

Drupal and Twig each provide a couple of methods for telling the template the variable is safe. Carefully read the warnings above before using any of these methods. Note the subtle differences between the methods, and especially note that since Twig's current methods do not cover some important scenarios, they require extra caution.

Drupal provides a helper class called `SafeMarkup` or by building a renderable array. Also Drupal will mark output as safe if it's been through the `t()` function as well as one the following SafeMarkup static methods:
  `SafeMarkup::checkPlain`
  `SafeMarkup::escape`
  `SafeMarkup::checkAdminXss`
  `SafeMarkup::placeholder`

And depending on the variables passed in being safe also:

  `SafeMarkup::format`
  `SafeMarkup::setMultiple`

**Warning!** We highly discourage the use of Drupal's `SafeMarkup::set()` as well as Twig's built-in processes for marking variables as safe, namely the `Twig_Markup()` object and the `|raw` filter. These methods open a security vunerablilty if the source of that printed variable originates from an unsafe source such as `$_GET`. If you do use them, please thoroughly document why you think the variable is safe so others can incorporate your reasoning into their decisionmaking.


## SafeMarkup vs Twig_Markup

We attempted to use `Twig_Markup` while enabled auto-escaping but there were many cases where wrapping a string in an object failed. When we try to concatinate two Safe strings wrapped in objects they would cease to be safe even if both Strings were orginally safe. Also many variables were used as keys as well and array keys are not allowed to be Objects in PHP. To work around these we decided to make strings safe by storing them in an array of known safe strings.  Still concatination will break their safety but we can now return strings after we've stored them as safe and no longer have to deal with problems of strings wrapped as objects as is `Twig_Markup`.