Configuring the Velocity file and file type allowlist

This page describes how to use the Velocity engine file allowlist plugin for template files that live on the file system.

Introduction

From Confluence 9.0 and Jira 10.0, all Velocity template files that live on the file system need to both be allowlisted and be of an allowlisted file type. This is a basic (but limited) defense in attacks that chain file system access with a request to achieve remote code execution.

This is only implemented in the Atlassian fork of Velocity.

This doesn't need to be done for templates rendered using Atlassian Template Renderer as it can only load templates from within plugin .jar files.

Alternatives

It's often best to not store template files directly on the filesystem. The alternative depends on the use-case.

For static templates

Some templates won't change at runtime, but are normally changed with a plugin update. In these cases, we recommend you store the template files inside the plugin or library .jar file. The benefits are;

there isn't any need to allowlist these files
the template files are easy to keep in sync with the plugin version (making it easier to support and debug)
the file cannot be easily modified at runtime (for the sake of security)

For dynamic templates

Some templates may change at runtime; for example, they could be user-generated content. Instead, consider storing the templates in the database. This can bring the usual properties like atomicity and being able to query arbitrarily. Of course, it also brings performance concerns, performance test your App if you implement this.

Configuration

The Velocity resource.loader.file.allowlist and file.resource.loader.filetype.allowlist configuration properties configure the file and file type allowlists respectively.

For reference:

Multiple values are comma separated.
Leading and trailing whitespace is ignored.
File paths must be relative to the template resource root directory (should be the root of the webapp folder by default).
File extensions must start with a period/full-stop character (.). For example, .vm.

If an engine is reused, it should have the allowlists appended to so that other code is not affected. If it's only instantiated and used in your plugin, then it's fine to just set the Velocity properties.

Example

Assuming the configuration of the Velocity engine is in Java, it could look like:

1
2
Velocity.setProperty(Velocity.RESOURCE_FILE_ALLOWLIST, "templates/example.vm, templates/example2.vtl");
Velocity.setProperty(Velocity.FILE_RESOURCE_FILETYPE_ALLOWLIST, ".vm , .vtl");

The example above would set the properties only, and not append to them.

Configuring the Velocity allowlist