jeffersongoncalves / laravel-scanner-guard-traefik
Traefik integration for laravel-scanner-guard: serves banned IPs to Traefik's HTTP provider as a deny-IP middleware
Package info
github.com/jeffersongoncalves/laravel-scanner-guard-traefik
pkg:composer/jeffersongoncalves/laravel-scanner-guard-traefik
Requires
- php: ^8.2
- illuminate/contracts: ^12.0|^13.0
- jeffersongoncalves/laravel-scanner-guard: ^2.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.24
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.0|^4.0
- pestphp/pest-plugin-laravel: ^3.0|^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Laravel Scanner Guard Traefik
Traefik integration for laravel-scanner-guard.
Serves your bans and ip_blocklist to Traefik's HTTP provider
as a deny-IP middleware, so Traefik rejects banned scanners before they reach any app behind it.
One app's bans can protect every router that uses the middleware.
Traefik has no built-in IP deny middleware (only ipAllowList), so this uses the
denyip plugin. Traefik
pulls the list: nothing is pushed, so there is no sink to add to scanner-guard.sinks.
Installation
composer require jeffersongoncalves/laravel-scanner-guard-traefik
SCANNER_GUARD_TRAEFIK_ENABLED=true SCANNER_GUARD_TRAEFIK_TOKEN=a-long-random-token
This registers GET /scanner-guard/traefik (no session, no CSRF), which answers 403 unless the
request sends Authorization: Bearer <token>. The response carries raw IPs: keep the token secret.
{"http":{"middlewares":{"scanner-guard":{"plugin":{"denyip":{"ipDenyList":["185.177.72.0/24","203.0.113.7"]}}}}}}
Traefik setup
Order matters. A router that references a middleware Traefik can't build stops serving. Finish steps 1–2, check the middleware is healthy, and only then attach it (step 3).
-
Static configuration (
traefik.yml, or the matching CLI flags): declare the plugin and the HTTP provider, and trust your CDN's forwarded headers.experimental: plugins: denyip: moduleName: github.com/kevtainer/denyip version: v1.0.0 # check the plugin catalog for the latest providers: http: # Reach the app directly over the Docker network, not through a Traefik router. endpoint: http://my-app-container/scanner-guard/traefik pollInterval: 30s headers: Authorization: Bearer a-long-random-token entryPoints: websecure: forwardedHeaders: # Behind Cloudflare: its ranges from https://www.cloudflare.com/ips/ trustedIPs: - 173.245.48.0/20 # ...
-
Restart Traefik and check its dashboard (or logs) for the
scanner-guard@httpmiddleware, with no plugin error. -
Attach the middleware to each router, e.g. with Docker labels:
labels: - traefik.http.routers.my-app.middlewares=scanner-guard@http
Behind Cloudflare (or any proxy)
denyip checks the connection's address and every entry of X-Forwarded-For. Cloudflare appends
the visitor's IP to X-Forwarded-For, so a banned visitor is blocked as long as Traefik keeps that
header: Traefik only trusts incoming forwarded headers from forwardedHeaders.trustedIPs, and
replaces them otherwise. Without the trusted ranges the plugin only ever sees Cloudflare's edge IP
and blocks nothing. A client spoofing X-Forwarded-For with a banned IP can only block itself.
Why the list is never empty
denyip refuses to load with an empty list, or with one invalid entry, and that takes the routers
using it down. Entries come validated from scanner-guard, and with nothing banned the endpoint
serves 192.0.2.1 (TEST-NET-1, RFC 5737), which is never a real client.
Configuration
php artisan vendor:publish --tag="laravel-scanner-guard-traefik-config"
| Key | Env | Default | |
|---|---|---|---|
enabled |
SCANNER_GUARD_TRAEFIK_ENABLED |
false |
registers the route |
path |
SCANNER_GUARD_TRAEFIK_PATH |
scanner-guard/traefik |
|
token |
SCANNER_GUARD_TRAEFIK_TOKEN |
null |
required; no token = always 403 |
middleware |
SCANNER_GUARD_TRAEFIK_MIDDLEWARE |
scanner-guard |
referenced as scanner-guard@http |
plugin |
SCANNER_GUARD_TRAEFIK_PLUGIN |
denyip |
key under experimental.plugins |
list_key |
SCANNER_GUARD_TRAEFIK_LIST_KEY |
ipDenyList |
the plugin's IP list option |
placeholder |
192.0.2.1 |
served when nothing is banned |
Each poll reads the active bans (one query with the database driver), so keep pollInterval at
tens of seconds rather than Traefik's 5s default. On an http satellite the endpoint serves the
last pulled central list.
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.
