Güvenli Dosya Yükleme Sistemi

Güvenli Dosya Yükleme Sistemi

PHP ile katmanlı güvenlik uygulanmış dosya yükleme örneği. Sürükle-bırak · İlerleme çubuğu · Tür/tarih klasörleme · İndirme sayacı · Ayarlanabilir tür beyaz listesi

cilginyazilim.com · MIT Lisansı

🇹🇷 Türkçe · 🇬🇧 English

---

İçindekiler

• Bu proje ne yapıyor?
• Katmanlı güvenlik savunması
• Ölçülmüş bulgular
• Dosya yapısı ve hangi dosya ne yapar
• Fonksiyon referansı
• Klasör yapısı
• Ayarlar ekranı
• API uç noktaları
• Veritabanı şeması
• Kurulum
• Özelleştirme
• Örnek kullanım alanları

---

Bu proje ne yapıyor?

Genel amaçlı bir dosya yükleme sistemi: görseller (JPG/PNG/GIF/WEBP) ve belgeler (PDF/TXT/ZIP/DOCX/XLSX) yükler, tür ve tarihe göre klasörler, listeler, süzer, indirir, sayar ve siler.

Odak noktası arayüz değil güvenliktir. Dosya yükleme, bir web uygulamasının en tehlikeli özelliğidir: yanlış yapılırsa saldırgan sunucuya kod yükleyip çalıştırabilir (remote code execution). Bu depo, o riski katman katman nasıl kapatacağınızı ölçülmüş kanıtlarla gösterir.

Bu depo hem öğretici hem portfolyodur. Koddaki her kararın gerekçesi, kodun içinde Türkçe yorum olarak yazılıdır. "Şunu yaptık" değil, "neden böyle yaptık, alternatifi neden yetersizdi" anlatılır.

---

Katmanlı güvenlik savunması

Her katman, diğerleri atlatılsa bile tek başına anlamlı bir engel oluşturacak şekilde tasarlanmıştır (defense in depth). Aşağıdaki tabloda her katmanın neden orada olduğu yazılıdır.

---

Ölçülmüş bulgular ve kapatılan açıklar

Bu bölümdeki her madde tahmin değil, ölçümdür: gerçek HTTP istekleriyle denendi, sonucu kaydedildi, düzeltildi, tekrar denendi.

1) Content-Disposition başlık enjeksiyonu (uzaktan erişilebilir)

Bulgu. download.php, veritabanındaki original_name değerini doğrudan başlığa yazıyordu. basename() yol bilgisini atar ama tırnak işaretini temizlemez.

PHP'nin çok parçalı (multipart) yükleme çözümleyicisi normalde tırnağı geçirmez — ancak ters bölü ile kaçırılırsa geçirir:

Content-Disposition: form-data; name="files[]"; filename="a\"; filename=kurulum.exe.png"

Bu istek sıradan bir yükleme olarak kabul edildi ve veritabanına şu ad yazıldı:

a"; filename=kurulum.exe.png

Sunucunun ürettiği indirme başlığı (ölçüldü):

Content-Disposition: attachment; filename="a"; filename=kurulum.exe.png"
                                            ↑ başlıktan kaçış, İKİNCİ filename parametresi

Yani kimlik doğrulaması olmayan bir yükleyici, indirme başlığına ikinci bir filename parametresi enjekte edebiliyordu. Bazı istemciler sonuncuyu dikkate alır; kullanıcı beklemediği bir adla (örn. .exe) dosya kaydedebilir.

Düzeltme. download_filename_header() iki temsil üretir: temizlenmiş ASCII (" \ ; ve kontrol karakterleri _ olur) + RFC 5987 yüzde kodlu UTF-8.

Düzeltme sonrası ölçüm:

Content-Disposition: attachment; filename="a__ filename=kurulum.exe.png"; filename*=UTF-8''a%22%3B%20filename%3Dkurulum.exe.png
                                          ↑ tek parametre, kaçış yok

2) Görsel doğrulama baypası (getimagesize() yetersiz)

Bulgu. 5. katman getimagesize() kullanıyordu. Bu fonksiyon dosyayı çözmez, yalnızca başlığını okur.

İçeriği GIF89a<?php system($_GET["c"]); ?> olan bir dosya gönderildiğinde:

Daha sinsi bir sürümde (geçerli 100×100 başlık + PHP kodu) sonuç aynıydı: getimagesize() → GEÇTİ (100x100).

