klevze/SkinbaseNova
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2119741ba776fa48bb347cdede14c517034e8394
SkinbaseNova/docs/forum-bot-protection.md

6.3 KiB
Raw Blame History

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:

'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
Reference in New Issue View Git Blame Copy Permalink