# 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