README

A comprehensive firewall middleware for Laravel applications that monitors and blocks suspicious activity, protecting your application from malicious requests and automated attacks.

Features

🛡️ Real-time Protection: Automatically detects and blocks suspicious requests
📊 Comprehensive Logging: Detailed logs of all firewall events with request information
🎯 Pattern Matching: Configurable suspicious path patterns with wildcard support
🔧 Admin Interface: Web interface for managing blocked IPs and viewing logs
⚙️ Configurable: Highly customizable settings via configuration file
🏠 IP Whitelisting: Protect trusted IPs from being blocked
📈 Statistics: Detailed statistics and reporting
🌍 Geo-location: Optional geographical logging of blocked IPs

Installation

Install the package via Composer:

composer require fill84/laravel-firewall

Laravel 11+ (Auto-Discovery)

The package will automatically register itself via Laravel's package auto-discovery feature.

Laravel 10 or Manual Registration

Add the service provider to your config/app.php:

'providers' => [
    // Other providers...
    Fill84\LaravelFirewall\FirewallServiceProvider::class,
];

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=firewall-config

This will create a config/firewall.php file where you can customize the package settings:

return [
    'suspicious_paths' => [
        'wp-admin.php',
        'wp-login.php',
        'phpinfo.php',
        // Add your own patterns...
    ],
    'max_attempts' => 3,
    'whitelist_ips' => [
        '127.0.0.1',
        // Add your trusted IPs...
    ],
    // More configuration options...
];

Database Setup

Publish and run the migrations:

php artisan vendor:publish --tag=firewall-migrations
php artisan migrate

This will create two tables:

firewall_logs - Stores all firewall events and request details
firewall_blocks - Manages blocked IP addresses

Usage

1. Register the Middleware

Add the firewall middleware to your application. You can do this globally or on specific routes.

Global Protection (Recommended)

Add to app/Http/Kernel.php:

protected $middleware = [
    // Other middleware...
    \Fill84\LaravelFirewall\Http\Middleware\Firewall::class,
];

Route-Specific Protection

Route::group(['middleware' => 'firewall'], function () {
    // Your protected routes...
});

Controller Protection

class YourController extends Controller
{
    public function __construct()
    {
        $this->middleware('firewall');
    }
}

2. Admin Interface (Optional)

Publish the views to customize the admin interface:

php artisan vendor:publish --tag=firewall-views

Add routes to your routes/web.php:

use Fill84\LaravelFirewall\Http\Controllers\FirewallController;

Route::prefix('admin/firewall')->middleware(['auth', 'admin'])->group(function () {
    Route::get('logs', [FirewallController::class, 'logs'])->name('admin.firewall.logs');
    Route::get('blocked', [FirewallController::class, 'blocked'])->name('admin.firewall.blocked');
    Route::get('stats', [FirewallController::class, 'stats'])->name('admin.firewall.stats');
    Route::post('unblock/{ip}', [FirewallController::class, 'unblock'])->name('admin.firewall.unblock');
    Route::post('block', [FirewallController::class, 'block'])->name('admin.firewall.block');
    Route::delete('cleanup', [FirewallController::class, 'cleanupLogs'])->name('admin.firewall.cleanup');
});

Configuration Options

Suspicious Paths

Define patterns that should be monitored:

'suspicious_paths' => [
    'wp-admin.php',        // Exact match
    'wp-login.php',        // Exact match
    '*admin*',             // Contains 'admin'
    'config*.php',         // Starts with 'config', ends with '.php'
    '*.env',               // Any .env file
],

Maximum Attempts

Set how many suspicious requests trigger a block:

'max_attempts' => 3, // Block after 3 attempts in 24 hours

IP Whitelisting

Protect trusted IPs from being blocked:

'whitelist_ips' => [
    '127.0.0.1',
    '192.168.1.100',
    '::1',
],

Detailed Logging

Control what information is logged:

'log_detailed_info' => true, // Log headers, POST data, etc.

Environment Variables

You can also configure the package using environment variables:

FIREWALL_MAX_ATTEMPTS=5
FIREWALL_BLOCK_DURATION=1440  # minutes (null for permanent)
FIREWALL_LOG_DETAILED=true
FIREWALL_GEO_LOGGING=false

Manual IP Management

Block an IP Programmatically

use Illuminate\Support\Facades\DB;

DB::table('firewall_blocks')->updateOrInsert(
    ['ip_address' => '192.168.1.100'],
    [
        'is_blocked' => true,
        'blocked_at' => now(),
        'admin_notes' => 'Manually blocked for suspicious activity',
        'updated_at' => now(),
    ]
);

Unblock an IP Programmatically

use Illuminate\Support\Facades\DB;

DB::table('firewall_blocks')
    ->where('ip_address', '192.168.1.100')
    ->update([
        'is_blocked' => false,
        'unblocked_at' => now(),
    ]);

Database Maintenance

Clean Up Old Logs

# Delete logs older than 30 days
php artisan tinker
> DB::table('firewall_logs')->where('created_at', '<', now()->subDays(30))->delete();

Monitor Database Size

The firewall logs can grow large over time. Consider:

Regular cleanup of old logs
Database indexing for performance
Log rotation strategies

Performance Considerations

The middleware adds minimal overhead (< 5ms typically)
Database queries are optimized with proper indexing
Consider caching for high-traffic applications
Monitor log table size and clean up regularly

Security Notes

Always keep your whitelist IPs updated
Regularly review blocked IPs for false positives
Monitor firewall logs for new attack patterns
Consider rate limiting in addition to this firewall

Troubleshooting

Common Issues

Middleware not working: Ensure it's properly registered in Kernel.php
Database errors: Run migrations with php artisan migrate
High false positives: Adjust suspicious_paths configuration
Performance issues: Clean up old logs and optimize database

Debug Mode

Enable detailed logging in your configuration:

'log_detailed_info' => true,

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Support

If you encounter any issues or have questions, please create an issue on GitHub.

Note: Replace fill84/laravel-firewall and Fill84 with your actual package name and namespace if you fork this project.

fill84 / laravel-firewall

Maintainers

Details