This page last changed on Jun 18, 2009 by ggaskell.

This documentation is aimed at developers. In Confluence 3.0, Anti-XSS mode is enabled by default for the core Confluence application, but in order to prevent this configuration change from breaking plugins, plugin authors must opt in to extend the protection to their own templates.

What is Anti-XSS?

Anti-XSS is a safeguard placed on Velocity template files that automatically HTML encodes inserted variables, therefore protecting against potential cross-site scripting vulnerabilities. It was introduced in Confluence 2.9, and enabled by default in Confluence 3.0. For more information, read the Anti-XSS documentation.

Why should I have my plugin opt in to Anti-XSS protection?

Cross site scripting is a real and dangerous security problem with many web applications. Anti-XSS protects against many potential sources of XSS vulnerabilities. Opting in to Anti-XSS protection requires very little effort, and results in a safer plugin.

Atlassian may make Anti-XSS apply automatically to Confluence plugin templates in the future, so by opting in now you save yourself from your plugin maybe breaking in a future Confluence update.

How do I opt in to Anti-XSS protection?

There are three mechanisms to mark that your Velocity template should have Anti-XSS protection applied to it:

  • Give the template's filename a .html.vm suffix (i.e. mypage.html.vm)
  • Place the template in a directory called html (i.e. /templates/html/mypage.vm)
  • Put the Velocity directive call #htmlSafe() somewhere in the template.

If you do any (or any combination) of the above, any variable substitution performed in your Velocity template will be HTML-encoded under the rules described in the Anti-XSS documentation.

A note on naming

You may notice that the #htmlSafe() velocity directive (which causes a template to opt in to Anti-XSS protection) has the opposite meaning to the @HTMLSafe Java annotation (which causes a Java method to opt out of Anti-XSS protection). We regret this confusing naming and hope to fix it in a future release, but unfortunately we didn't catch it in time to fix for 3.0. We will, however, ensure that #htmlSafe() continues to work.

Document generated by Confluence on Nov 05, 2009 23:34