SSP — Block Website Access by Region Pro (Docs)

SSP Documentation

Block Website Access by Region Pro

Admin Screens

The plugin adds a new menu item in your WordPress admin sidebar called Geoblocker Pro. Inside are three tabs:

Control tab

Enable or disable blocking globally.
Option to allow search crawlers like Googlebot.
Block data centers, VPNs, and hosting providers (strict ASN mode).
Choose policy for unknown IP locations (allow or block).
Enter MaxMind license key to enable local database lookups.
Select which states or countries are blocked (multi-country support).

Message tab

Optional redirect URL instead of showing block page.
Customize colors: background, text, and accent.
Set the heading of the block page.
Customize the body message, supports tokens like {STATE}.
Add custom CSS for advanced styling.

Logs tab

View past access attempts with location & decision.
Entries include hashed IP, state/country code, reason, and timestamp.
Export logs as CSV for external analysis.
Option to clear logs with one click.
Automatic pruning runs daily based on retention settings (default 30 days).

Navigation

Menu Location	Geoblocker Pro (shield icon) in the WP admin sidebar.
Permissions	Only roles with `manage_options` can see and change settings.
Settings Page	admin.php?page=bsas-settings

How It Works

This plugin enforces regional access restrictions as early as possible in WordPress load:

Early gate: Runs during plugins_loaded at priority 0, before theme output and most other plugins.
Multi-tier geo lookup: Uses local MaxMind DB if available. Falls back to Cloudflare headers, then rotates through multiple public APIs (ipwho.is, ip-api.com, ipapi.co, ipinfo.io) for redundancy.
Circuit breaker: Automatically disables failing APIs for 15 minutes to prevent cascading failures.
ASN screening: Detects suspicious Autonomous Systems (cloud/VPN/proxy providers) and can block them when strict mode is enabled.
Cookie bypass: Approved visitors get a signed short-lived cookie (30 minutes), avoiding repeated lookups.
Emergency bypass: Add ?bsas_unblock=1 to any URL to set bypass cookie manually.
No-cache headers: Block pages include comprehensive no-store headers so proxies/CDNs never cache them.
Admin/login exemptions: WordPress admin, login, AJAX, cron, and XML-RPC endpoints are always allowed.

Geo Lookup Priority

MaxMind GeoLite2 City DB (local, fastest, ~99% accurate) – requires license key
Cloudflare CF-IPCountry header (if site is behind Cloudflare)
Public APIs (with circuit breaker and SSL verification): ipwho.is, ip-api.com, ipapi.co, ipinfo.io

Performance: Geo lookups are cached for 24 hours using WordPress transients. Circuit breaker prevents wasting time on broken APIs.

Privacy & Data

The plugin is designed with GDPR and privacy compliance in mind:

Logs Table: wp_bsas_logs stores access attempts with location and decision data.
IP Hashing: By default, IPs are stored as SHA-256 hashes salted with WordPress AUTH_SALT constant.
Optional Plain IP: Can be enabled for debugging, but disabled by default. Stored as VARBINARY(16) for efficiency.
Retention: Logs older than the configured retention (default 30 days) are automatically deleted daily via WP-Cron.
Rate limiting: Prevents excessive log rows from single IPs (default: 20 entries per IP per day).
Crawler exclusion: Major search engine crawlers are excluded from logging to reduce noise.
Cache management: Log counts and queries are cached to minimize database load.

Data Collected

IP Hash	SHA-256 hash of visitor IP (always stored)
IP Plain	Binary representation of IP (optional, disabled by default)
Location Code	2-character state/country code or “–” for unknown
Decision	blocked, allowed, bypassed, or error
Reason	Why the decision was made (e.g., “state_blocked”, “country_blocked”)
Timestamp	MySQL datetime of access attempt

Advanced Features

Multi-Country State/Province Support

The plugin supports granular state and province blocking for multiple countries:

United States: All 50 states plus DC, Puerto Rico, Guam, and U.S. Virgin Islands
Canada: All 10 provinces and 3 territories
United Kingdom: England, Scotland, Wales, Northern Ireland
China: All provinces and autonomous regions
Australia: All states and territories
India: All states and union territories
Germany: All 16 federal states

Note: State-level blocking requires accurate geo data. MaxMind license key significantly improves state detection accuracy.

ASN Detection & Blocking

When “Block Data Centers & VPNs” is enabled, the plugin detects and blocks traffic from cloud providers, VPN services, data centers, and CDN networks using regex pattern matching against ASN organization strings.

Unknown IP Policy

Choose what happens when visitor’s location cannot be determined:

