Support

Documentation

This documentation page is for Joomla! 3.x

This documentation page does not apply to our software versions for Joomla! 4.0 and later versions. If you are not using Joomla 3 please consult the documentation index to find and read the correct version of the documentation.

WAF Exceptions
Prev Web Application Firewall Next

WAF Exceptions

WAF Exceptions

This page allows you to configure exceptions to the WAF filtering rules. Why you need that? Some components are designed to properly and safely parse and use data which triggers WAF protection rules. Most usually, a component accepts an absolute path to files on your server or can parse complex data which normally trigger WAF's filters. Without any exceptions set, these components would be blocked and you wouldn't be able to properly use your site. The workaround was to disable WAF's filters, but this ended up in degrading the security of your site. Using the WAF Exceptions view you can fine tune which components, views and query parameters are in the "safe list" and should never be blocked.

[Note]Note

WAF Exceptions is a very useful and powerful tool. It's also possible that you apply too many exceptions, opening potential security wholes in the firewall. Be very cautious when using it. Please keep in mind that when you add an exception, WAF is COMPLETELY TURNED OFF for all requests matching the exception. If you apply a too broad exception you will be deteriorating your site's security to the level it was before installing Admin Tools.

WAF Exception

[Important]Important

You create a new WAF Exception by clicking on the green New button at the toolbar which is located at the top of the page. The fields under the toolbar are filters: you can use them to filter the display of WAF Exception rules. They will NOT create a new WAF Exception. As a rule of thumb, which applies to all Joomla! components, if you don't see a Save & Close button at the top of the page you need to press the green New button before being able to create something.

WAF Exceptions are defined by specifying a combination of three things:

  • Component. Which component the exception applies to. For example, if you want to disable filtering for a query parameter in JCE you will have to set this to com_jce. If you want to apply the exception to all components, no matter what, leave this blank.

  • View. Each component has one or several views. When you turn off SEF you see something like index.php?option=com_foobar&view=example&id=1. Note the view=example part in this URL; this tells Joomla! that the view name (i.e. the area of the component we want to use) is example. As you might have guessed, the View option in a WAF Exception allows you to target the exception to exactly one view. If you leave it blank, the exception will match all views.

    Components using the classic Joomla! MVC might use a different notation, like index.php?option=com_foobar&task=item.edit&id=1 . Note the task=item.edit part; its value (item.edit) is a composition. The part to the left of the dot (item) is the View you need to use in the WAF Exception. Support for this Joomla! feature was added in Admin Tools 4.3.1; earlier versions cannot define WAF exceptions for components using this notation.

    [Important]Important

    Due to the way Joomla! works, if you are using Joomla!'s SEF URLs it is possible that WAF Exceptions will not work with some components. In this case, change the ordering of the System - Admin Tools and your SEF router plugins so that the SEF router plugin is published BEFORE Admin Tools' plugin. This way Admin Tools will not be able to protect your site against potential vulnerabilities in your SEF component, but it will be able to apply WAF Exceptions even when SEF URLs are turned on.

  • Query Parameter. Everything after the question mark in a non-SEF URL is called the URL query. You will see a lot of key/value pairs, like id=1, category=1:test and so on. The word at the left hand side of the equals sign is called the Query Parameter. The same-named parameter in WAF Exceptions allows you to target a very specific query parameter. If you leave it blank, all query parameters will be matched.

[Warning]Warning

You can not leave all three options blank. That would match all components, all views and all query strings or, in other words, EVERY PAGE you access. This would imply that WAF would be effectively turned off. Admin Tools detects an attempt to do that and won't allow you to perform such a change.

Understanding WAF exceptions

The best way to understand WAF exceptions is by some practical examples.

Whole-component exception. Set component to com_jce, leave view and query parameter empty. This tells WAF that if it sees a request for JCE's utility component (com_jce) is should turn off WAF no matter which view or which query parameters are set. Essentially, WAF is turned off for the entire JCE component.

Excepting a single component's view. Let's say we want to disable WAF for all front-end logins to avoid a complex password throwing a 403 error to our users. Front-end logins are handled by com_user's login view. So just set component to com_user, view to login and leave the query parameter blank. WAF is now disabled for the login/logout page of your site.

Excepting a query parameter of a specific component and view. Let's say we have a com_foobar component whose test view accepts a pass parameter. Strong passwords may accidentally trigger WAF. Just create a new exception where component is com_foobar, view is test and query parameter is pass. WAF will not deal with that specific query parameter on that specific component and view, but will be triggered by unsafe content passed in any other query parameter on that particular view.

Excepting a query parameter across all components and views. Let's say that you see a lot of 403s in your site because various components use a password query parameter to accept passwords and, as we mentioned above, complex passwords can trigger WAF. Instead of hunting down all the views across all components, you can simply leave component and view empty and set the query parameter to password. From now on, when WAF sees a password parameter coming into Joomla! it will not try to apply its protection filters against it. If other query parameters come in with the user request they will be filtered and, if they contain unsafe content, the request will still be blocked.

Prev Up Next
Web Application Firewall Home WAF Deny List