IPAbuse Developers

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

cURL
# Download and run the installer as root
curl -fsSL https://downloads.ipabuse.org/plugins/cpanel/install.sh | bash

The 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:

/etc/ipabuse/config.ini
[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
KeyDefaultDescription
api_key—Your IPAbuse API key (required)
risk_threshold50Block IPs with a reputation score below this value (0–100)
block_ttl3600Seconds 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.logPath to the block log

Restart the service after editing:

cURL
service ipabuse-hook restart

Update

The WHM interface shows a notice when a newer version is available. To update, run the updater as root on the cPanel server:

cURL
# Run as root on the cPanel server
bash /usr/local/ipabuse/update.sh

The updater:

  1. Reads the latest version from downloads.ipabuse.org and compares it with the installed version. If you are current, it exits without changing anything.
  2. Backs up the installed plugin and the WHM interface to /usr/local/cpanel/ipabuse_backups/. The backups are readable by root only.
  3. Downloads the new archive and checks its SHA-256 checksum. It stops if the checksum does not match.
  4. Installs the new files and keeps your config/config.ini. It then re-registers the hooks.

To confirm the installed version:

cURL
grep IPABUSE_PLUGIN_VERSION /usr/local/ipabuse/lib/config.php

To roll back to the previous version, restore both backups. Replace<old-version> and <timestamp> with the names of the files in the backup directory:

cURL
# 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/cgi

Uninstall

cURL
curl -fsSL https://downloads.ipabuse.org/plugins/cpanel/uninstall.sh | bash

Next steps