Download the PHP package keepsuit/laravel-threat-blocker without Composer
On this page you can find all versions of the php package keepsuit/laravel-threat-blocker. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download keepsuit/laravel-threat-blocker
More information about keepsuit/laravel-threat-blocker
Files in keepsuit/laravel-threat-blocker
Package laravel-threat-blocker
Short Description Block threat requests to your Laravel application
License MIT
Homepage https://github.com/keepsuit/laravel-threat-blocker
Informations about the package laravel-threat-blocker
Block threat request to your application
Laravel Threat Blocker is a package to block threat requests to your Laravel application based on different rules.
Installation
You can install the package via composer:
You can publish the config file with:
Usage
-
Add the
ProtectAgainstThreatsmiddleware to routes you want to protect: -
Run the update command to warm the detectors cache:
- Schedule the update command to run periodically (e.g., daily) using Laravel's task scheduling:
Configuration
This is the contents of the published config file:
Storage
Detectors keep their data (the downloaded lists and the MX lookup results) in a storage driver. The only driver
is cache, which uses a Laravel cache store: set THREAT_BLOCKER_CACHE_STORE (it falls back to CACHE_STORE)
and, if needed, THREAT_BLOCKER_CACHE_PREFIX. The lists expire after one year without updates (every update renews them).
Use a persistent store shared by all your servers (e.g. redis or database) and not array.
Responder
The responder decides what a request blocked by a detector receives. The package provides:
BlankPageResponder(default) answers with an empty200response.ForbiddenResponderaborts with a403response.
To customize it, implement Keepsuit\ThreatBlocker\Contracts\ThreatResponder and set it as the responder.
$next lets the request proceed, which is useful to only monitor threats through the event:
HTTP methods
Detectors run only on the methods listed in the global methods option (default ['POST']),
and * means any method. Methods are case-insensitive names or Keepsuit\ThreatBlocker\Enums\HttpMethod cases. A detector can override it with its own methods option:
FormHoneypotDetector, AiSpamDetector and EmailReputationDetector inspect the request body, so they
only support POST, PUT and PATCH: any other configured method is ignored. An empty list means the
detector never runs; use 'enabled' => false to turn it off.
Detectors
Detectors run in the order of the detectors option, and the first one that detects a threat blocks the request.
Detectors that download a list (AbuseIpDetector, EmailReputationDetector) refresh it with
php artisan threat-blocker:update, and in the background when it is older than 3 days.
AbuseIpDetector
Blocks requests coming from the IPs of the AbuseIPDB blocklist maintained by borestad/blocklist-abuseipdb.
sourceis one of theAbuseIpSourceurls (Days60,Days30,Days14,Days7) or a custom url with one IP per line.blacklistIPs are always blocked,whitelistIPs are never blocked (it wins over the blacklist and the list).- The list contains IPv4 addresses only: an IPv6 address is blocked just when it is in
blacklist.
It does not read the request body, so it can run on any method: set 'methods' => ['*'] to check them all.
EmailReputationDetector
Blocks registrations using disposable or undeliverable email domains. It reads the request body.
EmailReputationSource provides built-in disposable-domain list URLs for the default,
DNS-validated, curated, and high-coverage sources. The source option also accepts any
custom URL serving one domain per line.
fieldsare the input fields to check. An empty list disables the detector.emailalso matches nested fields with that name, use patterns such ascontacts.*.emailfor a specific nested path.blacklistdomains are always blocked,whitelistdomains are never blocked.check_mxblocks domains without an MX record, the DNS result is cached formx_cache_ttlseconds.
BotSignatureDetector
BotSignatureDetector reads only the request headers, so it can run on any method. Each configured rule is independent:
missing_user_agentblocks missing or blank User-Agent headers.known_bot_user_agentsmatches the configurable case-insensitive PCRE patterns.missing_accept_languageblocks missing or blank Accept-Language headers.invalid_refererblocks missing, malformed, or cross-host Referer headers.
The default User-Agent patterns are conservative and available through
BotSignatureDetector::DEFAULT_USER_AGENT_PATTERNS. Supplying user_agent_patterns
replaces them; extend them with array_merge() when needed. Crawler and link-preview
identities such as Googlebot, bingbot, Slackbot, and Discordbot are intentionally not
included in the defaults.
FormHoneypotDetector
Blocks form submissions with a filled honeypot field (or, if valid_from_timestamp is enabled in the Spatie config, submitted too fast). It reads the request body and
needs spatie/laravel-honeypot installed and its component added to
your forms; without it the check is skipped and a warning is logged.
- The check runs even if
honeypot.enabledisfalsein the Spatie config. strict=>false(default) checks only requests that contain the honeypot fields,truealso blocks requests without them, and a list of URI patterns (e.g.['/contact', '/newsletter/*']) requires them only there.
AiSpamDetector
AiSpamDetector classifies form data as legitimate, spam or phishing with
laravel/ai. It is disabled by default and needs
composer require laravel/ai plus the API key of a provider that supports classification (only typesafe and openrouter do). Every evaluated request adds latency and provider cost,
so restrict it with only and keep it last in the detectors list.
- Form data is sent to the external provider. Files,
_token,_method, password fields and the honeypot timestamp field configured viahoneypot.valid_from_field_nameare never sent, and the payload is truncated tomax_lengthcharacters. - A request is blocked when the spam + phishing probability reaches
threshold. Providers that return no probabilities never block. - On any provider error or timeout the request is allowed and a warning is logged (fail-open).
contextmaps URI patterns to extra instructions, appended to the default ones:
Models tested on OpenRouter, ordered by lowest provider price as of 2026-10-18 (output tokens are free for all of them):
| Model | Recommended | Input price / 1M tokens | Test results / limitations |
|---|---|---|---|
inception/mercury-decide:free |
✅ | free | Passes the live tests. |
~perplexity/pplx-decider-flash-latest |
✅ | $0.01 | Passes the live tests and is the fastest (tested on perplexity/pplx-decider-flash-v1.2). |
respan/span-02 |
✅ | $0.01 | Passes the live tests. |
~perplexity/pplx-decider-latest |
✅ | $0.02 | Passes the live tests (tested on perplexity/pplx-decider-v1.2). |
inception/mercury-decide |
✅ | $0.02 | Passes the live tests. |
cloudflare/clef-flash |
✅ | $0.021 | Passes the live tests. |
~typesafe/jev-latest |
✅ | $0.042 | Passes the live tests (tested on typesafe/jev-1.14). |
cloudflare/clef |
✅ | $0.042 | Passes the live tests. |
liquid/d1-ultra |
✅ | $0.042 | Passes the live tests. |
microsoft/microsoft-decision-1 |
✅ | $0.042 | Passes the live tests with the widest margins. |
openai/gpt-6-luna-decisions |
✅ | $0.10 | Passes the live tests. |
cloudflare/clef-omni |
✅ | $0.15 | Passes the live tests, but is the most expensive. |
liquid/d1 |
❌ | $0.02 | Passes the live tests, but scores close to the threshold. |
nace-ai/drex-v2.0 |
❌ | $0.06 | Passes the live tests, but scores close to the threshold. |
jaredpalmer/kev-4b |
❌ | $0.042 | Passes the live tests, but scores close to the threshold. |
togethercomputer/tev1-4b-experimental |
❌ | $0.042 | Passes the live tests, but scores close to the threshold. |
upstage/solar-decide-flash |
❌ | $0.05 | Passes the live tests, but scores legitimate submissions up to 0.46. |
nace-ai/drex-v1.5 |
❌ | $0.04 | Passes the live tests, but scores close to the threshold and is 2.3-2.5x slower. |
upstage/solar-decide |
❌ | $0.05 | Passes the live tests, but is 4.7-5.4x slower. |
respan/span-01-lite |
❌ | free | Returns an error: Respan state must be a string or an object with only input (a message array) and output (a message). |
respan/span-01-lite:free |
❌ | free | Returns an error: Respan state must be a string or an object with only input (a message array) and output (a message). |
respan/span-01 |
❌ | $0.02 | Returns an error: Respan state must be a string or an object with only input (a message array) and output (a message). |
scaledown/classify-1 |
❌ | $0.04 | Returns an error: ScaleDown state must be a string or an object with only text, document, and document_mime_type. |
The live tests cover legitimate, spam and phishing submissions in Italian and English; validate the selected model with your own form data before production use.
Events and logging
Detectors report a threat by throwing ThreatDetectedException, which exposes the detectorId
(e.g. bot-signature) and a context array with details about the detection. The message is prefixed with
the detector id ([bot-signature] Known bot User-Agent detected.).
The ThreatDetectedEvent event carries the request and the exception. Detectors put in the
context only derived values (category, score, domain), never request content or full email addresses.
The package does not log detections, listen to the event to log them the way your application needs (level, channel, request data):
Testing
Live tests that call the real provider are excluded from the default run. Run them with
vendor/bin/pest --group=live with TYPESAFE_API_KEY (or OPENROUTER_API_KEY) set in the shell or in the package .env; without a key they are skipped.
THREAT_BLOCKER_AI_SPAM_DETECTOR_PROVIDER and THREAT_BLOCKER_AI_SPAM_DETECTOR_MODEL select another provider or model.
Changelog
Please see CHANGELOG for more information on what has changed recently.
Credits
- Fabio Capucci
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of laravel-threat-blocker with dependencies
spatie/laravel-package-tools Version ^1.16
illuminate/contracts Version ^12.0 || ^13.0