PHPackages bale/gupa - 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. [Security](/categories/security) 4. / 5. bale/gupa ActiveLibrary[Security](/categories/security) bale/gupa ========= Guardian — IP protection, rate limiting, and bot detection for Bale landing pages v0.1.8(3w ago)060↓75%MITPHPPHP ^8.3 Since Jul 17Pushed 3w agoCompare [ Source](https://github.com/papa-ree/gupa)[ Packagist](https://packagist.org/packages/bale/gupa)[ Docs](https://github.com/bale/gupa)[ RSS](/packages/bale-gupa/feed)WikiDiscussions master Synced 1w ago READMEChangelog (8)Dependencies (7)Versions (10)Used By (0) Gupa ==== [](#gupa) > Perlindungan IP, rate limiting, dan deteksi bot untuk aplikasi Laravel. Gupa (dari Sansekerta *gup* — melindungi) adalah lapisan keamanan komprehensif yang secara otomatis memberi skor pada setiap request, memblokir aktor jahat, dan menyediakan visibilitas real-time terhadap ancaman di aplikasi Anda. Bagian dari ekosistem [Bale](https://github.com/bale). Dapat digunakan di proyek Laravel 11/12/13 mana pun. Fitur ----- [](#fitur) - **Mesin Skor Perilaku** — Sistem multi-detektor yang mengevaluasi setiap request secara real-time - **5 Detektor Bawaan** — Velocity, honeypot, header HTTP, serangan 404, rate limiting - **Pemblokiran Otomatis** — Blocking IP sementara atau permanen dengan threshold yang dapat dikonfigurasi - **Dual Storage** — Mode cache-only (Redis/file) atau persistent (database) - **Dukungan CIDR & Wildcard** — Whitelist/blacklist seluruh subnet atau range IP - **Blacklist/Whitelist Dinamis** — Tambah atau hapus IP saat runtime melalui Artisan - **Logging Path Mencurigakan** — Mencatat detail request saat skor mencapai threshold suspicious - **Notifikasi** — Alert webhook dan email saat IP diblokir - **Dashboard & CLI** — Pantau, query, dan kelola semuanya dari command line Persyaratan ----------- [](#persyaratan) - PHP ^8.3 - Laravel 11, 12, atau 13 Instalasi --------- [](#instalasi) ``` composer require bale/gupa php artisan gupa:setup ``` Wizard setup akan memandu Anda dalam pemilihan mode: ModeYang dilakukan**Auto** (default)Publish config dan env vars. Storage cache-only.**Advance**Auto + migrasi database + persistent storage.Mulai Cepat ----------- [](#mulai-cepat) Daftarkan middleware di `bootstrap/app.php`: ``` ->withMiddleware(function (Middleware $middleware) { $middleware->prepend(\Bale\Gupa\Middleware\GuardianMiddleware::class); }) ``` Aktifkan di `.env`: ``` GUPA_ENABLED=true ``` Setiap request sekarang terlindungi secara otomatis. Cara Kerja ---------- [](#cara-kerja) ``` Request → GuardianMiddleware → ScoreCalculator → Detectors → Skor │ ┌─────────────────┤ │ │ skor < threshold skor >= threshold │ │ PASS Block IP (403) ``` Setiap detektor secara independen mengevaluasi request dan memberikan kontribusi skor. Ketika total skor mencapai threshold, IP diblokir. ### Detektor [](#detektor) DetektorApa yang ditangkapSkor Default**Velocity**Request rate berlebihan30**Honeypot**Field jebakan bot dan rute tersembunyi50**Header**Header browser standar hilang, bot yang dikenal20**NotFound**Pencarian 404 berulang15 per hit**RateLimit**Request melebihi batas rate25Konfigurasi ----------- [](#konfigurasi) Semua pengaturan ada di `config/gupa.php` dan dapat di-override melalui `.env` atau environment variable: > **Docker / production container**: `env_file: .env` di docker-compose hanya meng-inject variabel ke environment container, **tidak** menyalin file `.env` ke dalam image. Nilai tetap terbaca oleh Laravel (sebagai env var). `gupa:about` membedakan sumber `dari environment` (env var container) vs `dari .env`(file fisik). ``` # Inti GUPA_ENABLED=true GUPA_THRESHOLD=100 # Total skor untuk trigger block GUPA_SCORE_DECAY_WINDOW=300 # Detik sebelum skor auto-reset (5 menit) GUPA_BLOCK_DURATION=3600 # Detik durasi block sementara (1 jam) GUPA_LOG_ENABLED=true GUPA_STORAGE=cache # "cache" atau "database" GUPA_SUSPICIOUS_THRESHOLD=10 # Log request saat skor mencapai ini (database mode) GUPA_LOG_RETENTION_DAYS=30 # Auto-prune log lebih lama dari ini (database mode) # Scoring (anti false-positive) GUPA_SCORING_SKIP_ASSETS=true # Lewati scoring untuk aset statis (CSS/JS/gambar/font) GUPA_SCORING_ASSET_EXTENSIONS=css,js,mjs,map,png,jpg,jpeg,gif,svg,webp,avif,ico,woff,woff2,ttf,otf,eot,txt,xml # Recidivist (permanent block setelah N block dalam M hari) GUPA_RECIDIVIST_DAYS=1 # Jendela waktu dalam hari GUPA_RECIDIVIST_THRESHOLD=3 # Jumlah block maks sebelum permanent # Whitelist & Blacklist GUPA_WHITELIST_ENABLED=true # Aktifkan whitelist (config + dinamis) GUPA_BLACKLIST_ENABLED=false # Aktifkan blacklist # Detector: Velocity GUPA_VELOCITY_ENABLED=true GUPA_VELOCITY_MAX_REQUESTS=60 # Maksimal request per window GUPA_VELOCITY_WINDOW=60 # Window dalam detik GUPA_VELOCITY_SCORE=15 # Detector: Honeypot GUPA_HONEYPOT_ENABLED=true GUPA_HONEYPOT_FIELD=website_url # Nama field jebakan GUPA_HONEYPOT_SCORE=50 # Detector: Header GUPA_HEADER_ENABLED=true GUPA_HEADER_BOT_UA_SCORE=20 # Skor untuk user-agent bot GUPA_HEADER_MISSING_ACCEPT_SCORE=10 GUPA_HEADER_MISSING_ACCEPT_LANG_SCORE=10 GUPA_HEADER_MISSING_REFERER_POST_SCORE=5 # Detector: NotFound GUPA_NOTFOUND_ENABLED=true GUPA_NOTFOUND_MAX_404S=10 # Maksimal 404 per window GUPA_NOTFOUND_WINDOW=60 # Window dalam detik GUPA_NOTFOUND_SCORE=20 # Detector: Rate Limit GUPA_RATE_LIMIT_DETECTOR_ENABLED=true # Rate Limits GUPA_RATE_LIMITS_ENABLED=false GUPA_RATE_LIMIT_MAX_ATTEMPTS=60 # Maksimal request per window GUPA_RATE_LIMIT_DECAY_SECONDS=60 GUPA_RATE_LIMIT_SCORE=10 # Notifikasi GUPA_NOTIFICATIONS_ENABLED=false GUPA_WEBHOOK_ENABLED=false GUPA_WEBHOOK_URL= GUPA_WEBHOOK_SECRET= GUPA_EMAIL_ENABLED=false GUPA_EMAIL_TO= GUPA_EMAIL_FROM= ``` Mode Storage ------------ [](#mode-storage) ModeBackendKelebihanKekurangan**cache**Redis / fileTanpa beban DB, cepatHilang saat cache flush**database**SQLite / MySQL / PostgreSQLPersistent, dapat di-querySedikit beban DBWhitelist & Blacklist ------------------------- [](#whitelist--blacklist) List statis melalui config: ``` // config/gupa.php 'whitelist' => [ 'enabled' => true, 'ips' => ['127.0.0.1', '::1', '10.0.0.0/8'], ], 'blacklist' => [ 'enabled' => true, 'ips' => ['192.168.1.*'], ], ``` List dinamis melalui Artisan: ``` # Blacklist — langsung blokir (whitelist otomatis dihapus jika ada) php artisan gupa:blacklist --add=1.2.3.4 php artisan gupa:blacklist --add=10.0.0.0/8 php artisan gupa:blacklist --remove=1.2.3.4 php artisan gupa:blacklist --list # Whitelist — lewati semua deteksi (blacklist otomatis dihapus jika ada) php artisan gupa:whitelist --add=10.0.0.1 php artisan gupa:whitelist --remove=10.0.0.1 php artisan gupa:whitelist --list ``` > Menambah ke blacklist otomatis menghapus dari whitelist, dan sebaliknya. Perintah Artisan ---------------- [](#perintah-artisan) ``` # Monitoring php artisan gupa:about # Ringkasan konfigurasi (nilai + sumber .env/environment/default config) php artisan gupa:dashboard # Ikhtisar real-time php artisan gupa:dashboard --json # Output JSON php artisan gupa:stats # Ringkasan konfigurasi # Manajemen IP php artisan gupa:unblock 192.168.1.100 # Buka blokir IP sementara php artisan gupa:clear-score 192.168.1.100 # Reset skor tanpa unblock # Whitelist & Blacklist php artisan gupa:whitelist --add=10.0.0.1 php artisan gupa:whitelist --remove=10.0.0.1 php artisan gupa:whitelist --list php artisan gupa:blacklist --add=1.2.3.4 php artisan gupa:blacklist --remove=1.2.3.4 php artisan gupa:blacklist --list # Logging (database mode) php artisan gupa:log # Log terbaru php artisan gupa:log --ip=1.2.3.4 # Filter berdasarkan IP php artisan gupa:log --status=404 # Filter berdasarkan status code php artisan gupa:log --event=block # Filter berdasarkan tipe event php artisan gupa:log --days=7 # 7 hari terakhir php artisan gupa:log --prune # Hapus log lama php artisan gupa:log --json # Output JSON ``` Honeypot -------- [](#honeypot) Gupa mendeteksi bot melalui 3 cara: field tersembunyi, exact route match, dan prefix path. ### Field Tersembunyi [](#field-tersembunyi) Sembunyikan field jebakan di form Anda: ``` {{-- Custom field name --}} ``` Bot yang mengisi field tersembunyi akan mendapat skor 50. ### Routes (Exact Match) [](#routes-exact-match) Salah satu segment path harus sama persis. Cocok untuk halaman admin atau endpoint yang jarang diakses user normal. ``` // config/gupa.php 'honeypot' => [ 'routes' => ['wp-login.php', 'xmlrpc.php'], ], ``` RequestTerdeteksi?Alasan`/wp-login.php`✓segment `wp-login.php` match`/2023/wp-login.php`✓segment `wp-login.php` match`/sub/wp-login.php/x`✓segment `wp-login.php` match`/wp-login`✗`wp-login` ≠ `wp-login.php``/login`✗tidak ada segment yang match### Prefixes (Awalan Segment) [](#prefixes-awalan-segment) Salah satu segment path harus diawali string tertentu. Cocok untuk memblokir seluruh grup path. ``` // config/gupa.php 'honeypot' => [ 'prefixes' => ['wp-', 'wpv-'], ], ``` RequestTerdeteksi?Alasan`/wp-admin.php`✓segment `wp-admin.php` diawali `wp-``/2023/wp-login.php`✓segment `wp-login.php` diawali `wp-``/wp-content/uploads/x`✓segment `wp-content` diawali `wp-``/wpv-view/123`✓segment `wpv-view` diawali `wpv-``/admin`✗tidak ada segment yang diawali `wp-``/login`✗tidak ada segment yang diawali `wp-`### Gabungan Routes + Prefixes [](#gabungan-routes--prefixes) Keduanya dicek secara bersamaan, skor tetap sama. ``` 'honeypot' => [ 'routes' => ['xmlrpc.php', 'wp-login.php'], 'prefixes' => ['wp-', 'wpv-'], 'score' => 50, ], ``` Semua request ke path yang match akan mendapat skor 50, apakah dari `routes` maupun `prefixes`. Coba Sendiri ------------ [](#coba-sendiri) ### 1. Cek status [](#1-cek-status) ``` php artisan gupa:dashboard ``` ### 2. Simulasi bot [](#2-simulasi-bot) ``` # Request normal — lolos curl -I https://yourdomain.com # User agent bot — kena skor curl -I -A "python-requests/2.28" https://yourdomain.com # Header standar hilang — kena skor curl -I -H "Accept:" -H "Accept-Language:" https://yourdomain.com ``` ### 3. Cek skor naik [](#3-cek-skor-naik) ``` php artisan gupa:dashboard --json ``` ### 4. Force block diri sendiri (untuk testing) [](#4-force-block-diri-sendiri-untuk-testing) ``` php artisan gupa:blacklist --add=IP_ANDA # Buka browser → 403 Forbidden php artisan gupa:blacklist --remove=IP_ANDA # Akses pulih ``` ### 5. Cek log [](#5-cek-log) ``` tail -f storage/logs/laravel.log | grep Gupa ``` Arsitektur ---------- [](#arsitektur) ``` packages/bale-gupa/ ├── config/gupa.php # Semua konfigurasi ├── database/migrations/ # 4 migrasi (database mode) ├── resources/views/ # Komponen Blade honeypot ├── src/ │ ├── Actions/ # BlockAction, LogAction, NotifyAction │ ├── Commands/ # 8 perintah Artisan │ ├── Detectors/ # 5 detektor (Velocity, Honeypot, Header, NotFound, RateLimit) │ ├── Middleware/ # GuardianMiddleware (entry point) │ ├── Models/ # BlockedIp, Log, Whitelist, Blacklist │ ├── Notifications/ # Channel Webhook & Email │ ├── Scorer/ # ScoreCalculator (orchestrator) │ └── Support/ # WhitelistChecker └── tests/ # 125 tes (Pest) ``` Pengujian --------- [](#pengujian) ``` cd packages/bale-gupa composer test ``` Lisensi ------- [](#lisensi) MIT ### Health Score 41 — FairBetter than 87% of packages Maintenance95 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 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 Every ~2 days Total 9 Last Release 24d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/6a4dff95fb8ef6beb3956487f0421a9229b3ded20f76917e49a1e7c2004267e4?d=identicon)[papa-ree](/maintainers/papa-ree) --- Top Contributors [![papa-ree](https://avatars.githubusercontent.com/u/79291092?v=4)](https://github.com/papa-ree "papa-ree (22 commits)") --- Tags laravelsecuritybot-detectionguardianBale ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/bale-gupa/health.svg) ``` [![Health](https://phpackages.com/badges/bale-gupa/health.svg)](https://phpackages.com/packages/bale-gupa) ``` ### Alternatives [spatie/laravel-permission Permission handling for Laravel 12 and up 13.0k113.1M1.7k](/packages/spatie-laravel-permission)[psalm/plugin-laravel Psalm plugin for Laravel 3365.5M359](/packages/psalm-plugin-laravel)[laravel/horizon Dashboard and code-driven configuration for Laravel queues. 4.2k104.7M369](/packages/laravel-horizon)[illuminate/database The Illuminate Database package. 3.0k56.7M13.6k](/packages/illuminate-database)[laravel/ai The official AI SDK for Laravel. 1.1k6.4M360](/packages/laravel-ai)[illuminate/encryption The Illuminate Encryption package. 9631.4M374](/packages/illuminate-encryption) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)