Why does the AnQiCMS template default to escaping HTML code? How can HTML content be safely output?

When using AnQiCMS for template development, we may notice an interesting phenomenon: sometimes, the directly output HTML code in the template, such as a<div>The tag was not parsed by the browser as a visible area as expected, but was displayed unchanged&lt;div&gt;Such characters. It may be confusing why AnQiCMS defaults to escaping HTML code.How can we safely output the HTML content we want?

Understand the necessity of the default HTML escaping in AnQiCMS templates

When we find that the template contains<p>Labels have changed&lt;p&gt;At the moment, this is actually the AnQiCMS template engine silently safeguarding the website security. This default behavior is not a fault, but a well-considered security design, with its core purpose beingPrevent Cross-Site Scripting (XSS).

AnQiCMS as an enterprise-level content management system has always placed security in a very important position, both its system architecture and development language (Go language) emphasize high concurrency and security.The document also clearly states that AnQiCMS is committed to providing an efficient, customizable, and scalable content management solution, and that the system design focuses on high concurrency, security, and scalability. We have always been moving forward in the direction of website security, allowing AnQiCMS to safeguard your website.This is enough to show the importance of website security by AnQiCMS.

How is HTML code escaping implemented safely?

Imagine if the template engine does not process the output content, any content submitted by users (such as article comments, message board information), which contains malicious scripts (such as<script>alert('您好！');</script>or<img src="invalid-image.jpg" onerror="alert('您的账户信息已被窃取！');">Could be directly injected into the page, once other users visit this page, these malicious scripts will execute on their browsers, resulting in:

  • Steal user information:Malicious scripts may obtain the user's Cookie and steal login credentials accordingly.
  • Page tampering:Malicious scripts can modify the page content and lead users to perform phishing operations.
  • Spreading malware:By诱使点击，可能使用户下载并install恶意软件。

通过默认转义HTML特殊字符，例如将<to&lt;, will>to&gt;The template engine effectively prevents the browser from parsing these characters as executable HTML or JavaScript code.This way, even if malicious code is submitted by the user and stored in the database, it will only be displayed as ordinary text on the frontend, losing its maliciousness.The template engine used by AnQiCMS (similar to the syntax of Django template engine) also follows this industry-wide security practice.

How to safely output HTML content in AnQiCMS template

Although default escaping is for security, in some cases, we indeed need to output HTML content with a specific structure, such as articles generated by rich text editors or HTML code snippets customized by administrators.At this time, AnQiCMS provides the corresponding mechanism to meet our needs, while ensuring that it is within a controllable range.

1. Use|safeFilter (the most commonly used and direct way)

|safeThe filter is the most direct and commonly used method in AnQiCMS templates, it clearly tells the template engine:This content is safe, do not escape it for HTML, and output it directly according to the original HTML.

Usage:

When your variable contains HTML code that needs to be parsed, just add it to the end of the variable name|safeand it is done:

{# 假设archive.Content变量中存储了HTML格式的文章内容 #}
<div>
    {{ archive.Content|safe }}
</div>

Important tips and risks:

  • Trust assumptions: |safeIt means that as a developer or content manager, you are fully responsible for the content in this variable.You must ensure that this content comes from a reliable source and has been strictly filtered for security, without any malicious code.
  • Not to be misused:Do not use any content directly from the frontend user input without any processing and validation|safeThis will reintroduce the risk of XSS attacks.
  • Application scenarios:Content typically used for background rich text editors (since the content of background editors is usually filtered for security when saved), manually configured by administrators in the background, and confirmed to be safe HTML snippets (such as custom ad code, statistical code, etc.). In addition, when using Markdown editors, and throughrenderThe filter converts Markdown to HTML, and the converted HTML content also needs to be coordinated|safeto display correctly.

2. Use{% autoescape %}tag (controls the escape behavior of a local area)

{% autoescape %}The tag allows you to temporarily enable or disable HTML auto-escaping in a specific area of the template.

Usage:

  • To turn off automatic escaping: {% autoescape off %}...{% endautoescape %}The content between them will not be automatically escaped.
  • Enable automatic escaping (default behavior): {% autoescape on %}...{% endautoescape %}The content between them will follow the default automatic escaping rules.
{# 临时关闭自动转义，输出一段管理员提供的HTML片段 #}
{% autoescape off %}
    <div class="custom-ad-slot">
        <script>console.log('这是一个安全的广告脚本');</script>
        <p>欢迎访问我们的网站！</p>
    </div>
{% endautoescape %}

{# 某个区域需要严格的转义，确保安全 #}
{% autoescape on %}
    <p>这个区域的变量内容 {{ user_input }} 会被严格转义。</p>
{% endautoescape %}

Application considerations:

  • autoescapeTags provide more flexible local control. Usually, we do not recommend turning off automatic escaping in the entire template, as it may introduce unnecessary risks.
  • It is mainly used for those templates or code blocks that require outputting a large amount of HTML code, and you have ensured that this code is completely trustworthy. For outputting a single variable,|safeFilters are usually more convenient.

3. Auxiliary filter:striptagsandremovetags(When the content is not trustworthy but needs to remove HTML)

When your content source is not completely trustworthy, but you also want to remove the HTML tags to prevent potential malicious code, you can use the following filter:

  • striptags:Remove all HTML tags from the string.
  • removetags:"tag1,tag2":Remove specified HTML tags from the string.
{# 移除所有HTML标签，只保留纯文本内容 #}
<p>{{ user_comment|striptags }}</p>

{# 移除特定的<script>标签，但保留其他标签 #}
<div>{{ article_excerpt|removetags:"script"|safe }}</div>

These filters are not used directly for 'safe output HTML', but are used for 'cleaning HTML' to ensure its safety or to display plain text only.They are very useful when handling user submitted content and can be used as a supplement to background security filtering.

Chapter 3, Summary

The default HTML code escaping in AnQiCMS templates is for website security purposes, aimed at effectively preventing XSS attacks.Understanding this mechanism is the basic literacy as an AnQiCMS developer or content operator.When it is indeed necessary to output HTML content, it should be chosen prudently according to the trust level of the content|safeOr filter.{% autoescape off %}Tags. Always be