breizhwave / wave-security-ip-restrict
Restrict a whole Laravel application to an IP allow list (IPv4, IPv6, CIDR), deny list, attack attempts log and automatic blocking of brute force and scans, managed from .env and an optional admin page. PHP 5.6+ and Laravel 5.1 to 13.
Package info
github.com/breizhwave/wave-security-ip-restrict
pkg:composer/breizhwave/wave-security-ip-restrict
Requires
- php: >=5.6
- illuminate/console: ^5.1|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^5.1|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/routing: ^5.1|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^5.1|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/view: ^5.1|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Restrict a whole Laravel application to an allow list of IP addresses (IPv4, IPv6, CIDR ranges), deny unwanted addresses, and block brute force and scans automatically.
- The
.env(IP_RESTRICT_IPS) switches the restriction on and gives the base list. An empty.envlist means no restriction at all. A JSON file adds to that list or hides some of its entries (see How the allow list is built). - An optional admin page and console commands let someone who already has access add, remove (hide) and restore entries. These changes go to a JSON file that survives deployments.
- Removing an added entry deletes it from the JSON file.
- Removing a
.enventry only hides it: the JSON file records the address with when and by whom (hidden_at,hidden_by), and the address is refused from then on. The.envitself is never changed. The application often can't write to it (read-only file, cached config, managed by the deployment), and it stays the reference list that you version and deploy. Hiding also keeps the removal reversible: restoring (ip-restrict:remove <ip> --restore, or the button on the page) takes the address off the hidden list, with its original.envlabel, without touching the server. To remove a.envaddress for good, delete it fromIP_RESTRICT_IPS.
- Some
.enventries can be protected (they are never removable from the page), and nobody can remove the entry that covers the address they are using. - The allow list covers the whole application, or only some paths (
IP_RESTRICT_PATHS, e.g. your back office) while the rest of the site stays public. See Use cases. - A deny list (
IP_RESTRICT_DENY, the admin page, the console) refuses addresses even when the restriction is off: it works on a public site too. See Deny list. - Attack attempts (failed logins, lockouts, scanner probes such as
wp-login.phpor.env, refused requests) are logged one file per day, shown by date on the admin page, and an address that repeats them is blocked automatically for a while. See Attack attempts and automatic blocking. - Refused requests get a 403 page that shows the visitor's address. The page is in English and French and can be published to change it.
- PHP 5.6 to 8.x, Laravel 5.1 to 13: the package uses PHP 5.6 syntax only, framework features that exist since Laravel 5.1, and its own CIDR matcher with no Symfony version dependency.
- It is not a WAF: it does not inspect request content (SQL injection, XSS…). See Compared with other packages for akaunting/laravel-firewall and the alternatives.
How the allow list is built
Every request is checked against both sources:
| Source | Role |
|---|---|
.env (IP_RESTRICT_IPS) |
On/off switch and base list. Edited by hand, deployed with the application. |
JSON file (storage/app/ip-restrict.json) |
Changes made from the admin page or the console: added entries and hidden .env entries. Never deployed, survives deployments. |
restriction on = IP_RESTRICT_IPS has at least one valid entry
allowed = (.env entries − hidden ones) + added entries + local (127.0.0.1, ::1)
restricted path = every path, or only IP_RESTRICT_PATHS (+ the admin page) when it is set
What follows from it:
.envempty: everyone gets in, even when the JSON file has added entries. They take effect once the.envlist is set again.- Every
.enventry hidden: the restriction stays on, and only added entries and local addresses get in. - JSON file missing or deleted: back to the plain
.envlist.
Deny list
A denied address gets the 403 page ("Access blocked"), whatever the allow list says:
refused = denied (deny list, not expired) even when the restriction is off
else = allow list rules above
local addresses (127.0.0.1, ::1) and `except` paths always pass
| Source | Role |
|---|---|
.env (IP_RESTRICT_DENY) |
Same ip=label format as IP_RESTRICT_IPS. Read only: remove an entry from the .env. |
JSON file (denied) |
Entries added from the admin page, the console or the automatic blocking, each with an optional end date (expires_at). Expired entries are ignored, then dropped on the next change. |
Two safety rails, on the admin page and in IpList::deny():
- you cannot deny a range that covers the address you are using;
- you cannot deny a range that overlaps a protected allowed entry (
IP_RESTRICT_PROTECTED).
Attack attempts and automatic blocking
An attempt is one JSON line in storage/app/ip-restrict-attempts/YYYY-MM-DD.jsonl, with time, address, type, detail, method, path and user agent. Types:
| Type | Recorded when | Counted for blocking |
|---|---|---|
login_failed |
Laravel fires Illuminate\Auth\Events\Failed (Laravel 5.2+). The detail is the email field tried (attempts.login_field), never the password. |
yes |
lockout |
Laravel fires Illuminate\Auth\Events\Lockout (too many logins, ThrottlesLogins / Breeze / Fortify, Laravel 5.3+). |
yes |
probe |
The path matches attempts.probes (wp-login.php, wp-admin/*, xmlrpc.php, .env, .git/*, phpmyadmin…). The request then goes on normally (usually a 404). |
yes |
not_allowed |
The allow list refused the request. | no |
custom (or yours) |
Your code calls app(\Wave\SecurityIpRestrict\Attempts::class)->recordRequest($request, 'custom', 'Bad API token'). |
custom yes |
Automatic blocking: an address with threshold counted attempts (5) within window minutes (10) is added to the deny list for ban minutes (60, 0 = until unblocked), with added_by: "auto". The request that crosses the threshold already gets the 403 page.
What is never logged or blocked:
- local addresses (
127.0.0.1,::1): never logged; - addresses on the allow list,
.envor added (even while the restriction is off): logged as trusted, never counted, so a colleague who mistypes a password does not lock the office out. Add your office or VPN address to be safe; - addresses already denied: refused before anything else, not logged, so a blocked scanner does not fill the disk.
The log keeps keep_days days (30). Past max_day_bytes (10 MB) in a day, only blockings are still written. Set IP_RESTRICT_ATTEMPTS_LOG=true to copy each attempt to the Laravel log as a warning too (for your alerting).
The admin page has an Attack attempts tab: pick a day, see the attempts grouped by address (count, types, first and last time, state), the detail of one address, and Block or Unblock in one click.
Who can open the admin page
The package has no admin account of its own: it has no users and no password. The admin page is protected by the allow list and by the middleware you give it (admin.middleware).
| Setup | Who gets into /ip-restrict |
|---|---|
IP_RESTRICT_ADMIN unset (default) |
Nobody: the routes are not registered. Use the console. |
| Allow list on the whole application | Allowed addresses and local ones, then admin.middleware. |
Allow list on some paths (IP_RESTRICT_PATHS) |
The same: the admin page is always added to the scope. |
Allow list empty (IP_RESTRICT_IPS="") |
Anyone who passes admin.middleware. Add your authentication, e.g. ['web', 'auth'], or set an allow list scoped to the admin page (use case 3). |
A denied address never gets in, whatever the setup. With IP_RESTRICT_GLOBAL=false, the admin routes still get the IP checks.
The top of the admin page shows this for your live configuration: which use case below it matches, a grid of who gets where (local, allowed, everyone else, denied × always open paths, restricted paths, rest of the site, admin page), and warnings when the admin page is open to everyone or the server seems to see a proxy's address instead of yours.
Use cases
1. Private application (staging, intranet, client preview)
The whole application is closed to everyone except the team. Health checks stay open.
whole application
office 203.0.113.10 ─► allowed ─► / /login /admin /api … 200
Alice 2001:db8:1:2::5 ─► allowed (her /64 range) 200
stranger 192.0.2.1 ─► not on the list 403 "Restricted access"
logged as not_allowed
load balancer ─► /up (in except) 200
IP_RESTRICT_IPS="203.0.113.10=Office,2001:db8:1:2::/64=Alice (IPv6)" IP_RESTRICT_PROTECTED="Office" IP_RESTRICT_ADMIN=true
The team manages the list at /ip-restrict. Strangers never reach the login page, so brute force is not possible. Scanner probes from allowed addresses are logged as trusted.
2. Public site, back office for the team only, automatic blocking everywhere
The site is public. Only /admin is restricted to the team's addresses. Scanners and brute force are blocked on the whole site.
public part │ restricted part (IP_RESTRICT_PATHS)
/ /blog /login /api │ /admin/* /ip-restrict/*
visitor 192.0.2.1 ─► 200 │ 403 "Restricted access"
office 203.0.113.10 ─► 200 │ 200
scanner 192.0.2.66 ─► /wp-login.php 404, /.env 404 …
5th probe within 10 min ─► 403 "Access blocked" on EVERY path, 60 min
brute force 192.0.2.77 ─► POST /login failed ×5 ─► blocked the same way
IP_RESTRICT_IPS="203.0.113.10=Office,198.51.100.7=Alice" IP_RESTRICT_PROTECTED="Office" IP_RESTRICT_PATHS="admin,admin/*" IP_RESTRICT_ADMIN=true # defaults: 5 attempts in 10 min, 60 min ban
- The team's addresses are trusted: never blocked automatically, even when someone mistypes a password.
- If your login page is under
/admin(/admin/login), it is restricted too, and brute force from outside never reaches it. If it is public (/login), customers who fail 5 times in 10 minutes are blocked for an hour. RaiseIP_RESTRICT_AUTO_BLOCK_THRESHOLDif that is too strict. - The Attack attempts tab shows who tried what, by day. Use it to unblock a customer or to block a range for good.
3. Public site, deny list and automatic blocking only (like fail2ban)
There is no allow list at all: the package only refuses bad addresses.
every request ─► denied? ──yes──► 403 "Access blocked" (not logged again)
│ no
▼
probe path? ──yes──► log + count ─► threshold reached? ─► deny for 60 min, 403
│ no │ no
▼ ▼
application ◄────────────────────────────┘
│
failed login / lockout / your own report ─► log + count ─► …
IP_RESTRICT_IPS="" IP_RESTRICT_DENY="198.51.100.0/24=Scraper" IP_RESTRICT_ADMIN=true
With an empty allow list, only admin.middleware protects the admin page. Choose one:
- publish the config and set
'middleware' => array('web', 'auth'), plus your own admin check; - or protect the admin page alone by address:
IP_RESTRICT_IPS="203.0.113.10=Office"andIP_RESTRICT_PATHS="ip-restrict,ip-restrict/*". The rest of the site stays public, as in use case 2.
4. Behind a reverse proxy or a CDN
visitor 192.0.2.1 ─► CDN / load balancer 172.68.1.2 ─► nginx ─► Laravel
adds X-Forwarded-For: 192.0.2.1
trusted proxies set $request->ip() = 192.0.2.1 ✔ each visitor is seen as themselves
trusted proxies missing $request->ip() = 172.68.1.2 ✘ every visitor has the same address:
- allow list: everyone refused (or everyone allowed if the proxy is 127.0.0.1)
- automatic blocking: the first scanner blocks the proxy, so the whole site
Configure trusted proxies before you turn anything on: ->withMiddleware(fn ($m) => $m->trustProxies(at: [...])) in bootstrap/app.php (Laravel 11+), or App\Http\Middleware\TrustProxies (earlier versions). Then check that the Attack attempts tab shows your visitors' addresses, not the proxy's. Run the header spoofing check too.
5. Locked out
you ─► 403 "Restricted access" (new home address) ─► ssh ─► php artisan ip-restrict:add 192.0.2.10 "Me, home"
you ─► 403 "Access blocked" (blocked by mistake) ─► ssh ─► php artisan ip-restrict:remove 192.0.2.10 --deny
The page shows the address the server sees: that's the one to add or unblock. php artisan ip-restrict:list shows both lists.
6. Report your own attempts
Anything your code considers hostile can count toward the blocking: a wrong API token, a failed 2FA code, a spam form, a forged signature.
use Wave\SecurityIpRestrict\Attempts; if (! hash_equals($expected, (string) $request->header('X-Token'))) { if (app(Attempts::class)->recordRequest($request, 'custom', 'Bad API token') === Attempts::BLOCKED) { abort(403); } abort(401); }
To count your own type, add it to auto_block.types (published config), e.g. 'types' => array('login_failed', 'lockout', 'probe', 'custom', 'api_token').
Install
composer require breizhwave/wave-security-ip-restrict
Laravel 5.5 and later discover the service provider automatically. On Laravel 5.1 to 5.4, add it to config/app.php:
'providers' => [ // ... Wave\SecurityIpRestrict\IpRestrictServiceProvider::class, ],
Configure
.env:
# Addresses or CIDR ranges, comma separated, optional label after "=" IP_RESTRICT_IPS="203.0.113.10=Office,198.51.100.7=Alice,2001:db8:1:2::/64=Alice (IPv6)" # .env entries never removable from the admin page (label prefixes) IP_RESTRICT_PROTECTED="Office,Alice" # Restrict only these paths (empty: the whole application). The admin page is always included. IP_RESTRICT_PATHS="" # Admin page at /ip-restrict (off by default) IP_RESTRICT_ADMIN=true # Denied addresses, always refused (same format) IP_RESTRICT_DENY="198.51.100.0/24=Scraper" # Attempts log and automatic blocking (defaults shown) IP_RESTRICT_ATTEMPTS=true IP_RESTRICT_AUTO_BLOCK=true IP_RESTRICT_AUTO_BLOCK_THRESHOLD=5 # attempts… IP_RESTRICT_AUTO_BLOCK_WINDOW=10 # …within this many minutes IP_RESTRICT_AUTO_BLOCK_BAN=60 # minutes blocked, 0 = until unblocked IP_RESTRICT_ATTEMPTS_LOG=false # also write attempts to the Laravel log
To change the other settings, publish the config file (config/ip-restrict.php):
php artisan vendor:publish --tag=ip-restrict-config php artisan vendor:publish --tag=ip-restrict-views # 403 and admin pages php artisan vendor:publish --tag=ip-restrict-lang # en / fr texts
| Key | Default | Purpose |
|---|---|---|
ips |
IP_RESTRICT_IPS |
Allowed entries. An empty list turns the restriction off. |
protected |
IP_RESTRICT_PROTECTED |
Label prefixes of protected .env entries. |
local |
127.0.0.1, ::1 |
Always allowed, for php artisan serve. |
except |
['up'] |
Paths that stay open, as $request->is() patterns. |
paths |
IP_RESTRICT_PATHS (empty) |
Scope of the allow list, comma separated $request->is() patterns. Empty: the whole application. The admin page is always added. The deny list and the blocking cover every path. |
file |
storage/app/ip-restrict.json |
Added and hidden entries. |
global |
true |
Prepends the middleware to the global HTTP stack. |
forbidden_view |
ip-restrict::forbidden |
The 403 page. |
admin.enabled |
IP_RESTRICT_ADMIN (false) |
Turns the admin routes on. |
admin.path |
ip-restrict |
URL prefix of the admin page. |
admin.middleware |
['web'] |
Add your authentication here, e.g. ['web', 'auth']. |
admin.write_middleware |
['throttle:20,1'] |
Applied to add, remove, restore, deny and unblock. |
deny |
IP_RESTRICT_DENY |
Denied entries, always refused. |
attempts.enabled |
IP_RESTRICT_ATTEMPTS (true) |
Turns the attempts log (and so the automatic blocking) on. |
attempts.dir |
storage/app/ip-restrict-attempts |
One file per day, plus counters.json. |
attempts.keep_days |
30 |
Older day files are deleted. |
attempts.max_day_bytes |
10 MB | Past it, only blockings are written that day. |
attempts.laravel_log |
IP_RESTRICT_ATTEMPTS_LOG (false) |
Copy each attempt to the Laravel log (warning). |
attempts.login_failed |
true |
Listen to Laravel's Failed and Lockout events. |
attempts.login_field |
email |
Credential logged with a failed login. null: none. |
attempts.not_allowed |
true |
Log the requests the allow list refuses. |
attempts.probes |
wp-login.php, .env… |
Scanner paths, as $request->is() patterns. [] turns probes off. |
auto_block.enabled |
IP_RESTRICT_AUTO_BLOCK (true) |
Off: attempts are only logged. |
auto_block.types |
login_failed, lockout, probe, custom |
Types that count. |
auto_block.threshold / window / ban |
5 / 10 min / 60 min |
See above. ban 0: until unblocked. |
Using the middleware on some routes only
To keep part of the site public, prefer IP_RESTRICT_PATHS (use case 2): the deny list and the automatic blocking then still cover every path. With global set to false, every check, deny list and probes included, only runs on the routes you put the middleware on.
Set global to false (IP_RESTRICT_GLOBAL=false), then use the class as you would any middleware:
Route::group(['middleware' => \Wave\SecurityIpRestrict\Http\Middleware\RestrictIp::class], function () { // ... });
Laravel 5.1
Laravel 5.1 has no web middleware group and no throttle middleware. Publish the config and set both admin.middleware and admin.write_middleware to array(), or to middleware your application has.
Console
These commands also let you get back in if you lock yourself out:
php artisan ip-restrict:list php artisan ip-restrict:add 192.0.2.10 "Bob, home" php artisan ip-restrict:remove 192.0.2.10 php artisan ip-restrict:remove 198.51.100.7 --restore # restore a hidden .env entry php artisan ip-restrict:add 192.0.2.66 "Brute force" --deny # deny, until unblocked php artisan ip-restrict:add 192.0.2.66 "Brute force" --deny --minutes=60 # deny for an hour php artisan ip-restrict:remove 192.0.2.66 --deny # unblock php artisan ip-restrict:attempts # latest day, by address php artisan ip-restrict:attempts 2026-11-15 --ip=192.0.2.66 # one address, in detail
ip-restrict:list shows the denied entries too. Blocked yourself by mistake? ip-restrict:remove <your ip> --deny from the server shell.
Managing the list from your own admin
The bundled admin page is plain on purpose. To manage the list inside your own back office (your layout, your authentication, your language), leave IP_RESTRICT_ADMIN off and call Wave\SecurityIpRestrict\IpList yourself. The container gives one shared instance built from the config, so you can type-hint it in a controller.
| Method | Returns |
|---|---|
isActive() |
true when the .env list is not empty. |
isAllowed($ip) |
Whether an address gets in (list or local). |
all() |
Every entry: ip, label, source (env or added), hidden, protected, and added_at, added_by, hidden_at when set. |
add($ip, $label, $by) |
false if the entry is already there. |
remove($ip, $myIp, $by) |
IpList::REMOVED, PROTECTED_ENTRY, IN_USE (covers $myIp) or UNKNOWN. A .env entry is only hidden. |
restore($ip) |
Shows a hidden .env entry again. false if it was not hidden. |
IpList::isValid($ip) |
Valid IPv4 / IPv6 address or CIDR range. |
isDenied($ip) / denyEntryFor($ip) |
Whether the deny list refuses an address / the entry that does. |
denied() |
Deny entries not expired: ip, label, source (env or added), added_at, added_by (auto for automatic blocks), expires_at. |
deny($ip, $label, $by, $myIp = null, $minutes = null) |
IpList::DENIED, ALREADY, IN_USE (covers $myIp) or PROTECTED_ENTRY. |
undeny($ip) |
IpList::REMOVED, ENV_ENTRY (remove it from the .env) or UNKNOWN. |
For the attempts, use Wave\SecurityIpRestrict\Attempts:
| Method | Returns |
|---|---|
recordRequest($request, $type, $detail) |
Attempts::BLOCKED (this attempt blocked the address), LOGGED or IGNORED (local, denied, or log off). |
record($ip, $type, $detail, $path, $userAgent, $method) |
Same, without a request. |
days() |
Logged days, newest first: date, bytes. |
forDay('YYYY-MM-DD', $limit = 0) |
Attempts of a day, newest first: at, ip, type, detail, method, path, user_agent, and trusted, count, blocked when set. |
Attempts::summary($entries) |
Grouped by address: ip, count, types, first, last, trusted, blocked. |
IpList::covers($entry, $ip) |
Whether an entry matches an address. Use it to highlight the row of the current visitor. |
1. Routes
Put them inside your admin group, behind your own authentication. Throttle the write routes:
use App\Http\Controllers\Admin\IpAccessController; Route::middleware(['web', 'auth', 'can:admin'])->prefix('admin')->group(function () { Route::get('ip-access', [IpAccessController::class, 'index'])->name('ip-access'); Route::middleware('throttle:20,1')->group(function () { Route::post('ip-access', [IpAccessController::class, 'add'])->name('ip-access.add'); Route::delete('ip-access', [IpAccessController::class, 'remove'])->name('ip-access.remove'); Route::post('ip-access/restore', [IpAccessController::class, 'restore'])->name('ip-access.restore'); }); });
2. Controller
namespace App\Http\Controllers\Admin; use App\Http\Controllers\Controller; use Illuminate\Http\Request; use Wave\SecurityIpRestrict\IpList; class IpAccessController extends Controller { public function index(Request $request, IpList $ips) { return view('admin.ip-access', [ 'entries' => $ips->all(), 'active' => $ips->isActive(), 'myIp' => $request->ip(), 'myIpAllowed' => $ips->isAllowed($request->ip()), ]); } public function add(Request $request, IpList $ips) { $data = $request->validate([ 'ip' => ['required', 'string', 'max:64', function ($attribute, $value, $fail) { if (! IpList::isValid(trim((string) $value))) { $fail('Expected an IPv4 or IPv6 address, or a CIDR range.'); } }], 'label' => ['required', 'string', 'max:100'], ]); $ip = trim($data['ip']); $by = $request->user() ? $request->user()->email : $request->ip(); // stored as added_by return $ips->add($ip, trim($data['label']), $by) ? redirect()->route('ip-access')->with('status', "$ip added.") : back()->withErrors("$ip is already in the list."); } public function remove(Request $request, IpList $ips) { $ip = (string) $request->input('ip'); switch ($ips->remove($ip, $request->ip(), (string) $request->ip())) { case IpList::REMOVED: return redirect()->route('ip-access')->with('status', "$ip removed."); case IpList::PROTECTED_ENTRY: return back()->withErrors("$ip is protected."); case IpList::IN_USE: return back()->withErrors("$ip covers your own address: removing it would lock you out."); default: return back()->withErrors("$ip is not in the list."); } } public function restore(Request $request, IpList $ips) { $ip = (string) $request->input('ip'); return $ips->restore($ip) ? redirect()->route('ip-access')->with('status', "$ip restored.") : back()->withErrors("$ip was not removed."); } }
3. View
Extend your own layout. One row per entry, with the right action for each case:
@extends('admin.layout') @section('content') <p> Restriction <strong>{{ $active ? 'active' : 'off (IP_RESTRICT_IPS is empty)' }}</strong>. Your address: <code>{{ $myIp }}</code> ({{ $myIpAllowed ? 'allowed' : 'not listed' }}). </p> <table> @foreach ($entries as $entry) @php($mine = ! $entry['hidden'] && \Wave\SecurityIpRestrict\IpList::covers($entry['ip'], $myIp)) <tr @class(['hidden-entry' => $entry['hidden'], 'mine' => $mine])> <td><code>{{ $entry['ip'] }}</code> @if ($mine) (your address) @endif</td> <td>{{ $entry['label'] }}</td> <td>{{ $entry['source'] === 'env' ? '.env' : 'added by '.($entry['added_by'] ?? '?') }}</td> <td> @if ($entry['hidden']) <form method="POST" action="{{ route('ip-access.restore') }}"> @csrf <input type="hidden" name="ip" value="{{ $entry['ip'] }}"> <button>Restore</button> </form> @elseif ($entry['protected']) protected @elseif ($mine) in use @else <form method="POST" action="{{ route('ip-access.remove') }}"> @csrf @method('DELETE') <input type="hidden" name="ip" value="{{ $entry['ip'] }}"> <button>Remove</button> </form> @endif </td> </tr> @endforeach </table> <form method="POST" action="{{ route('ip-access.add') }}"> @csrf <input name="ip" required maxlength="64" placeholder="90.12.34.56 or 2001:db8::/64"> <input name="label" required maxlength="100" placeholder="Who, where"> <button>Add</button> @unless ($myIpAllowed) <button onclick="this.form.ip.value = @js($myIp)">Add my address</button> @endunless </form> @endsection
4. Tips
- Your own 403 page: set
forbidden_viewto one of your views. It receives$ipand$reason(not_allowedordenied). - Your own
.envnames: the config file is yours once published, e.g.'ips' => env('ALLOWED_IPS', ''). - IPv6 at home: a home IPv6 address changes often. Suggest adding its
/64range (first four groups, then::/64). - Older Laravel:
@class,@js,@php(...)and$request->validate()need recent versions. On Laravel 5.x, use$this->validate($request, ...), plainclass="..."attributes andjson_encode.
Checking that the restriction is active
Browsing from an allowed address only shows that you get in. To check the restriction, send a request from an address that is not on the list. You should get the 403 page, and it shows the address the server saw. Ways to do this:
-
Phone on mobile data: turn Wi-Fi off and open the site. The mobile network gives the phone a different public address.
-
Remote or cloud browser: a browser running on someone else's machine (a remote browser service, a browser on a cloud VM, a browser testing platform) connects from that machine's address.
-
VPN or Tor: connect through a VPN, or open the site in Tor Browser.
-
curlfrom a server you can log into (a VPS, another host, a CI job):curl -s -o /dev/null -w "%{http_code}\n" https://example.com/ # expect 403 curl -s -o /dev/null -w "%{http_code}\n" https://example.com/up # expect 200 (in `except`)
-
Header spoofing check: from a refused address, pretend to be an allowed one. This must still return 403. If it returns 200, your trusted proxy settings accept forwarded headers from anyone (see the notes below):
curl -s -o /dev/null -w "%{http_code}\n" -H "X-Forwarded-For: 203.0.113.10" https://example.com/
-
Locally, without a second address:
php artisan ip-restrict:listshows the active entries.127.0.0.1and::1are always allowed, so a test onphp artisan serveproves nothing. Use the package tests (php tests/run.php) for the matching logic.
Does testing weaken the security? No. A refused request only receives the 403 page, and that page shows the visitor their own address. It never shows the list. The one risk is how you test: don't add a remote browser, VPN or public Wi-Fi address to the list "to see if it works", because many other people share that address. If you do add one for a test, remove it straight after with php artisan ip-restrict:remove <ip>.
Security notes
-
Reverse proxy or CDN: the package checks
$request->ip(). Behind a proxy, configure Laravel's trusted proxies first. If you don't, every visitor seems to come from the proxy, and if the proxy is127.0.0.1every visitor passes. -
Automatic blocking behind a proxy: if trusted proxies are not configured, every request seems to come from the proxy, so the first scanner gets the proxy blocked, and so every visitor. Configure trusted proxies before you leave
IP_RESTRICT_AUTO_BLOCKon, and check the attempts tab shows real visitor addresses. If your proxies trust forwarded headers from anyone, an attacker can also get any address blocked by forgingX-Forwarded-For. -
Shared addresses and automatic blocking: an office, a school or a mobile operator's NAT shares one address. Five failed logins there block everyone behind it for
banminutes. Put the addresses you rely on in the allow list (they are never blocked), and keepbanshort. -
The log is personal data: it holds addresses, user agents and the login tried.
keep_dayslimits how long it is kept, and it is shown only on the admin page. -
Admin page with the restriction off: when
IP_RESTRICT_IPSis empty, onlyadmin.middlewareprotects the admin page. Keep it disabled, or put it behind authentication (see Who can open the admin page). -
Static files: files the web server serves directly from
public/never reach Laravel, so they stay readable. To close them too, add a rule to the web server configuration, for example in Apache:<Directory "/path/to/site/public"> Require ip 203.0.113.10 198.51.100.7 2001:db8:1:2::/64 </Directory>
-
An IP address does not identify a person: an office, a public Wi-Fi network or a VPN shares one address between many people. Treat the allow list as an extra barrier, not as authentication.
Compared with other packages
This package is about who may reach the application (an allow list for private sites, a deny list and automatic blocking for public ones). It does not inspect request content. If that is what you need, look at a WAF package, or use both.
akaunting/laravel-firewall
akaunting/laravel-firewall (about 1,000 stars, MIT, v3.0.0 in May 2026) is a Web Application Firewall: it reads request input to detect attacks.
| wave-security-ip-restrict | akaunting/laravel-firewall | |
|---|---|---|
| Main goal | Close a whole site to an allow list, deny addresses, block repeat offenders | Detect and block attacks in requests (WAF) |
| PHP / Laravel | PHP 5.6+, Laravel 5.1 to 13 | PHP 8.2+, Laravel 10 to 13 |
| Storage | .env + one JSON file, no database |
Database (firewall_ips, firewall_logs tables, migrations) |
| Allow list | Whole application, on/off from .env, IPv4/IPv6/CIDR, labels, added and hidden entries |
FIREWALL_WHITELIST (CIDR through Symfony IpUtils): exempted from the checks, and firewall.whitelist middleware to keep routes to these addresses only |
| Deny list | .env + JSON, CIDR ranges, optional end date |
Blocked addresses in the database, single addresses |
| Content inspection | None | SQL injection, XSS, LFI, RFI, PHP code, session fixation, bad URLs, swear words |
| Client filters | None | User agent, bots, referrer, geolocation (country, continent, region, city through an external service such as ipapi or ipinfo) |
| Brute force | Laravel Failed / Lockout events, scanner probe paths (wp-login.php, .env…), your own recordRequest() |
Failed logins, plus each middleware's detections |
| Automatic blocking | One rule: threshold attempts in window minutes → banned ban minutes, expiry checked on each request |
Per middleware (attempts, frequency, period), expiry by the scheduled firewall:unblockip command (cron) |
| Logs | One JSONL file per day, size cap, kept keep_days days |
Database table |
| Notifications | None built in (IP_RESTRICT_ATTEMPTS_LOG copies attempts to the Laravel log for your alerting) |
Email and Slack on each attack |
| Admin | Built-in page (allow list, deny list, attempts by day, block/unblock) and ip-restrict:* commands |
No built-in page, Filament panels exist separately (see below) |
| Safety rails | Cannot remove or deny your own address, protected .env entries, allow list never auto-blocked |
Whitelisted addresses skip the checks |
When to pick which:
- Private site, back office, staging, intranet: this package. One
.envline closes everything, with nothing to migrate. - Public site that receives untrusted input: laravel-firewall adds the content checks this package does not do. Payload detection by patterns has false positives and can be bypassed, so treat it as a layer on top of validation, parameter binding and output escaping.
- Old Laravel (5.x to 9) or PHP before 8.2: this package only, laravel-firewall 3 does not install there.
- Both together work: this one as the outer gate (allow and deny lists, probes, brute force), laravel-firewall for content checks on the public routes. Do not run two automatic blockings on the same events, or one address gets two bans with two expiries.
Other packages
Checked in November 2026 (stars and last activity on GitHub):
| Package | What it does | Status |
|---|---|---|
| pragmarx/firewall | Allow and deny lists in config or database, CIDR and ranges, countries through GeoIP, attack detection by request rate, artisan commands | About 1,400 stars, no activity since 2023 |
| shieldon/shieldon | Framework-agnostic PHP WAF with a Laravel integration: rate limits, CAPTCHA page, filters, admin panel | About 870 stars, last release 2.1.1 in June 2023 |
| solution-forest/filament-firewall | Allow and deny lists (ranges) in the database, managed from a Filament admin panel | v4 for Filament 5 (February 2026), needs Filament |
| orkhanahmadov/laravel-ip-middleware | Route middleware that allows or refuses a list of addresses | v1.10 (2025), Laravel 8 to 12, PHP 8+ |
| xultech/laravel-ip-whitelist | Allow list middleware, CIDR and wildcards, config or database, artisan commands | Small project (2025), Laravel 6 to 12 |
| spatie/laravel-honeypot | Stops form spam bots (hidden field, timing). Not IP based, works well next to this package | Maintained |
Outside the application, often a better first line on a public site:
- CDN or proxy WAF (Cloudflare, AWS WAF, a hosting provider's firewall): attacks are stopped before they use your PHP workers, with managed rule sets kept up to date.
- Web server rules (Apache
Require ip, nginxallow/deny): cheapest allow list, and the only one that also covers static files (see Security notes). - fail2ban on the server's logs: blocks at the network level, for SSH and other services too.
- Laravel's own rate limiting (
throttlemiddleware,RateLimiter): slows abuse without keeping a list.
Storage format
{
"version": 3,
"ips": [{"ip": "192.0.2.0/28", "label": "Carol", "added_at": "2026-11-14T10:00:00+01:00", "added_by": "203.0.113.10"}],
"hidden": [{"ip": "198.51.100.7", "hidden_at": "2026-11-14T10:05:00+01:00", "hidden_by": "203.0.113.10"}],
"denied": [{"ip": "192.0.2.66", "label": "Auto: 5 attempts in 10 min (last: probe)", "added_at": "2026-11-15T10:00:00+01:00", "added_by": "auto", "expires_at": "2026-11-15T11:00:00+01:00"}]
}
Version 2 files are read as is (no denied entry) and rewritten as version 3 on the next change.
Attempts (attempts.dir), one JSON object per line in YYYY-MM-DD.jsonl:
{"at":"2026-11-15T10:00:00+01:00","ip":"192.0.2.66","type":"probe","detail":"","method":"GET","path":"/wp-login.php","user_agent":"Mozilla/5.0","count":5,"blocked":true}
counters.json in the same folder holds the recent attempt times per address, for the blocking window.
The package still reads files written by the module it was extracted from (version 1, French keys libelle, ajoute_le, retirees…). It rewrites them in this format on the next change.
Tests
php tests/run.php # IP logic, no framework and no Composer needed, any PHP from 5.6
License
MIT
Made with Breizhvibe, a set of vibe-coding skills and tools for web development.