Admin API

CodeIgniter 4 Shield punya API admin opsional berbasis JSON: daftar ban, detail ban, lepas ban, perpanjang ban, daftar event, daftar rule, dan pemeriksaan kesehatan.

Ini bukan halaman HTML — semuanya endpoint JSON. Kalau Anda ingin antarmuka grafis, bangun sendiri di atas API ini (atau pakai perintah Spark CLI untuk kebutuhan sederhana).

Mengaktifkan

Berbeda dengan Laravel, CI4 Shield memakai project CodeIgniter receiver untuk admin. Di app/Config/Shield.php:

public bool $adminEnabled = true;
public string $adminPrefix = 'shield';        // prefix URL
public string $adminAuthorize = 'admin.authorize';

Default nonaktif

adminEnabled bernilai false secara bawaan — dan memang sebaiknya begitu, karena halaman ini menampilkan reputasi pengguna.

Batasi akses dengan adminAuthorize

Nilai	Perilaku
'admin.authorize'	Hanya user login yang punya izin admin.authorize yang bisa.
'' (kosong)	Siapa saja bisa mengatur ban, tanpa login. Tidak aman.

adminAuthorize diperiksa lewat service authentication CodeIgniter: user diambil dari service itu, lalu izinnya dicek dengan getPermissions(). Kalau adminAuthorize diisi tetapi aplikasi tidak punya service auth, semua permintaan ditolak 403 ({"error":"forbidden"}). Jika adminAuthorize kosong, pemeriksaan dilewati sepenuhnya.

Jangan biarkan adminAuthorize kosong

Endpoint admin GET /{prefix}/health menampilkan admin_authorize_warning kalau panel aktif tetapi adminAuthorize kosong. php spark shield:health tidak memeriksa admin. Kalau Anda melihat peringatan, isi adminAuthorize dengan nama permission yang benar.

Endpoint

Semua respons JSON. Prefix bawaan shield.

Method	URL	Keterangan
GET	/shield/bans	Daftar ban dengan page/per_page (tanpa metadata total).
GET	/shield/bans/{id}	Detail satu ban.
POST	/shield/bans/{id}/release	Lepas ban. Body: reason (opsional).
POST	/shield/bans/{id}/extend	Perpanjang ban. Body: minutes (default 60).
GET	/shield/events	Daftar kejadian keamanan, paginated.
GET	/shield/rules	Daftar rule aktif beserta skornya.
GET	/shield/health	Pemeriksaan kesehatan komponen.

Daftar ban

GET /shield/bans?ip=203.0.113.10&status=active&active=true&page=1&per_page=50

Parameter	Fungsi
ip	Filter alamat IP.
status	Filter status (active, expired, released, …).
active	Kehadirannya (?active) = hanya ban yang sedang aktif.
page, per_page	Pagination (max 200).

Respons (GET /shield/bans):

{
  "data": [
    {
      "id": 12,
      "ip_address": "203.0.113.10",
      "status": "active",
      "reason": "rule:path_traversal",
      "expires_at": "2026-10-08 09:00:00"
    }
  ]
}

Detail satu ban (GET /shield/bans/12) memakai kunci camelCase karena dikembalikan sebagai objek ban. DateTimeImmutable diserialkan sebagai objek, bukan string:

{
  "ban": {
    "id": "12",
    "ipAddress": "203.0.113.10",
    "status": "active",
    "reason": "rule:path_traversal",
    "expiresAt": {
      "date": "2026-10-08 09:00:00.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "offenseCount": 3
  }
}

Lepas & perpanjang ban

curl -X POST http://localhost:8080/shield/bans/12/release \
  -d "reason=pelanggan salah ketik"

curl -X POST http://localhost:8080/shield/bans/12/extend \
  -d "minutes=120"

Daftar event

GET /shield/events?rule_id=r.path_traversal&decision=blocked&severity=high

Filter yang tersedia: ip, host, rule_id, severity, decision.

Kesehatan

GET /shield/health

Menampilkan status database, cache, engine, plus dua peringatan umum: trusted_proxy_warning (ada header forwarded tanpa proxyIPs) dan admin_authorize_warning (panel aktif tanpa izin).

Kalau tidak ingin memakai API

Tidak apa-apa — API ini opsional. Tanpa adminEnabled, route admin tidak didaftarkan sama sekali, dan semua perintah Spark tetap tersedia.

Checklist sebelum menyalakan

1. adminAuthorize diisi permission yang ketat (jangan kosong).
2. Panel sebaiknya hanya bisa diakses via HTTPS.
3. Pertimbangkan membatasi akses di level route yang menaungi prefix admin.
4. Uji dengan GET /shield/health terlebih dahulu sebelum membuka ban.