explorin / laravel-guard

v1.7.0 2026-10-20 11:08 UTC

Requires

• php: ^8.1
• illuminate/auth: ^10.0|^11.0|^12.0
• illuminate/cache: ^10.0|^11.0|^12.0
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/events: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• psr/log: ^1.0|^2.0|^3.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

Published on Packagist.org on 2026-10-20 11:08 UTC

README

Application-Level Security Guard, Scoring-Based WAF, and Autonomous Anti-Banned with Vulnerability Dataset Capture.

app-guard adalah package keamanan modular yang menggabungkan kemampuan Network/Perimeter WAF (deteksi bot, brute force, honeypot, scanning/fuzzing) dengan Domain & Business Logic Guard (IDOR, tampering, auto-banned user, dan penutupan celah).

Dibangun dengan prinsip Scoring-based Detection (bukan if-else kaku), berjalan sebelum request mencapai controller (PRE) dan belajar dari respon controller (POST), serta dilengkapi Vulnerability Store (JSONL) untuk mencatat celah yang terekspose sebagai dataset pelatihan Machine Learning masa depan.

⚡ 3-Step Quick Start

1. Instalasi & Konfigurasi

composer require explorin/laravel-guard
php artisan vendor:publish --tag=guard-config

Tip

Minimal Config Pattern (Delta Overrides): Berkas config/guard.php host app hanya perlu memuat opsi yang ingin Anda kustomisasi (misal: profiles, safe_fields, user_ban.attributes). Seluruh konfigurasi default package (detektor honeypot, brute force, bobot rules, dsb) otomatis digabung via mergeConfigRecursive tanpa perlu menduplikasi 400+ baris kode.

2. Konfigurasi .env

GUARD_MODE=enforce
GUARD_CACHE_STORE=redis
GUARD_TELEMETRY_DRIVER=redis
GUARD_USER_BAN_ENABLED=true
GUARD_USER_MODEL=App\Models\User
GUARD_TEBOT_ENABLED=true

3. Gunakan di Controller (Pencegahan IDOR)

use AppGuard\Facades\SecurityGuard;

if ($permohonan->user_id !== auth()->id()) {
    SecurityGuard::recordViolation(auth()->user(), 'idor', 25, "Percobaan akses dokumen orang lain");
    abort(403);
}

(Jika pelanggaran mencapai 100 poin, akun otomatis di-banned c_status = 1, dipaksa logout, dan notifikasi Telegram terkirim).

🎛️ Cookbook Penggunaan Fleksibel

1. Parameter Middleware Per-Route / Group & #[GuardProfile]

use AppGuard\Attributes\GuardProfile;

// Pilih profile preset, batasi detektor, atau ubah ambang skor langsung di route:
Route::middleware('guard:strict')->group(...);
Route::post('/webhook/payment', ...)->middleware('guard:bypass');
Route::post('/search', ...)->middleware('guard:waf,threshold=60,mode=monitor');

// Atau gunakan PHP Attribute pada Controller / Method:
#[GuardProfile('strict', block: 60)]
class CheckoutController extends Controller
{
    #[GuardProfile(mode: 'monitor', detectors: ['honeypot', 'malicious_payload'])]
    public function preview() { ... }
}

2. Monitoring & Operasional CLI via Artisan

AppGuard menyediakan serangkaian perintah CLI lengkap untuk monitoring, pengujian, sinkronisasi, dan manajemen keamanan:

# === Manajemen Ban Terpadu (IP & User) ===
php artisan guard:ban                       # Tabel daftar IP & user yang sedang diban
php artisan guard:ban list --type=ip        # Filter daftar berdasarkan tipe (ip / user)
php artisan guard:ban show 203.0.113.50     # Detail mendalam status & reputasi IP / user
php artisan guard:ban check 203.0.113.50    # Cek cepat (exit code non-zero jika terblokir - cocok untuk CI/Script)
php artisan guard:ban stats                 # Statistik agregat ban aktif & grafik mini proporsi detektor
php artisan guard:ban unban 203.0.113.50    # Buka blokir (interaktif jika subject dikosongkan)
php artisan guard:ban clear --force         # Bersihkan seluruh daftar ban aktif (IP & User) sekaligus
php artisan guard:ban sync                  # Rekonsiliasi indeks ban lokal Redis ↔ Control Plane

