cPanel / WHM Plugin
The IPAbuse cPanel plugin checks every incoming connection against the IPAbuse reputation API and blocks high-risk IPs via CSF (ConfigServer Security & Firewall) before they reach your server.
Requirements
- cPanel & WHM 102 or later
- CSF (ConfigServer Security & Firewall) installed
- Root SSH access
- IPAbuse API key
- Outbound HTTPS to
api.ipabuse.org
Install
# Download and run the installer as root
curl -fsSL https://downloads.ipabuse.org/plugins/cpanel/install.sh | bashThe installer registers a cPanel hook that fires on each incoming connection, installs the IPAbuse WHM plugin interface, and adds a cron job to keep the local blocklist cache warm.
Configure
Edit /etc/ipabuse/config.ini with your settings:
[ipabuse]
api_key = YOUR_API_KEY
risk_threshold = 50
block_ttl = 3600
categories = SPAM,MALWARE,PHISHING,BRUTE_FORCE,DDoS,BOT,SCANNING,FRAUD,OTHER
log_file = /var/log/ipabuse/blocks.log| Key | Default | Description |
|---|---|---|
| api_key | — | Your IPAbuse API key (required) |
| risk_threshold | 50 | Block IPs with a reputation score below this value (0–100) |
| block_ttl | 3600 | Seconds to keep an IP in the local deny list before re-checking |
| categories | (all) | Comma-separated list of abuse categories to act on |
| log_file | /var/log/ipabuse/blocks.log | Path to the block log |
Restart the service after editing:
service ipabuse-hook restartUpdate
The WHM interface shows a notice when a newer version is available. To update, run the updater as root on the cPanel server:
# Run as root on the cPanel server
bash /usr/local/ipabuse/update.shThe updater:
- Reads the latest version from
downloads.ipabuse.organd compares it with the installed version. If you are current, it exits without changing anything. - Backs up the installed plugin and the WHM interface to
/usr/local/cpanel/ipabuse_backups/. The backups are readable by root only. - Downloads the new archive and checks its SHA-256 checksum. It stops if the checksum does not match.
- Installs the new files and keeps your
config/config.ini. It then re-registers the hooks.
To confirm the installed version:
grep IPABUSE_PLUGIN_VERSION /usr/local/ipabuse/lib/config.phpTo roll back to the previous version, restore both backups. Replace<old-version> and <timestamp> with the names of the files in the backup directory:
# Restore hooks, library and config from the backup taken before the update
tar -xzf /usr/local/cpanel/ipabuse_backups/ipabuse_cpanel_<old-version>_<timestamp>.tar.gz -C /usr/local
# Restore the WHM interface
tar -xzf /usr/local/cpanel/ipabuse_backups/ipabuse_cpanel_whm_<old-version>_<timestamp>.tar.gz -C /usr/local/cpanel/whostmgr/docroot/cgiUninstall
curl -fsSL https://downloads.ipabuse.org/plugins/cpanel/uninstall.sh | bashNext steps
- All Plugins
- Authentication — rotate your API key.