Allow (default)	Grant access when country cannot be resolved. More permissive, better for legitimate users with unusual network configurations.
Block	Deny access when location is unknown. Stricter security, but may cause false positives for users behind complex proxies or unusual networks.

Custom CSS & Redirect Options

Redirect URL: Send blocked visitors to an external page instead of showing the block message.
Custom CSS: Full control over block page styling with syntax-highlighted CSS editor (WordPress CodeMirror).
Color customization: Background, text, and accent colors with WordPress color picker.
Message tokens: Use {STATE} placeholder to display the blocked region name.

MaxMind GeoLite2 Integration

For maximum accuracy, add a free MaxMind license key:

Sign up at maxmind.com
Generate a license key in your account
Enter key in Control tab settings
Database auto-updates weekly via WP-Cron
Stored at: /wp-content/uploads/GeoLite2-City.mmdb

Benefits: ~99% accuracy, faster lookups, reduced API dependencies, state-level precision.

Troubleshooting

Visitors from a blocked place still get through

Verify blocking is enabled in Control tab.
Check if visitor is using a crawler user-agent and “Allow Crawlers” is enabled.
Confirm your host is passing the real visitor IP (check for proxy headers: CF-Connecting-IP, X-Real-IP, X-Forwarded-For).
For higher accuracy, add a MaxMind license key and wait for the weekly database update (or trigger manually).
Check Logs tab to see what country/state was detected for that visitor.

Everyone is blocked or showing as “Unknown”

Ensure your server can make outbound HTTPS requests to API endpoints.
Check if APIs are temporarily down (plugin will try multiple sources automatically).
Confirm you are not forcing private IPs (like 127.0.0.1) in server configs.
If using strict ASN blocking, try disabling temporarily to test.
Set Unknown IP Policy to “Allow” temporarily for debugging.
Check error logs for circuit breaker messages about API failures.

Logs not updating

Log entries are rate-limited per IP (default 20/day) – check if limit is reached.
Search crawlers are excluded from logging if “Allow Crawlers” is enabled.
Admin, login, and AJAX requests are never logged.
Check that log cache isn’t stale – try clearing it and reloading.

MaxMind DB fails to download

Confirm your MaxMind license key is valid (try regenerating it).
Check folder permissions for /wp-content/uploads/ (needs write access).
Ensure PHP Phar extension is enabled.
Remember the updater runs weekly via WP-Cron — ensure WP-Cron is functioning.
Check server firewall allows outbound HTTPS to download.maxmind.com.

I accidentally blocked myself

Don’t worry! You have several recovery options:

WordPress Login: Go to your WP login URL (always accessible) and sign in as admin. The plugin never blocks admin areas.
Emergency Bypass: Add ?bsas_unblock=1 to any URL to set a bypass cookie.
FTP/SFTP: Rename the plugin folder temporarily to disable it.
Database: Run: UPDATE wp_options SET option_value='0' WHERE option_name='bsas_enabled'

Circuit breaker keeps triggering

Check server firewall and security plugins aren’t blocking outbound API requests.
Verify DNS resolution is working for API domains.
SSL verification is enabled – ensure SSL certificates are up to date.
If behind restrictive hosting, add a MaxMind license to reduce API dependency.
Circuit breaker automatically resets after 15 minutes of no failures.

Test / Verification

Follow these steps to confirm the plugin is configured correctly:

Go to Control tab in plugin settings.
Verify the detected information for your current connection (IP, country, state will be shown in status messages).
Block your own state or country temporarily.
Open the site in an incognito/private window (or different browser) and confirm you see the block page.
Unblock your location and reload. You should be granted access.
Check the Logs tab to confirm entries for your IP showing “blocked” and then “allowed” decisions.
Test the emergency bypass: add ?bsas_unblock=1 to any URL while “blocked” to verify cookie bypass works.
If using MaxMind, verify the database file exists at /wp-content/uploads/GeoLite2-City.mmdb.

Testing with VPN/Proxy

Recommended: Use VPN services or proxy tools to simulate different regions and confirm blocking behavior matches your configuration. Test both allowed and blocked regions.

CSV Export for Analysis

Use the “Export Logs (CSV)” button in the Logs tab to download up to 10,000 recent log entries. The CSV includes: Entry ID, IP Hash (SHA-256), Location code (state or country), Decision (blocked/allowed/bypassed/error), Reason for decision, and Timestamp.

Performance Testing

Monitor the impact of geoblocking on your site:

First visit (no cookie): One geo lookup, cached for 24 hours
Subsequent visits: Cookie bypass, near-zero overhead
With MaxMind: Local DB lookup, ~1-2ms
Without MaxMind: API fallback, ~100-500ms (varies by network)
Circuit breaker prevents slow APIs from affecting performance