manggala/sentinel (sentinel)

manggala/sentinel (Package Name: sentinel) adalah Web Application Firewall (WAF), Intrusion Detection System (IDS), Brute Force Shield, dan Security Monitoring Dashboard serbaguna untuk aplikasi Laravel.

Package ini memberikan perlindungan real-time otomatis dari ancaman OWASP Top 10 (SQL Injection, Cross-Site Scripting, Path Traversal, Remote Code Execution) dan serangan Brute Force Login pada tingkat HTTP Kernel.

🌟 Mengapa Menggunakan manggala/sentinel?

1. Universal WAF Engine: Beroperasi di tingkat HTTP Kernel Laravel, otomatis melindungi semua stack frontend tanpa perlu mengubah kode controller.
2. OWASP Top 10 Protection: Scanner regex presisi tinggi untuk mencegah SQLi, XSS, Path Traversal (../), dan Remote Execution (eval(), system()).
3. Smart Lockout (Zero Friction): Membedakan pengguna asli yang salah password (Temporary Lockout 60 detik) dari bot peretas (Permanent IP Ban).
4. Multi-Stack Security Dashboard: Tampilan visual monitoring ancaman untuk Blade, Livewire, Inertia React, Inertia Vue, dan REST API.
5. Dukungan 4 Versi Major Laravel: 100% kompatibel dengan Laravel ^10.0 || ^11.0 || ^12.0 || ^13.0 dan PHP ^8.2 || ^8.3 || ^8.4.

📋 Matriks Kompatibilitas Framework & Stack

| Parameter | Dukungan Versi & Framework | |---|---| | Package Name | manggala/sentinel (Folder: sentinel) | | PHP Version | ^8.2 || ^8.3 || ^8.4 | | Laravel Framework (4 Major Versions) | ^10.0 || ^11.0 || ^12.0 || ^13.0 | | Frontend Stack Support | Blade, Livewire (v2/v3), Inertia React, Inertia Vue, REST API | | Testing Engine | Pest PHP (pestphp/pest) | | Static Analysis | PHPStan Level 5+ (larastan/larastan) |

📦 Instalasi

Pasang package menggunakan Composer:

composer require manggala/sentinel

Jalankan perintah instalasi otomatis untuk mempublikasikan file konfigurasi dan migrasi database:

php artisan sentinel:install

Jalankan migrasi database untuk membuat tabel sentinel_logs dan sentinel_blocked_ips:

php artisan migrate

⚙️ Pengaturan Middleware WAF

Untuk Laravel 11, 12, dan 13 (bootstrap/app.php)

Daftarkan SentinelGuardMiddleware di bootstrap/app.php:

use Manggala\Sentinel\Http\Middleware\SentinelGuardMiddleware;
use Manggala\Sentinel\Http\Middleware\SentinelBruteForceMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Daftarkan WAF guard global
        $middleware->append(SentinelGuardMiddleware::class);
        
        // Daftarkan Brute Force guard pada endpoint auth
        $middleware->alias([
            'sentinel.bruteforce' => SentinelBruteForceMiddleware::class,
        ]);
    })
    ->create();

Untuk Laravel 10 (app/Http/Kernel.php)

Tambahkan SentinelGuardMiddleware pada array $middleware di app/Http/Kernel.php:

protected $middleware = [
    // ...
    \Manggala\Sentinel\Http\Middleware\SentinelGuardMiddleware::class,
];

protected $routeMiddleware = [
    // ...
    'sentinel.bruteforce' => \Manggala\Sentinel\Http\Middleware\SentinelBruteForceMiddleware::class,
];

🛡️ Mesin Pemindai Ancaman (Threat Inspection Engine)

manggala/sentinel menggunakan model Anomaly Scoring untuk mengevaluasi setiap request yang masuk:

1. SQL Injection Scanner (SqlInjectionScanner):
   • Mendeteksi perintah berbahaya seperti UNION SELECT, OR 1=1, DROP TABLE, SLEEP(), BENCHMARK().
   • Skor Ancaman: +5 poin.
2. Cross-Site Scripting Scanner (XssScanner):
   • Mendeteksi tag script dan inline event berbahaya seperti <script>, javascript:, onload=, onerror=.
   • Skor Ancaman: +4 poin.
3. Path Traversal Scanner (PathTraversalScanner):
   • Mendeteksi upaya navigasi folder terlarang seperti ../../../../etc/passwd atau ..\..\windows.
   • Skor Ancaman: +5 poin.
4. Command Injection Scanner (CommandInjectionScanner):
   • Mendeteksi perintah eksekusi kode seperti system(), passthru(), exec(), shell_exec(), eval().
   • Skor Ancaman: +5 poin.

Setiap request dengan Total Anomaly Score >= 5 (dapat diubah di config/sentinel.php) akan otomatis diblokir dengan status HTTP 403 Forbidden dan dicatat ke dalam log.

🔒 Proteksi Brute Force & Smart Lockout

Sistem proteksi login manggala/sentinel membedakan kesalahan tak sengaja dari serangan bot:

• 1 - 2 Kali Salah Password: Request berjalan normal tanpa hambatan.
• 3 Kali Salah Password: Otomatis memicu tantangan Captcha (reCAPTCHA / Cloudflare Turnstile).
• 5 Kali Salah Password: Pengguna asli terkena Temporary Lockout selama 60 detik (dapat dikonfigurasi).
• Serangan Bot Masif: Jika IP yang sama terus mencoba puluhan kali, IP tersebut otomatis dimasukkan ke daftar Permanent Ban.

Menerapkan Brute Force Guard pada Route Login

Route::post('/login', [AuthController::class, 'store'])
    ->middleware('sentinel.bruteforce');

🖥️ Security Monitoring Dashboard

manggala/sentinel menyediakan dashboard visual untuk memantau serangan secara real-time.

Akses Dashboard Web

Navigasikan peramban Anda ke:

http://your-app.test/sentinel

Akses REST API Dashboard

GET /api/sentinel/metrics
Authorization: Bearer <your-token>

Response JSON:

{
  "status": "success",
  "data": {
    "total_attacks_prevented": 1420,
    "blocked_ips_count": 18,
    "threat_breakdown": {
      "sqli": 520,
      "xss": 410,
      "lfi": 290,
      "rce": 200
    }
  }
}

⚙️ Opsi Konfigurasi (config/sentinel.php)

return [
    /*
    |--------------------------------------------------------------------------
    | Status Keaktifan WAF
    |--------------------------------------------------------------------------
    */
    'enabled' => env('SENTINEL_ENABLED', true),

    /*
    |--------------------------------------------------------------------------
    | Anomaly Threat Threshold
    |--------------------------------------------------------------------------
    | Request dengan total skor ancaman >= threshold akan otomatis diblokir (403).
    */
    'threshold' => env('SENTINEL_THRESHOLD', 5),

    /*
    |--------------------------------------------------------------------------
    | Proteksi Login & Brute Force
    |--------------------------------------------------------------------------
    */
    'brute_force' => [
        'max_attempts' => 5,
        'decay_seconds' => 60,
        'captcha_after' => 3,
    ],

    /*
    |--------------------------------------------------------------------------
    | IP Whitelist & Blacklist
    |--------------------------------------------------------------------------
    */
    'whitelist_ips' => [
        '127.0.0.1',
        '::1',
    ],

    /*
    |--------------------------------------------------------------------------
    | Route Exclusions (Pengecualian)
    |--------------------------------------------------------------------------
    */
    'excluded_routes' => [
        'admin/page-builder/*',
        'api/webhooks/*',
    ],
];

🛠️ Perintah Artisan (Artisan Commands)

1. Memasang Package

php artisan sentinel:install

2. Membuka Blokir IP (Unban IP)

php artisan sentinel:unban 192.168.1.100

3. Memasukkan IP ke Whitelist

php artisan sentinel:whitelist 10.0.0.1

4. Membersihkan Log Lama

php artisan sentinel:clear-logs --days=30

5. Menampilkan Ringkasan Keamanan

php artisan sentinel:stats

📖 Penggunaan Facade Sentinel

Anda dapat berinteraksi secara programatis menggunakan Facade Sentinel:

use Manggala\Sentinel\Facades\Sentinel;

// Memeriksa apakah IP diblokir
if (Sentinel::isIpBlocked('192.168.1.50')) {
    // IP sedang diblokir
}

// Memblokir IP secara manual
Sentinel::blockIp('192.168.1.50', 'Aktivitas peretasan mencurigakan');

// Membuka blokir IP
Sentinel::unbanIp('192.168.1.50');

// Mendapatkan ringkasan statistik keamanan
$stats = Sentinel::getMetrics();

🔗 Integrasi Manggala Suite

manggala/sentinel terintegrasi secara native dengan package Manggala Suite lainnya:

• ⚡ manggala/laravel-spotlight: Ketik Cmd+K untuk langsung membuka perintah "Open Security Dashboard" atau "Check Blocked IPs".
• 📋 manggala/laravel-datatable: Menggunakan komponen data table reaktif untuk menampilkan log serangan dan daftar IP terblokir di dashboard.
• 🧱 manggala/laravel-dashboard-builder: Menyediakan widget SecurityAlertsWidget untuk dipasang pada canvas dashboard utama.

🧪 Pengujian (Testing)

Jalankan pengujian otomatis menggunakan Pest PHP:

vendor/bin/pest

Jalankan analisis statis menggunakan PHPStan:

vendor/bin/phpstan analyse src --memory-limit=512M

🤝 Kontribusi

Silakan baca CONTRIBUTING.md untuk panduan berkontribusi pada proyek ini.

🔒 Kebijakan Keamanan

Jika Anda menemukan kerentanan keamanan pada package ini, mohon laporkan melalui email ke [email protected] sesuai dengan petunjuk pada SECURITY.md.

📄 Lisensi

Package manggala/sentinel dirilis di bawah Lisensi MIT. Copyright (c) 2026 Ilham Hatta Manggala.