Düzeltme. imagecreatefromstring() ile gerçek çözümleme eklendi + 50 MP piksel sınırı.

Düzeltme sonrası ölçüm (aynı 100×100 polyglot):

getimagesize          -> GECTI (100x100)     ← eski katman hâlâ kanardı
imagecreatefromstring -> RED                 ← yeni katman yakaladı
sunucu yaniti         -> {"success":false,"description":"... Dosya geçerli bir görsel değil (içerik çözümlenemedi)."}

Meşru bir PNG aynı testte sorunsuz yüklendi — düzeltme normal kullanımı bozmadı.

3) Yükleme klasöründe güvenlik başlığı yokluğu

Bulgu. download.php yanıtlarında nosniff vardı, ama küçük resim önizlemelerinin kullandığı doğrudan erişim yolunda hiçbir güvenlik başlığı yoktu:

GET /uploads/....gif
Content-Type: image/gif        ← başka başlık YOK

Bir GIF/PNG içine HTML gömülüp tarayıcı içerik tahmini yaparsa, betik sitenin kendi alan adında çalışır (depolanmış XSS).

Düzeltme + ölçüm:

X-Content-Type-Options: nosniff
Content-Security-Policy: default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; sandbox
X-Frame-Options: DENY

4) CSRF reddi HTTP 500 döndürüyordu

Bulgu. require_csrf() başarısızlıkta 419 döndürüyordu. 419 resmî bir HTTP durum kodu değildir (Laravel'in icadı) ve bu kurulumda Apache onu sessizce 500'e çeviriyordu — istemci "sunucu çöktü" sanıyordu.

bozuk token -> HTTP 500      (düzeltme öncesi)
bozuk token -> HTTP 403      (düzeltme sonrası)

5) .htaccess kilidi — doğrulandı, açık bulunamadı

Bu katman atlatılamadı. Denenen ve hepsi 403 dönen yollar:

uploads/zz.php            uploads/zz.php/         uploads/./zz.php
uploads//zz.php           uploads/ZZ.PHP          uploads/zz.php.
uploads/zz.phtml          uploads/zz.php%00.png   (404)
uploads/image/2026/08/zz.php   ← alt klasörlerde de geçerli

Dizin listeleme de her seviyede kapalı (403).

6) Dizin aşımı (path traversal) — savunma doğrulandı

safe_upload_path() şu girdilerin tamamını reddetti; meşru yolu kabul etti:

../../system/config.php                      -> REDDEDILDI
image/2026/08/../../../../system/config.php  -> REDDEDILDI
image/2026/08/../../../.htaccess             -> REDDEDILDI
..\..\system\config.php                      -> REDDEDILDI
image/2026/08/%2e%2e%2fconfig.php            -> REDDEDILDI
document/2026/08/AAAA.php                    -> REDDEDILDI
image/2026/08/deada12d...474.png             -> kabul  ← meşru

7) SQL enjeksiyonu — savunma doğrulandı

Sıralama parametresine id; DROP TABLE files; -- gönderildi. Sıralama sütunu parametre olamayacağı için beyaz listeden seçilir; girdi eşleşmediğinden varsayılana düştü, tablo yerinde kaldı.

8) Ayarlar güvenlik sınırı — doğrulandı

Ayar kaydetme isteğine application/x-php ve application/x-httpd-php eklendi, boyut 500 MB, dosya sayısı 9999 istendi:

ETKIN turler: image/png                    ← .php türleri sessizce elendi
max_bytes=8388608  max_files=10            ← tavana kelepçelendi

---

Dosya yapısı ve hangi dosya ne yapar

secure-file-upload/
├── index.php                  ← Arayüz: sürükle-bırak, süzgeçler, özet, ayarlar penceresi
├── cy_upload.sql              ← Veritabanı kurulumu (files + settings tabloları)
│
├── system/
│   ├── config.php             ← Ayarlar, TÜR KATALOĞU, sınır tavanları, PDO bağlantısı
│   ├── function.php           ← Çekirdek: doğrulama, kaydetme, ayarlar, yol güvenliği
│   ├── ajax.php               ← JSON uç noktası (list / upload / delete / settings)
│   └── download.php           ← İndirme uç noktası (GET, zorunlu attachment, sayaç)
│
├── assets/
│   ├── css/cilginyazilim.css  ← ORTAK MARKA KALIBI — dokunulmaz
│   ├── css/style.css          ← Yalnızca bu sayfaya özel stiller
│   ├── js/upload.js           ← Sürükle-bırak, ilerleme, süzgeç, ayar arayüzü
│   └── images/                ← Logo + ekran görüntüleri
│
├── ornek-dosyalar/            ← Denemek için hazır örnekler (PNG/JPG/WEBP/GIF/PDF/TXT/ZIP)
│
└── uploads/                   ← Yüklenen dosyalar (tür/yıl/ay ağacı)
    └── .htaccess              ← Çalıştırma kilidi + güvenlik başlıkları

