Introduction

A whitelist Attachment Filter for Confluence

The Attachment Filter for Confluence plugin provides a whitelist filter mechanism for attachments uploaded into Confluence. Whitelist filter means that only attachments with a file extension on the list will be accepted and uploaded. In the case of this plugin the list are filter rules. Filter rules can be defined on different levels for a certain context (e. g. a group) and will be validated in a given hierarchy - the most specific filter rule will be taken by the attachment filter to decide whether or not the upload is allowed to perform.

Rule-based filter

The simplest way to filter attachments might be done by defining a list of admissible file extensions. Based on this list, all attachments will be checked and only those with a file extension found in the list will be accepted and uploaded. Since Confluence is a highly configurable system, providing different levels of content definition and access, the Attachment Filter for Confluence also takes this into consideration and allows to define filter rules on several levels. Sounds like a lot of work? Believe us - it is not!

This is because the Global Filter Rule is the only filter rule required to activate and make the filter work. All other rules (e.g. for groups or users) are optional. If you define the Global Filter Rule, all attachments uploaded in Confluence will be checked against this rule (as long as no other, more specific filter rules are in place). The Global Filter Rule is the most general rule you can define.

If you need a more specific rule, e.g. allowing the group "confluence-administrators" to upload a few more file types than all the rest, you can define a Group Filter Rule. So, if a user as a member of the confluence-administrators group uploads an attachment the Group Filter Rule (not the Global Filter Rule) will decide whether the upload is allowed or not.

Let's play it again! If you need a specific rule for one particular user (let's say his username is "superjohn", he is the top-level project manager and wants to upload report files for all his projects), you can define a User Filter Rule. You don't want to allow every project manager to upload report files. If so, you could define a Group Filter Rule for the "projectlead" group. "superjohn" is a special case and you therefore define a particular User Filter Rule for him. If the rule is in place and "superjohn" uploads a report file, his upload will be checked by the User Filter Rule defined for specially for him.

Mechanism of rule validation

"From specific to general" - this is how it works. The most specific rule found for the current upload will eventually decide whether or not the attachment is allowed to be uploaded.

Basic mechanism

The Attachment Filter for Confluence plugin provides several kinds of rules:

The most general rule, which is required to make the filter run, is the Global Filter Rule. As long as no other (more specific) rule is in place, all attachments uploaded in Confluence will be checked against this Global Filter Rule.
A Group Filter Rule is more specific than the Global Filter Rule. Therefore, if a member of a particular group uploads an attachment and a Group Filter Rule for this group is defined, only the Group Filter Rule is taken into account to validate the upload.
A User Filter Rule is even more specific than a Group Filter Rule. Therefore, if a user uploads an attachment and a User Filter Rule for this user is defined, only this user-specific filter rule is taken into account to validate the upload.
A Filter Rule for Anonymous Access is more specific than the Global Filter Rule. If an unauthenticated user uploads an attachment (which is only possible when Confluence permissions allow anonymous access) and a filter rule for anonymous access is defined, only this rule is used for validating the upload.

Special case: several group filter rules

Since a user can be member of more than one group, her file upload might be under control of several Group Filter Rules (unless a more specific user filter rule has been defined). If an attachment upload is validated on the level of Group Filter Rules and there are more than one group filter rules in place for the user (because she is a member of several groups), the upload will be allowed if at least one of the eligible Group Filter Rules has the corresponding file extension on its whitelist. In other words, the upload will be checked against the union of all file extensions defined in these groups.

File extensions and file extension categories

All filter rules are defined through file extensions, such as txt, doc or gif. The available file extensions are grouped in categories, e. g. Documents or Media Files. On the one hand this keeps them well-arranged and manageable, while on the other hand this makes rule definitions easier, because you do not have to select each extension a filter rule should contain one after the other. Instead, you can select categories consisting of several file extensions. Thus, file extension categories act as a template for filter rule definitions.

In order to define your filter rules, you need to globally specify the basic set of available file extensions. Because the Attachment Filter for Confluence plugin is a whitelist attachment filter, you have to explicitly define any file extension you want to allow for attachments. The steps you have to take for this task will be explained in detail in the remainder of this document.