209 lines
6.3 KiB
Markdown
209 lines
6.3 KiB
Markdown
# Forum Bot Protection
|
|
|
|
This document describes the production anti-bot stack protecting forum, auth, profile, and selected API write actions.
|
|
|
|
## Scope
|
|
|
|
Primary implementation lives in:
|
|
|
|
- `config/forum_bot_protection.php`
|
|
- `packages/klevze/Plugins/Forum/Services/Security`
|
|
- `app/Http/Middleware/ForumBotProtectionMiddleware.php`
|
|
- `packages/klevze/Plugins/Forum/Console/ForumBotScanCommand.php`
|
|
- `packages/klevze/Plugins/Forum/Jobs/BotActivityMonitor.php`
|
|
|
|
Protected actions currently include:
|
|
|
|
- registration
|
|
- login
|
|
- forum topic create
|
|
- forum reply create
|
|
- forum post update
|
|
- profile update
|
|
- selected API write routes
|
|
|
|
## Detection Layers
|
|
|
|
Risk scoring combines multiple signals:
|
|
|
|
- honeypot hits
|
|
- browser and device fingerprints
|
|
- repeated content and spam phrase analysis
|
|
- account age and action burst behavior
|
|
- proxy, Tor, and blacklist checks
|
|
- provider and datacenter CIDR range checks
|
|
- account farm heuristics across IP and fingerprint reuse
|
|
|
|
The score is interpreted through `config/forum_bot_protection.php`:
|
|
|
|
- `allow`
|
|
- `log`
|
|
- `captcha`
|
|
- `moderate`
|
|
- `block`
|
|
|
|
## Persistence
|
|
|
|
Bot activity is stored in:
|
|
|
|
- `forum_bot_logs`
|
|
- `forum_bot_ip_blacklist`
|
|
- `forum_bot_device_fingerprints`
|
|
- `forum_bot_behavior_profiles`
|
|
|
|
User records also carry:
|
|
|
|
- `bot_risk_score`
|
|
- `bot_flags`
|
|
- `last_bot_activity_at`
|
|
|
|
## Captcha Escalation
|
|
|
|
When a request risk score reaches the configured captcha threshold, middleware requires a provider-backed challenge before allowing the action.
|
|
|
|
Provider selection:
|
|
|
|
- `FORUM_BOT_CAPTCHA_PROVIDER=turnstile`
|
|
- `FORUM_BOT_CAPTCHA_PROVIDER=recaptcha`
|
|
- `FORUM_BOT_CAPTCHA_PROVIDER=hcaptcha`
|
|
|
|
Optional request input override:
|
|
|
|
- `FORUM_BOT_CAPTCHA_INPUT`
|
|
|
|
Supported provider environment keys:
|
|
|
|
### Turnstile
|
|
|
|
- `TURNSTILE_SITE_KEY`
|
|
- `TURNSTILE_SECRET_KEY`
|
|
- `TURNSTILE_SCRIPT_URL`
|
|
- `TURNSTILE_VERIFY_URL`
|
|
|
|
### reCAPTCHA
|
|
|
|
- `RECAPTCHA_ENABLED`
|
|
- `RECAPTCHA_SITE_KEY`
|
|
- `RECAPTCHA_SECRET_KEY`
|
|
- `RECAPTCHA_SCRIPT_URL`
|
|
- `RECAPTCHA_VERIFY_URL`
|
|
|
|
### hCaptcha
|
|
|
|
- `HCAPTCHA_ENABLED`
|
|
- `HCAPTCHA_SITE_KEY`
|
|
- `HCAPTCHA_SECRET_KEY`
|
|
- `HCAPTCHA_SCRIPT_URL`
|
|
- `HCAPTCHA_VERIFY_URL`
|
|
|
|
If the selected provider is missing required keys, captcha escalation is effectively disabled and high-risk requests will continue through the non-captcha anti-bot path.
|
|
|
|
## Origin Header Setup
|
|
|
|
Geo-behavior scoring only activates when the origin receives a trusted two-letter country header. The current analyzer checks these headers in order:
|
|
|
|
- `CF-IPCountry`
|
|
- `CloudFront-Viewer-Country`
|
|
- `X-Country-Code`
|
|
- `X-App-Country-Code`
|
|
|
|
Recommended production setup:
|
|
|
|
### Cloudflare
|
|
|
|
- If you only need country detection: Cloudflare Dashboard → `Network` → turn `IP Geolocation` on.
|
|
- If you want the broader location header set: Cloudflare Dashboard → `Rules` → `Managed Transforms` → enable `Add visitor location headers`.
|
|
- The origin header used by this app is `CF-IPCountry`.
|
|
|
|
### Amazon CloudFront
|
|
|
|
- Edit the distribution behavior used for the app origin.
|
|
- Attach an origin request policy that includes geolocation headers, or create a custom origin request policy that forwards `CloudFront-Viewer-Country`.
|
|
- If you cache on that behavior and want cache variation by forwarded headers, ensure the paired cache policy is compatible with the origin request policy you choose.
|
|
|
|
### Reverse Proxy / Load Balancer
|
|
|
|
- Pass the CDN country header through unchanged to PHP-FPM / Laravel.
|
|
- For Nginx, avoid clearing the header and explicitly preserve it if you normalize upstream headers, for example: `proxy_set_header CF-IPCountry $http_cf_ipcountry;` or `proxy_set_header CloudFront-Viewer-Country $http_cloudfront_viewer_country;`.
|
|
- If you terminate the CDN header at the proxy and want a normalized application header instead, map it to `X-Country-Code` and keep the value as a two-letter ISO country code.
|
|
|
|
Validation:
|
|
|
|
- Send a request through the real edge and confirm the header is visible in Laravel request headers.
|
|
- Check that a login event stored in `forum_bot_logs.metadata.country_code` contains the expected country code.
|
|
|
|
## IP Range Configuration
|
|
|
|
IP reputation supports three types of network lists in `config/forum_bot_protection.php`:
|
|
|
|
- `known_proxies`: exact IPs or CIDRs for proxy and VPN ranges
|
|
- `datacenter_ranges`: generic datacenter or hosting CIDRs
|
|
- `provider_ranges`: provider-specific buckets such as `aws`, `azure`, `gcp`, `digitalocean`, `hetzner`, and `ovh`
|
|
|
|
All three lists accept either exact IP strings or CIDR notation.
|
|
|
|
Example:
|
|
|
|
```php
|
|
'ip' => [
|
|
'known_proxies' => ['198.51.100.0/24'],
|
|
'datacenter_ranges' => ['203.0.113.0/24'],
|
|
'provider_ranges' => [
|
|
'aws' => ['54.240.0.0/12'],
|
|
'hetzner' => ['88.198.0.0/16'],
|
|
],
|
|
],
|
|
```
|
|
|
|
Operational guidance:
|
|
|
|
- keep provider ranges in the named `provider_ranges` buckets so the control panel can show per-provider coverage counts
|
|
- populate ranges only from provider-owned feeds or other trusted sources you maintain internally
|
|
- after changing CIDR lists, clear cache if you need immediate effect on hot IPs
|
|
|
|
## Queue and Scheduling
|
|
|
|
Recent activity scanning runs through:
|
|
|
|
- command: `php artisan forum:bot-scan`
|
|
- queued job: `BotActivityMonitor`
|
|
- schedule: every 5 minutes in `routes/console.php`
|
|
|
|
Default command behavior dispatches the monitor job onto the configured queue. Use `--sync` for inline execution.
|
|
|
|
## Admin Operations
|
|
|
|
Control panel screen:
|
|
|
|
- route: `admin.forum.security.bot-protection.main`
|
|
|
|
Available actions:
|
|
|
|
- review recent bot events
|
|
- inspect suspicious users
|
|
- inspect high-risk fingerprints
|
|
- inspect recent rate-limit violations and their limiter metadata
|
|
- manually blacklist IPs
|
|
- approve or ban flagged users
|
|
- confirm current captcha provider, threshold, and required env keys
|
|
- confirm configured proxy, datacenter, tor, and provider CIDR coverage counts
|
|
- filter analytics by time window and action
|
|
- export recent bot events as CSV
|
|
- export top bot reasons as JSON
|
|
|
|
## Validation Checklist
|
|
|
|
Useful commands:
|
|
|
|
- `php artisan forum:bot-scan --help`
|
|
- `php artisan forum:bot-scan --sync --minutes=5`
|
|
- `php artisan route:list --name=admin.forum.security.bot-protection.main`
|
|
- `npm run build`
|
|
|
|
Quick runtime checks:
|
|
|
|
- confirm new bot events land in `forum_bot_logs`
|
|
- confirm fingerprints land in `forum_bot_device_fingerprints`
|
|
- confirm the jobs table contains `BotActivityMonitor` after `forum:bot-scan`
|
|
- confirm the control panel shows the expected captcha provider and action list
|