Sorumluluk ayrımı

Altın kural: upload.js içindeki tür ve boyut kontrolleri güvenlik değildir. Kötü niyetli biri JavaScript'i hiç çalıştırmadan doğrudan system/ajax.php'ye istek gönderebilir. Gerçek doğrulama her zaman sunucudadır.

---

Fonksiyon referansı

system/function.php

---

Diskteki klasör yapısı

Dosyalar düz bir klasöre değil, tür + tarih ağacına yazılır:

uploads/
├── .htaccess
├── image/
│   └── 2026/
│       └── 08/
│           ├── deada12df99150cb71bc731822d9b474.png
│           └── 2516fdb120e4253593217a923eac0580.jpg
└── document/
    └── 2026/
        └── 08/
            ├── f4384d8cf06ccaa65b0e70da95f75036.pdf
            └── 372c1b698c106b7e94500fb620d138f2.zip

Neden?

1. Performans — Tek klasörde on binlerce dosya biriktiğinde dosya sistemi dizin taramasında yavaşlar.
2. Yönetilebilirlik — "2025'in tamamını arşivle" tek komuta iner.
3. Yedekleme — Aylık artımlı yedek almak kolaylaşır.

Güvenlik notu: Bu yolun hiçbir parçası kullanıcı girdisinden gelmez — kategori katalogdan, yıl/ay sunucu saatinden, dosya adı random_bytes()'tan. uploads/.htaccess alt klasörlere de miras kalır (ölçüldü); her derinlikte .php isteği 403 döner.

Bir dosya silindiğinde boş kalan 08/, 2026/ klasörleri otomatik toplanır.

---

Ayarlar ekranı

Yönetici, arayüzden izin verilen dosya türlerini ve boyut/sayı sınırlarını koda dokunmadan değiştirebilir.

Güvenlik sınırı — bu ekranın yapamadıkları

Ayarlar veritabanında durur ve bir veritabanı, koddan farklı olarak, yanlış bir yedek geri yüklemesiyle veya başka bir açıkla değişebilir. Bu yüzden ayarlar hiçbir zaman güvenliği gevşetemez:

etkin türler = SUPPORTED_UPLOAD_TYPES (config.php)  ∩  settings tablosu

Yani tehlikeli bir türü etkinleştirmenin tek yolu system/config.php dosyasını düzenlemektir — bu da sunucuya dosya yazma yetkisi gerektirir.

---

API uç noktaları

Tümü system/ajax.php üzerinden POST ile çalışır ve CSRF anahtarı zorunludur (csrf_token alanı veya X-CSRF-Token başlığı).

action=list — Dosyaları listele

{
  "success": true,
  "total": 7,
  "files": [
    {
      "id": 1, "original_name": "ornek-gorsel-1.png",
      "extension": "png", "category": "image",
      "size": "8,7 KB", "uploaded_at": "15.08.2026 15:16",
      "downloads": 3, "folder": "image/2026/08",
      "download_url": "system/download.php?id=1",
      "thumb_url": "uploads/image/2026/08/deada12d....png"
    }
  ],
  "stats": {
    "by_category": [{"category": "image", "total": 4}],
    "by_period":   [{"period": "2026-08", "total": 7}],
    "totals":      {"files": 7, "bytes": 111923, "downloads": 3}
  }
}

action=upload — Dosya yükle

multipart/form-data ile files[] alanı (çoklu). Her dosya bağımsız doğrulanır: biri reddedilse bile diğerleri kaydedilir.

{ "success": true, "description": "7 dosya başarıyla yüklendi.", "uploaded": 7, "failed": 0 }

action=delete — Dosya sil

action=settings — Ayarları oku / kaydet

system/download.php?id=N — İndirme (GET)

