Firewall Learning Mode

Learning Mode allows the Web Application Firewall to be adjusted to your site.

The Wordfence firewall blocks requests (visits) to your site that match specific patterns. For example, if a visitor makes a request with a query string that includes a pattern such as “../../” Wordfence detects it as a “Directory Traversal” attack and will block that request. Sometimes WordPress plugins and themes will exhibit behavior that resembles known attack patterns, which may then result in the firewall blocking something that is not actually malicious. This is called a false positive.

To prevent false positives from causing problems with the functionality of your site, the Wordfence firewall has a feature called “Learning Mode”. When “Learning Mode” is active, Wordfence will add any requests that resemble attack patterns to the allowlist. If the “Web Application Firewall Status” had been set to “Enabled and Protecting” then the requests would instead have been blocked. When a request is added to the allowlist it is considered safe and will not be blocked, unless it is removed from the allowlist.

You can see the firewall status one of two ways:

  • In the “Basic Firewall Options” section on the “Firewall” > “All Firewall Options” page
  • In the “Basic Firewall Options” section on the “All Options” page

The firewall has three status modes as follows:

  • Enabled and Protecting
  • Learning Mode
  • Disabled

It’s important to understand that your site is not protected from certain complex attacks while it is in “Learning Mode”.

When “Learning Mode” is active, some requests that look suspicious are added to the allowlist. Other parts of the firewall remain fully active, including “Brute Force Protection”, “Login Security”, other blocking features, and the “Real-Time IP Blocklist” (premium feature). If you are installing Wordfence because your site was recently hacked, or because your site is currently under attack, then you should not use “Learning Mode”.

To view the current firewall status, or to change the firewall status to “Learning Mode”, you can do this from two areas of the plugin. You can open the “Firewall” > “All Firewall Options” page. You can then view or change the firewall status in the “Web Application Firewall Status” section. Alternatively, you can expand the “Basic Firewall Options” section on the Wordfence “All Options” page and view or change the firewall status in the “Web Application Firewall Status” section.

How to Use Learning Mode

When Wordfence is first installed, “Learning Mode” will be active for seven days, but you can choose a different time period on the firewall options page if desired.

When “Learning Mode” is active, you should visit your site and perform everyday tasks as you usually would. Try to use all of the features of your site. The more features you use during this period, the less likely you are to run into unwanted blocks of valid actions in the future.

For example, you may want to try each of these:

  • Write and publish posts and pages
  • Change theme styles
  • Change plugin settings
  • Add or remove widgets
  • Write or moderate comments
  • Use all of the features of your other plugins

If you have used all of the features of the site while in “Learning Mode”, you can go to the firewall options page and change the Firewall Status to “Enabled and Protecting”. If you are not certain that you have used all of the features, you can let “Learning Mode” run for the full seven days.

Understanding the Allowlist

The allowlist shows the location of each item that has been added to the allowlist, and which related parameters are allowed. This means those parameters could have been blocked if they were not found during “Learning Mode”.

You may recognize most allowed plugin or theme files and parameters by the URL or parameters listed. The IP address of the visitor who triggered the addition of the request to the allowlist is also listed, so you can see whether it was your own action or another visitor.

If you find a large number of allowed items, more than 20 for example, then it could mean that one of your plugins displays a form on multiple pages on the site, like a custom comments plugin, which could be blocked when it should be allowed. Otherwise, it may mean that there was an attempted attack on your site during “Learning Mode”, and you may need to remove some of the allowed items.

What to Do If a Page Is Blocked After Learning Mode Is Complete

If you are logged in as an admin, and a request was blocked because of a potentially dangerous action, you will see a button below the blocking message that you can use to add that action to the allowlist. Only use this button if you are certain that you are doing something safe. If someone has sent you a link to your own site that triggers this message, or they ask you to copy and paste something and you see this message as a result, it is very likely to be unsafe! If you’re not sure it is safe, then do not add it to the allowlist.

If you were not logged in when the problem occurred, or if a regular visitor reports the problem, then you can find the blocked visit on the “Tools” > “Live Traffic” page feed. In the box that says “Filter Traffic,” choose “Blocked by Firewall” to see the blocked request. If you know that the action was something safe (especially if it was your own visit), you can click the “Add param to firewall allowlist” button. If you are not sure if the visitor was doing something safe, you should ask for more details about what they were doing at the time the message appeared, and see if you can get the same message yourself.

When installing or updating a new plugin or theme, if multiple actions are blocked or some features do not work, you can turn on “Learning Mode” again, at the top of the firewall options page. When you turn on “Learning Mode” manually, it does not expire unless you choose a date when it should be automatically enabled. After trying the page or action that was being blocked, any necessary parameters should be added to the allowlist automatically. You can then review the allowlist and set the “Web Application Firewall Status” back to “Enabled and Protecting”. It is important to remember to re-enable it, or the firewall will continue to add potentially unsafe requests to the allowlist in “Learning Mode”.