Logging That Tells You Something

The hardened site from the first two lessons in this module now has a log file outside the web root, debug logging on, and automatic updates enabled. Three weeks later, someone asks a question the log cannot answer: did an administrator account get created last Tuesday night? The log contains 40,000 entries, most of them from a plugin that fires a notice on every request, and nobody has read any of them.

Logging fails in two directions. Write too little and you cannot answer the question. Write everything and you have answered nothing while spending disk and attention. The way out is to start from the questions, not the events. "Did an account change happen without a deploy" is a question. "Log all admin activity" is a wish.

A log answers a question or it is noise

Four questions cover most of what you will ever need on a WordPress site. They are worth recording because each has a small, bounded set of events that answer it, and because the answers are cheap to keep.

The fourth question is the one WordPress answers least well on its own. The hooks tell you a plugin was activated; they do not tell you a PHP file was written into wp-content/uploads/ by an upload handler that should not have allowed it. File modification detection belongs outside WordPress, on the filesystem, and lesson 1 already showed why the naive version fails: whatever writes the file also owns it.

All four hooks are real, and their signatures are stable. wp_login_failed receives the raw username, set_user_role receives the user ID, the new role and the old roles, and update_option receives the option name, the old value and the new value. That last one is a trap for two reasons: it fires for options that change constantly, and both values are arbitrary serialised data.

WP_DEBUG_LOG is an error log, not an audit log

People discover WP_DEBUG_LOG and reach for it as a general-purpose sink, because it is already there and it writes without any setup. It has three properties that make it a poor audit log and a fine error log. It lives inside wp-content by default. Nothing rotates or truncates it. And it records PHP notices and warnings, which on a WordPress site with a few plugins means thousands of lines a day that are nobody's fault and nobody's problem.

If you use it for error logging, use it deliberately:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', '/var/log/wp/site-error.log' );

An absolute path outside the document root is the whole point. With the boolean form, the log lands at wp-content/debug.log, and a request to that URL returns the file as text/plain with no WordPress involvement at all. If you inherited a site where that is true, the log has been readable for as long as it has existed, and it contains absolute paths, plugin names, and occasionally a database error with the connection string in it.

For the audit events from the previous section, write to the same place with your own logger, and prefer the system log over a file you own. On a host that hands you syslog, PHP's openlog() and syslog() put your lines where the rest of the machine's logs go, with the host's rotation, permissions and shipping:

function m5_audit( $event, array $context = array() ) {
    static $open = false;
    if ( ! $open ) {
        openlog( 'wordpress', LOG_PID | LOG_NDELAY, LOG_AUTH );
        $open = true;
    }

    $line = $event;
    foreach ( $context as $key => $value ) {
        $line .= ' ' . $key . '=' . m5_log_value( $value );
    }

    syslog( LOG_WARNING, $line );
}

error_log() is not the enemy, but it has one argument: the message. You cannot set a severity, you cannot attach structured fields, and the destination depends on a php.ini setting you did not choose. A real logger gives you levels, so that an authentication failure and a PHP deprecation notice can be filtered differently, and sending your audit trail to syslog or to the same infrastructure as your application logs is what lets a search span both.

User input writes its own lines unless you stop it

This is the failure that makes a log actively dangerous rather than merely useless. Every line in a log implies a structure. If a single field can contain a newline, that field can create a line of its own with whatever structure the attacker wants.

A failed-login handler is the classic case, because the username comes straight from the request. The naive version:

add_action( 'wp_login_failed', function ( $username ) {
    error_log( 'login_failed user=' . $username . ' ip=' . $_SERVER['REMOTE_ADDR'] );
} );

Now submit the login form with a username containing a newline. I used WordPress 7.0.7 on PHP 8.5.6 and the login form directly:

curl -b 'wordpress_test_cookie=WP Cookie check' \
  --data-urlencode 'log=ana
[16-Oct-2026 03:00:00 UTC] SUCCESS: admin logged in from 10.0.0.9' \
  --data 'pwd=wrong&wp-submit=Log+In&testcookie=1' \
  https://example.test/wp-login.php

