As of BBQ Pro version 1.3, it is possible to log the details of blocked requests by hooking into the scan() function. This tutorial explains how to get started and provides a free logging plugin to help you go further with logging requests and sending email alerts.

Update! As of BBQ Pro version 2.5, email alerts are provided by the plugin, if enabled. Eventually, logging will be integrated. Until then, the following tutorial explains how to set it up.

How it works

BBQ Pro 1.3 and better provides the following action hook:

bbq_scan

This hook enables you to access the following variables for each request:

  • $match – the matching pattern
  • $request_uri – the requested URI
  • $query_string – the query string
  • $user_agent – the user agent
  • $referrer – the referrer
  • $protocol – the HTTP protocol
  • $ip_address – the IP address
  • $the_request – the full URI request

So you can write your own custom logging functions to record requests that are blocked by BBQ Pro. Here is a simple example:

function bbq_log_requests($match, $request_uri, $query_string, $user_agent, $referrer, $protocol, $ip_address, $the_request) { 
	
	if (!isset($match) || empty($match)) return;
	
	$admin_email = get_bloginfo('admin_email');
	
	$subject = 'BBQ Alert: Blocked Request';
	
	$pattern = isset($match[0]) ? $match[0] : '';
	$count   = isset($match[1]) ? $match[1] : '';
	
	wp_mail($admin_email, $subject, $pattern .' = '. $count);
	
}
add_action('bbq_scan', 'bbq_log_requests', 10, 8);

This simple function grabs the variables, lines them up, and sends the site admin an email alert. It is a simple example, but shows how to hook into BBQ Pro and do some custom logging of blocked queries.

Important! When tapping into BBQ (as in the above example), you must do so via custom plugin. Trying to add the above code to your theme template will not work (nothing will happen). To check out an example of how it works, download the free plugin below.

Why isn’t detailed logging built-in to BBQ Pro?

One reason: performance. BBQ Pro is designed with two main objectives: security and speed. I heart BBQ Pro because it is so ultra lightweight and super fast, so it protects your site without slowing things down. You should not have to sacrifice speed for security. With BBQ Pro you can have both.

Additionally, BBQ Pro does provide basic count statistics in a nice graphical interface to show you which patterns are blocked the most. Here is a screenshot of the stats that are included with BBQ Pro:

BBQ Pro - BBQ Statistics

But it’s also nice to be able to log more robust data, details and such. So the bbq_scan hook now is available to help make it happen. For a more complete example of how the hook can be used to log request data, download the following free logging addon/plugin.

BBQ Log-Requests Plugin

Below you can download the BBQ Logging plugin. The first version of this plugin was very simple, not too far from the basic logging example function provided above. Thanks to feedback from Farrhad A. and others, the latest version of the logging plugin features both logging and email alerts, and is much improved over the previous version.

Note: By default, only email alerts are enabled, with no logging.

Usage

Here are steps to using the BBQ Pro Log Requests plugin:

  • Open the file, bbq-pro-log-requests.php
  • Edit the variables located near the top of the file
  • Save changes and upload/activate the plugin
  • Done.
Important

If you enable logging, the included plugin file, bbq-pro-log.txt, must be made writable by the server. This file is protected from public access via the included .htaccess file (see next note about the .htaccess file).

Apache/.htaccess file

This plugin includes an file named .htaccess that is invisible on most systems. This file can be seen using any decent code editor app, either by default or enable to view hidden files in the app settings. No changes need made to the file, but you should be aware of its existence and purpose: it protects the log file from public access. This is important for security reasons: the .htaccess file ensures that the log file (and all of its logged data) remains 100% private.

Download

Here you can download the latest version of the BBQ Pro Log Requests plugin.

Current version: 2.3

Download BBQ Log Requests Plugin (4KB ZIP)

For more infos and Changelog, check out the plugin’s readme.txt (included in download zip file).

More development in the works

Note that this example plugin is just a starting point because people have asked for it. I will be beefing up the plugin to include database logging in future updates of BBQ Pro, so stay tuned!

Related