Access Shield Pro applies IP rules, scanner and honeypot checks, sensitive-route rate limits and administrator access restrictions inside WHMCS. It complements a firewall, reverse proxy or web application firewall; it does not replace them.
A PHP addon cannot stop traffic before it reaches the web server and PHP. Use edge or web-server controls for volumetric attacks, global rate limiting and site-wide country blocking.
Requirements and installation
- Use WHMCS 8.9 or later, PHP 8.1 or later, MySQL or MariaDB, cURL and a valid module license.
- Upload the supplied module to
/modules/addons/access_shield_pro/. - Activate Access Shield Pro in WHMCS Addon Modules, enter the license key and assign administrator permissions.
- Open the addon and review its settings before relying on enforcement. Configure IP rules, trusted proxies, administrator restrictions, scanner and honeypot patterns, rate limits, logging and threat feeds.
- Keep the normal WHMCS cron running. Do not create a separate module-specific cron command.
IP rules
Add individual IPv4 or IPv6 addresses, or CIDR networks, in the IP Rules area. Choose a whitelist or blacklist rule, add a useful comment and set an expiry where appropriate.
A matching whitelist takes precedence over other module restrictions. Otherwise an active blacklist blocks the address, followed by threat-intelligence rules. Expired rules do not apply. Feed-owned rules are managed by feed refreshes rather than manual deletion; comments do not change a rule's ownership.
Trusted proxies
Leave trusted-proxy settings empty if visitors connect directly to WHMCS. Behind a reverse proxy, configure only the proxy's actual CIDR networks, or use the validated Cloudflare range option when appropriate. Forwarded client-IP headers are accepted only from trusted proxy sources. Do not add customer networks as trusted proxies.
Administrator restrictions
The module uses WHMCS authenticated-admin login and admin-area hooks. You do not need to enter a guessed or renamed administrator directory.
Allowed administrator countries and IP/CIDR networks are optional. With both lists empty, neither adds an allow-list restriction. If either is configured, matching an allowed network or an allowed country is enough for that allow-list check. The general blocked-country policy still applies, and blacklisted or threat-listed addresses are denied unless a module whitelist takes precedence.
Keep a separate administrator session and a controlled recovery route while testing restrictive changes. Do not assume that a country identifies an attacker or that a feed listing proves a customer's device is compromised.
Scanner and honeypot rules
Enter one pattern per line. Blank lines and lines beginning with # are ignored. Matching is case-insensitive and uses the URL-decoded path, not the query string.
- An exact path such as
/examplealso matches its descendants. - Wildcards match the full path:
*matches any number of characters and?matches one character. - Regular-expression patterns are supported. Test narrow rules before enabling them for customers.
A scanner match blocks the request immediately. Repeated matches within the scanner window create a blacklist entry at the configured threshold. A honeypot match creates a blacklist entry immediately for the configured duration; it is not always a permanent ban. Use only trap paths that your installation does not need. Do not add a working admin or application path as a trap.
User-agent names such as Googlebot are not a trusted bypass. Automated scanner and honeypot rules have their own cleanup policy; manual blocks are retained.
Rate limiting and threat feeds
The per-IP, per-minute rate limit covers sensitive authentication, registration, password-reset and checkout POST routes. Ordinary allowed GET requests do not create rate-limit or access-log writes. Set the threshold and block duration for your customer traffic, then review false positives.
Enabled Blocklist.de, Spamhaus DROP and Emerging Threats feeds refresh during the daily WHMCS cron. A failed download, parse or database update keeps the previous complete feed generation. The cron also refreshes license and GeoIP data and performs scheduled cleanup.
Logs, exports and privacy
Use the event log to investigate a decision, filter the events and export CSV or JSON when needed. Repeated equivalent events are aggregated with counts and first/last-seen timestamps. Storage is capped at 100,000 events; exports contain the newest 10,000 events matching the filters, not an unlimited history.
Optional IP anonymization applies when new events are stored, not retroactively. Log-based whitelist and blacklist actions are unavailable with anonymization enabled because a masked address is not a valid enforcement target. IP rules still retain the addresses needed for enforcement. Anonymization alone does not establish privacy-law compliance.
Upgrades and troubleshooting
- Back up the WHMCS database and existing module directory.
- Leave Remove Tables on Deactivation disabled. Deactivation with that option enabled deletes module rules, logs and settings.
- Replace the module files and let WHMCS run the addon upgrade hook. Review the settings after migration.
- Confirm that the normal cron resumes feed, GeoIP and maintenance work.
For unexpected blocking, identify the matching rule and verify the source IP and proxy configuration before changing policy. For missing feed updates, check cron execution, outbound access and the WHMCS activity log. Send support the module, WHMCS and PHP versions, the relevant redacted log entry and reproduction steps.
