Fitur unggah file adalah salah satu pintu masuk paling berbahaya di aplikasi web. Panduan ini menyusun pertahanan berlapis: validasi isi file, nama acak, penyimpanan privat, penyajian lewat controller berotorisasi, pemrosesan ulang gambar, larangan eksekusi di server, pemindaian antivirus, dan test dengan file berbahaya.
Overview
Di aplikasi RW, warga mengunggah foto KK untuk verifikasi, bendahara mengunggah bukti transfer, dan pengurus mengunggah foto kegiatan. Setiap fitur ini membuka risiko:
| Ancaman | Contoh | Dampak |
|---|---|---|
| Web shell | bukti.php atau foto.jpg.php diunggah lalu dibuka lewat URL |
Penyerang menjalankan perintah di server |
| File poliglot | Gambar JPG valid yang juga berisi kode PHP | Lolos pemeriksaan sederhana, tereksekusi bila server salah konfigurasi |
| SVG/HTML berisi skrip | logo.svg dengan <script> |
XSS saat file dibuka di domain aplikasi |
| Akses tanpa izin | /storage/kk/3276....jpg bisa ditebak |
Dokumen kependudukan bocor |
| Path traversal | Nama file ../../.env |
File penting tertimpa |
| DoS | File 2 GB, ribuan file, decompression bomb | Disk penuh, server melambat |
| Bocor metadata | EXIF berisi koordinat GPS | Lokasi rumah warga terungkap |
Hasil akhir: alur upload yang aman untuk dua jenis file: dokumen privat (KK, bukti transfer) dan gambar publik (foto kegiatan), lengkap dengan konfigurasi server, pemindaian antivirus opsional, dan test.
Prerequisites
| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4), ekstensi fileinfo dan gd atau imagick |
| Laravel | 13.x |
| Intervention Image | 3.x (intervention/image) |
| Nginx | 1.24+ |
| ClamAV (opsional) | clamd 1.x |
| Testing | Pest 4 |
Step-by-step Tutorial
Langkah 1: Tetapkan Batas di Server Terlebih Dahulu
Validasi Laravel baru berjalan setelah file selesai diterima. Batasi ukuran di lapisan yang lebih awal agar file raksasa ditolak sebelum memakan disk dan memori.
# /etc/nginx/sites-available/rw.conf
server {
client_max_body_size 10M;
# ...
}
; php.ini (atau pool PHP-FPM)
upload_max_filesize = 8M
post_max_size = 10M
max_file_uploads = 10
file_uploads = On
post_max_size harus sedikit lebih besar dari upload_max_filesize karena satu request berisi file dan field lainnya.
Langkah 2: Validasi Berdasarkan Isi dan Ekstensi
Gunakan objek aturan File agar mudah dibaca:
// app/Http/Requests/UnggahBuktiTransferRequest.php
use Illuminate\Validation\Rules\File;
public function rules(): array
{
return [
'bukti' => [
'required',
File::types(['jpg', 'jpeg', 'png', 'pdf']) // memeriksa tipe MIME dari isi file
->max(4 * 1024), // KB → 4 MB
'extensions:jpg,jpeg,png,pdf', // juga memeriksa ekstensi nama file
],
'keterangan' => ['nullable', 'string', 'max:255'],
];
}
Kenapa dua pemeriksaan:
| Aturan | Memeriksa | Mencegah |
|---|---|---|
File::types([...]) / mimes: |
Tipe MIME hasil deteksi isi file (fileinfo) | File PHP yang diganti namanya menjadi .jpg |
extensions: |
Ekstensi pada nama file asli | File yang isinya terdeteksi gambar tetapi bernama .php |
Untuk gambar, tambahkan pemeriksaan dimensi agar decompression bomb (gambar kecil di disk tetapi berukuran puluhan ribu piksel) ditolak:
'foto' => [
'required',
File::image()->types(['jpg', 'jpeg', 'png', 'webp'])->max(5 * 1024)
->dimensions(Rule::dimensions()->maxWidth(6000)->maxHeight(6000)),
'extensions:jpg,jpeg,png,webp',
],
File::image() secara bawaan tidak menerima SVG. Biarkan begitu, kecuali Anda benar-benar butuh SVG (lihat Langkah 7).
Ingat: validasi tipe MIME bukan jaminan. File poliglot bisa lolos. Karena itu langkah berikutnya tetap diperlukan.
Langkah 3: Simpan dengan Nama Acak, Jangan Pakai Nama Asli
// AMAN: Laravel membuat nama acak 40 karakter + ekstensi berdasarkan isi file
$path = $request->file('bukti')->store('bukti-transfer', 'private');
// bukti-transfer/7a1Fd0Wq...Kp.pdf
// RENTAN: nama dari pengguna dipakai sebagai path
$request->file('bukti')->storeAs('bukti-transfer', $request->file('bukti')->getClientOriginalName());
Nama asli boleh disimpan di database hanya untuk ditampilkan, setelah dibersihkan:
$namaAsli = Str::of($file->getClientOriginalName())
->basename() // buang path
->replaceMatches('/[^\pL\pN._\- ]/u', '') // hanya huruf, angka, titik, garis
->limit(100, '');
Simpan metadata di tabel tersendiri:
Schema::create('lampiran', function (Blueprint $table) {
$table->id();
$table->morphs('lampiranable'); // milik transaksi kas, keluarga, dll.
$table->string('disk', 20);
$table->string('path');
$table->string('nama_asli', 150);
$table->string('mime', 100);
$table->unsignedBigInteger('ukuran');
$table->char('sha256', 64)->index();
$table->string('status_pemindaian', 15)->default('menunggu'); // menunggu | bersih | terinfeksi
$table->foreignId('diunggah_oleh')->constrained('users');
$table->timestamps();
});
Langkah 4: Pisahkan Disk Privat dan Publik
Dokumen kependudukan dan bukti transfer tidak boleh disimpan di disk public, karena semua file di sana bisa diakses siapa pun yang tahu URL-nya.
// config/filesystems.php
'disks' => [
'private' => [
'driver' => 'local',
'root' => storage_path('app/private'),
'serve' => false,
'throw' => true,
],
'public' => [
'driver' => 'local',
'root' => storage_path('app/public'),
'url' => env('APP_URL').'/storage',
'visibility' => 'public',
'throw' => true,
],
's3-private' => [
'driver' => 's3',
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION'),
'bucket' => env('AWS_BUCKET_PRIVATE'),
'visibility' => 'private',
'throw' => true,
],
],
| Jenis file | Disk |
|---|---|
| Scan KK, KTP, bukti transfer, dokumen keuangan | private / s3-private |
| Foto kegiatan untuk halaman publik | public (setelah diproses ulang, Langkah 6) |
Langkah 5: Sajikan File Privat Lewat Controller Berotorisasi
// app/Http/Controllers/LampiranController.php
namespace App\Http\Controllers;
use App\Models\Lampiran;
use Illuminate\Support\Facades\{Gate, Storage};
class LampiranController extends Controller
{
public function show(Lampiran $lampiran)
{
Gate::authorize('view', $lampiran);
abort_unless($lampiran->status_pemindaian === 'bersih', 409, 'File masih diperiksa atau ditolak.');
return Storage::disk($lampiran->disk)->download(
$lampiran->path,
$lampiran->nama_asli,
[
'Content-Type' => $lampiran->mime,
'X-Content-Type-Options' => 'nosniff',
'Content-Security-Policy' => "default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; sandbox",
'Cache-Control' => 'private, no-store',
],
);
}
}
// app/Policies/LampiranPolicy.php
public function view(User $user, Lampiran $lampiran): Response
{
// Delegasikan ke Policy pemilik lampiran (transaksi kas, keluarga, ...)
return $user->can('view', $lampiran->lampiranable)
? Response::allow()
: Response::denyAsNotFound();
}
// routes/web.php
Route::get('lampiran/{lampiran}', [LampiranController::class, 'show'])
->middleware(['auth', 'active'])
->name('lampiran.show');
Hal penting:
download()mengirim headerContent-Disposition: attachment, sehingga browser mengunduh file, bukan menampilkannya. File HTML/SVG berbahaya tidak dijalankan di domain aplikasi.X-Content-Type-Options: nosniffmencegah browser menebak tipe file.- CSP
sandboxmembatasi apa pun yang tetap dirender. - Untuk S3, gunakan URL sementara dengan masa berlaku singkat setelah otorisasi:
return redirect(Storage::disk('s3-private')->temporaryUrl(
$lampiran->path,
now()->addMinutes(5),
['ResponseContentDisposition' => 'attachment; filename="'.$lampiran->nama_asli.'"'],
));
Langkah 6: Proses Ulang Gambar Publik
Membuat ulang gambar dari pikselnya membuang kode tersembunyi, metadata EXIF (termasuk lokasi GPS), dan menormalkan ukuran.
composer require intervention/image
// app/Services/ProsesFotoKegiatan.php
namespace App\Services;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;
use Intervention\Image\ImageManager;
use Intervention\Image\Drivers\Gd\Driver;
final class ProsesFotoKegiatan
{
public function simpan(UploadedFile $file): string
{
$manager = new ImageManager(new Driver());
$gambar = $manager->read($file->getRealPath())
->scaleDown(width: 1920, height: 1920); // batasi resolusi
$path = 'kegiatan/'.now()->format('Y/m').'/'.Str::uuid().'.webp';
Storage::disk('public')->put($path, (string) $gambar->toWebp(quality: 80));
return $path;
}
}
File yang tersimpan adalah gambar WebP baru hasil encoding ulang, bukan file asli unggahan pengguna. Encoding ulang tidak menyimpan metadata EXIF asli.
Langkah 7: Tangani SVG dengan Sangat Hati-hati
SVG adalah dokumen XML yang bisa berisi <script>, event handler, dan tautan eksternal. Pilihan dari yang paling aman:
- Jangan terima SVG dari pengguna (rekomendasi untuk sebagian besar aplikasi).
- Konversi SVG ke PNG di server dan simpan hasil PNG-nya.
- Bila harus menyimpan SVG, sanitasi dengan pustaka khusus SVG, sajikan dari domain terpisah (misalnya
cdn-rw.contoh.id), dan selalu denganContent-Disposition: attachmentatau CSPsandbox.
Langkah 8: Larang Eksekusi Skrip di Folder Unggahan
Ini lapisan terpenting: walaupun file berbahaya lolos semua pemeriksaan, server tidak boleh menjalankannya.
server {
root /var/www/rw/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# Tidak ada PHP di folder storage publik
location ^~ /storage/ {
location ~* \.(php|phtml|phar|pl|py|cgi|sh)$ { deny all; return 403; }
add_header X-Content-Type-Options "nosniff" always;
try_files $uri =404;
}
# Hanya index.php yang boleh dieksekusi
location ~ ^/index\.php(/|$) {
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
internal;
}
location ~ \.php$ { return 404; }
}
Pola location ~ ^/index\.php dengan return 404 untuk file .php lainnya memastikan hanya front controller Laravel yang dijalankan. File .php apa pun yang entah bagaimana sampai ke public/ tidak akan dieksekusi.
Pastikan juga folder storage/ dan public/storage tidak dimiliki user yang sama dengan proses yang bisa menulis kode aplikasi, dan bahwa document root adalah folder public, bukan root proyek.
Langkah 9: Pemindaian Antivirus di Queue
Untuk dokumen dari pengguna, terutama PDF, pemindaian antivirus menambah satu lapisan. Jalankan di queue agar upload tetap cepat, dan jangan sajikan file sebelum dinyatakan bersih.
// app/Jobs/PindaiLampiran.php
namespace App\Jobs;
use App\Models\Lampiran;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\{Log, Process, Storage};
class PindaiLampiran implements ShouldQueue
{
use Queueable;
public int $tries = 3;
public function __construct(public int $lampiranId) {}
public function handle(): void
{
$lampiran = Lampiran::findOrFail($this->lampiranId);
$fullPath = Storage::disk($lampiran->disk)->path($lampiran->path);
$hasil = Process::timeout(60)->run(['clamdscan', '--no-summary', '--fdpass', $fullPath]);
$status = match ($hasil->exitCode()) {
0 => 'bersih',
1 => 'terinfeksi',
default => throw new \RuntimeException('Pemindaian gagal: '.$hasil->errorOutput()),
};
$lampiran->update(['status_pemindaian' => $status]);
if ($status === 'terinfeksi') {
Storage::disk($lampiran->disk)->delete($lampiran->path);
Log::channel('security')->alert('upload.infected', [
'lampiran_id' => $lampiran->id,
'user_id' => $lampiran->diunggah_oleh,
'output' => $hasil->output(),
]);
}
}
}
Perhatikan pemanggilan Process::run([...]) dengan array argumen, bukan string. Path file diteruskan sebagai satu argumen sehingga tidak bisa disalahgunakan untuk menyisipkan perintah shell.
Untuk disk S3, unduh file ke direktori sementara terlebih dahulu, atau gunakan layanan pemindaian dari penyedia cloud.
Langkah 10: Rangkai Alurnya di Service
// app/Services/UnggahLampiran.php
namespace App\Services;
use App\Jobs\PindaiLampiran;
use App\Models\{Lampiran, User};
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Str;
final class UnggahLampiran
{
public function handle(Model $pemilik, UploadedFile $file, User $pengunggah): Lampiran
{
$this->periksaKuota($pengunggah);
$path = $file->store($pemilik->getTable(), 'private');
$lampiran = $pemilik->lampiran()->create([
'disk' => 'private',
'path' => $path,
'nama_asli' => Str::of($file->getClientOriginalName())->basename()->limit(100, ''),
'mime' => $file->getMimeType(),
'ukuran' => $file->getSize(),
'sha256' => hash_file('sha256', $file->getRealPath()),
'diunggah_oleh' => $pengunggah->id,
]);
PindaiLampiran::dispatch($lampiran->id)->afterCommit();
return $lampiran;
}
private function periksaKuota(User $user): void
{
$hariIni = Lampiran::where('diunggah_oleh', $user->id)->whereDate('created_at', today())->count();
if ($hariIni >= 50) {
throw new \DomainException('Batas unggah harian tercapai.');
}
}
}
Tambahkan juga rate limit pada route unggah (misalnya throttle:20,1) sebagai lapisan pertama.
Langkah 11: Test dengan File Berbahaya
// tests/Feature/Security/UploadTest.php
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\{Queue, Storage};
beforeEach(function () {
Storage::fake('private');
Storage::fake('public');
Queue::fake();
$this->bendahara = User::factory()->create()->assignRole('bendahara');
$this->trx = TransaksiKas::factory()->create(['dicatat_oleh' => $this->bendahara->id]);
});
it('menolak file PHP yang diganti nama menjadi jpg', function () {
$file = UploadedFile::fake()->createWithContent('bukti.jpg', '<?php system($_GET["c"]); ?>');
$this->actingAs($this->bendahara)
->post("/kas/{$this->trx->id}/lampiran", ['bukti' => $file])
->assertSessionHasErrors('bukti');
expect(Storage::disk('private')->allFiles())->toBeEmpty();
});
it('menolak ekstensi ganda', function () {
$file = UploadedFile::fake()->image('bukti.jpg.php');
$this->actingAs($this->bendahara)
->post("/kas/{$this->trx->id}/lampiran", ['bukti' => $file])
->assertSessionHasErrors('bukti');
});
it('menolak SVG', function () {
$svg = UploadedFile::fake()->createWithContent('logo.svg', '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>');
$this->actingAs($this->bendahara)
->post("/kas/{$this->trx->id}/lampiran", ['bukti' => $svg])
->assertSessionHasErrors('bukti');
});
it('menyimpan file valid dengan nama acak di disk privat dan menjadwalkan pemindaian', function () {
$file = UploadedFile::fake()->create('Bukti Transfer Oktober.pdf', 200, 'application/pdf');
$this->actingAs($this->bendahara)
->post("/kas/{$this->trx->id}/lampiran", ['bukti' => $file])
->assertRedirect();
$lampiran = Lampiran::first();
expect($lampiran->path)->not->toContain('Bukti Transfer')
->and($lampiran->disk)->toBe('private');
Storage::disk('private')->assertExists($lampiran->path);
Queue::assertPushed(PindaiLampiran::class);
});
it('warga tidak bisa mengunduh lampiran kas', function () {
$lampiran = Lampiran::factory()->for($this->trx, 'lampiranable')->create(['status_pemindaian' => 'bersih']);
$warga = User::factory()->create()->assignRole('warga');
$this->actingAs($warga)->get("/lampiran/{$lampiran->id}")->assertNotFound();
});
Juga uji konfigurasi Nginx di staging:
echo '<?php echo "TEREKSEKUSI";' > /var/www/rw/storage/app/public/uji.php
curl -s -o /dev/null -w "%{http_code}\n" https://staging.rw.contoh.id/storage/uji.php # harus 403
rm /var/www/rw/storage/app/public/uji.php
Troubleshooting
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
The bukti failed to upload. |
File melebihi upload_max_filesize / post_max_size PHP |
Sesuaikan php.ini dan restart PHP-FPM |
413 Request Entity Too Large |
Batas Nginx | Sesuaikan client_max_body_size |
| File PDF valid ditolak | Tipe MIME terdeteksi berbeda (misalnya application/octet-stream) |
Periksa file dengan file --mime-type; jangan longgarkan aturan tanpa memahami penyebabnya |
| Gambar dari kamera ponsel ditolak | Format HEIC tidak ada di daftar | Tambahkan konversi HEIC di sisi klien, atau dukung HEIC bila ekstensi imagick mendukungnya |
| Foto tersimpan terbalik orientasinya | Orientasi EXIF dibuang saat re-encode | Intervention Image v3 menerapkan orientasi saat membaca; periksa konfigurasi autoOrientation |
clamdscan: Can't connect to clamd |
Layanan clamd belum berjalan atau socket berbeda |
systemctl status clamav-daemon, sesuaikan konfigurasi socket |
Link /storage/... 404 |
storage:link belum dijalankan |
php artisan storage:link |
| File privat bisa diakses lewat URL | Disimpan di disk public |
Pindahkan ke disk private, sajikan lewat controller |
Best Practices
Keamanan
- Validasi isi dan ekstensi file; tolak SVG dan HTML dari pengguna.
- Nama file selalu acak; nama asli hanya untuk tampilan setelah dibersihkan.
- Dokumen sensitif di disk privat, disajikan lewat controller dengan Policy dan header
attachment+nosniff. - Proses ulang gambar publik untuk membuang kode tersembunyi dan EXIF.
- Konfigurasi server agar tidak ada skrip yang bisa dieksekusi di luar
index.php. - Pindai antivirus untuk dokumen dan jangan sajikan file sebelum bersih.
- Batasi ukuran, jumlah, dan frekuensi unggahan.
Performa
- Proses gambar dan pemindaian antivirus di queue.
- Simpan file di object storage (S3 atau kompatibel) untuk aplikasi multi-server, dan gunakan URL sementara.
- Simpan hash SHA-256 untuk mendeteksi duplikat dan memudahkan investigasi.
Maintainability
- Satu service unggah yang dipakai semua fitur, bukan logika upload yang tersebar.
- Tabel
lampiranpolimorfik dengan metadata lengkap. - Jadwalkan pembersihan file yatim (ada di disk tetapi tidak ada di database).
- Pertahankan test file berbahaya di CI dan uji konfigurasi Nginx di staging.
Related Articles
- Panduan Validasi Form Laravel Menggunakan Form Request dan Custom Validation Rules
- Cara Mengamankan Route, Controller, dan API Laravel Menggunakan Middleware dan Policy
- Laravel Security Hardening: 15 Langkah Penting Sebelum Aplikasi Dipublikasikan
- Cara Membangun CRUD Laravel yang Terstruktur Menggunakan Form Request, Service, dan Resource
Last Tested
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| Intervention Image | 3.x |
| Nginx | 1.26 |
| ClamAV | 1.4 |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |