Banhammer, a Model and IP ban package for Laravel

Banhammer for Laravel offers a very simple way to ban any Model by ID and by IP. It also allows to block requests by IP addresses.

Banned models can have an expiration date and will be automatically unbanned using the Scheduler.

Version Compatibility

Laravel	Banhammer
^9.0	1.x.x
^10.0	1.x.x

Installation

You can install the package via composer:

composer require mchev/banhammer

Then run the migrations with:

php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="banhammer-config"

It is possible to define the table name and the fallback_url in the config/ban.php file.

Usage

To make a model bannable, add the Mchev\Banhammer\Traits\Bannable trait to the model:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Mchev\Banhammer\Traits\Bannable;

class User extends Authenticatable
{
    use Bannable;
}

You can add the Bannable trait on as many models as you want (Team, Group, User, etc.).

Ban / Unban

Simple ban

$user->ban();

Without the expired_at attribute specified, the user will be banned forever.

IP Ban

$user->ban([
	'ip' => $user->ip,
]);

Full

All attributes are optional

$model->ban([
	'created_by_type' => 'App\Models\User',
	'created_by_id' => 1,
	'comment' => "You've been evil",
	'ip' => "8.8.8.8",
	'expired_at' => Carbon::now()->addDays(7),
	'metas' => [
		'route' => request()->route()->getName(),
		'user_agent' => request()->header('user-agent')
	]
]);

Shorthand

$user->banUntil('2 days');

Check if model is banned.

You can create custom middlewares using these methods.

$model->isBanned();
$model->isNotBanned();

List model bans

// All model bans
$bans = $model->bans()->get();

// Expired bans
$expired = $model->bans()->expired()->get();

// Not expired and permanent bans
$notExpired = $model->bans()->notExpired()->get();

Filters

$bannedTeams = Team::banned()->get(); 
$notBannedTeams = Team::notBanned()->get();

Unban

$user->unban();

IP

Ban IPs

use Mchev\Banhammer\IP;

IP::ban("8.8.8.8");
IP::ban(["8.8.8.8", "4.4.4.4"]);

Unban IPs

use Mchev\Banhammer\IP;

IP::unban("8.8.8.8");
IP::unban(["8.8.8.8", "4.4.4.4"]);

List all banned IPs

use Mchev\Banhammer\IP;

$ips = IP::banned()->get(); // Collection
$ips = IP::banned()->pluck('ip')->toArray(); // Array

Metas

Ban IP with metas

use Mchev\Banhammer\IP;

IP::ban("8.8.8.8", [
	'route' => request()->route()->getName(),
	'user_agent' => request()->header('user-agent')
]);

Metas usage

$ban->setMeta('username', 'Jane');
$ban->getMeta('username'); // Jane
$ban->hasMeta('username'); // boolean
$ban->forgetMeta('username');

Filtering by Meta

IP::banned()->whereMeta('username', 'Jane')->get();
// OR
$users->bans()->whereMeta('username', 'Jane')->get();
// OR
$users->whereBansMeta('username', 'Jane')->get();

Middleware

To prevent banned users from accessing certain parts of your application, simply add the auth.banned middleware on the concerned routes.

Route::middleware(['auth.banned'])->group(function () {
    // ...
});

To prevent banned ips from accessing certain parts of your application, simply add the ip.banned middleware on the concerned routes.

Route::middleware(['ip.banned'])->group(function () {
    // ...
});

To block and logout banned Users or IP, add the logout.banned middleware:

Route::middleware(['logout.banned'])->group(function () {
    // ...
});

If you use the logout.banned middleware, it is not necessary to cumulate the other middlewares.

If you want to block IPs on every HTTP request of your application, list Mchev\Banhammer\Middleware\IPBanned in the $middleware property of your app/Http/Kernel.php class.

Scheduler

⚠ IMPORTANT

In order to be able to automatically delete expired bans, you must have a cron job set up on your server to run the Laravel Scheduled Jobs

Running the scheduler

Configure Scheduler on Forge

Events

If entity is banned Mchev\Banhammer\Events\ModelWasBanned event is fired.

Is entity is unbanned Mchev\Banhammer\Events\ModelWasUnbanned event is fired.

MISC

To manually unban expired bans :

use Mchev\Banhammer\Banhammer;

Banhammer::unbanExpired();

Or you can use the command:

php artisan banhammer:unban

To permanently delete all the expired bans :

use Mchev\Banhammer\Banhammer;

Banhammer::clear();

Or you can use the command:

php artisan banhammer:clear

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Roadmap

• Handle UUIDs and ULIDs
• More tests
• Block IP range
• Auto block IP (Rate Limiting)
• Cache
• Ban history (expired, not expired)

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Inspired by laravel-ban from cybercog

License

The MIT License (MIT). Please see License File for more information.