PHPackages                             therealmkadmi/laravel-citadel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. therealmkadmi/laravel-citadel

ActiveLibrary[Logging & Monitoring](/categories/logging)

therealmkadmi/laravel-citadel
=============================

A passive survaillance and firewall package for laravel to protect your public facing endpoints.

v0.1(1y ago)1218MITPHPPHP ^8.4CI failing

Since Mar 13Pushed 11mo ago1 watchersCompare

[ Source](https://github.com/TheRealMkadmi/laravel-citadel)[ Packagist](https://packagist.org/packages/therealmkadmi/laravel-citadel)[ Docs](https://github.com/therealmkadmi/laravel-citadel)[ GitHub Sponsors](https://github.com/TheRealMkadmi)[ RSS](/packages/therealmkadmi-laravel-citadel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (13)Versions (2)Used By (0)

Laravel Citadel Documentation
=============================

[](#laravel-citadel-documentation)

Introduction
------------

[](#introduction)

Laravel Citadel is a passive surveillance package designed to protect your public-facing endpoints. It provides a robust firewall system that analyzes incoming requests, detects anomalies, and blocks malicious traffic. The package is highly configurable and integrates seamlessly with Laravel applications.

---

Installation
------------

[](#installation)

1. Install the package via Composer:

```
composer require therealmkadmi/laravel-citadel
```

2. Publish the configuration file:

```
php artisan vendor:publish --provider="TheRealMkadmi\\Citadel\\CitadelServiceProvider"
```

3. Add the middleware to your routes or global middleware stack as needed.

---

Configuration
-------------

[](#configuration)

The configuration file is located at `config/citadel.php`. Below are the available settings:

### General Settings

[](#general-settings)

- **version**: Current version of Laravel Citadel.

### Geofencing Settings

[](#geofencing-settings)

- **enabled**: Enable or disable geofencing.
- **mode**: `allow` (whitelist) or `block` (blacklist).
- **countries**: Comma-separated ISO-3166-1 alpha-2 country codes.

### Device Analyzer Settings

[](#device-analyzer-settings)

- **smartphone\_score**: Score for smartphone devices.
- **tablet\_score**: Score for tablet devices.
- **desktop\_score**: Score for desktop devices.
- **bot\_score**: Score for bots or automated tools.

### IP Analyzer Settings

[](#ip-analyzer-settings)

- **weights**: Weights for different IP characteristics (e.g., `bogon`, `datacenter`, `tor`, etc.).

### Burstiness Analyzer Settings

[](#burstiness-analyzer-settings)

- **min\_interval**: Minimum interval between requests (in milliseconds).
- **window\_size**: Sliding window size (in milliseconds).
- **max\_requests\_per\_window**: Maximum requests allowed in the window.

### Payload Analyzer Settings

[](#payload-analyzer-settings)

- **required\_fields**: Fields required in the payload.
- **max\_size**: Maximum payload size (in bytes).
- **max\_params**: Maximum number of parameters allowed.
- **suspicious\_patterns**: Patterns to detect malicious payloads.

### Spamminess Analyzer Settings

[](#spamminess-analyzer-settings)

- **weights**: Weights for spam-related anomalies (e.g., gibberish text, repetitive content).

### Ban Settings

[](#ban-settings)

- **ban\_ttl**: Default time-to-live for bans (in seconds).
- **cache\_key**: Key prefix for storing banned IPs or fingerprints.
- **message**: Message displayed to banned users.

### API Settings

[](#api-settings)

- **enabled**: Enable or disable API endpoints.
- **token**: Secret token for API authentication.
- **prefix**: Prefix for API routes.

---

Middleware Groups
-----------------

[](#middleware-groups)

Laravel Citadel provides three middleware groups that you can use in your application:

### 1. Passive Monitoring Only (`citadel-passive`)

[](#1-passive-monitoring-only-citadel-passive)

The passive middleware group only runs analyzers that don't make external requests. It provides monitoring and logging without blocking any requests, ideal for gathering intelligence about traffic patterns.

```
Route::middleware(['citadel-passive'])->group(function () {
    // These routes will be monitored but never blocked
    Route::get('/public-content', 'ContentController@index');
});
```

### 2. Active Protection (`citadel-active`)

[](#2-active-protection-citadel-active)

The active middleware group runs analyzers that may make external requests (such as IP intelligence lookups) and will block malicious traffic. This includes geofencing and ban checking.

```
Route::middleware(['citadel-active'])->group(function () {
    // These routes get full protection with external API calls
    Route::post('/login', 'AuthController@login');
    Route::post('/register', 'AuthController@register');
});
```

### 3. Complete Protection (`citadel-protect`)

[](#3-complete-protection-citadel-protect)

For maximum security, the complete protection middleware group combines both active and passive analyzers. This is the original middleware group and provides backward compatibility.

```
Route::middleware(['citadel-protect'])->group(function () {
    // These routes get complete protection with all analyzers
    Route::post('/checkout', 'PaymentController@processPayment');
});
```

### Configuration

[](#configuration-1)

You can enable or disable each middleware group independently in your configuration:

```
// In config/citadel.php
'middleware' => [
    'enabled' => env('CITADEL_ENABLED', true),             // Global on/off switch
    'passive_enabled' => env('CITADEL_PASSIVE_ENABLED', true), // Enable passive monitoring
    'active_enabled' => env('CITADEL_ACTIVE_ENABLED', true),   // Enable active protection
],
```

This configuration also applies to your `.env` file:

```
CITADEL_ENABLED=true
CITADEL_PASSIVE_ENABLED=true
CITADEL_ACTIVE_ENABLED=true

```

---

Middleware
----------

[](#middleware)

### ProtectRouteMiddleware

[](#protectroutemiddleware)

Analyzes incoming requests using registered analyzers and blocks requests exceeding the configured threshold.

### ApiAuthMiddleware

[](#apiauthmiddleware)

Authenticates API requests using a token.

### GeofenceMiddleware

[](#geofencemiddleware)

Blocks requests based on geographical location.

### BanMiddleware

[](#banmiddleware)

Checks if a request originates from a banned IP or fingerprint.

---

Analyzers
---------

[](#analyzers)

### BurstinessAnalyzer

[](#burstinessanalyzer)

Detects rapid consecutive requests and suspicious patterns in request timing.

### DeviceAnalyzer

[](#deviceanalyzer)

Analyzes the User-Agent header to determine the type of device making the request.

### IpAnalyzer

[](#ipanalyzer)

Analyzes the IP address for characteristics like being a datacenter, Tor exit node, or VPN.

### PayloadAnalyzer

[](#payloadanalyzer)

Analyzes the request payload for anomalies, missing fields, and malicious patterns.

### SpamminessAnalyzer

[](#spamminessanalyzer)

Detects spam-like behavior in request payloads.

---

API Endpoints
-------------

[](#api-endpoints)

### Ban Endpoint

[](#ban-endpoint)

**POST** `/api/citadel/ban`

**Parameters:**

- `identifier` (string, required): The IP or fingerprint to ban.
- `type` (string, required): `ip` or `fingerprint`.
- `duration` (integer, optional): Duration of the ban in minutes.

**Response:**

- `success` (boolean): Whether the operation was successful.
- `message` (string): Description of the result.

### Unban Endpoint

[](#unban-endpoint)

**POST** `/api/citadel/unban`

**Parameters:**

- `identifier` (string, required): The IP or fingerprint to unban.
- `type` (string, required): `ip` or `fingerprint`.

**Response:**

- `success` (boolean): Whether the operation was successful.
- `message` (string): Description of the result.

### Status Endpoint

[](#status-endpoint)

**GET** `/api/citadel/status`

**Response:**

- `status` (string): `ok` if the API is accessible.
- `version` (string): Current version of the package.
- `timestamp` (string): Current server timestamp.

---

Commands
--------

[](#commands)

### CitadelBanCommand

[](#citadelbancommand)

Bans a user by IP or fingerprint from the command line.

**Usage:**

```
php artisan citadel:ban {identifier} --type={ip|fingerprint|auto} --duration={minutes}
```

### CitadelUnbanCommand

[](#citadelunbancommand)

Unbans a user by IP or fingerprint from the command line.

**Usage:**

```
php artisan citadel:unban {identifier} --type={ip|fingerprint|auto}
```

### CitadelCommand

[](#citadelcommand)

Displays general information about the Citadel package.

**Usage:**

```
php artisan laravel-citadel
```

---

Usage Examples
--------------

[](#usage-examples)

### Protecting Routes

[](#protecting-routes)

Add the `citadel-protect` middleware group to your routes:

```
Route::middleware(['citadel-protect'])->group(function () {
    Route::get('/protected', function () {
        return 'This route is protected by Citadel.';
    });
});
```

### Using the API

[](#using-the-api)

Enable the API in the configuration file and set a token:

```
'api' => [
    'enabled' => true,
    'token' => env('CITADEL_API_TOKEN', 'your-secret-token'),
    'prefix' => 'api/citadel',
],
```

Make a request to ban an IP:

```
curl -X POST \
     -H "Authorization: Bearer your-secret-token" \
     -d "identifier=192.168.1.1&type=ip&duration=60" \
     http://your-app.test/api/citadel/ban
```

### Customizing Analyzers

[](#customizing-analyzers)

You can create custom analyzers by implementing the `IRequestAnalyzer` interface and registering them in the service provider.

---

Logging
-------

[](#logging)

Citadel logs various events, such as bans, unbans, and detected threats. You can configure the log channel in the `citadel.php` configuration file.

---

Testing
-------

[](#testing)

Run the test suite using PHPUnit:

```
vendor/bin/phpunit
```

---

Contributing
------------

[](#contributing)

Contributions are welcome! Please follow the Laravel coding standards and submit a pull request.

---

License
-------

[](#license)

Laravel Citadel is open-sourced software licensed under the [MIT license](LICENSE.md).

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance49

Moderate activity, may be stable

Popularity13

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

425d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7e0b854207595b839fb721c8a699ccc7d4932aa897ae4366ee63d4cd54f99a8a?d=identicon)[TheRealMkadmi](/maintainers/TheRealMkadmi)

---

Top Contributors

[![TheRealMkadmi](https://avatars.githubusercontent.com/u/33043525?v=4)](https://github.com/TheRealMkadmi "TheRealMkadmi (145 commits)")

---

Tags

laravelmonitoringsecurityspamfirewallprotectionattackmalicioussurveillanceTheRealMkadmilaravel-citadelmalicious-trafficmalicious-requestsmalicious-activity

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/therealmkadmi-laravel-citadel/health.svg)

```
[![Health](https://phpackages.com/badges/therealmkadmi-laravel-citadel/health.svg)](https://phpackages.com/packages/therealmkadmi-laravel-citadel)
```

###  Alternatives

[spatie/laravel-health

Monitor the health of a Laravel application

85810.0M83](/packages/spatie-laravel-health)[spatie/laravel-slack-alerts

Send a message to Slack

3212.6M4](/packages/spatie-laravel-slack-alerts)[inspector-apm/inspector-laravel

Code Execution Monitoring, built for developers.

2332.0M2](/packages/inspector-apm-inspector-laravel)[spatie/laravel-error-share

Share your Laravel errors to Flare

43965.6k3](/packages/spatie-laravel-error-share)[muhammadsadeeq/laravel-activitylog-ui

A beautiful, modern UI for Spatie's Activity Log with advanced filtering, analytics, and real-time features.

17510.1k](/packages/muhammadsadeeq-laravel-activitylog-ui)[tapp/filament-maillog

Filament plugin to view outgoing mail

2952.6k1](/packages/tapp-filament-maillog)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)