CodeIgniter 4 Shield

Firewall aplikasi untuk CodeIgniter 4 — memeriksa setiap permintaan yang masuk dan memblokir yang berbahaya sebelum sampai ke aplikasi Anda.

Setiap aplikasi web punya dua pintu masuk. Satu untuk orang yang memang memakai aplikasi Anda, dan satu lagi yang terbuka untuk siapa saja di internet. Pintu kedua itulah yang berbahaya — setiap permintaan datang dari mana saja, dan ada orang yang sengaja membuatnya berbahaya.

CodeIgniter 4 Shield menjadi penjaga pintu kedua tersebut. Dia memeriksa setiap permintaan, lalu:

• Meneruskan permintaan biasa, seperti tidak ada apa-apa. Pengunjung asli tidak pernah terganggu.
• Meminta bukti ketika pola perilaku mencurigakan tapi belum tentu berbahaya — misalnya dengan captcha.
• Memblokir permintaan yang jelas merupakan serangan, dan mencatat semua kejadiannya ke database.

Bagian pentingnya: Shield bukan pengganti sistem keamanan Anda sendiri. Filter SQL, validasi input, Filter Auth, dan proteksi CSRF tetap milik Anda. Shield hanya menambahkan satu lapisan lagi di depannya.

Cloudflare / Edge WAF  ->  WAF hosting / ModSecurity  ->  CI4 Shield  ->  Aplikasi Anda

Shield sebaiknya berada di belakang firewall yang lebih umum, bukan sebagai pengganti. Kalau hosting Anda sudah punya ModSecurity, keduanya saling melengkapi.

• Percobaan membuka file rahasia. Bot pemindai mencari .env, .git/config, wp-config.php, dan kredensial AWS untuk membocorkan password dan API key.
• Path traversal. Termasuk varian yang di-encode tiga kali seperti %252e%252e/, plus /proc/self/environ dan /etc/passwd.
• Percobaan remote code execution. Termasuk php://input, auto_prepend_file, file backup, dan file PHP yang disembunyikan di folder gambar atau upload.
• SQL injection, XSS, LFI, dan command injection — bukan hanya di alamat URL, tapi juga di isi request.
• Bot yang mengaku-ngaku. Bot resmi seperti Googlebot dan Bingbot dikenali lewat pemeriksaan DNS, jadi website Anda tetap bisa dibaca mesin pencari. Bot palsu yang hanya mengaku-ngaku dicatat dan diblokir.
• Pengepungan endpoint login. Terlalu banyak percobaan login dari satu alamat IP akan memicu challenge, sehingga brute-force tidak berhasil.
• Penelusuran file. Deretan permintaan yang berakhir 404 di seluruh situs, plus aktivitas otomatis dengan User-Agent mencurigakan seperti sqlmap atau nikto.

composer require ganadev/codeigniter4-shield

Package ini menarik ganadev/shield-core secara otomatis, jadi tidak perlu memasangnya terpisah.

Konfigurasi bawaan sudah cukup untuk memulai. Kalau ingin menyesuaikan, buat app/Config/Shield.php yang extends Ganadev\Shield\Codeigniter\Config\Shield, lalu ubah propertinya di sana.

Buka app/Config/Events.php dan daftarkan provider pada event pre_system:

Events::on('pre_system', static function (): void {
    \Ganadev\Shield\Codeigniter\ShieldServiceProvider::register();
});

Satu baris ini mendaftarkan service Shield (engine, resolver, cache, challenge driver), filter firewall global, dan perintah CLI sekaligus. Panggilan berulang aman — provider membangun ulang service dari konfigurasi terkini.

Tanpa baris ini Shield tetap berjalan dengan fallback internal, tapi filter firewall tidak otomatis terpasang dan perintah php spark shield:* tidak terdaftar.

php spark migrate --all

Kalau Anda memakai ShieldServiceProvider::register() seperti di atas, filter firewall sudah otomatis terdaftar global — tidak perlu melakukan apa pun lagi.

Kalau memasang manual tanpa provider, buka app/Config/Filters.php, lalu daftarkan filter Shield secara global — posisinya menentukan segalanya:

public $aliases = [
    'shield.firewall' => \Ganadev\Shield\Codeigniter\Filters\SecurityFirewallFilter::class,
];

public $globals = [
    'before' => [
        'shield.firewall',
    ],
];

Filter ini harus berjalan sebelum filter lain, setelah IP klien asli dibaca. Shield akan memberi tahu lewat log kalau posisinya bergeser.

Kalau hanya ingin melindungi sebagian route, daftarkan sebagai filter bernama lalu pakai di route yang diperlukan.

Dua hal ini paling sering terlewat, dan keduanya membuat Shield tidak bekerja seperti yang Anda kira.

