PHPackages shieldapp/laravel-shield - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. shieldapp/laravel-shield ActiveLibrary[Logging & Monitoring](/categories/logging) shieldapp/laravel-shield ======================== A Laravel package for website health monitoring, IP threat detection, traffic analysis and auto-banning. 00PHP Since May 9Pushed 2mo agoCompare [ Source](https://github.com/sunilluhana/laravel-shield)[ Packagist](https://packagist.org/packages/shieldapp/laravel-shield)[ RSS](/packages/shieldapp-laravel-shield/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependenciesVersions (1)Used By (0) Laravel Shield 🛡️ ================= [](#laravel-shield-️) [![Latest Version on Packagist](https://camo.githubusercontent.com/7999f5d6c25dcd914969d1041a4ff569d2fe1f227928ee24832dbef2f6be4196/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736869656c646170702f6c61726176656c2d736869656c642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/shieldapp/laravel-shield)[![PHP Version](https://camo.githubusercontent.com/ee631d1b3535e8b3a99c9152d465e9db0c74b77d6c84694515f8ebc38cda9aea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c75653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/shieldapp/laravel-shield)[![Laravel Version](https://camo.githubusercontent.com/c1e6b486529380b445b3384d0d5e4de8b0cb4ce9d894233d6a507b350f7182e4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d313025323025374325323031312d7265643f7374796c653d666c61742d737175617265)](https://packagist.org/packages/shieldapp/laravel-shield)[![License](https://camo.githubusercontent.com/422db9fd40f5831c765cf6530b6750c081b696bd18d904cf89554df98c676277/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e3f7374796c653d666c61742d737175617265)](LICENSE.md) A production-grade Laravel package for **IP threat detection & auto-banning**, **external health monitoring**, **real-time traffic analysis**, and **multi-channel alerting** — with a beautiful live dashboard. --- Features -------- [](#features) - 🚫 **IP auto-banning** — sliding-window rate limiting; automatically blocks IPs that exceed configurable RPM thresholds - 📡 **External health checks** — uptime, SSL certificate expiry, DNS, response time, security headers, domain expiry - 📊 **Live dashboard** — real-time traffic map, threat level meter, audit log, ban management, and site monitors in one glassmorphism UI - 🔔 **Multi-channel alerts** — Email, Slack (Block Kit), and WhatsApp (via Twilio) with per-channel cooldowns to prevent flooding - 🗂️ **Audit log** — full trail of every DETECT, WARN, AUTO-BAN, BAN, UNBAN, and BLOCKED event - ⚡ **Redis-first architecture** — all per-request counting stays in Redis; DB writes only for significant events - 🔄 **Async logging** — optional queue-based DB writes to keep your request cycle fast - 🤖 **Agent mode** — report CPU, RAM, disk, and queue stats from any server back to a central Shield instance - 🧹 **Auto-pruning** — configurable retention windows automatically keep your tables lean - 🔒 **Security hardened** — timing-safe API key comparison, cache-key injection prevention, SSL verification configurable --- Requirements ------------ [](#requirements) - PHP 8.1+ - Laravel 10 or 11 - A cache driver (Redis recommended for production; `array` works for testing) --- Installation ------------ [](#installation) ``` composer require shieldapp/laravel-shield php artisan shield:install ``` `shield:install` publishes the config, runs migrations, and prints a setup checklist. --- Configuration ------------- [](#configuration) Publish the config file independently if needed: ``` php artisan vendor:publish --tag=shield-config ``` ### Core `.env` variables [](#core-env-variables) ``` # --- Core --- SHIELD_ENABLED=true SHIELD_DASHBOARD_PATH=shield # URL path, e.g. "admin/shield" SHIELD_WHITELIST=127.0.0.1,::1 # Comma-separated IPs never blocked # --- Thresholds --- SHIELD_AUTO_BAN_RPM=500 # Auto-ban above this req/min SHIELD_WARN_RPM=200 # Log WARN event above this req/min SHIELD_BAN_DURATION= # null = permanent; or minutes # --- External checks --- SHIELD_SSL_WARN_DAYS=14 # Alert when SSL expires within N days SHIELD_DOMAIN_WARN_DAYS=30 # Alert when domain expires within N days SHIELD_RESPONSE_WARN_MS=1500 # Alert when response time exceeds N ms SHIELD_VERIFY_SSL=true # Set false only in local dev # --- Async logging (optional, requires a queue worker) --- SHIELD_ASYNC_LOGGING=false # true = DB writes happen on a queue SHIELD_QUEUE=shield # Queue name for async log jobs # --- Data retention --- SHIELD_LOG_RETENTION_DAYS=30 SHIELD_CHECK_RETENTION_DAYS=7 SHIELD_BAN_RETENTION_DAYS=90 ``` --- Dashboard --------- [](#dashboard) Visit `/shield` in your browser (protected by `web` + `auth` middleware by default). ``` https://yourapp.com/shield ``` Customise the path and middleware in `config/shield.php`: ``` 'dashboard_path' => 'admin/shield', 'dashboard_middleware' => ['web', 'auth', 'role:admin'], ``` ### Dashboard features [](#dashboard-features) FeatureDescription**Threat level meter**Live LOW / MEDIUM / HIGH / CRITICAL indicator based on peak RPM vs your ban threshold**Live traffic table**Per-IP request counts, user agents, last-seen timestamps — updates every 4 s**Risk badges**Colour-coded LOW / MEDIUM / HIGH / CRITICAL per IP row**Stat cards**Active bans, auto-bans, log entries, and monitor count at a glance**Site monitors**Add any URL and see uptime, SSL, response time, and individual check badges**Audit log**Filterable full event trail with action colours**Ban / unban**Modal to add manual bans; one-click unban from the bans table**Toast notifications**In-browser alerts when new auto-bans are detected between polls--- Multi-Channel Alerts -------------------- [](#multi-channel-alerts) Alerts fire for: IP auto-ban, site down, SSL expiry. All channels are optional and independent — configure only the ones you need. ### Email [](#email) ``` SHIELD_ALERT_EMAIL=admin@yoursite.com ``` ### Slack [](#slack) Create an [Incoming Webhook](https://api.slack.com/messaging/webhooks) in your Slack workspace: 1. Go to **api.slack.com/apps** → Create App → Incoming Webhooks 2. Activate Incoming Webhooks → Add to channel 3. Copy the webhook URL ``` SHIELD_SLACK_WEBHOOK=https://hooks.slack.com/services/T.../B.../xxx ``` Alerts arrive as rich Block Kit messages with colour-coded headers, IP/URL detail fields, and a **View Dashboard** button. ### WhatsApp (via Twilio) [](#whatsapp-via-twilio) 1. Sign up at [twilio.com](https://www.twilio.com) 2. Enable the **WhatsApp Sandbox** (or a dedicated WhatsApp sender) in your Twilio console 3. Note your Account SID and Auth Token ``` TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx TWILIO_AUTH_TOKEN=your_auth_token SHIELD_WHATSAPP_FROM=whatsapp:+14155238886 # Twilio sandbox number (or your approved number) SHIELD_WHATSAPP_TO=whatsapp:+447700000000 # The number that receives alerts ``` ### Alert cooldown [](#alert-cooldown) To prevent flooding, the same alert for the same IP/URL won't re-fire until the cooldown window expires: ``` // config/shield.php 'alert_cooldown_minutes' => 15, ``` --- Async Logging (Queue) --------------------- [](#async-logging-queue) By default every significant event (WARN, BAN, BLOCKED) is written to the database synchronously. Enable async mode to push DB writes onto a queue worker: ``` SHIELD_ASYNC_LOGGING=true SHIELD_QUEUE=shield ``` Start a queue worker on the `shield` queue: ``` php artisan queue:work --queue=shield ``` > **Note:** The `shield:active_ips` Redis map used by the live dashboard is always updated synchronously regardless of this setting — async mode only affects DB writes. --- Artisan Commands ---------------- [](#artisan-commands) ``` # Run all health checks now (also prunes old data) php artisan shield:check # Check a specific URL php artisan shield:check --url=https://example.com # Print daily traffic + health summary report php artisan shield:report ``` --- Scheduler --------- [](#scheduler) Add the Laravel scheduler to your crontab and Shield registers itself automatically: ``` * * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1 ``` Shield registers: CommandFrequency`shield:check`Every 5 minutes`shield:report`Daily at 08:00Pruning of old traffic logs, check results, and expired bans runs inside `shield:check`. --- Middleware ---------- [](#middleware) The `IpShield` middleware is registered automatically for all HTTP routes via the service provider. You can also apply it selectively: ``` // routes/web.php Route::middleware(['shield'])->group(function () { // ... }); ``` Or exclude specific routes from Shield checks by IP-whitelisting in your config. --- Agent Mode ---------- [](#agent-mode) Install Shield on any client server. It will POST CPU, RAM, disk, queue, and error stats back to your central Shield dashboard every 5 minutes. ``` # On the remote (agent) server SHIELD_AGENT_ENABLED=true SHIELD_AGENT_ENDPOINT=https://your-shield-saas.com/shield/agent/report SHIELD_AGENT_KEY=your-secret-api-key ``` On the receiving (hub) server, set the same key: ``` SHIELD_AGENT_API_KEY=your-secret-api-key ``` ### What can be monitored? [](#what-can-be-monitored) CheckURL-onlyWith agentUptime✅✅Response time✅✅SSL certificate✅✅DNS records✅✅Security headers✅✅Domain expiry✅✅CPU / RAM / disk❌✅Queue depth❌✅Error log count❌✅IP traffic & bansOwn server only✅--- Data Retention -------------- [](#data-retention) Shield automatically prunes old records during every `shield:check` run: TableDefault retentionConfig key`shield_traffic_logs`30 days`shield.log_retention_days``shield_check_results`7 days`shield.check_retention_days``shield_ip_bans` (expired)90 days`shield.ban_retention_days`Override in `.env`: ``` SHIELD_LOG_RETENTION_DAYS=14 SHIELD_CHECK_RETENTION_DAYS=3 SHIELD_BAN_RETENTION_DAYS=60 ``` --- Testing ------- [](#testing) ``` composer test ``` The test suite uses Orchestra Testbench with an in-memory SQLite database and the array cache driver — no Redis or MySQL required. --- Security -------- [](#security) If you discover a security vulnerability please email **** rather than opening a public issue. --- License ------- [](#license) The MIT License (MIT). See [LICENSE.md](LICENSE.md) for details. ### Health Score 19 — LowBetter than 9% of packages Maintenance56 Moderate activity, may be stable Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity12 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/439d85c5029aa604a584999203131946486ab851ee31c9c9230cce69ce1f9192?d=identicon)[sunilluhana](/maintainers/sunilluhana) --- Top Contributors [![sunilluhana-gl](https://avatars.githubusercontent.com/u/205151355?v=4)](https://github.com/sunilluhana-gl "sunilluhana-gl (10 commits)") ### Embed Badge ![Health badge](/badges/shieldapp-laravel-shield/health.svg) ``` [![Health](https://phpackages.com/badges/shieldapp-laravel-shield/health.svg)](https://phpackages.com/packages/shieldapp-laravel-shield) ``` ### Alternatives [psr/log Common interface for logging libraries 10.4k1.2B11.9k](/packages/psr-log)[open-telemetry/api API for OpenTelemetry PHP. 2041.5M289](/packages/open-telemetry-api)[open-telemetry/sdk SDK for OpenTelemetry PHP. 2428.5M356](/packages/open-telemetry-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)