# === Diagnostik & Dry-Run Pengujian ===
php artisan guard:doctor                    # Health check konfigurasi, koneksi cache/Redis, dataset, & Control Plane
php artisan guard:test-rule /search --input="q=' union select 1--" # Uji coba payload terhadap detektor (tanpa simpan ke Redis)

# === Manajemen Status & Pemblokiran IP ===
php artisan guard:status {ip?}              # Cek status global sistem atau status spesifik IP
php artisan guard:block {ip} --minutes=60   # Blokir IP manual secara instan
php artisan guard:unblock {ip}              # Hapus blokir IP manual & reset reputasi

# === Manajemen Pemblokiran User (Akun) ===
php artisan guard:user-status {userId}      # Cek status ban, skor reputasi, & kolom status database user
php artisan guard:ban-user {userId} --reason="Aktivitas mencurigakan" # Blokir akun user di cache & database
php artisan guard:unban-user {userId} --sync-db # Buka blokir user di cache & pulihkan status di database

# === Sinkronisasi & Integrasi Control Plane ===
php artisan guard:sync                      # Tarik aturan dinamis, honeypots baru, & remote policy
php artisan guard:ship-telemetry            # Kirim batch rekaman insiden (jsonl/redis/cache) ke Control Plane
php artisan guard:heartbeat                 # Kirim sinyal heartbeat status kesehatan sensor ke Control Plane

# === Audit, Diff & Sinkronisasi Konfigurasi ===
php artisan guard:config                    # Audit status konfigurasi host vs default package
php artisan guard:config --diff             # Perbandingan detail (diff) nilai kustom host vs package default
php artisan guard:config --snippet=ip_ban   # Potongan kode konfigurasi asli siap salin
php artisan guard:config --sync --key=<key> # Sisipkan opsi baru ke config/guard.php secara aman (auto-backup)

3. Event Hook, Custom Responder, & Resolver

use AppGuard\Facades\SecurityGuard;

SecurityGuard::onBan(fn ($ban) => logger()->warning("Banned {$ban->id()}"));
SecurityGuard::onBanLifted(fn ($type, $subject, $by) => logger()->info("Unbanned {$type}:{$subject} by {$by}"));
SecurityGuard::respondUsing(fn ($request, $decision) => response()->json(['blocked' => true], 403));
SecurityGuard::resolveTenantUsing(fn ($request) => $request->header('X-Tenant-Id'));

📚 Indeks Dokumentasi Lengkap

Untuk panduan mendalam dan spesifikasi teknis, silakan merujuk pada dokumen berikut:

Dokumen	Deskripsi
🏛️ ARCHITECTURE.md	Desain arsitektur internal, POPO Core vs Laravel Adapter, dan siklus hidup request (PRE & POST).
📋 docs/06-incident-dataset.md	Pencatatan insiden/celah (vulnerabilities.jsonl), inspeksi forensik, dan roadmap analisis data.
⚙️ docs/01-installation-config.md	Panduan instalasi detail, opsi environment .env, dan penjelasan file konfigurasi.
🛡️ docs/02-detectors-scoring.md	Penjelasan 7 detektor bawaan, formula scoring, dan tutorial membuat custom detector.
👤 docs/03-business-guard-auto-banned.md	Mitigasi IDOR di controller, mutasi status database, event UserBanned, dan force logout.
📢 docs/04-tebot-alerts.md	Integrasi notifikasi darurat Telegram via package Tebot dengan failsafe logger.
💻 docs/05-artisan-cli.md	Panduan perintah Artisan (guard:status, guard:block, guard:unblock).

🧪 Uji Coba Mandiri (Smoke Test)

Package ini menyediakan script smoke test mandiri yang dapat dijalankan tanpa dependensi database/framework:

php tests/smoke.php

(Seluruh 104 checks pengujian lolos 100%).

📄 Lisensi

Open-source di bawah lisensi MIT.