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

The admin interface is built with Tailwind CSS for modern, responsive design. Make sure your Laravel application has Tailwind CSS configured.

Option 1: Manual Route Registration

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('logs/{id}', [FirewallController::class, 'logDetail'])->name('admin.firewall.logs.detail');
    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');
});

Option 2: Publish Routes File

Alternatively, publish the routes file and load it automatically:

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

This creates routes/firewall-admin.php which will be automatically loaded by the package.

⚠️ Important: If you get a "Route not defined" error, make sure you have added the routes above to your application's routes/web.php file. You can also copy the example routes from vendor/fill84/laravel-firewall/routes/web.php.

Admin Interface Features:

• 📊 Logs Dashboard (/admin/firewall/logs) - View and filter all firewall events
• 🚫 Blocked IPs Management (/admin/firewall/blocked) - Manage blocked IP addresses
• 📈 Statistics Overview (/admin/firewall/stats) - Security metrics and top attackers
• 🔍 Detailed Log View (/admin/firewall/logs/{id}) - In-depth analysis of individual events
• 🎨 Modern UI - Built with Tailwind CSS for responsive, professional design

Styling Requirements:

The admin interface requires Tailwind CSS. If your Laravel application doesn't have Tailwind CSS installed:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Add to your tailwind.config.js:

module.exports = {
  content: [
    './resources/**/*.blade.php',
    './vendor/fill84/laravel-firewall/resources/views/**/*.blade.php',
  ],
  // ... rest of your config
}

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

1. Route [admin.firewall.logs.detail] not defined

   • Solution: Make sure you have added all the admin routes to your routes/web.php file
   • Copy the routes from the installation section above or from vendor/fill84/laravel-firewall/routes/web.php

2. Middleware not working: Ensure it's properly registered in Kernel.php

3. Database errors: Run migrations with php artisan migrate

4. High false positives: Adjust suspicious_paths configuration

5. Performance issues: Clean up old logs and optimize database

6. Tailwind CSS not working: Ensure Tailwind is properly installed and configured

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.