Skip to content

Auditing password changes — postpasswd hooks for compliance and notifications

Customer password changes happen all day; without a hook, the security team sees none of them. A short postpasswd hook gives you the audit trail compliance needs.

Compliance frameworks — SOC 2, PCI, ISO 27001 — expect an audit trail of credential changes. The default cPanel logs include password-change events, but they’re scattered across several log files and the message format isn’t consistent. A postpasswd hook centralizes the audit: every password change, for every user, with a structured record you ship to your SIEM or compliance store. Two hours of setup; a permanent answer to “show me every credential change on this server.”

What’s happening

cPanel fires the Whostmgr::Accounts::Modify [post] event after a modifyacct call that includes a password change, and Cpanel::Passwd::change [post] for end-user password changes through the cPanel UI. A registered post-hook receives the payload — user, action, timestamp, source IP if known — and can ship the record anywhere. The hook does not store the password; only the metadata of the change.

How to verify

Inspect what’s currently logged and what hooks are registered:

grep passwd /usr/local/cpanel/logs/access_log | tail -20
whmapi1 list_hooks category=Cpanel event=Passwd
ls /var/log/cpanel-audit/ 2>/dev/null
tail -f /usr/local/cpanel/logs/cphulkd.log

The cPanel access log records the API call but not the structured context. Without a hook, the cphulkd log catches some failed password attempts but not successful changes initiated by the legitimate user.

The fix

A postpasswd audit hook:

  1. Write the hook script at /usr/local/cpanel/scripts/yourorg-postpasswd-audit.pl:
#!/usr/bin/perl
use strict;
use Cpanel::JSON ();
use POSIX qw(strftime);
my $data = Cpanel::JSON::Load(do { local $/; <STDIN> });
my $user = $data->{user};
my $source_ip = $data->{remote_ip} // 'unknown';
my $timestamp = strftime("%Y-%m-%dT%H:%M:%SZ", gmtime);
my $event = {
  timestamp => $timestamp,
  event_type => 'password_change',
  user => $user,
  source_ip => $source_ip,
  hostname => `hostname -f` =~ s/\s+$//r,
};
open my $fh, '>>', '/var/log/cpanel-audit/passwd.jsonl';
print $fh Cpanel::JSON::Dump($event) . "\n";
close $fh;
exit 0;
  1. Register the hook for both cPanel and WHM password changes:
whmapi1 add_hook category=Cpanel event=Passwd::ChangePasswd stage=post hook=/usr/local/cpanel/scripts/yourorg-postpasswd-audit.pl
whmapi1 add_hook category=Whostmgr event=Accounts::passwd stage=post hook=/usr/local/cpanel/scripts/yourorg-postpasswd-audit.pl
  1. Set up log shipping from /var/log/cpanel-audit/passwd.jsonl to your SIEM (Elastic, Splunk, Datadog). The JSONL format ingests cleanly into any of them.
  2. Test: change a password through cPanel and through WHM; verify each appears in the audit log within seconds.
  3. Add retention: the audit log file grows; logrotate it weekly or monthly per your compliance retention policy. Compliance frameworks typically require six to twelve months of online access plus longer cold storage.

When credential audit trails are part of the SOC 2 or PCI scope, Stack Harbor’s cPanel and WHM management practice wires the audit hook into the standard build so every server in scope is logging from day one.