$ od -c wp-content/debug.log | tail -4
0000140   l   o   g   i   n   _   f   a   i   l   e   d       u   s   e   r
0000160   =   a   n   a  \n   [   1   6   -   O   c   t   -   2   0   2   6

The \n is in the file. A grep for SUCCESS finds a line that no WordPress code wrote, and a human reading the log at 2am has no way to tell it from a real entry. The attacker has not gained access; they have corrupted your evidence, which is worse than useless during an incident because it points your investigation at a fabricated login from a fabricated IP.

The fix is to make every value safe for a single-line format before it is written. Encode what must be preserved and discard what cannot be encoded:

function m5_log_value( $value ) {
    $value = is_scalar( $value ) ? (string) $value : wp_json_encode( $value );
    $value = str_replace( array( "\r", "\n", "\t" ), array( '\r', '\n', '\t' ), $value );
    return substr( $value, 0, 200 );
}

The substr() is not decoration. Without a length cap, a 4 MB username becomes a 4 MB log line, and enough of those fill the disk on a host that has one. Cap every field, including the ones you believe a user cannot reach.

Retention is a decision about disk, privacy and evidence

An unbounded log is a scheduled outage. WP_DEBUG_LOG never rotates; a file-based audit log you wrote never rotates either. On a busy site with a chatty plugin, the debug log can grow faster than the database. The fix is logrotate or a log handler that ships lines off the machine, plus a maximum size at which old lines are dropped.

Decide the window before you need it, because three forces disagree. Forensics wants months: an incident that started as a slow account takeover is rarely visible on the day you notice it. Privacy wants days: authentication logs contain personal data, and the regimes you might be under do not let you keep it forever because it is convenient. Disk wants whatever is cheapest. A common compromise is 30 days of full-fidelity application logs shipped off the host, plus 12 months of daily aggregates that keep the counts but not the rows.

Two rules make that defensible. Keep logs where the application cannot rewrite them, because the first thing a competent attacker does with file access is edit the log. And make sure the log itself is not the leak, which means permissions, a location outside the document root, and no secrets, tokens or full card numbers in a log line. If you find yourself logging a token to debug an integration problem, log its first six characters and a hash.

A compromised WordPress looks like a pattern, not a line

No individual entry proves anything. Authenticated users 404 too, and a plugin activation at 3am is a deploy that ran late. What identifies a compromise is a combination across two logs, and the access log is the one most people never look at.

• A spike in 404s to wp-login.php is either a broken redirect or a scanner, and the difference is the response code distribution: scanners produce a long tail of unique paths and low traffic per path.
• POST requests to a file that should only ever be read. A POST to an image in wp-content/uploads/, or to a .txt file, is a webshell phoning home. Upload directories should not appear in the access log with a POST method at all.
• A new administrator created at 3am. Correlate the application log line for set_user_role with the access log line for the request that caused it. If the triggering request came from an IP that has never logged in before, that is the finding.
• An option that changed without a deploy. Record deploys in the same timeline as the log. An option write five minutes after a deploy is expected; the same write on a Tuesday at 04:12 with no deploy is not.
• File mtimes that disagree with the release. A PHP file in wp-content/plugins/ modified after your last deploy, where your deploy did not touch it, is the strongest single signal available.

The shortest useful alert set is five rules, and all five are expressible in a shell script or a log product's query language:

1. More than 20 failed logins for one IP in 10 minutes.
2. More than 5 failed logins across 5 or more distinct usernames from one IP in 10 minutes.
3. Any set_user_role or user creation event outside a deploy window.
4. Any activated_plugin or switch_theme event outside a deploy window.
5. Any PHP file under wp-content/ with an mtime newer than the last recorded deploy.

Rules 1 and 2 are the same attack at two speeds, and 3 to 5 are the persistence that follows a successful one. Note what is not on the list: a generic "suspicious activity" detector, a total-requests threshold, or anything that fires on 404 volume alone. Every rule above either names a specific event or a rate with a specific unit, which is what makes it possible to tune without turning it off.

add_action( 'wp_login_failed', function ( $username ) {
    m5_audit( 'login_failed', array( 'user' => $username, 'ip' => m5_client_ip() ) );
} );

add_action( 'set_user_role', function ( $user_id, $role, $old_roles ) {
    m5_audit( 'role_change', array(
        'user_id' => $user_id,
        'role'    => $role,
        'old'     => implode( ',', (array) $old_roles ),
    ) );
}, 10, 3 );

add_action( 'activated_plugin', function ( $plugin ) {
    m5_audit( 'plugin_activated', array( 'plugin' => $plugin ) );
} );