laravel-scanner-guard-cloudflare maintained by jeffersongoncalves

Laravel Scanner Guard Cloudflare
Cloudflare denylist sink for laravel-scanner-guard.
Keeps a Cloudflare Custom IP List in sync with your bans and ip_blocklist, so a WAF custom
rule blocks them at the edge: banned scanners never reach your server, and one list covers every
zone in the account.
Installation
composer require jeffersongoncalves/laravel-scanner-guard-cloudflare
Add the sink to config/scanner-guard.php:
'sinks' => [
\JeffersonGoncalves\ScannerGuardCloudflare\CloudflareSink::class,
],
Cloudflare setup
-
Create the list. Dashboard → Manage Account → Configurations → Lists → Create new list, type IP, e.g.
scanner_guard. The sink replaces the whole list on every change, so give it a list of its own. -
Create an API token. My Profile → API Tokens → Create Token → custom token with Account → Account Filter Lists → Edit for your account.
-
Find the ids. The account id is in the dashboard URL (or the zone overview sidebar). The list id is in the list's URL, or:
curl -s https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/rules/lists \ -H "Authorization: Bearer $TOKEN" -
Block the list. In each zone: Security → WAF → Custom rules → Create rule, expression
(ip.src in $scanner_guard), action Block. -
Configure the app:
SCANNER_GUARD_CLOUDFLARE_API_TOKEN=... SCANNER_GUARD_CLOUDFLARE_ACCOUNT_ID=... SCANNER_GUARD_CLOUDFLARE_LIST_ID=...
Run php artisan scanner-guard:sync-denylist once to check: it exits non-zero and logs the
Cloudflare error if something is wrong.
How it syncs
scanner-guard:sync-denylist runs every minute and right after every ban, unban and blocklist
change. The sink sends one PUT …/rules/lists/{list_id}/items with the full list (each item
commented with its reason and expiry), then polls the asynchronous bulk operation until it
completes. A SHA-256 of the last completed list is kept in the scanner-guard cache store, so an
unchanged list costs no API call: in practice the API is only called when a ban starts or ends.
- A replace still pending after
poll_attemptsis retried on the next sync. Cloudflare allows one pending bulk operation per account, so a retry while it runs fails, is logged, and succeeds once it finishes. - A failed operation or API error throws:
sync-denylistlogs it, exits non-zero and keeps running your other sinks. Nothing is cached, so the next sync retries. - Cloudflare lists accept IPv4
/8–/32and IPv6/12–/128. Wider ranges in yourip_blocklistare skipped here (logged as a warning) but still blocked by the app. - How many lists and items you get depends on your Cloudflare plan; check the limits for yours.
Configuration
php artisan vendor:publish --tag="laravel-scanner-guard-cloudflare-config"
| Key | Env | Default |
|---|---|---|
api_token |
SCANNER_GUARD_CLOUDFLARE_API_TOKEN |
null |
account_id |
SCANNER_GUARD_CLOUDFLARE_ACCOUNT_ID |
null |
list_id |
SCANNER_GUARD_CLOUDFLARE_LIST_ID |
null |
timeout |
SCANNER_GUARD_CLOUDFLARE_TIMEOUT |
10 (seconds per call) |
poll_attempts |
SCANNER_GUARD_CLOUDFLARE_POLL_ATTEMPTS |
10 |
poll_interval |
SCANNER_GUARD_CLOUDFLARE_POLL_INTERVAL |
1 (seconds) |
Behind Cloudflare: the app needs the visitor's IP
scanner-guard bans whatever $request->ip() returns. Behind Cloudflare that is a Cloudflare edge
IP unless the app trusts the proxy and reads the client IP (CF-Connecting-IP, or
X-Forwarded-For through TrustProxies limited to Cloudflare's ranges). Otherwise the app bans
edge IPs (rejecting real visitors itself) and this list fills with addresses ip.src never
matches, so check $request->ip() before turning the sink on.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Credits
License
The MIT License (MIT). Please see License File for more information.