Support

Documentation

Web Application Firewall

[Note]Note

This feature is only available in the Professional release

The Web Application Firewall feature of Admin Tools is designed to offer real-time protection against the most common fingerprinting attacks, used by attackers to deduce information about your site in order to tailor an attack to it, and the most common attacks. The real-time protection is performed by the "System - Admin Tools" plugin.

Before configuring Admin Tools' WAF you have to make sure that the plugin is published and it's the first to run, i.e. it should appear first in the ordering menu. These conditions are automatically applied when you install the Admin Tools bundle. However, if you have installed more system plugins make sure that plg_admintools is published before all other system plugins. If not, the protection offered will not be thorough. Do note that, by default, Admin Tools will try to automatically reorder its system plugin as the first published plugin.

When you launch the Web Application Firewall feature of Admin Tools you are presented with its panel page:

The Web Application Firewall page

Clicking on any icon will launch the respective sub-tool. The Back button on the upper right-hand corner will get you back to the Control Panel page.

Configure WAF

This page lets you configure Admin Tools' Web Application Firewall. This tells Admin Tools how to protect your site. By default, only a basic set of options is enabled. When you use the Quick Setup Wizard feature when you first install Admin Tools a slightly bigger subset of features which are generally “safe” for use on most sites will be enabled.

Using this page you can tailor Admin Tools' protection for your site. Remember that the options are not automatically applied; you will need to click the Save button to apply them. If you change your mind midway through changing the options click on the Back button to return to the Web Application Firewall control panel page.

[Important]Important

If you do something wrong and you inadvertently lock yourself out of the administrator area of your site, do not panic! Read this section about regaining entrance.

The Configure WAF page is split into several tabs to make it easier for you to locate the correct option. The documentation of this page is organized as one section per tab to help you locate the option you are looking for.

Basic Features

WAF: Basic Features

The Basic Features section contains the very basic options which allow you to control who can access your site.

Enable IP workarounds

Some sites are behind a load balancer, caching proxy, CDN (e.g. CloudFlare) or third party web application firewall service (e.g. Sucuri). In these cases the IP address your web server sees is always the same, regardless of who is actually visiting your site. Therefore Joomla and Admin Tools will always see the same IP address which prevents some features from working properly. Especially for Admin Tools this can be a major problem because the Exclusive Allow IP address and all IP blocking features will no longer work correctly.

There are two ways to deal with this, depending on your Joomla and Admin Tools version.

Joomla 4 and Admin Tools 7 or later

Go to your site's Global Configuration. Find the “Behind Load Balancer” setting and set it to Yes. Click on Save.

Back in Admin Tools' Configure WAF page set the Enable IP Workarounds option to No.

If and only if you see that everyone is blocked from accessing the site as soon as Admin Tools blocks an attack should you set Enable IP Workarounds to Yes. Normally this is NOT required because Joomla 4 uses the same code we added in Admin Tools back in 2012 to apply IP workarounds when the “Behind Load Balancer” setting is enabled. We have not seen any practical use case where this option was required with Joomla 4, therefore this option is scheduled for removal when we stop supporting Joomla 3 towards the end of 2023.

Joomla 3 and Admin Tools 6 or earlier

Admin Tools 6 uses its own code to determine the visitor's IP address, without going through Joomla's copy of our code. This was necessary to support older versions of Joomla 3 which did not have the “Behind Load Balancer” option.

If your site is behind a load balancer, caching proxy, CDN etc you need to set this option to Yes.

If you are unsure about your server setup set this option to Auto. Then wait until there is an attack on your site. Did your site become inaccessible for everyone after the last time Admin Tools detected an attack? Do you always see the same IP or variations of the same in the Blocked Requests Log? If the answer to both questions is "yes" then you must set the "Enable IP workarounds" option to Yes.

How does this work?

Load balancers, proxies, CDNs etc set up an HTTP header called X-Forwarded-For which contains the list of IP addresses throughout the forwarding chain, up to an including the real IP address of the visitor of the site. Enabling Joomla 4's “Behind Load Balancer” option or Admin Tools' “Enable IP Workarounds” option will use the contents of this HTTP header instead of the visitor's IP address reported by the browser.

There are two cases where you do NOT want to do that:

  • If your site is NOT behind a load balancer, proxy, CDN etc. In this case the X-Forwarded-For header could be set by an attacker to cover their tracks. Essentially, they would be spoofing their IP address to evade blocking.

  • If your web server already takes the X-Forwarded-For header into account, e.g. using the Allow IP forwarding setting in the NginX Config Maker. In this case the visitor's IP address reported by the server is the correct one; the web server has taken the contents of the X-Forwarded-For header into account. Enabling Joomla 4's “Behind Load Balancer” option or Admin Tools' “Enable IP Workarounds” option won't hurt but it's unnecessary.

Remember the golden rule. If unsure, set to No. If crap happens as a result of setting this option to No then set it back to Yes.

Allow administrator access only to IPs in the Exclusive Allow IP List

When enabled, only IPs in the Exclusive Allow IP List (see the following sections of this documentation about configuring it) will be allowed to access the administrator area of the site. All other attempts to access the administrator pages will be redirected to the site's home page. Be careful when using this feature! If you haven't added your own IP to the Exclusive Allow IP List you will get locked out of your administrator area!

Please look into the Exclusive Allow IP List documentation section for more information.

[Important]Important

IPs added to the Administrator Exclusive Allow IP List are fully vetted as far as Admin Tools is concerned. This means that no security measure will be applied against them. Please place only very well trusted IPs in this list! If an attack is launched from this IP, it will not be blocked by Admin Tools!

Disallow site access to IPs in the IP Disallow List

When enabled, if the visitor's IP is in the IP Disallow List (see the following sections of this documentation about configuring it) they will immediately get a 403 Forbidden error message upon trying to access your site.

Administrator secret URL parameter

Normally, you can access your site's administrator area using a URL similar to http://www.example.com/administrator. Potential hackers already know that and will try to access your site's administrator area the same way. From that point they can try to brute force their way in (guess your username and password) or simply use the fact that an administrator area exists to deduce that your site is running Joomla! and attack it. By entering a word here, you are required to include it as a URL parameter in order to access your administrator area. For instance, if you enter the word test here you will only be able to access your site's administrator area with a URL similar to http://www.example.com/administrator?test . All other attempts to access the administrator area will be redirected to the site's home page. If you do not wish to use this feature, leave this field blank.

The secret URL parameter must start with a letter. If it starts with a number, you will immediately get a "Illegal variable _files or _env or _get or _post or _cookie or _server or _session or globals passed to script" error when trying to access your site's administrator back-end. It should also contain only lowercase and uppercase ASCII characters and numbers (a-z, A-Z, 0-9), dashes and underscores in order to ensure the widest compatibility with all possible browser and server combinations.

Any other characters you use (such as: punctuation; special characters; Latin letters with accents or diacritics; Greek, Cyrillic, Chinese, Japanese and other ethnic script characters)will have to be URL-encoded. This makes it difficult and tricky to use, hence our recommendation not to use it.