Kalau aplikasi Anda berada di belakang Cloudflare, reverse proxy, atau load balancer, dan proxyIPs belum dikonfigurasi, maka setiap pengunjung akan terlihat datang dari satu alamat IP yang sama — yaitu IP proxy. Akibatnya rate limit per-IP jadi tidak berguna, dan ban tidak pernah kena pada orang yang seharusnya.

Di app/Config/App.php:

public $proxyIPs = [
    // Cloudflare IPv4
    '173.245.48.0/20', '103.21.244.0/22', '103.22.200.0/22', '103.31.4.0/22',
    '141.101.64.0/18', '108.162.192.0/18', '190.93.240.0/20', '188.114.96.0/20',
    '197.234.240.0/22', '198.41.128.0/17', '162.158.0.0/15', '104.16.0.0/13',
    '104.24.0.0/14', '172.64.0.0/13', '131.0.72.0/22',
    // Cloudflare IPv6
    '2400:cb00::/32', '2606:4700::/32', '2803:f800::/32', '2405:b500::/32',
    '2405:8100::/32', '2a06:98c0::/29', '2c0f:f248::/32',
];

Jangan pernah pakai proxyIPs = '*' atau ['*']. Bentuk itu mempercayai semua orang, sehingga penyerang bisa memalsukan alamat IP pada header dan lolos dari ban.

Kalau Anda tidak memakai Cloudflare, ganti dengan CIDR proxy Anda sendiri. Daftar resmi Cloudflare ada di https://www.cloudflare.com/ips/.

Cek apakah konfigurasi ini sudah benar:

php spark shield:health

Supaya tidak mengagetkan siapa pun saat pertama dipasang, Shield mulai dalam mode observe: keputusan tetap dihitung dan dicatat, tapi request diteruskan seperti biasa. Jadi secara bawaan, Shield belum memblokir apa pun.

Agar blokir benar-benar dijalankan, atur:

SHIELD_MODE=enforce

Cara paling aman adalah naikkan bertahap. Biarkan di observe beberapa hari, pantau php spark shield:report untuk melihat apa yang sebenarnya terjadi, lalu naikkan ke enforce saat sudah yakin tidak ada pengguna sah yang ikut kena.

Semua opsi ada di satu file: app/Config/Shield.php, dan setiap propertinya sudah diberi komentar penjelasan dalam bahasa Indonesia. Mulai dari situ — tidak perlu mengatur semuanya di awal.

Beberapa yang paling sering diubah:

SHIELD_ENABLED=true
SHIELD_MODE=observe
SHIELD_APP_ID=my-app
SHIELD_CHALLENGE=turnstile
SHIELD_TURNSTILE_SITE_KEY=your-site-key
SHIELD_TURNSTILE_SECRET_KEY=your-secret-key

shield:prune sudah dijadwalkan otomatis setiap hari, tapi host Anda tetap wajib menjalankan cron berikut:

* * * * * cd /path-ke-aplikasi && php spark shield:prune >> /dev/null 2>&1

Ada juga panel admin opsional untuk melihat laporan, mengelola ban, dan menelusuri event. Panel ini default-nya nonaktif, karena halaman tersebut menampilkan reputasi pengguna — dan wajib dibatasi dengan izin admin.authorize kalau diaktifkan.

• Permintaan tanpa route (404) tidak diperiksa. CodeIgniter melempar PageNotFoundException ketika URI tidak cocok dengan route mana pun, dan hal itu terjadi sebelum filter before global sempat berjalan. Scanner yang membidik path tak dikenal (misalnya /.env) oleh karena itu tidak disentuh Shield. Untuk lapisan ini, andalkan WAF di depan (Cloudflare, ModSecurity) atau aturan mod_rewrite di server.

Untuk mencoba Shield secara langsung, gunakan demo app:

cd examples/codeigniter4-demo
composer install
php spark migrate --all
php spark serve

Demo app menyediakan route untuk testing:

• GET /home — normal route
• GET /login — sensitive path
• POST /login — form submission
• GET /api/users — API endpoint

Dokumentasi lengkap ada di shield.ganadev.com:

CodeIgniter 4 Shield adalah proyek open source berlisensi MIT. Kode dan dokumentasinya bebas dibaca, diubah, dan dipakai ulang.

Kami terbuka pada masukan dan revisi apa pun — laporan bug, usulan fitur, perbaikan dokumentasi, sampai pull request. Semua itu membantu Shield menjadi lebih baik untuk semua orang, dan tidak ada yang perlu izin lebih dulu.

• Laporkan bug lewat Issues
• Usulkan fitur lewat Discussions
• Temukan celah keamanan lewat Security Advisory, jangan lewat Issues publik
• Koreksi dokumentasi lewat pull request langsung — sekecil apa pun tetap berharga

Sebelum contribute, jalankan dulu:

composer test        # Pest
composer analyse     # PHPStan
composer format-test # Pint

Ketiganya harus hijau sebelum pull request dikirim.

MIT — © 2026 Ganadev / PT Ganadev Multi Solusi