{"id":34834427,"url":"https://github.com/equalitie/baskerville","last_synced_at":"2026-04-06T11:04:06.478Z","repository":{"id":325111353,"uuid":"1064666766","full_name":"equalitie/baskerville","owner":"equalitie","description":"Baskerville Wordpress Plugin","archived":false,"fork":false,"pushed_at":"2026-04-03T11:52:10.000Z","size":720,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T16:28:25.374Z","etag":null,"topics":["ai-bots","bot-detection","country-blocking","crawler-detection","ddos-protection","privacy","security","web-security","wordpress","wordpress-plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/equalitie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-26T11:22:03.000Z","updated_at":"2026-04-03T11:52:15.000Z","dependencies_parsed_at":"2026-02-23T11:03:05.375Z","dependency_job_id":null,"html_url":"https://github.com/equalitie/baskerville","commit_stats":null,"previous_names":["equalitie/baskerville_plugin","equalitie/baskerville"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/equalitie/baskerville","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fbaskerville","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fbaskerville/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fbaskerville/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fbaskerville/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/equalitie","download_url":"https://codeload.github.com/equalitie/baskerville/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equalitie%2Fbaskerville/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31469746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-bots","bot-detection","country-blocking","crawler-detection","ddos-protection","privacy","security","web-security","wordpress","wordpress-plugin"],"created_at":"2025-12-25T15:59:54.301Z","updated_at":"2026-04-06T11:04:06.462Z","avatar_url":"https://github.com/equalitie.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Baskerville WordPress Plugin\n\nA WordPress security plugin with GeoIP-based access control, AI-powered bot detection, Cloudflare Turnstile integration, and advanced fingerprinting.\n\n## Features\n\n- 🛡️ **AI-Powered Bot Detection** - Classification of bots vs. humans with configurable thresholds\n- 🌍 **GeoIP Access Control** - Block or allow traffic by country (whitelist/blacklist)\n- 🔍 **Browser Fingerprinting** - Advanced client-side fingerprinting with Canvas, WebGL, Audio\n- ☁️ **Cloudflare Turnstile** - CAPTCHA challenge for borderline bot scores with precision analytics\n- 🍯 **Honeypot Detection** - Hidden links to catch AI crawlers\n- 📊 **Traffic Analytics** - Real-time statistics, live feed, and Turnstile precision metrics\n- ⚡ **Performance Optimized** - Minimal overhead (~1ms with page cache, ~30-50ms without)\n- 🔐 **IP Whitelist** - Bypass firewall for trusted IPs\n- 🚀 **Caching** - APCu + file-based caching for GeoIP lookups\n- 🚨 **Under Attack Mode** - Emergency mode to challenge all visitors\n\n## Building\n\nRun from the **parent directory** of the plugin folder:\n\n```bash\ncd ..   # from baskerville/ go to parent directory\nzip -r9 baskerville.zip baskerville/ \\\n  -x \"*.DS_Store\" \\\n  -x \"baskerville/.git/*\" \\\n  -x \"baskerville/.gitignore\" \\\n  -x \"baskerville/.idea/*\" \\\n  -x \"baskerville/.claude/*\" \\\n  -x \"baskerville/vendor/*\" \\\n  -x \"*.log\" \\\n  -x \"*.txt\" \\\n  -x \"*.sh\" \\\n  -x \"*.html\" \\\n  -x \"baskerville/test-*.php\" \\\n  -x \"baskerville/composer.json\" \\\n  -x \"baskerville/deployment.md\" \\\n  -x \"baskerville/bot-detector*.js\" \\\n  -x \"baskerville/ab\" \\\n  -x \"baskerville/done\" \\\n  -x \"baskerville/sleep\"\n```\n\n**Note**: The `vendor/` folder is excluded. After plugin installation, go to **Settings → Baskerville → Settings** and click \"Install MaxMind Library\" to enable GeoIP features.\n\n## Installation\n\n1. Upload `baskerville.zip` in WordPress Admin → Plugins → Add New → Upload Plugin\n2. Activate the plugin\n3. Go to Settings → Baskerville to configure\n\n## Configuration\n\n### GeoIP Setup\n\n1. Go to **Settings → Baskerville → Settings**\n2. Install MaxMind GeoLite2 database (one-click installer)\n3. Configure access mode:\n   - **Allow All** (default) - No country restrictions\n   - **Blacklist** - Block specific countries\n   - **Whitelist** - Allow only specific countries\n\n### IP Whitelist\n\n1. Go to **Settings → Baskerville → IP Whitelist**\n2. Click \"Add My IP\" to whitelist your current IP\n3. Or manually add IPs (one per line or comma-separated)\n\n**Use cases**:\n- Load testing with Apache Bench\n- Whitelisting office network\n- Development environments\n- Monitoring services\n\n### Cloudflare Turnstile\n\nTurnstile provides a CAPTCHA-like challenge for visitors with borderline bot scores, allowing legitimate users to prove they're human instead of being blocked outright.\n\n1. Go to **Settings → Baskerville → Turnstile**\n2. Get your Site Key and Secret Key from [Cloudflare Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)\n3. Enter the keys and enable Turnstile\n4. Configure the borderline score range (default: 40-70)\n\n**Settings**:\n- **Bot Score Challenge** - Show Turnstile to visitors with scores in the borderline range\n- **Score Range** - Define min/max bot score for challenge (e.g., 40-70)\n- **Under Attack Mode** - Emergency mode that challenges ALL visitors (use during attacks)\n- **Form Protection** - Protect login, registration, and comment forms\n\n**Score interpretation**:\n- 0-39: Likely human (allowed)\n- 40-70: Borderline (show Turnstile challenge)\n- 71-100: Likely bot (blocked)\n\n**Precision Analytics**:\nThe Analytics tab shows Turnstile effectiveness:\n- **Redirects** - Number of challenges shown\n- **Passed** - Visitors who completed the challenge\n- **Failed** - Visitors who failed or abandoned (likely bots)\n- **Precision** - % of challenges that caught bots: `(redirects - passes) / redirects`\n\n### Bot Control\n\nConfigure how bots are detected and banned.\n\n1. Go to **Settings → Baskerville → Bot Control**\n\n**Settings**:\n- **Ban All Detected Bots** - Ban all `bot` classifications, not just `bad_bot`\n- **Instant Ban Threshold** - Score threshold (0-100) for immediate ban without waiting for burst protection. Visitors with scores \u003e= threshold are banned instantly if they don't look like a browser and aren't verified crawlers.\n\n**Example**: With threshold set to 70, a visitor with score 75 and suspicious headers will be banned immediately.\n\n### Performance Optimization Tips\n\n#### 1. Enable Page Caching (Critical!)\n\n**Impact**: -95% response time\n\n```bash\n# Install one of:\n- WP Super Cache (free)\n- W3 Total Cache (free)\n- LiteSpeed Cache (free)\n- WP Rocket (paid)\n```\n\n**Why it helps**:\n- Cached pages bypass WordPress PHP execution\n- Baskerville firewall is not executed for cached pages\n- Overhead drops from 50ms → 0ms\n\n---\n\n#### 2. Enable APCu for Object Caching\n\n**Impact**: 10x faster cache operations\n\n```bash\n# Ubuntu/Debian\nsudo apt install php-apcu\nsudo systemctl restart php-fpm\n\n# Verify\nphp -m | grep apcu\n```\n\n**Why it helps**:\n- GeoIP lookups cached in memory (not disk)\n- Ban cache uses RAM (faster than file I/O)\n- APCu: 0.05ms, File: 0.5ms per operation\n\n---\n\n#### 3. Use NGINX GeoIP2 Module\n\n**Impact**: 10x faster GeoIP lookups\n\n```nginx\n# /etc/nginx/nginx.conf\nload_module modules/ngx_http_geoip2_module.so;\n\nhttp {\n    geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {\n        auto_reload 5m;\n        $geoip2_data_country_code country iso_code;\n    }\n\n    fastcgi_param GEOIP2_COUNTRY_CODE $geoip2_data_country_code;\n}\n```\n\n**Why it helps**:\n- NGINX does GeoIP lookup (not PHP)\n- Result passed via `$_SERVER['GEOIP2_COUNTRY_CODE']`\n- Baskerville uses NGINX result (no MaxMind DB lookup needed)\n\n---\n\n#### 4. Enable PHP OPcache\n\n**Impact**: 30-50% faster PHP execution\n\n```bash\n# Check if enabled\nphp -i | grep opcache.enable\n\n# Enable in php.ini\nopcache.enable=1\nopcache.memory_consumption=256\nopcache.interned_strings_buffer=16\nopcache.max_accelerated_files=10000\nopcache.validate_timestamps=0 # Production only\n```\n\n### Logging Mode Comparison\n\n| Mode | Overhead | Analytics | Shared Hosting | Recommended For |\n|------|----------|-----------|----------------|-----------------|\n| **File** | ~50-70ms (5%) | ✅ Full (5min delay) | ✅ Perfect | Production |\n| **Disabled** | ~0ms (0%) | ❌ None | ✅ Perfect | Testing/Dev |\n| **Database** | ~500ms (36%) | ✅ Instant | ❌ Slow | VPS only |\n\n---\n\n### Conclusion\n\nBaskerville with **File Logging** adds **5% overhead** while providing:\n- ✅ GeoIP-based access control\n- ✅ AI-powered bot detection with configurable thresholds\n- ✅ Cloudflare Turnstile for borderline cases\n- ✅ Honeypot detection for AI crawlers\n- ✅ Advanced fingerprinting\n- ✅ Real-time traffic analytics with precision metrics\n- ✅ Rate limiting \u0026 ban management\n\n**Recommendations**:\n- ✅ Use **File Logging** mode for production (default)\n- ✅ Enable page caching (WP Super Cache, etc.)\n- ✅ Install APCu if available (10x faster cache)\n- ✅ Whitelist monitoring/testing IPs\n- ✅ Configure Turnstile for borderline scores (40-70)\n- ✅ Set Instant Ban Threshold for high-risk visitors (e.g., 85)\n\n---\n\n## Troubleshooting\n\n### Slow Performance\n\n**Symptom**: Page loads take \u003e5 seconds\n\n**Solutions**:\n1. ✅ Enable page caching (WP Super Cache)\n2. ✅ Install APCu: `apt install php-apcu`\n3. ✅ Enable PHP OPcache\n4. ✅ Use NGINX GeoIP2 module (optional)\n\n### Cache Issues\n\n**Symptom**: GeoIP shows wrong country after VPN change\n\n**Solution**: Clear GeoIP cache\n1. Go to **Settings → Baskerville → GeoIP Test**\n2. Click \"Clear GeoIP Cache\" button\n3. Page will reload with updated country\n\n### Load Testing Blocked\n\n**Symptom**: Apache Bench gets 403 errors\n\n**Solution**: Whitelist your IP\n1. Go to **Settings → Baskerville → IP Whitelist**\n2. Click \"Add My IP\" button\n3. Run tests again\n\n---\n\n## Development\n\n### File Structure\n\n```\nbaskerville/\n├── admin/\n│   └── class-baskerville-admin.php      # Admin UI, settings, analytics\n├── includes/\n│   ├── class-baskerville-core.php       # Core functions, caching, GeoIP\n│   ├── class-baskerville-firewall.php   # Firewall logic, blocking rules\n│   ├── class-baskerville-ai-ua.php      # AI bot detection \u0026 classification\n│   ├── class-baskerville-stats.php      # Analytics \u0026 database logging\n│   ├── class-baskerville-rest.php       # REST API for fingerprinting\n│   ├── class-baskerville-turnstile.php  # Cloudflare Turnstile integration\n│   └── class-baskerville-honeypot.php   # Honeypot for AI crawler detection\n├── assets/\n│   ├── js/baskerville.js                # Frontend fingerprinting script\n│   └── css/                             # Styles\n├── vendor/                              # MaxMind GeoIP2 library (auto-installed)\n└── baskerville.php                      # Main plugin file\n```\n\n### Database Schema\n\n```sql\nCREATE TABLE wp_baskerville_stats (\n    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,\n    visit_key VARCHAR(64),\n    ip VARCHAR(45),\n    country_code VARCHAR(2),          -- Added in v1.0.0\n    baskerville_id VARCHAR(32),\n    timestamp_utc DATETIME,\n    score INT,\n    classification VARCHAR(32),\n    user_agent TEXT,\n    evaluation_json LONGTEXT,\n    score_reasons TEXT,\n    classification_reason TEXT,\n    block_reason VARCHAR(120),\n    event_type VARCHAR(16),\n    had_fp TINYINT(1),\n    INDEX idx_timestamp (timestamp_utc),\n    INDEX idx_ip (ip),\n    INDEX idx_country_code (country_code),  -- Added in v1.0.0\n    INDEX idx_event_type (event_type)\n);\n```\n\n---\n\n## License\n\nGPL v3 or later - Compatible with WordPress.org plugin directory requirements.\n\n## Support\n\nFor issues and feature requests, please open an issue on GitHub.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequalitie%2Fbaskerville","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fequalitie%2Fbaskerville","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequalitie%2Fbaskerville/lists"}