Moreover note that some extended Unicode characters such as certain Traditional Chinese characters and Emoji cannot be used. They will be either rejected by the server or trigger a server protection which will lock you out from your site at the hosting level (you'll have to contact your host to unblock you).

Finally note that on most servers this is case sensitive, i.e. abc, ABC and Abc are three different secret words.

[Tip]Tip

Some servers do not work with http://www.example.com/administrator?test due to their configuration. You may want to try using http://www.example.com/administrator/?test (add a slash right before the question mark) or http://www.example.com/administrator/index.php?test (add /index.php right before the question mark). One of them is bound to work on your server. Unfortunately, there is no way to know which ones will work on your server except for trying them out. The first one (http://www.example.com/administrator?test) works on 95% of servers and that's what we recommend trying out first.

Please be aware of some pitfalls with this feature:

  1. This feature works by checking whether the URL used to log into your site has the secret URL parameter present in it. If your session expires and you try to access any backend page Joomla will redirect you to the site's administrator login page without the secret URL parameter. As a result you will be redirected to the frontend of the site and a Blocked Request will be logged against your IP with the reason “Admin Query String”.

    If this happens too many times, e.g. because you have multiple background tabs opened to different administrator pages which get silently reloaded by your browser, or because your browser's “Frequently Used” / ”Top Sites” / similar feature tries to silently load an administrator page you are using frequently you may find that your IP is temporarily blocked.

    The best way to prevent that from happening is to a. not have multiple administrator pages open in different tabs / browser windows at the same time; b. close all administrator page tabs when you are going to not be interacting with them for more than a minute or two; c. use Joomla's Logout feature when you are not going to be using your site's administrator for a few minutes; and d. set the session expiration time in your site's Global Configuration to a higher value which is representative of your workflow (e.g. 300 minutes if you are likely to leave an admin page open for up to 5 hours before coming back to it).

    Alternatively, set the “Browser cookie override for the administrator secret URL parameter” to a setting other than Disabled.

  2. As alluded to above, sometimes you may see that your IP is blocked even though you haven't tried visiting your site's administrator, with Blocked Requests recorded from your IP address with the reason “Admin Query String”. This is NOT a bug in Admin Tools. It's how your browser works. Most modern browsers have a pinned sites, reading list and/or frequently visited sites feature which is updated every time you open a new browser window or tab and sometimes also updated in the background, without further interaction from you. This means that your browser is accessing an administrator URL on your site because it appears in one of these features. If this URL does not contain the secret URL parameter and your session has expires a Blocked Request from your IP address is recorded.

    There is no way for Admin Tools (or anything on your server, really) to know that these requests are automated background requests from your browser. As far as your browser is concerned, these are legitimate requests coming from a real browser. Since the Joomla session does not have the administrator secret URL parameter set when this happens they will be treated as requests to be blocked.

    The only thing you can do is either disable these features on your browser (or at least remove any administrator URLs to your site from these features); OR set the “Browser cookie override for the administrator secret URL parameter” to a setting other thanDisabled; OR not use the administrator secret URL parameter.

    In fact, we recommend using the Administrator Password Protection feature instead ofthe administrator secret URL parameter: it is more secure, more reliable, more resistant to Denial of Service attacks and does not suffer from the accidental locking out of your IP address . The downside is that the Administrator Password Protection feature only works on Apache and Litespeed, the two servers which support .htaccess files.

  3. If you are sharing your public (Internet-facing) IP address with other people, e.g. in an IPv4 network using NAT to access the Internet, if one person gets the IP address blocked then all people behind the same IP address are blocked as well. This is very important if you are working in an office / company with other developers, site integrators and site administrators on a public site. One member of the team gets blocked, everyone is blocked. This is not a bug; as far as the site's server knows, it receives requests from the same IP address regardless of the person, machine or browser being used. This problem is mostly resolved if both you and the server are using IPv6. In this case each machine has a different IP address, even when using the equivalent of NAT under IPv6.

Browser cookie override for the administrator secret URL parameter

As noted above, when your login session expires and you try to access an administrator page you will get redirected to the site's frontend and a Blocked Request will be logged against your IP with the reason “Admin Query String”. If that happens enough times — for example because your browser is trying to silently access administrator pages without your interaction such as when you have multiple background tabs open or because of its Frequently Visited / Top Sites / similar feature — you might have your own IP temporarily blocked, preventing you from accessing your site.

When this option is set to a value other than Disabled, Admin Tools will set a secure browser cookie when you log into your site's administrator. If this cookie is present and valid Admin Tools will allow you access to Joomla's administrator login page even if the URL does not include the Administrator Secret URL Parameter — like, for example, when your session expires. This allows you to log back into your site's administrator without a Blocked Request being logged for your IP address therefore without risking getting blocked off your site.

The cookie is removed from your browser and made invalid in the database when you a. log out of the site's backend (see caveat below); b. when you change the user's password (if Joomla's Remember Me plugin is published); and c. when a possible attack against this feature is detected.

Caveat: if you have enabled Linked Sessions on your site the cookie will be removed when you log out from either the backend of the frontend of your site. That's how Joomla works, it's not an Admin Tools bug. Joomla's Linked Sessions feature issues a logout on both the frontend and backend application in such a way that the backend application cannot discern whether it's a real backend logout or a Linked Sessions logout.

There are four settings for this option:

  • Disabled. This feature is disabled. No new cookies will be set and existing ones are ignored.

  • Enabled. This feature is enabled. New cookies are set when you log into your site, removed when you log out and used instead of the Administrator Secret URL Parameter when it is missing from the administrator login URL or the wrong secret URL parameter is used.

  • Enabled, notify when used. Same as “Enabled”, additionally prints a reminder message in the login page when this feature is used instead of the Administrator Secret URL Parameter.

  • Enabled, remind to use the full URL. Same as “Enabled, notify when used”, additionally prints a message reminding you to use the correct administrator login URL, not to have multiple browser tabs open in the background and log out when you are not going to be using the site's administrator pages for the next few minutes. Furthermore, if the last user who had logged into the site with the current browser was a Super User it will additionally print a reminder that you may need to adjust your Session Length and that this feature can be controlled from the Components, Admin Tools, Web Application Firewall, Configure WAF page.

We recommend setting this feature to “Enabled, notify when used” or “Enabled” on most sites. The “Enabled, remind to use the full URL” is normally only necessary as a default, to remind Super Users that this feature exists and how to control it.

If you want to customise the message displayed when this is set to “Enabled, notify when used” and the first part of the message displayed when this is set to “Enabled, remind to use the full URL” you can do a language override for the language key PLG_ADMINTOOLS_MSG_ADMINPW_COOKIE .

If you would like to customise the second half of the messages printed to regular backend users and Super Users when this is set to “Enabled, remind to use the full URL” you can do a language override for the language keys PLG_ADMINTOOLS_MSG_ADMINPW_COOKIE_NONSUPERUSER and PLG_ADMINTOOLS_MSG_ADMINPW_COOKIE_SUPERUSER respectively.

The cookies for this feature are stored in Joomla's #__user_keys database table, along with Joomla's Remember Me secure cookie settings and possibly other third party extensions' secure cookie settings, as per Joomla's best practices for implementing any feature requiring the use of secure cookies. Joomla's Remember Me may remove ALL cookie settings for a user when the user logs out, their password changes or it detects a possible attack — this includes the secure cookie settings for Admin Tools itself. Third party extensions may remove secure cookie settings for a user under other circumstances as well. Before assuming this feature does not work please make sure that neither Joomla's Remember Me nor a third party extension are removing records from that table.

Defend against plugin deactivation

When enabled, Admin Tools will prevent back-end users from trying to disable (unpublish) the plugin. This means that you will also be unable to unpublish the plugin until you disable this option!

Away Schedule

By default, Joomla! allows users with back-end access to log in to the site any time of the day. On smaller sites which have only a handful, or even just one, administrators on the same zone this means that someone can try to log in with a stolen username / password while you are fast asleep and unable to respond to the unexpected login. This where the Away Schedule comes into play. If a user with back-end login privileges tries to log in to the front- or back-end of your sute between the "from" and "to" hour of the day they will be denied login. Moreover, if someone tries to access the administrator login page during that time they will be redirected to the front-end of the site – even if the have used the correct Administrator secret URL parameter.

Please note that this feature does not affect your regular users logging in to the front-end of your site. It only prevents users belonging to a group with the Admin Login privilege. You can check which groups have that privilege by clicking on the System, Global Configuration menu of your site and visiting the Permissions tab.

The From and To time has to to be entered in 24-hour format with trailing zeros, e.g. 09:15 for a quarter past 9 a.m. and 21:30 for half past 9 p.m. The time is entered in your server's timezone which may be different than the timezone you live in. For your convenience, the server's time at the time of the page load (in 24 hour format) is shown to you right below the Away Schedule.

Request Filtering

WAF: Request Filtering

The Request Filtering section contains the options which are the heart and soul of the Web Application Firewall. Admin Tools will monitor incoming requests and their variables, filter them using these options and decide which requests seem to be nefarious, blocking them.

SQLiShield protection against SQL injection attacks

When enabled, Admin Tools will try to detect common SQL injection attacks against your site and block them.

But what is a SQLi attack? A few Joomla extension developers are hobbyists, without experience and / or security training; or mistakes do happen, as Joomla itself has found out the hard way. One of the common mistakes they do is to make assumptions about the nature or the content of user-submitted data, interpolating them into database queries as-is. Database queries are also called SQL queries (SQL, pronounced "sequel", is the shorthand for Structured Query Language, the programming language the database queries are written in). An attacker can exploit this mistake by sending data which have the effect of terminating the developer's database query and starting a new one which either dumps privileged data -such as usernames and passwords- or modifies data into the database - such as adding a new Super User under the control of the attacker. This class of attacks is called an SQL Injection, or SQLi for short, since the attacker "injects" his own code into a SQL query running on the site.

Malicious User Agent block (MUAShield)

Many hackers will try to access your site using a browser configured to send malicious PHP code in its user agent string (a small piece of text used to describe the browser to your server). The idea is that buggy log processing software will parse it and allow the hacker to gain control of your website. When enabled, this feature allows Admin Tools to detect such attacks and block the request.

Remote File Inclusion block (RFIShield)

Some hackers will try to force a vulnerable extension into loading PHP code directly from their server. This is done by passing an http(s):// or ftp:// URL in their request, pointing to their malicious site. When this option is enabled, Admin Tools will look for such cases, try to fetch the remote URL and scan its contents. If it is found to contain PHP code, it will block the request.

[Important]Important

If your site starts throwing white pages when submitting a URL in your site's front-end, please disable this option. The white page means that your server is not susceptible to this kind of attack and doesn't properly advertise this to Admin Tools when requested. In this case, Admin Tools crashes while trying to scan the contents of the remote location, causing the white page error. Disabling this option in such a case poses no security risk.

Remote PHP protocol block (PHPShield)

Some hackers will try to read the files of your site using the php:// wrapper and some advanced PHP filters. When this option is enabled, Admin Tools will block every request that contains the php:// string.

Direct File Inclusion shield (DFIShield)

Some hackers try to trick vulnerable components into loading arbitrary files. Depending on the vulnerable component, the file will either be output verbatim or parsed as a PHP file. This allows attackers to disclose sensitive information about your site or run malicious code uploaded to your site through another vulnerable vector, e.g. an unfiltered upload of executable PHP code. When this option is enabled, Admin Tools will search the request parameters for anything which looks like a file path. If one is found, it will be scanned. If it is found to contain PHP code, the request will be rejected.

[Important]Important

This feature does NOT prevent dumping of non-PHP files, e.g. the /etc/passwd file of Linux servers.

PHP session data poisoning protection (SessionShield)

Prevents malicious input data which can be used to trick PHP's internal session handler into executing arbitrary code when it's restoring the user session.

The PHP session unserializer has a major bug which makes it misinterpret stored session data if they contain specific character combinations, overwriting the legitimate session data with the attacker-defined contents. Combined with some other features of PHP this can lead to the execution of arbitrary PHP code. In short, attackers can send malicious data in one page load and get arbitrary code to execute in the next page load. This feature of Admin Tools detects and blocks this kind of malicious data. CAUTION: It may block some legitimate requests as well.

[Warning]Warning

This attack vector is NOT unique to Joomla!. It is a low level PHP bug / vulnerability which was fixed only in PHP 5.5.4 and later versions. Furthermore, default PHP settings even in newer versions of PHP use the old, vulnerable setting, putting all sites using session data at risk! We VERY STRONGLY recommend that all our clients use PHP 5.5.4 or later and edit their php.ini to modify this line:

session.serialize_handler = php

to

session.serialize_handler = php_serialize

This is the ONLY guaranteed way to fix this low level PHP vulnerability across all possible attack vectors, including those yet undiscovered.

Anti-spam filtering based on Bad Words list

When enabled, all requests containing at least one word in the Bad Words list (configured separately, see the next sessions) will be blocked. By default the Bad Words list is empty; you have to configure it to match your site's needs. One good idea is to include pharmaceutical, luxury watches and shoes brand names, as this makes up the majority of comment and contact spam received on web sites.

Allowed domains

This is a list of fully qualified domain names your site can be accessed on, one domain per line. DO NOT enter http:// or https:// in front, do NOT enter the / after the domain name or the path that follows it. This is a domain name, not a URL. For example: example.com. You do not need to enter the www/non-www versions of the domain names or domain names which resolve to the localhost IP address (127.0.0.1 for IPv4 or ::1 for IPv6). If an attacker tries to access your site with an HTTP Host header that does not match these domain names (or their www/non-www versions) they will receive an HTTP 400 Bad Request error message.

This feature mitigates a class of attacks called “HTTP Host spoofing” which affects a stark minority of servers, mostly servers which were set up by someone who doesn't understand web server security enough or at all. On those servers you can send an HTTP Host header which confuses the server into believing that this is the domain name it's running on. So, even though you are accessing a site on www.example.com you can send it a Host: www.evil.hack HTTP header and now all URLs generated by the server will use the www.evil.hack domain name. This is used in phishing attacks to misdirect a submitted form with login credentials to a server under the attacker's control even though the browser's address bar shows a legitimate domain name.

If you are on an affected server you are VERY STRONGLY recommended to use this feature INSTEAD OF setting the $live_site URL in configuration.php, the latter being the traditional but incorrect way of mitigating such an issue. Setting the $live_site URL limits your site to exactly one domain name (remember that example.com and www.example.com are two different domain names!) and protocol (HTTP vs HTTPS). Therefore using $live_site is extremely limiting and can cause your site to stop working if you try to enable/disable HTTPS everywhere in Joomla's Global Configuration, enable/disable www to non-www redirections etc. Moreover, the $live_site URL in configuration.php does NOT protect against all host spoofing attacks. What Admin Tools does will indeed protect all requests handled by Joomla against such attacks without causing any of the adverse effects of Joomla's recommended course of action.

Hardening Options

WAF: Hardening Options (partial screenshot)

With the Hardening Options section you are able to harden the way some basic Joomla! features work. These are advanced settings, so please make sure you understand what each option does before you enable it.

Warn about use of well-known passwords

When this option is enabled, Admin Tools will connect to the Have I Been Pwned database and check if the hash of the current password is known. If a match is found, the user will be blocked from using an insecure password.

Wait, are you sharing my password? Is that service secure?

First of all, we do not share your password. We're only sending a fraction (only first 5 chars) of the hash of your password. This method is called k-anonymity and it's a very secure way to share sensitive data without compromising its privacy. Your password CAN NOT be derived from this partial information. If you want to read the whole details of this implementation, you can take a look at this page.

Regarding the external service, it is powered by two well known figures: Troy Hunt (a security research) and CloudFlare (leader in Content Deliver System services). The service is so important for the security of computer systems that even the United States of America Federal Bureau of Investigation (FBI) contributes to it.

User groups to check for well-known passwords

Most likely you want to enable this feature only for specific groups: Admin Tools will check for well-known passwords only users belonging to those groups (default is Super Users)

Disable password reset for specific User Groups

Joomla allows all users who do not have the Super User permission to request a self-service password reset. This is typically through the “Forgot your password?” feature in the frontend login module and the frontend users component, both of which go through the frontend users component to send an email to the user to help them reset their password.

In some cases it is prudent to disallow this feature for certain types of users. For example, you may have user groups which do not have the Super User permission but can be critical to the operation of your site such as people doing end user support, handle personal or privileged information, control content publication workflows etc. A successful account takeover could have far-reaching implications for the operation of your site and/or business.

This feature allows you to disable the self-service password reset feature for users belonging in specific user groups.

Please note that this feature DOES NOT control whether users with Super User permissions are allowed to reset their password! Joomla itself automatically disallows self-service password resets for these users and this cannot be changed (it's a hard-coded check no third party plugin can change). This means that Super Users cannot reset their own password using the Forgot Your Password feature; this has to be done either by logging in and editing their user profile OR by having their user profile edited by another user with sufficient permissions to edit user profiles. This is a built-in Joomla feature, not under the control of Admin Tools.

Finally, please note that this feature only applies to self-service password resets sent by Joomla's frontend com_users component. It DOES NOT prevent third party software implementing its own password reset feature from allowing these users to reset their passwords.

User groups blocked from resetting the password

Choose the user groups which will be prevented from using Joomla's self-service password reset. Only visible and applicable when the “Disable password reset for specific User Groups” option is enabled.

Only users which are directly assigned a user group will be disallowed to reset their password. That is to say, you cannot just select the Public group and expect nobody to be able to use this feature; the restriction is NOT applied to child user groups.

Also note that you do not need to select the Super Users group or any other group which grants the Super User permission. Joomla itself automatically disallows self-service password resets for these users and this cannot be changed (it's a hard-coded check no third party plugin can change). This means that Super Users cannot reset their own password using the Forgot Your Password feature; this has to be done either by logging in and editing their user profile OR by having their user profile edited by another user with sufficient permissions to edit user profiles. This is a built-in Joomla feature, not under the control of Admin Tools.

Disable editing backend users' properties

When enabled, trying to modify the settings of an existing or create a new Manager, Administrator or Super User will fail.

Disable creating / editing backend users from the frontend

You should normally be unable to create a new user with administrative backend login privileges from the public frontend. When this option is enabled it will treat attempts to create this kind of accounts as hacking attempts and block them from executing. This addresses some of the most notorious zero day attacks in Joomla! which took place between 2015 and 2016 and we recommend having it turned on at all times. If you need to disable it we STRONGLY recommend rethinking whatever leads you to disable this setting because it's creating a gaping security hole on your site.

Monitor Global Configuration

When this is enabled and someone tries to change the Global Configuration of Joomla!, either from the back-end or the front-end, you will either be notified or they will get blocked (depending on your settings below). This feature is designed to protect you against sly hackers or malicious administrators who subtly change your site's configuration for nefarious purposes, e.g. by elevating the global privileges of user groups.

Monitor component configuration

When this is enabled and someone tries to change the configuration of any core Joomla! or third party component (what you see when you click Options in a component's toolbar) from the back-end of your site you will either be notified or they will get blocked (depending on your settings below). This feature is designed to protect you against sly hackers or malicious administrators who subtly change your components' configuration for nefarious purposes, e.g. by elevating the privileges of user groups with regards to a particular component.

Action for configuration monitoring

This option works in conjunction with the two above. You define what do you want to do when either global or component configuration is enabled and a change is detected in the configuration.

  • Email will simply send a warning email to the email addresses you've configured to receive emails for blocked requests and only if you have configured such email addresses. The changes in configuration will go through. This is the recommended setting for most sites.

  • Block will treat any such changes as a reason to block the request. The changes in configuration will NOT go through. This setting should only be used on "locked down" sites where configuration changes are not expected (or will only be performed by an administrator who has adequate access to modify Admin Tools' configuration).

Monitor Critical Files

Critical files commonly modified by hackers (index.php, administrator/index.php and the index.php, error.php and component.php of all templates installed on the site) will be monitored for changes on every page load. If a change is detected you will be notified by email. This usually lets you get an ahead warning in case of a successful hacking attempt.

Monitor these files for changes

Monitor the following files (one per line) for changes. If a change is detected you will be notified by email.

The file paths must be entered relative to the site's root, without a leading forward slash.

Monitor Super User accounts

Admin Tools will keep track of the user accounts with Super User access. If a new Super User is added outside of Joomla's Users page you will be notified by email. Moreover, the detected new Super User accounts will be automatically blocked. The idea is that these Super Users are most likely create as the result of a hack or rogue code.

Please note that users created or added by other Super Users in the backend of the site using Joomla's Users page will NOT be blocked by this feature. If you wish to disable this please use the Disable editing backend users' properties feature.

Disable Joomla!'s Two-Factor Authentication on password reset

When enabled, Admin Tools will disable the Joomla! Two Factor Authentication configuration for a user when they are resetting their password.

Joomla! allows every user of the site to enable Two Factor Authentication (TFA) for their user account. In case the user misplace their TFA device or is otherwise unable to use TFA they are given emergency one time passwords. However, many people forget to note them down or do not understand how to use them. Every time they cannot use TFA they have to contact an administrator of the site to disable TFA on their account. Even worse, when the user is an Administrator themselves they have no way to disable TFA without renaming files – and knowing which files to rename. This is where this Admin Tools feature comes in handy.

The workflow is the following: The locked out user starts by using the "Forgot your password?" link in Joomla! to request a password reset. The receive an email with instructions. They follow the link which takes them back to the site where they enter their username and the password reset authorisation code found in the email. Now they enter their new password. When the password changes, the "Disable Joomla!'s Two-Factor Authentication on password reset" feature of Admin Tools kicks in and disables Two Factor Authentication on this user's account. The user can now log in to the site using just their username and password.

[Important]Important

Please remember that this ONLY applies to the two factor authentication feature built in Joomla! itself. If you are using third party Two Factor Authentication solutions such as Akeeba LoginGuard this option will have NO effect on them.

We recommend AGAINST using this option because it can degrade the security of your user accounts. If an attacker gains control of the email account of a privileged user of your site, e.g. an Administrator or Super User, they will be able to reset their password AND disable their Two Factor Authentication at the same time. This will allow them to log into and take over your site. We strongly advise you to use a different Two Factor Authentication solution, e.g. Akeeba LoginGuard, with one or more fallback authentication methods. Alternatively, set up and use WebAuthn for logging into your site which bypasses the Two Factor Authentication and is far more secure than using a username, password and Two Factor Authentication code to log into your site.

Forbid front-end Super Administrator login

When enabled, it will not be possible for Super Administrators to log in to your site's front-end. This is a security precaution against password brute forcing. One common method is an attacker trying to login to the front-end of your site as a Super Administrator, trying different password until he finds the correct one. When this option is enabled, he will not be able to log in as a Super Administrator in the front-end of the site, crippling this brute forcing method of determining the Super Administrator password.

Treat failed logins as a reason for blocking the request

When enabled, failed login attempts of any kind of user (even simple registered users) count as a reason to block the request and are being logged in Admin Tools' Blocked Requests Log. There is a very useful implication to that. Since they count as security blocked requests they count towards the limit you set up in the automatic IP blocking. Therefore, after a number of failed login attempts, the user's IP will be automatically blocked for the duration you have set up.

Log usernames

By default, when a failed login is treated as a blocked request no other information is logged except the IP address of the failed login. This is very unhelpful if a user gets blocked and they can't figure out what is their IP address. Enabling this option will also log the username they used for the failed login. The downside is that your Blocked Requests Log now contains the usernames of all failed logins which can be a privacy issue if the log file is leaked to an attacker or other unauthorised person due to a vulnerability in a third party extension or by a mistake by one of the administrators of the site.

Please note that Admin Tools WILL NOT log passwords for failed logins and we WILL NOT consider any feature request to implement this kind of option. If were to log failed logins' passwords we'd be essentially storing a password the user may be using on a different service OR a slight variation of their real password in plain text in the database. This can be a major security concern.

Deactivate users on failed login

Admin Tools can optionally deactivate existing user accounts when there are multiple failed attempts to log in using their username, protecting user accounts from brute force attacks. In here you can specify the number of failed logins and the time period these have to occur before the user is deactivated, e.g. 3 failed logins in 1 minute.

In order for this feature to work you must have enabled the Treat failed logins as a reason for blocking the request option above and NOT include Login failure in the Do not log these reasons option in the Logging And Reporting area of this configuration page.

The behaviour of this feature depends on the user registration setup of your site, as defined in Users, User Manager, Options in your site's back-end. When Allow User Registration is set to No this Admin Tools feature does not do anything at all! When Allow User Registration is set to Yes there are three possible behaviours depending on the setting of the New User Account Activation option:

  • Self: The user is deactivated and an activation email is sent to them by Admin Tools using the User re-activation email template.

  • Admin: The user is deactivated and an activation email is sent to all of your site's Super Users by Admin Tools using the User re-activation email template.

  • None: This Admin Tools feature does absolutely nothing at all. The user is not deactivated and the fields for this feature are not editable. You are also shown an error message stating “User registration on your site is disabled, therefore Admin Tools can't deactivate users”.

Warn about self XSS

Display a message in browser console to warn the user to avoid running any command inside it. This can lead to hacking yourself (a.k.a. Self XSS attacks) and steal your account data.

Filter user registration by email

Admin Tools can block user registration based on the email domain they are using (listed in the field below):

  • Allow Will allow registration only if the email domain is contained inside the list. A typical use case is to allow registration only from site company addresses or student of a campus

  • Block Registration will be blocked if the user tries to use a domain contain in the list. This is usually useful if you want to block people from using temporary or disposable email accounts.

Email domains

Enter one domain per line. Having no non-empty lines disables this feature.

Below that you will find the Forgotten backend users section. This feature lets you automatically block or force a password reset for users with backend access who have not logged into the site for a very long time. This feature was inspired by a tweet by Jeff Atwood (of Discourse fame) and our observations by logging into real world sites when our clients request us to do so.

The idea is that privileged user accounts who have not logged into the site for a very long time are probably left over user accounts the site owner forgot to disable when the person stopped having a reason to log into the site's administrator backend. The password of the forgotten user account may have been compromised in the meantime. For example, the user may have reused their password on a different site which got hacked; or they may had used an easy to guess password. If Two Factor Authentication isn't enabled on the account, an attacker who has successfully compromised the password could now log into your site. Since they are using a legitimate user account they do not get their request blocked and they have full access to your site with everything that entails about your site's integrity.

This Admin Tools feature is designed to prevent this kind of awkward situation. If a user with backend access has not logged in for the configured time period (default: 90 days) they will either be completely blocked from accessing the site or they will be forced to reset their password (default and recommended action). In the first case only another Super User can unblock them, by editing their user account. In the latter case the user will try to log in and Joomla! will immediately force them to reset their password. Password reset requires providing information sent by email. This way an attacker cannot use a compromised password; they cannot read the email sent to the legitimate account holder's email address, therefore they cannot reset the password and log into your site.

For even better protection of your site we recommend that you take two more optional steps. Make sure that all privileged users have Two Factor Authentication set up on their user account. Joomla has Two Factor Authentication built in. Alternatively, you can use our more thorough, free of charge Akeeba LoginGuard extension to provide Two Step Verification (it also lets you force certain user groups to enable it). Moreover, it is recommended to have inactive user accounts automatically deleted. This can be done, for example, with our free of charge Akeeba DataCompliance component for Joomla! (however, it will not delete Super User accounts by default to prevent any accidents -- deletion through Akeeba DataCompliance is irreversible by design as it implements the GDPR requirements of Data Minimization and the Right To Be Forgotten).

The following options are available for this feature:

Prevent forgotten backend users from logging in

Should this feature be enabled at all?

Check every [minutes]

For performance reasons, this feature only runs periodically, checking which backend user accounts are inactive and disabling / forcing a password reset on them. Here you can define how often it will run. The default is 60 minutes which means that it will run at most once every 60 minutes. Other useful values are 1440 (at most once a day) and 10080 (at most once a week).

Backend user groups

Which user groups this feature should apply to? We recommend choosing at the very least the Administrator and Super User groups. If you have other user groups with backend login we recommend you add them as well.

If you do not specify any groups, or choose the "Show All Groups" option, Admin Tools will consider users from all user groups which have the Admin Login privilege, as set up in the Global Configuration of your site.

Even though you can select user groups without backend access they are NOT taken into account. The user groups list is rendered by Joomla! and it does not provide a way to remove user groups which lack backend access.

Maximum number of days since last login

Users who have not logged into the site for at least this many days will be blocked or forced to reset their password. The default is 90 days (three months). Reasonable values are between 30 and 365 days. If you set this to 0 or leave this blank the feature will effectively be disabled.

Login prevention method

What should Admin Tools do with the user accounts which have not logged in for a long time?

Block means that the user will be completely blocked from accessing the site. This is implemented by setting the Block User to Yes. The blocked users cannot unblock themselves. A Super User will have to do that by editing the user from the Joomla backend Users, Manage menu item.

Force Password Reset is the recommended and selected by default method. In this case the user account is allowed to log in but they will have to immediately reset their password and log back in before they can do anything on the site. The password reset takes place through Joomla's built in password reset method. It is NOT handled by Admin Tools.

Protected users

Any users you select here are not going to be prevented from logging into the site. We recommend that you add the site owner here. Moreover, if you are building a site for a client, you should add your user account as well. This will let you log into the site to provide technical assistant should your client require it.

It is worth noting that if Login prevention method is set to Block and Protected Users is empty Admin Tools will NOT block ANY Super Users, even if they haven't logged in for a time period longer than the specified maximum number of days. This is a precaution against losing all access to the site by accident (if all Super Users get blocked then nobody is left to unblock you). If you have a site with multiple Super Users and use the Block method you MUST specify at least one Protected User for Admin Tools to provide a sensible level of protection against forgotten user accounts.

Cloaking

WAF: Cloaking

The next section is called Cloaking and contains options to allow you to modify the way several features in Joomla! which are frequently exploited by attackers to locate Joomla! sites work. The idea is that potential attackers use automated tools to scan thousands of sites, trying to identify which of them run Joomla! in order to attack them. Using these options will allow you to "cloak" your site against such fingerprinting (scanning) attacks.

Customise generator meta tag

All Joomla! installations set the meta generator tag, a piece of HTML in the header of all pages, to advertise the fact that your site is running on Joomla!. This information is cached by search engines and is exploited by attackers to deduce that your site is running Joomla! when looking for potential targets. Enabling this option allows to set up a custom generator tag.

Generator tag

Enter the custom content of the generator meta tag. This will be applied on all frontend HTML pages generated by Joomla.

Block tmpl=foo system template switch

One of the lesser known Joomla! features are its system templates. The value of the tmpl keyword tells Joomla which .php file in the template's folder it will use to render the page. For example, ?tmpl=component tells Joomla to use the component.php file which renders only the component output, without any modules, menus or other embellishments on the page. Of and by itself this feature is not dangerous. However, hackers have realized that this feature is being abused by badly architectured plugins and components beyond the intended purpose in Joomla itself. This badly constructed third party software expects non-standard values in the tmpl keyword to do something specific, e.g. handle AJAX requests, update a shopping cart etc. The downside is that depending on how this is implemented it may open a security hole, e.g. if the code parsing the tmpl keyword in a third party extension gets confused by certain types of data and executes arbitrary code or does something unintended. For this reason Admin Tools has the Block tmpl=foo system template switch feature which will block any request that does not have one of the expected tmpl keywords for your site.

List of allowed tmpl= keywords

The list of tmpl keywords which should be allowed of your site, as a comma separated list. At the very least you MUST include system and component, otherwise Joomla! will not work properly. Default value: component,system,raw,koowa,cartupdate

The component, system and raw keywords are defined and used by Joomla itself. tmpl=component tells Joomla to only show the component output, without any modules, menus or other embellishments – however, the template's CSS files are loaded. tmpl=raw has a similar effect to tmpl=component, without loading the template's CSS files at all. tmpl=system is used for displaying error pages. Your site will NOT work properly if you remove any of these keywords from the list of allowed tmpl keywords.

[Note]Note

The koowa keyword is only required when you run components based on Nooku Framework a.k.a. Koowa, for example DOCman. According to the Koowa developers' email we received on January 2015 there are two reasons for the use of the koowa keyword:

  • The modals which contain full page JavaScript "applications", like the multi file uploader, was breaking on some templates out there because they do weird stuff in their JavaScript. No matter the precautions taken by Koowa there is at least one template out there removing the JavaScript files from the page output because they "looked like JavaScript".

  • Frontend edit forms. The Koowa developers also had a lot of problems by using tmpl=component or the normal template in frontend forms. Templates re-define Bootstrap rules, use Bootstrap 3, add weird JavaScript to "enhance" the page that has no job in the component output and so on.

So, basically, they added the custom "koowa" tmpl keyword to work around restrictions imposed by templates. The correct solution would be using tmpl=raw&format=raw but they decided otherwise. Therefore we include this keyword by default. If you are not using any extension powered by Koowa you are advised to remove that keyword from your site.

[Note]Note

The cartupdate keyword is currently only used by VirtueMart. For some strange reason its developer does not want to use format=raw for cart updates even though this is the recommended, tried and tested way to do this since Joomla! 1.5. Having had the past experience of trying to discuss best practices with him to no avail we decided to add this keyword by default without even contacting him to propose an alternative. If you are not using VirtueMart please remove this keyword from your site.

Block template=foo site template switch

Another Joomla! hidden feature is the ability to switch between installed templates by passing a special URL parameter called "template". Enabling this option will turn off this hidden Joomla! feature.

Allow site templates

Enabling this option partially overrides the previous option (the blocking of template=foo in the URL). If the template= URL query parameter specifies the name of a template which exists in your template directory, then it will be allowed without the request being blocked.

[Important]Important

If you are using the "Send this page by email" icon in your articles and/or multiple templates on your site, you MUST enable this option.

You MUST enable this option if you want your site visitors to be able to use Joomla!'s com_mailto component, i.e. the "Send this page by email" icon in your articles.

Moreover, you must use it on sites which are using more than one template at the same time. What we mean by that is that you can go to Joomla!'s back-end, go to Extensions, Templates and assign any of the installed templates to any number of menu items. When you do that, several components need to append template=yourDefaultTemplateName to the URL. This would cause your site to block the request. By enabling this option you prevent these requests from being accidentally blocked.

Enable 404 Shield

Whether the 404 Shield feature should be enabled or not.

404Shield

This feature 404 will block irregular "Page not found" requests which typically indicate that your site is being targeted by an automatic vulnerability scanner or hacking tool. For example, someone trying to access the folder wp-admin on your Joomla site is irregular since that folder is the administration area of WordPress. Since your site is running Joomla it means that the request to your site was very likely malicious, e.g. an automated tool (bot) trying to guess your access credentials by trying various common combinations of usernames and passwords. In this light, the request has to be blocked.

The default list of URLs to be blocked by 404Shield consists of known WordPress-only paths. That's because we know that these URLs cannot be found on a Joomla site and are typically used by automated hacking tools, therefore minimising the possibility of false positives. You can always add more if you want to.

Project Honeypot

WAF: Project Honeypot

Project Honeypot allows you to integrate with Project Honeypot's spam fighting services. Project Honeypot is a collective effort to detect spammers, email harversters and crackers. Its HTTP:BL service allows participants to query the IP addresses of their visitors and figure out if it is a malicious user behind it. If you enable this feature, Admin Tools will check the IP address of each visitor and, if it is a malicious user, it will block him. You have the following options:

Enable HTTP:BL filtering

Turns the entire feature on and off

Project Honeypot HTTP:BL key

Enter your HTTP:BL key. You can sign up for Project Honeypot and get your key at http://www.projecthoneypot.org/httpbl_configure.php.

Minimum Threat Rating to block (0-255, default 25)

Project Honeypot uses a logarithmic "threat rating" to rank the possibility of a specific IP being a spammer. This options defines the minimum threat level an IP must have before it's blocked. A value of 25 means that this IP has submitted 100 spam messages on Project Honeypot's spam catching honeypots and is usually a safe indication that it belongs to a spammer. Do note that the rating is logarithmic. A value of 50 means 1,000 spam messages and a value of 75 means one million spam messages. Do not set it to values over 50, as you will most likely never block any spammer at all.

Maximum age of accepted HTTP:BL results

Project Honeypot reports when was the last time this IP was caught sending spam messages. The older this is (the higher the age is), the less likely is that this IP is still used by a spammer. You can chose here what will be the maximum reported age that will be blocked. The default value of 30 means that IPs which have submitted a spam message in the last 30 days will be blocked.

Also block suspicious IPs, not just confirmed spammers

Sometimes Project Honeypot is not sure if an IP belongs to a spammer or it's a hapless chap who clicked on the wrong link. In this case the IP is marked as "suspicious". The default behaviour is to not block these IPs. However, if you are receiving a lot of spam it's a good idea to enable this feature and block even "suspicious" IPs. Ultimately, some unfortunate users will be inadvertently blocked, so use this option with caution!

Exceptions

WAF: Exceptions

Sometimes you do not want to block certain IPs or domain names. For example, you don't want to block Google Bot, MSN (Bing) Bot and so on. You can easily add Exceptions from blocking. You can set the following options to prevent Admin Tools from blocking certain IPs and domain names:

Never block these IPs

Enter the IP addresses or address blocks which should never be automatically blocked. You can enter IPv4 and IPv6 addresses in the following formats:

  • Single IPv4 or IPv6 address e.g. 127.0.0.1 or ::1

  • IPv4 address range e.g. 127.0.0.1-127.0.255.255

  • IPv4 implied range e.g. 127.0.0. for the entire 127.0.0.1 to 127.0.0.255 block

  • IPv4 or IPv6 CIDR block notation e.g. 127.0.0.0/8

You may enter a dynamic IP domain name prefixed by the at-sign (for IPv4) or hash-sign (for IPv6). This only applies if you are using a dynamic IP address domain provider (e.g. DynDNS). For example, if you are using DynDNS and your dynamic IP address domain name is example.dyndns.info and resolves to an IPv4 address you can enter @example.dyndns.info to always allow your dynamic IPv4 address. Conversely, if your dynamic hostanem resolves to an IPv6 address you can enter #example.dyndns.info to always allow your dynamic IPv4 address. Be careful to enter the correct domain name or you may have a delay of up to 30" processing blocked requests.

[Tip]Tip

If you are using the Exclusive Allow IP List feature to allow access to the administrator section of your site only to specific IPs, these IPs are automatically added to the safe list of IPs which should never be automatically blocked. You do not have to enter them here.

IPs added to this list are fully allowed to do anything. This means that no security measure will be applied against them. Please place only very well trusted IPs in this list! If an attack is launched from this IP, it will not be blocked by Admin Tools!

The default list of IP addresses lists the known good IP addresses of major search engines: 20.191.45.212, 23.21.227.69, 40.88.21.235, 50.16.241.113, 50.16.241.114, 50.16.241.117, 50.16.247.234, 52.5.190.19, 52.204.97.54, 54.197.234.188, 54.208.100.253, 54.208.102.37, 107.21.1.8

Allowed domains

If the IP address of the visitor whose request would be blocked resolves to a domain name ending in what you enter here they will not be blocked. Effectively, these domain names have a free pass on your site.

[Warning]Warning

Malicious URLs from these domain names WILL be blocked but a. this will not be logged and b. their IP address will not be automatically blocked by the "Auto-ban Repeat Offenders" feature below. This is done to protect your site against reflected search engine attacks. Let us explain this.

Some hackers try to exploit search engines' eagerness to scan URLs, crafting malicious URLs to your site and putting them on their own sites. Search engines will see them and try to visit them on your site. You are explicitly allowing these search engines as you don't want to lock them out of your site. If the malicious URL wasn't blocked just because the request comes from a seemingly innocent source your site would be instantly hacked. That's why the malicious URLs are still blocked, just not logged or cause IP addresses to be automatically banned.

The default list of domain names is .crawl.baidu.com, .crawl.baidu.jp, .google.com, .googlebot.com, .search.msn.com, .crawl.yahoo.net, .yandex.ru, .yandex.net, .yandex.com which allows the search engine indexers for Baidu, Google, Bing, Yahoo and Yandex.

Auto-ban

WAF: Auto-ban

This feature allows you to automatically and temporarily ban IP addresses which get repeatedly blocked. This can be prove to be an effective measure against malicious users who try to probe your site for vulnerabilities. You MUST enable logging of blocked requests for this feature to work. You can set the following options to define how Admin Tools will behave in those cases:

IP blocking of repeat offenders

When requests from an IP address are blocked a certain number of times within a specified time period, as defined by the next three options, the IP address will be temporarily from accessing the site.

This feature is meant to be used as an additional defence against bots attacking your site. You should keep the Block After time period relatively short (in the range of a few seconds to a few minutes) and the number of detected attacks relative high. Otherwise a number of false positives or more innocuous block reasons such as trating failed logins as a block reason could result in your or your visitors' IP addresses being blocked.

For the same reason you should keep the block time relatively short, between a few minutes to an hour. Otherwise a legitimate visitor blocked accidentally due to false positives will be unable to access your site in a practical amount of time, losing you that site visitor possibly forever.

Block IP after this many blocked requests

When requests from an IP address are blocked at least this many times within the period of time defined by the next two options it will be temporarily blocked from accessing the site. For example, if you set it to 3 attacks in 1 hour, Admin Tools will disallow access from an IP address which got at least 3 of its requests blocked within the last hour.

Time period

The number of blocked requests defined above must occur within this many seconds, minutes, hours or days. You enter the number here; you choose the unit of time measurement in the option below.

Unit of time measurement

The unit of time measurement for the “Time period” setting above. Choose one of seconds, minutes, days or hours.

Block duration

How long the block will last. For example, setting it to 1 day will block all access from this IP address for a whole day. Enter the number in this field, select the unit of time measurement in the next field.

Unit of time measurement for block duration

The unit of time measurement for the “Block duration” setting above. Choose one of seconds, minutes, days or hours.

Add persistent offenders to the IP Disallow List

If an IP triggers this many auto-bans it will be permanently banned (added to the IP Disallow List) if they are about to be auto-banned again. Make sure that you turn on the IP Disallow List feature by setting Disallow site access to IPs in the IP Disallow List to Yes, otherwise the permanent adding to the IP Disallow List will have no effect.

Permanently disallow IP after this many automatic blocks

When the previous option is enabled, after how many auto-bans an IP will be permanently banned (added to the IP Disallow List).

Email this address if an IP is auto banned

Admin Tools can optionally send you an email when an IP is automatically banned, to the email address entered in this field. This will allow you, for example, to determine if some IP is being regularly blocked, in which case it may be a good idea to place it in the permanent IP black list. Leave this field empty (default) to disable this feature.

Show this message to blocked IPs

Allows you to show a specific message to blocked IP addresses. You may want to explain to the user that his IP was blocked because suspicious activity was detected as originating from his IP address.

You can use the special text [IP] in all capital letters, without spaces between the brackets and IP, to display the user's IP in the message. This may be useful if someone gets accidentally blocked and asks you to help them.

Logging & reporting

WAF: Logging & reporting

In the Logging and reporting section you can change the way Admin Tools logs and reports various activity items and blocked requests on your site.

Email PHP Exceptions to this address

Whenever an unhandled PHP exception is raised (ie an error on a database query), Admin Tools will send an email containing all the details (time, file and line raising the exception) for later debugging.

Save user sign-up IP in User Notes

When enabled, the IP new users signed up from will be stored as User Notes.

[Important]Important

This feature is guaranteed to work only when a user registers to your site using the front-end user registration form provided by Joomla!. Users created through the back-end will not have their IP saved as a User Note because it makes no sense to do so (it's an administrator registering the user account on their behalf). Third party components creating new user accounts may also not trigger the plugin event.

Log blocked requests

It is suggested to keep this option enabled. When enabled, all potential security issues —blocked by Admin Tools— will be logged in the database and made available under the Blocked Requests Log tool. This is required for the automatic IP blocking feature to work.

Please note that turning off this feature will also disable the debug log file, even if the option below is set to Yes.

[Important]Important

When this option is turned off the automatic IP blocking of repeat offenders, automatic adding of IPs to the IP Disallow List and most email notification features will be deactivated.

Do not log these reasons

Blocked requests due to these blocking reasons will not be logged. As a result, IPs getting their requests repeatedly blocked because of this reason will not be automatically banned from your site. Moreover, as there is no log, it will be impossible to tell why someone is being blocked from accessing your site when they trigger one of those reasons.

For a list of what each reason means please consult the list of WAF log reasons. You can start typing or click on on the field to show the list of reasons.

The default setting is empty

Keep a debug log file

It is suggested to keep this option disabled unless you are troubleshooting.

When enabled, Admin Tools will create a file named admintools_blocked.php in your site's administrator/logs directory (or wherever you have configured your logs directory to be). This contains all the information sent in the request that Admin Tools blocked. This may include sensitive information such as usernames, passwords and personally identifiable information. For this reason you must only enable this feature for a limited amount of time when troubleshooting. We may ask you to do this, and send us a copy of the log file, if you ask us for support.

The file has an extension of .php and begins with a PHP die() statement to prevent direct web access if your log directory is accidentally left web accessible. An attacker may try to access the file but all they will get is a blank page.

When you disable that option, the existing log files will be removed once you visit Admin Tools' Control Panel page again.

Do note that your logs directory MUST be writable for the log file to be generated.

Some servers use automated file scanners which will mistakenly flag Admin Tools' log file as a security threat. Because of that they might issue an automated warning to you that your site is hacked, rename / delete the file or prevent web access to your site (put it offline). This is a mistake and does not reflect the truth. Our log file does have an executable extension (.php) and does contain the signatures of hacking attempts (the hacking attempts it stopped from hacking your site!) BUT the hacking attempts signature themselves are NOT executable. In fact, the only reason this is a .php file is so that we can put a PHP die() statement at the top of the file to prevent it from being executable over the web. This information is also printed at the top of the file, in its header. If your host is giving you grief about the log file please show them this documentation page or ask them to actually review the file and read its header. If they still insist that they have to block your site please go to a different host that understands how PHP works and, by extent, is a much safer choice. In the meantime, just disable the Keep a debug log file option.

IP Lookup Service

Admin Tools will provide you with a link to look up the owner of an IP address in the emails it sends you, as well as the Blocked Requests Log and Auto IP Blocking Administrator pages. By default, it uses the ip-lookup.net service. This option allows you to use a different IP lookup service if you so wish.

As of Admin Tools 7, the IP lookup service MUST use HTTPS since you are sending it IP addresses. Doing so over plain HTTP may carry privacy and/or security risks.

Enter the URL of the IP lookup service you want to use in this text box. The {ip} part of the URL will be replaced with the IP address to look up. For example, the default URL (for ip-lookup.net) is http://ip-lookup.net/index.php?ip={ip}

Email this address on blocked request

Enter one or more email addresses (separated by commas) which will get notified whenever a request is blocked on your site. For example alice@example.com for one recipient only or bob@example.com, charlie@example.net, diane@example.org for multiple recipients. The email addresses need not be in the same domain name and don't even need to be users of the site itself. Any email address will do.

A "blocked request" is anything which triggers the Web Application Firewall and causes it to block an incoming request to serve a page. This is useful to get an ahead warning in the event of a bot trying to perform a series of attacks on your site.

The contents of the e-mails can be configured using the Email Templates feature in the Web Application Firewall page.

Do not send email notifications for these reasons

Blocked requests caused by these blocking reasons will not result in an email being sent to the email address specified in "Email this address on blocked request".

For a list of what each reason means please consult the list of WAF log reasons. You can start typing or click on on the field to show the list of reasons.

The default setting is empty

Email this address on successful back-end login

Enter an email address which will get notified whenever someone successfully logs in to your site's administrator back-end. If you do not wish to use this feature, leave this field blank. If you enter an email address, every time someone logs in to the administrator area an email will be sent out to this email address stating the username and site name. If you want to send a notification to multiple email addresses separate them with commas, e.g. alice@example.com, bob@example.net. The email addresses do not need to be in the same domain and they don't even have to be linked to users of your site.

This allows you to get instant notification of unexpected administrator area logins which are a tell-tale sign of a hacked site. In that unlikely event, immediately log in to your site's back-end area, go to Extensions, Admin Tools and click on the Emergency Off-Line Mode button. This will cut off the attacker's access to the entirety of your site and gives you ample time to upgrade your site and its extensions, as well as change the password (and maybe the username) of the compromised Super Administrator account. For maximum security, after taking your site back on-line, log out, clear your browser's cookies and cache and log in again.

The contents of the e-mails can be configured using the Email Templates feature in the Web Application Firewall page.

Email this address on failed administrator login

Enter an email address which will get notified whenever someone tries to log in to your site's administrator back-end but is denied access. If you do not wish to use this feature, leave this field blank. If you enter an email address, every time someone unsuccessfully tries to log in to the administrator area an email will be sent out to this email address stating the username and site name. If you want to send a notification to multiple email addresses separate them with commas, e.g. alice@example.com, bob@example.net. The email addresses do not need to be in the same domain and they don't even have to be linked to users of your site.

This allows you to get instant notification of unexpected administrator area login attempts which are a tell-tale sign of a hacked site. In that unlikely event, immediately log in to your site's back-end area, go to Extensions, Admin Tools and click on the Emergency Off-Line Mode button. This will cut off the attacker's access to the entirety of your site and gives you ample time to upgrade your site and its extensions, as well as change the password (and maybe the username) of a potentially compromised Super Administrator account. For maximum security, after taking your site back on-line, log out, clear your browser's cookies and cache and log in again.

The contents of the e-mails can be configured using the Email Templates feature in the Web Application Firewall page.

Customisation

WAF: Customisation

The Customisation section allows you to change the way Admin Tools presents the error message to people who are denied access to the site.

Custom Message

By default, Admin Tools uses a generic message ("We detected that your latest request may have been part of suspicious activity and has been blocked. If you believe you are getting this message in error please let us know through our site's contact form.") when a request is blocked. Considering that this may not be exactly the kind of message you want your visitors to see, we allow you to customise it. Just type in the message to be shown to site visitors when a request is blocked.

Show errors using a customisable HTML template

By default, the Custom Message will be shown using Joomla!'s standard error message page. This is not always desirable, as that page lacks proper styling and admittedly looks very cheesy. When this option is enabled, however, Admin Tools will use a customisable HTML template.

The default HTML template file is located in the components/com_admintools/tmpl/Block/default.php file. DO NOT MODIFY THIS FILE DIRECTLY! It will be overwritten on each upgrade. Instead, you will have to do a template override. For more information regarding template overrides, please consult Joomla!'s documentation wiki page.

Send troubleshooting email on administrative functions

Some Admin Tools administrative functions have the potential to make your site behave in a way you didn't expect or even lock you out of your site. This can happen because of a misunderstanding of what a security feature does, a misconfiguration or –more rarely– a browser or server mangling the configuration you are submitting to Admin Tools. We understand that this leads to frustration and occasional panic as you have no idea what happened and how to fix it.

For this reason Admin Tools will automatically send you an email with troubleshooting instructions every time you take any administrative action which might result in getting locked out of your site or your site not working properly. These actions include applying the initial configuration with the Quick Setup Wizard, changing the Web Application Firewall configuration, applying administrator password protection or saving a new .htaccess, web.config or NginX configuration file through the relevant Admin Tools features.

The email explains what change took place and includes links to our troubleshooter documentation which can help you get your site back to a working state. Moreover, it has a reminder about getting support from us if all else fails.

The email is sent only to the email address recorded on the user account logged into Joomla who initiated this change. It is not sent to other Super Users, Administrators or, in general, any other email address. Also note that if you have set Receive system email to No in your Joomla! user profile you will not receive this email.

This option can be used to turn off this feature for all administrator users with access to Admin Tools, regardless of their Receive system email status. We recommend leaving this option enabled unless you are absolutely sure you know what you're doing and you're confident you can find your way to the troubleshooter documentation on your own.

Troubleshooting (I got locked out of my site)

It's possible to accidentally lock yourself out of the administrator area, especially when using the Exclusive Allow IP List or IP Disallow List options of the Web Application Firewall. The easiest way to work around this issue is using an FTP application or your hosting control panel's File Manager to rename a file.

Go inside the plugins/system/admintools/services directory on your site. You will see a file named provider.php. Rename it to provider-disable.php. This will turn disable the Web Application Firewall from executing and you can access your site's back-end again. After you have fixed the cause of your issue remember to rename provider-disable.php back to provider.php, otherwise your site will remain unprotected!