Ayrı bir uç noktadır çünkü tarayıcının kendi indirme akışını kullanır (``, "Farklı Kaydet", yeni sekme). GET olması güvenli, çünkü hiçbir veri değiştirmez — yalnızca indirme sayacını artırır.

Durum kodları

---

Veritabanı şeması

Veritabanı adı cy_upload, kurulum dosyası cy_upload.sql.

Adlandırma kuralı: Çılgın Yazılım projelerinde veritabanları cy_ önekiyle adlandırılır ve kurulum dosyası veritabanıyla aynı adı taşır. Bir sunucuda onlarca .sql arasında hangisinin nereye ait olduğu tek bakışta anlaşılsın diye.

files

settings

---

Kurulum

Gereksinimler: PHP 8.1+ (fileinfo, pdo_mysql, gd), MySQL/MariaDB, Apache (mod_headers, AllowOverride All).

cd C:/xampp/htdocs
git clone https://github.com/CilginYazilim/secure-file-upload.git

mysql -u root -p < secure-file-upload/cy_upload.sql

system/config.php içindeki DB_* satırlarını düzenleyin veya ortam değişkeni tanımlayın (DB_HOST, DB_NAME, DB_USER, DB_PASS).

Ardından: http://localhost/secure-file-upload/

ornek-dosyalar/ klasöründeki hazır dosyaları sürükle-bırak alanına bırakarak sistemi hemen deneyebilirsiniz.

Canlıya alırken

1. APP_DEBUG → false (hata ayrıntıları kullanıcıya gösterilmesin)
2. mod_headers etkin olmalı — yoksa 8. katman (nosniff/CSP) sessizce devre dışı kalır
3. Sunucunuz .htaccess okumuyorsa (Nginx) eşdeğer kuralları sunucu yapılandırmasına taşıyın
4. Bu demoda indirme kimlik doğrulamasızdır; gerçek projede yetki kontrolü ekleyin

---

Özelleştirme

Yeni bir dosya türü eklemek

system/config.php içindeki SUPPORTED_UPLOAD_TYPES kataloğuna bir satır ekleyin:

'audio/mpeg' => ['ext' => 'mp3', 'category' => 'document', 'label' => 'MP3 ses'],

Arayüzdeki ipucu metni, accept özniteliği, ayarlar ekranı ve sunucu doğrulaması bu tek tanımdan beslenir.

Dikkat: category => 'image' yalnızca GD'nin çözebildiği formatlar için kullanılın; aksi hâlde 5. katman geçerli dosyaları reddeder.

Sınırları değiştirmek

config.php içindeki UPLOAD_MAX_BYTES / UPLOAD_MAX_FILES tavandır. Ayarlar ekranından bu tavanın altında herhangi bir değer seçilebilir. Tavanı yükseltirseniz php.ini içindeki upload_max_filesize ve post_max_size değerlerini de yükseltin.

Klasör düzenini değiştirmek

store_upload() içindeki $relativeDir satırı klasör düzenini belirler:

$relativeDir = $category . '/' . date('Y') . '/' . date('m');   // image/2026/08
$relativeDir = date('Y/m/d');                                    // 2026/08/15
$relativeDir = $category;                                        // yalnızca tür

Değiştirirseniz safe_upload_path() içindeki kalıbı da güncelleyin — yoksa yeni yollar reddedilir.

Görünümü değiştirmek

Sayfaya özel stiller assets/css/style.css içindedir. assets/css/cilginyazilim.css ortak marka kalıbıdır, değiştirmeyin — tüm Çılgın Yazılım projeleri onu paylaşır.

---

Örnek kullanım alanları

Bu kod, "dosya kabul eden" hemen her işin başlangıç noktası olabilir:

Bu kodu kullanırken eklemeniz gerekenler

Bu bir demodur; gerçek projede ayrıca şunlar gerekir:

• Yetkilendirme — Şu an dosya numarasını bilen herkes indirebilir. download.php içine oturum/sahiplik kontrolü ekleyin.
• Hız sınırı — Aynı IP'den saniyede onlarca yükleme engellenmiyor.
• Virüs taraması — ClamAV gibi bir tarayıcı, MIME doğrulamanın yakalayamadığı zararlı içerikleri yakalar.
• Depolama kotası — Kullanıcı başına toplam boyut sınırı.

---

Lisans

MIT — dilediğiniz gibi indirip kullanabilirsiniz.

Telif © Çılgın Yazılım (cilginyazilim.com)

github.com/CilginYazilim/secure-file-upload