Panduan Instalasi & Migrasi

Halaman ini memandu proses instalasi paket robyajo/laravel-security-monitor ke dalam aplikasi Laravel Anda.

🌟 Nol Ketergantungan NPM (Zero NPM): Paket ini murni PHP Composer library standar seperti paket Spatie. Anda tidak perlu menginstal dependensi npm atau menjalankan build tools frontend.

---

1. Persyaratan Sistem

Pastikan lingkungan server Anda memenuhi spesifikasi minimum berikut:

• PHP: ^8.2, ^8.3, ^8.4, atau ^8.5
• Laravel: ^10.0, ^11.0, ^12.0, atau ^13.0
• Ekstensi PHP: pdo, mbstring, json, filter, openssl.

---

2. Pemasangan via Composer

Menggunakan Packagist (Publik)

Jika paket sudah diterbitkan di Packagist:

composer require robyajo/laravel-security-monitor

Menggunakan Repositori Lokal / Private Git (Monorepo atau Path)

Jika Anda menggunakan paket ini secara internal sebelum publikasi ke Packagist, tambahkan konfigurasi repositori pada berkas composer.json proyek Laravel Anda:

"repositories": [
    {
        "type": "path",
        "url": "../laravel-security-monitor",
        "options": {
            "symlink": true
        }
    }
]

Kemudian pasang paket:

composer require robyajo/laravel-security-monitor:@dev

---

3. Publikasi Aset Otomatis (security:install)

Paket menyediakan perintah Artisan interaktif satu langkah untuk mempublikasikan seluruh berkas konfigurasi, migrasi, template Nginx, serta menerapkan aturan Hardening Apache .htaccess:

php artisan security:install

Perintah ini akan secara otomatis:

1. Mempublikasikan berkas konfigurasi config/security.php.
2. Mempublikasikan berkas migrasi database ke database/migrations/.
3. Mempublikasikan template virtual host nginx.conf di root proyek.
4. Memperbarui berkas public/.htaccess:
   • Jika berkas belum ada: membuat public/.htaccess baru dengan aturan rewrite standar Laravel + blok hardening keamanan.
   • Jika berkas sudah ada: membuat cadangan otomatis public/.htaccess.backup-YYYYMMDD_HHMMSS dan menyisipkan blok hardening keamanan di bagian bawah berkas tanpa merusak aturan rewrite kustom Anda.
   • Jika sudah memiliki aturan hardening: mendeteksi dan mempertahankan berkas yang sudah terlindungi.
5. Menyematkan Variabel Lingkungan ke .env & .env.example:
   • Menambahkan blok konfigurasi lengkap (SECURITY_*) disertai dokumentasi penjelasan fungsi berbahasa Indonesia langsung di bagian bawah berkas .env dan .env.example.
   • Menggunakan deteksi cerdas agar tidak terjadi duplikasi jika variabel sudah pernah ditambahkan sebelumnya.
6. Menyematkan Trait HasSecurityRelations ke Model User:
   • Secara otomatis mendeteksi model User (app/Models/User.php) dan menambahkan import use Internal\SecurityMonitor\Concerns\HasSecurityRelations; serta menyematkan trait HasSecurityRelations.
   • Idempotent: tidak akan menduplikasi jika trait sudah ada.
7. Mendaftarkan Middleware WAF ke Aplikasi Host:
   • Otomatis mendaftarkan BlockIpAddress dan DetectSecurityThreats ke dalam bootstrap/app.php (Laravel 11 & 12) atau app/Http/Kernel.php (Laravel 10).
   • Idempotent: memeriksa keberadaan middleware terlebih dahulu sebelum mendaftarkan.
8. Menyiapkan Dukungan API & Berkas Rute Kustom (routes/):
   • Memeriksa apakah berkas routes/api.php sudah tersedia. Jika belum (pada Laravel 11+), otomatis menjalankan php artisan install:api agar dukungan API aktif.
   • Menghasilkan berkas routes/security-api.php untuk endpoint headless REST API dan menyertakannya di routes/api.php (require __DIR__.'/security-api.php';).
   • Menghasilkan berkas routes/security.php untuk rute web dashboard yang langsung me-render ke view dan menyertakannya di routes/web.php (require __DIR__.'/security.php';).
   • Memberikan kebebasan penuh kepada developer untuk mengkustomisasi prefix URL, middleware, otorisasi, dan tampilan tanpa terkunci pada rute internal paket.

Opsi Perintah:

Opsi	Fungsi
--force	Menimpa seluruh berkas konfigurasi, migrasi, nginx.conf, dan public/.htaccess dengan template bawaan paket.
--with-blade	Mempublikasikan tampilan dashboard monitoring Blade (Livewire Starter Kit — Pure Vanilla CSS).
--with-tsx	Mempublikasikan tampilan dashboard monitoring TSX (Inertia + React Starter Kit — Pure Vanilla CSS).
--with-both	Mempublikasikan kedua tampilan dashboard monitoring sekaligus (Blade & TSX).
--stack=...	Menentukan stack dashboard yang ingin dipublikasikan (blade, tsx, both, none).
--without-user-trait	Melewatkan penyematan otomatis trait HasSecurityRelations ke model User.
--without-middleware	Melewatkan pendaftaran otomatis middleware WAF di bootstrap/app.php / Kernel.php.
--without-routes	Melewatkan pembuatan berkas rute routes/security.php dan routes/security-api.php.
--without-api	Melewatkan pemeriksaan dan instalasi rute API (install:api).
--without-nginx	Melewatkan publikasi berkas nginx.conf jika server Anda tidak menggunakan web server Nginx.
--without-htaccess	Melewatkan pembaruan berkas public/.htaccess jika Anda menggunakan Nginx murni dan tidak memerlukan Apache .htaccess.
--with-htaccess	Memaksa pembaruan berkas public/.htaccess dengan aturan hardening keamanan paket.
--without-env	Melewatkan penyematan variabel konfigurasi ke berkas .env dan .env.example.

---

4. Publikasi Aset Manual via Vendor Publish

Jika Anda ingin mempublikasikan aset secara bertahap atau terpisah:

1. Publikasikan Konfigurasi Saja

php artisan vendor:publish --tag=security-config

Berkas akan ditempatkan di: config/security.php.

2. Publikasikan Migrasi Saja

php artisan vendor:publish --tag=security-migrations

Berkas migrasi akan disalin ke folder database/migrations/.

3. Publikasikan Berkas Rute Kustom

# Publikasikan rute web dan API sekaligus:
php artisan vendor:publish --tag=security-routes

# Atau publikasikan terpisah:
php artisan vendor:publish --tag=security-routes-web
php artisan vendor:publish --tag=security-routes-api

Berkas akan ditempatkan di:

• routes/security.php (rute web dashboard yang langsung me-render view).
• routes/security-api.php (rute headless REST API).

4. Publikasikan Template Nginx WAF Hardened Saja

php artisan vendor:publish --tag=security-nginx

Berkas akan ditempatkan di root proyek: nginx.conf.

4. Publikasikan Template Apache .htaccess Hardened Saja

php artisan vendor:publish --tag=security-htaccess --force

Berkas akan ditempatkan di: public/.htaccess.

5. Publikasikan Seluruh Aset Sekaligus

php artisan vendor:publish --tag=security-all --force

6. Publikasikan Dashboard Monitoring Starter Kit

# Blade Starter Kit (Livewire + Flux UI)
php artisan vendor:publish --tag=starterkit-blade

# React / TSX Starter Kit (Inertia + React + shadcn/ui)
php artisan vendor:publish --tag=starterkit-tsx

# Keduanya (Blade & TSX)
php artisan vendor:publish --tag=starterkit-all

Perintah Blade menyalin enam halaman Livewire (single-file component) ke resources/views/pages/security/. Perintah TSX menyalin enam halaman Inertia/React ke resources/js/pages/security/ beserta komponen pendukung di resources/js/components/security/. Keduanya juga menyertakan konfigurasi dashboard pada config/security.php. Dashboard diakses di prefix /security dan wajib login (lihat bagian Dashboard Monitoring Starter Kit).

---

5. Menjalankan Migrasi Database

Jalankan perintah migrasi Laravel untuk membuat tabel-tabel pendukung paket:

php artisan migrate

Tabel-tabel yang dibuat secara default:

1. blocked_ips: Menyimpan daftar karantina IP dan perangkat aktif/kedaluwarsa beserta hit counter.
2. security_logs: Log audit ancaman keamanan, pola yang terdeteksi, bukti payload, dan aksi mitigasi.
3. login_attempts: Pelacakan kegagalan login bertingkat (stepped lockout) per kombinasi email & IP.
4. ip_unblock_requests: Tiket banding pembukaan blokir yang diajukan oleh pengguna publik.
5. user_logins: Rekam jejak riwayat login pengguna, detail perangkat/browser, sesi aktif, dan waktu aktivitas terakhir.
6. trusted_ips: Daftar alamat IP terpercaya per pengguna untuk otorisasi akses khusus.

---

6. Mendaftarkan Trait ke Model User (Standar Spatie)

Buka model pengguna aplikasi Anda (biasanya app/Models/User.php) dan sertakan trait HasSecurityRelations:

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Internal\SecurityMonitor\Concerns\HasSecurityRelations;

class User extends Authenticatable
{
    use HasSecurityRelations;

    // ... sisa model Anda
}

Metode relasi Eloquent yang otomatis tersedia:

• $user->logins(): Mengambil seluruh riwayat login (HasMany ke UserLogin).
• $user->trustedIps(): Mengambil daftar IP terpercaya milik pengguna (HasMany ke TrustedIp).
• $user->securityLogs(): Mengambil audit ancaman yang diasosiasikan dengan akun ini (HasMany ke SecurityLog).
• $user->blockedIps(): Mengambil daftar entri blokir yang dieksekusi oleh user admin ini (HasMany ke BlockedIp).
• $user->resolvedTickets(): Mengambil daftar tiket banding yang diselesaikan oleh user admin ini (HasMany ke IpUnblockRequest).

---

7. Mendaftarkan Middleware Keamanan ke Core Laravel

Paket menyediakan 4 middleware terisolasi:

Alias	Kelas Middleware	Peran
security.block	Internal\SecurityMonitor\Http\Middleware\BlockIpAddress	Menolak request dari IP/perangkat yang sedang terblokir aktif (HTTP 403).
security.detect	Internal\SecurityMonitor\Http\Middleware\DetectSecurityThreats	Menginspeksi payload request terhadap tanda-tanda serangan siber dan mengaktifkan auto-block/instant block.
security.admin	Internal\SecurityMonitor\Http\Middleware\EnsureSecurityAdmin	Memastikan hanya user dengan wewenang admin yang dapat mengakses REST API admin.
security.activity	Internal\SecurityMonitor\Http\Middleware\TrackUserActivity	Memperbarui heartbeat aktivitas login pengguna di database (ter-throttle 45 detik).

Pendaftaran pada Laravel 11 / 12 / 13 (bootstrap/app.php)

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
use Internal\SecurityMonitor\Http\Middleware\BlockIpAddress;
use Internal\SecurityMonitor\Http\Middleware\DetectSecurityThreats;
use Internal\SecurityMonitor\Http\Middleware\TrackUserActivity;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Pasang di lapisan global
        $middleware->append(BlockIpAddress::class);
        $middleware->append(DetectSecurityThreats::class);

        // Pasang di grup web untuk pelacakan aktivitas user login
        $middleware->web(append: [
            TrackUserActivity::class,
        ]);
    })
    ->create();

Pendaftaran pada Laravel 10 (app/Http/Kernel.php)

Buka app/Http/Kernel.php dan tambahkan ke array $middleware:

protected $middleware = [
    // ...
    \Internal\SecurityMonitor\Http\Middleware\BlockIpAddress::class,
    \Internal\SecurityMonitor\Http\Middleware\DetectSecurityThreats::class,
];

Tips Opsi Otomatis (Zero-Touch): Jika Anda mengatur SECURITY_AUTO_REGISTER_MIDDLEWARE=true di berkas .env, paket akan otomatis menyuntikkan BlockIpAddress dan DetectSecurityThreats ke Kernel HTTP aplikasi secara otomatis saat booting.

---

8. Dashboard Monitoring Starter Kit (Opsional)

Paket tetap 100% headless secara default. Bila aplikasi host menggunakan starter kit resmi Laravel, Anda dapat mengaktifkan panel monitoring siap pakai. Pilih salah satu stack.

A. Livewire Starter Kit (Flux UI)

php artisan vendor:publish --tag=starterkit-livewire

B. React Starter Kit (Inertia + React + shadcn/ui)

php artisan vendor:publish --tag=starterkit-react

# Setelah publikasi tampilan React, bangun ulang aset frontend
npm run build

ℹ️ Halaman React di-render server-side melalui controller Inertia bawaan paket (tidak melalui REST API /api/*), sehingga cookie sesi Laravel langsung bekerja.

Mengaktifkan

# Aktifkan di .env
#    SECURITY_DASHBOARD_ENABLED=true
#    SECURITY_DASHBOARD_DRIVER=livewire   # atau "react"
#    SECURITY_DASHBOARD_PREFIX=security

# Bersihkan cache
php artisan optimize:clear

Panel tersedia di /security dan berisi enam modul: Overview, Security Logs, Blocked IPs, Server Audit, User Sessions, dan Unblock Appeals.

Keamanan & Kontrol Akses

• Rute hanya didaftarkan ketika security.dashboard.enabled=true dan stack frontend yang sesuai (driver) terpasang (Livewire atau Inertia).
• Seluruh rute memakai middleware web + auth (wajib login) dan, secara bawaan, security.admin (Gate manage-security-monitor).
• Kustomisasi melalui config/security.php:

  'dashboard' => [
      'enabled' => (bool) env('SECURITY_DASHBOARD_ENABLED', false),
      'driver' => env('SECURITY_DASHBOARD_DRIVER', 'livewire'),
      'prefix' => env('SECURITY_DASHBOARD_PREFIX', 'security'),
      'middleware' => ['web', 'auth'],
      'admin_middleware' => ['Internal\\SecurityMonitor\\Http\\Middleware\\EnsureSecurityAdmin'],
  ],