Download the PHP package metalinked/laravel-defender without Composer

Laravel Defender

A modular security package for Laravel that helps you monitor, detect, and block suspicious or malicious activity in your applications.
Laravel Defender offers advanced request logging, risk pattern detection, brute force and spam protection, and real-time alerts—all fully configurable and privacy-friendly.
Easily integrate Defender into your Laravel projects to enhance your application's security with flexible, modern tools.

ℹ️ Actively maintained. Feedback and contributions are welcome.

Note:
This package is 100% open source and does not connect to any external service by default.

✨ Features

• 🛡️ Honeypot-based spam protection for forms
• 👁️ Request logging and alert system for suspicious activity
• 📝 View logs and alerts via Artisan command
• ⚙️ Customizable rules and middleware
• 🚨 Advanced risk pattern detection (user-agents, routes, login attempts, country/IP restrictions, path traversal, fuzzing)
• 🔔 Local real-time alerts (log, mail, Slack, webhook)
• 🔍 Security audit command for common Laravel misconfigurations

🚀 Installation

After installation, publish the config file:

Note:
The database channel is optional, but enabled by default in the alert system.
Only publish and run the migration if you want to keep database logging enabled (see the alerts.channels option in config/defender.php).
If you disable the database channel, you do not need to publish or run the migration, and no logs will be stored in the database.

Publish the migration file:

Run the migrations:

🔒 Global Protection (Recommended)

To ensure Defender can detect and block a wide range of suspicious and malicious access attempts—including requests to non-existent routes (such as /wp-admin, /phpmyadmin, /xmlrpc.php), brute force attacks, access from non-allowed countries, and risky login patterns, you should register all Defender middlewares as global middlewares:

• IpLoggerMiddleware: logs all requests if the ip_logging.log_all option is enabled in the configuration.
• AdvancedDetectionMiddleware: detects suspicious user-agents, common attack routes, and login attempts with common usernames.
• BruteForceMiddleware: detects and blocks brute force attempts from the same IP.
• CountryAccessMiddleware: allows or denies access based on country or IP whitelist/denylist.

Registering these middlewares globally ensures your application is protected against a broad spectrum of attacks, including those targeting non-existent or sensitive routes.

For Laravel 11 or higher

Add the following to your bootstrap/app.php inside the withMiddleware callback:

For Laravel 10 and earlier

Add the following to the $middleware array in your app/Http/Kernel.php:

Recommended:
Registering these middlewares globally ensures all requests are protected, including non-existent routes, without needing to add them to individual routes.

🛡️ Honeypot Spam Protection

This package provides configurable honeypot protection for your Laravel forms.

Quick start

1. Publish the Blade view (optional):

2. Add the honeypot field to your forms:

3. Configure automatic protection (optional): In config/defender.php, set:

4. Manual middleware (if auto protection is disabled): Add the middleware to your route:

🚨 Advanced Risk Pattern Detection

Laravel Defender can detect and alert on suspicious patterns beyond just IPs.

What is detected?

• Suspicious user-agents: (e.g. curl, python, sqlmap, scanner, etc.)
• Access to common attack routes: /wp-admin, /phpmyadmin, /xmlrpc.php, etc.
• Login attempts with common usernames: admin, root, test, etc.
• Access from blocked or non-allowed countries: (with free IP geolocation)
• Brute force attempts: Too many requests from the same IP in a short period
• Path traversal and fuzzing patterns: Attempts to exploit with ../, encoded traversal, or common fuzzing payloads/tools (e.g. sqlmap, acunetix, etc.)

How to configure

In your config/defender.php:

Note:

• You can set mode to 'allow' (only allow listed countries) or 'deny' (block listed countries).
• IPs in whitelist_ips are always allowed, regardless of country or mode.
• Country detection uses ip-api.com (free tier, no registration required).

🔔 Alert System

Laravel Defender supports local real-time alerts via multiple channels.

Supported channels

• log (Laravel log)
• database (save to the database)
• mail (send to a configured email)
• slack (send to a Slack webhook)
• webhook (send to any external URL)

Only the log and database channels are enabled by default.

How to configure

In your config/defender.php:

Environment Variables

You can configure Laravel Defender using the following .env variables:

All variables are optional and only required if you enable the corresponding alert channel or feature in config/defender.php.

📝 IP Logging & Brute Force Protection

You can control global request logging and brute force protection in your config/defender.php:

• ip_logging.log_all: If set to true, logs every request (not just suspicious ones).
  Warning: Only enable this for testing or temporary audits. Not recommended for production!
• brute_force.max_attempts: Number of allowed attempts before blocking an IP.
• brute_force.decay_minutes: Time window for counting attempts.

📊 Viewing and Exporting IP Logs and Alerts

Laravel Defender provides an Artisan command to review access logs and suspicious activity directly from the console.

Important:
Only logs stored in the database (with the database alert channel enabled and migration run) can be viewed or exported using these commands.
Logs written to the Laravel log file (storage/logs/laravel.log) are not accessible via Defender commands.

This approach is secure and convenient, as it does not expose sensitive data via the web and works even if your app does not have a backoffice.

Note:
Viewing and exporting logs is only available if the database channel is enabled and the migration has been run.

Usage

Show the latest 50 logs:

Show only suspicious logs:

Filter by IP:

Limit the number of results:

You can combine options as needed.

Export logs to CSV or JSON

Export all logs to CSV:

Export only suspicious logs to JSON:

Export logs for a specific IP and date range:

🧹 Pruning Old Logs

You can easily clean up old logs from the database (and optionally from Laravel log files) using the built-in Artisan command:

Delete Defender logs older than 90 days from the database:

Delete Defender logs older than 30 days and also remove old Laravel log files:

Note:
Only logs stored in the database can be listed and exported with Defender commands.
Logs written to the Laravel log file (storage/logs/laravel.log) are not accessible via Defender commands and must be managed manually or with the --laravel prune option.

Scheduled log pruning

To automatically prune old Defender logs on a schedule, add the following to your scheduler file:

For Laravel 11 and newer (bootstrap/routes/console.php):

For Laravel 10 and earlier (app/Console/Kernel.php):

This will delete Defender logs older than 90 days every day.
You can adjust the frequency and retention period as needed.

🔒 Security Audit

Run a local security audit of your Laravel project:

This command checks for:

• Publicly accessible .env file
• APP_DEBUG enabled
• Permissive CORS configuration
• Insecure session cookies
• Laravel version

It gives clear recommendations for each issue found.

🧪 Testing

Run tests with:

Or if using Pest:

Note:
Make sure your PHP installation has the sqlite3 and pdo_sqlite extensions enabled.
These are required for running the package tests (Testbench uses SQLite in-memory by default).

🛡️ Security

If you discover a security vulnerability, please report it via email to [email protected]. All reports will be handled responsibly and in confidence.

Usage Model

• Free & Open Source (offline):
  All users can use the basic security features locally, without connecting to any external service. No registration required. Privacy-friendly and self-hosted.

🤝 Contributing

See CONTRIBUTING.md for guidelines on how to contribute.

📄 License

MIT © Metalinked

📢 Stay in touch

If you're interested in using this tool or contributing, feel free to open an issue or start a discussion.

💬 Questions, suggestions or feedback? Join the Discussions!