Last updated Jul 8, 2024

Anti-XSS documentation

AvailabilityConfluence 4.0 or later

In Confluence 4.0, Anti-XSS encoding for plugins is enforced by default. This is a new setting for this release.

This documentation is aimed at developers. It covers instructions to get Velocity template rendering to function correctly with the new Anti-XSS mechanism, as some Confluence 3.x plugins may have their content double encoded.

What is Anti XSS mode?

This mode will engage certain behaviours in Confluence intended to reduce the incidence of cross site scripting (XSS) vulnerabilities. At present this mode enables an automatic data encoding strategy designed to reduce XSS exploits arising from the incorrect encoding of data embedded in HTML templates. This mechanism does not encode HTML output that plugins generate outside of Velocity templates.

Developers interested in extending this XSS protection feature to their plugins should consult the Enabling XSS Protection in Plugins document.

Automatic reference encoding in Velocity templates

Many of the past XSS vulnerabilities in Confluence have arisen simply because data from untrusted sources have not been encoded correctly when mixed with other HTML in Velocity templates. Such encoding failures lead to possible HTML injection attacks that can range from breaking page rendering, to hijacking user sessions. These security vulnerabilities will always be easily introduced when template authors have to make a conscious decision to specifically encode untrusted data when rendered. Other disadvantages of this opt-in security include a proliferation of noise in templates related directly to encoding operations ($generalUtil.htmlEncode et al) and a general obscuration of where data are being written unsafely to the client. Confluence uses a new rendering mode where all data is HTML encoded by default unless steps are taken explicitly to avoid this behaviour in templates.

States of XSS Protection

The table below explains how to apply XSS protection and how your plugin will behave.

Protection state

Effect of protection

Activation mechanism

Anti-XSS protection for plugins.

HTML encoding of Velocity templates is enforced for plugins.

Confluence Admin setting 'Enforce Anti-XSS for plugins' in the 'Security Configuration' screen (default is on).

Plugin opts in. Plugin chooses to enforce Anti-XSS

Keeps Anti-XSS encoding of plugin template's output even if Confluence administrator turns off Anti-XSS protection for plugins.

See Enabling XSS Protection in Plugins.

Plugin opts out.

Useful when you encounter compatibility issues. Template output is not HTML encoded. If opting out, your plugin needs to be HTML encoding all the user-supplied data. It is recommended to update the plugin so that it is compatible with the new setting.

See Enabling XSS Protection in Plugins.

Understanding when HTML encoding is applied

The table below shows how and when HTML encoding of templates is applied for plugins.

'Enforce Anti-XSS for plugins' setting

On (default)


Plugin opts in. See Enabling XSS Protection in Plugins.



Plugin opts out. See Enabling XSS Protection in Plugins.



Plugin takes no action.



Key: Yes = HTML encoding is applied. No = No HTML encoding.

NOTE: When taking no action, your plugin may no longer work correctly because it encounters double HTML encoding of output. See the following paragraphs for ways of addressing this. It is recommended to always opt in.

Explicity opting in to automatic HTML encoding for plugins

See Enabling XSS Protection in Plugins.

Opting out of automatic HTML encoding for plugins

See Enabling XSS Protection in Plugins.

Advanced HTML encoding Enabling XSS Protection in Plugins Preventing XSS issues with macros in Confluence 4.0

Rate this page: