When building a website, ensuring the security of the content, especially in preventing cross-site scripting (XSS) attacks, is a crucial step.AnQiCMS (AnQiCMS) provides us with powerful tools at the template level to manage the escaping of HTML content, thereby effectively protecting the website and its users.Understanding how to safely handle HTML code in templates is essential knowledge for every Anqi CMS user when engaging in content operation and template development.

The default security mechanism of the AnQi CMS template

The template engine of Anqi CMS adopts a design philosophy similar to Django, which means it enables the automatic escaping (Auto-escaping) feature by default.This is a very important security feature.{{ 变量名 }}When outputting content, the template engine will automatically convert HTML special characters (such as<,>,&,",') to their corresponding HTML entities.

For example, if a variableuser_inputContains malicious HTML code, such as<script>alert('XSS攻击');</script>When you output like this in the template:

<p>用户评论：{{ user_input }}</p>

AnQi CMS will escape this code as:

<p>用户评论：&lt;script&gt;alert(&#39;XSS攻击&#39;);&lt;/script&gt;</p>

So, the browser will display it as plain text rather than executing JavaScript code, effectively preventing XSS attacks.This default mechanism is the first line of defense provided by Anqi CMS for website security, greatly reducing the risk of security vulnerabilities due to negligence.

When do you need to force non-escaping of HTML content?

Although automatic escaping ensures security, in certain specific scenarios, we may need to display content that has been confirmed safe and contains HTML tags.For example, the article details, product descriptions, or some strictly reviewed custom HTML snippets written by the website administrator through the rich text editor in the background.If this content is also escaped, the original formatting and style will be lost, resulting in poor display.

In this case, we can use|safea filter to explicitly inform the template engine that this content is “safe” and does not require HTML escaping.

<div>文章内容：{{ archiveContent|safe }}</div>

Here are thearchiveContentVariables usually come from the background rich text editor. By adding|safe,archiveContentof<p>,<strong>,<a>These HTML tags will be correctly parsed and rendered by the browser, rather than displayed as plain text.

Important reminder: |safeThe filter must be used with caution. Once you use|safe, you entrust the responsibility of content security to yourself. Make sure to use|safeThe content source is absolutely reliable and has been thoroughly disinfected and verified before being stored in the database to prevent any potential malicious code injection.

When is it necessary to manually escape HTML content or control the escaping area?

In most cases, due to the default automatic escaping behavior of the security CMS, we rarely need to manually use|escapeFilter to enforce escaping. In fact, if you use it under the default automatic escaping environment|escape, it may cause the content to be doubly escaped, resulting in unnecessary HTML entities.

|escapeFilter is mainly used when you explicitly disable auto-escaping (for example, by using the {% autoescape off %}Tags) after, and also want to escape a specific variable in the scene. Or, it can also be used to demonstrate the effect of HTML escaping.

The Anqi CMS also provides{% autoescape %}Label to control the automatic escaping behavior of a certain area in the template.

{# 默认行为下，以下内容会被自动转义 #}
{{ user_comment_safe }}

{% autoescape off %}
    {# 在这个区块内，所有变量输出都将不再自动转义 #}
    <p>管理员输入的HTML：{{ admin_html_content }}</p>
    {# 如果这里admin_html_content是用户输入，则需手动转义 #}
    <p>强制转义的用户输入：{{ user_input_again|escape }}</p>
{% endautoescape %}

{% autoescape on %}
    {# 在这个区块内，即使之前关闭了，现在又会重新开启自动转义 #}
    <p>重新开启自动转义：{{ another_user_input }}</p>
{% endautoescape %}

For situations where variables need to be inserted into JavaScript code blocks, it is especially important to pay attention to XSS risks. The Anqi CMS provides|escapejsFilter. It will escape special characters in a string to a JavaScript-safe format, for example, escaping single quotes\'to\nAvoid breaking JavaScript syntax or injecting malicious code.

<script>
    var data = '{{ some_variable|escapejs }}';
    alert(data);
</script>

Handling rich text content and Markdown rendering

The backend content management of Anqi CMS supports Markdown editor.When the content of the article we publish is written in Markdown format, the template engine needs to convert it to HTML when displaying it.archiveDetailTags will automatically convert content from Markdown to HTML when the Markdown editor is enabled. If you want to manually control the conversion, you can userenderParameter.

For example, if you have a variablemarkdown_textContains Markdown formatted content, do you want to render it as HTML and display it?

<div>
    {{ markdown_text|render|safe }}
</div>

Here,|renderThe filter is responsible for parsing Markdown text and converting it to HTML format.Note:The translated HTML content still needs to be processed|safeto be marked as safe, because it is already in HTML format, if it is missing|safeThese HTML tags will be processed by the default automatic escaping mechanism, resulting in the HTML being displayed as plain text.

**实践与安全建议

  1. Trust default escaping:Rely on the default automatic escaping mechanism of Priority Trust CMS. It can effectively prevent XSS attacks in most cases.
  2. Use with caution|safe:Only use it when you are absolutely sure that the content source is safe, and it has been verified and purified by the server|safeFilter. This is usually applicable to rich text content published by backend administrators
  3. Server-side validation and filtering:Whether any content submitted by the user, it should be strictly input validated, filtered, and sanitized on the server side before being saved to the database.This includes limiting HTML tags, attributes, and even using a whitelist mechanism to ensure that only safe HTML elements are allowed.
  4. |escapejsApplied in the JavaScript context:When you need to<script>Insert any dynamic data within the tag, be sure to use|escapejsFilter to prevent JavaScript injection.
  5. Understanding|renderWith|safeThe combination of:For Markdown or other content that needs to be converted to HTML, remember to use first:|renderPerform the conversion, then use|safeTo allow the rendering of HTML content.

By mastering the escaping and unescaping strategies of HTML content in the Anqi CMS template, you will be able to better balance the richness and security of website content, providing users with a stable and secure browsing environment.

Common Questions (FAQ)

Q1: I edited an article with a rich text editor in the background, which contains images and paragraphs, but when displayed on the front end, I saw that<p>/<img>These tags, rather than the rendered effect, what's going on?A1: This situation usually occurs because you did not use|safeFilter. The CMS defaults to filtering all{{ 变量 }}The content output is HTML escaped to prevent XSS attacks.The content generated by the rich text editor inherently contains HTML tags, and you need to explicitly inform the system in the template that these contents are safe and should not be escaped.{{ archiveContent|safe }}(AssumingarchiveContentarticle content variables).

Q2: Does the default automatic escaping mechanism of AnQi CMS completely prevent XSS attacks? Do I still need to filter the user submitted content on the server side?

Q3: How can I display a piece of HTML code I retrieve from an external source in an Anqi CMS template, while ensuring it is safe?A3: If the external HTML code source is very trustworthy and you have confirmed it does not contain malicious content, you can use it directly|safeFilter. But a safer approach is to strictly sanitize the external HTML on the server side before saving it to the database or rendering it to the page, for example using special