How to Create Custom Alerts in the WordPress Audit Trail

You are here:

Keep a Record of Any WordPress Change You Want in the WordPress Audit Trail

This document explains how you can build a sensor  and create custom alerts in WP Security Audit Log plugin to keep track of any type of change on your WordPress. Therefore now you can easily monitor changes on your WordPress that an out of the box installation of the plugin does not.

Introduction to the Process of Creating a Custom Alert in the WordPress Audit Trail

WP Security Audit Log Sensors

For every set of changes, WP Security Audit Log has a sensor. For example to monitor all the login and logouts on WordPress, the plugin’s sensor is called LogInOut.php. All sensor files can be found in the following plugin directory:  /wp-security-audit-log/classes/sensors/. 

Note: Custom sensors should be stored in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory so they are not overwritten during plugin updates.

The Alerts

All the alerts that the plugin uses in the WordPress audit log are declared in the file defaults.php which can be found in the root directory of the plugin (/wp-content/plugins/wp-security-audit-log). Refer to the complete list of WordPress security alerts for more information on the alerts.

Custom alerts should be declared in a file called custom-alerts.php which should be saved in the following directory: /wp-content/uploads/wp-security-audit-log/. Custom alerts are saved in another file so they are not overwritten during an upgrade.

The Process of Creating a Custom Alert

Therefore the process of creating a custom alert, or a number of custom alerts in the WordPress audit trail is very simple:

  1. Create a sensor in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory
  2. Declare the alerts in the file /wp-content/uploads/wp-security-audit-log/custom-alerts.php. As simple as that. Let’s start

Read the rest of this post for more detailed explanation of how to build your sensor.

WP Security Audit Log Sensors Documentation and Sample Code

Before proceeding please download the file which includes the sample sensor file and custom alerts file used for the below example.

Developing the Sensor for WP Security Audit Log

Extract and open the sensor file WSAL_Sensors_CustomHooks.php from the zip file. The code in the sample sensor is fully documented  but just in case here is also a quick introduction. First you have to specify a class for your custom sensor:

Then specify the hooks you are going to use in this sensor in the section HookEvents, shown in the following code sample:

In the next and last part is where you should have the actual sensor code, i.e. the code that specifies what to monitor and what is the change that should generate the alert. In this section you should also specify the details about the WordPress security alert that is created in the WordPress audit trail, including the alert severity, alert code, alert text and any other variables that you want to use in the alert text.

Save and Name Your Sensor File

Once you’re ready with the code save the sensor file in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory. The filename should always be the same as that of the class without the WSAL_Sensors_ prefix. So in this example the file is CustomHooks.php.

Declaring the Alerts in WP Security Audit Log

Once you create your sensor file, declare the alerts in the file custom-alerts.php which you can also find in the zip file you downloaded. The file should be saved in: /wp-content/uploads/wp-security-audit-log/. Below is the sample code for 3 alerts with different severity:

Once the custom alerts have been declared and the code is ready, navigate to the Enable/Disable Alerts nodes and you should be able to see your custom alerts in the Third Party Support tab, as seen in the below screenshot.

Custom alerts in WP Security Audit Log

Register Your Custom Alerts with Us

If you create your own sensor and custom alerts we recommend you to contact us and register your custom alerts, especially if you are creating alerts for a plugin or a component that is available to the public. By registering the alert you ensure that it is not used by anyone else, hence avoiding conflicts.