Güvenli Dosya Yükleme Sistemi

---

Örnek dosyaları yükleyin; sonra uzantısı .png yapılmış bir PHP dosyasını deneyin.

---

İç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ı
• Arayüz özellikleri ve mobil uyum
• API uç noktaları
• Veritabanı şeması
• Kurulum
• Özelleştirme
• Örnek kullanım alanları
• Sürüm geçmişi

---

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 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, arama, süzgeçler, özet, ayarlar + önizleme pencereleri
├── .env.example               ← Veritabanı bilgileri (isteğe bağlı) — .gitignore içinde
├── 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 + mobil uyum
│   ├── js/upload.js           ← Sürükle-bırak, ilerleme, arama, süzgeç, tema, 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.

---

Arayüz özellikleri ve mobil uyum

Sürüm 1.1.0 ile arayüz masaüstünde olduğu kadar telefonda da kullanılabilir hâle getirildi. Aşağıda ne değişti ve daha önemlisi neden değişti yazılıdır.

Yeni arayüz özellikleri

Tema titremesi (FOUC) neden ` içinde çözüldü? Tercihi okuyan betik upload.js içine konsaydı sayfa önce işletim sistemi temasıyla çizilir, betik yüklendiğinde bir anda diğer temaya sıçrardı. Bu sıçramayı önlemenin tek yolu, ilk boyamadan önce çalışan satır içi bir betiktir — bu yüzden index.php içindeki o küçük ` bilerek oradadır.

Arama neden ESCAPE kullanıyor?

Aranan metin hazırlanmış ifade parametresi olarak geçer, yani SQL enjeksiyonu riski yoktur. Ama LIKE'ın kendi joker karakterleri (% ve _) parametre içinde de anlamlıdır:

Bu bir güvenlik açığı değil, doğruluk sorunudur; yine de sessizce yanlış sonuç vermek kabul edilebilir değildir.

Mobil düzenlemeler

Bu sayfada mobilin asıl sorunu "sığmamak" değil, dokunma hedeflerinin küçüklüğüydü: 34×34 piksellik indir/sil düğmeleri parmakla ıskalanıyordu. WCAG 2.5.5 en az 44×44 piksel önerir.

@media (hover: none) neden gerekli? Dokunmatik ekranda :hover bir kez tetiklendiğinde başka bir yere dokunulana kadar sürer — kullanıcı bir karta dokunur, kart yukarıda asılı kalır. Bu kural, kaldırma efektini yalnızca gerçek imleci olan cihazlarda çalıştırır.

---

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

İsteğe bağlı — kendi veritabanı bilgileriniz:
cp .env.example .env (Windows: copy .env.example .env) deyip DB_*
satırlarını doldurun. Bu dosya olmadan da çalışır; varsayılanlar yerel bir
XAMPP kurulumuna (root, boş parola) göredir. .env .gitignore
içindedir — parolanız depoya gitmez.

Veritabanı bilgilerini depo kökündeki .env dosyasına yazın; system/config.php
dosyasına dokunmanız gerekmez:

cp .env.example .env        # Windows: copy .env.example .env

Ayrıntı için aşağıdaki Ortam değişkenleri bölümüne bakın.

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

Ortam değişkenleri

Depo kökündeki .env dosyasına yazın; system/config.php dosyasına
hiç dokunmayın:

cp .env.example .env        # Windows: copy .env.example .env

.env .gitignore içindedir: depoya gönderilmez ve dağıtım (deploy) onu
silmez. system/config.php ise depoda durur ve her dağıtımda depodaki
sürümle değiştirilir — parolayı oraya yazarsanız hem GitHub'a gider hem de
ilk deploy'da kaybolur.

Dosyayı hiç oluşturmasanız da uygulama çalışır; aşağıdaki varsayılanlar
yerel bir XAMPP kurulumuna göredir.

Değer arama sırası: .env → sunucunun gerçek ortam değişkeni
(Apache SetEnv, systemd…) → buradaki varsayılan.

APP_TIMEZONE neden var? XAMPP'ın php.ini dosyasındaki
date.timezone, MySQL'in kullandığı sistem diliminden farklı olabilir.
Test makinesinde PHP Europe/Berlin, MySQL Europe/Istanbul
kullanıyordu; aynı anı anlatan iki satır bir saat farklı görünüyordu.
Zaman hesapları SQL tarafında yapıldığı için doğruydu, ama ekrana
basılan saat kayıyordu. Artık dilim açıkça sabitleniyor — sunucunuz başka
bir bölgedeyse bu değişkeni tanımlamanız yeterli, koda dokunmayın.

---

Ö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ı.

---

Sürüm geçmişi

Sürüm numarası tek bir yerde tutulur: system/config.php içindeki APP_VERSION. Arayüzün alt bilgisinde görünen değer de oradan okunur.

1.1.0

Arayüz

• Dosya adında arama — sunucu tarafında LIKE ... ESCAPE, 300 ms debounce, temizleme düğmesi
• Izgara / liste görünümü anahtarı, tercih localStorage'da saklanır
• Görsel önizleme penceresi — küçük resme tıklayınca tam boy, indirme bağlantısıyla birlikte
• Açık / koyu tema anahtarı — `` içinde erken uygulanır, tema titremesi (FOUC) yok
• Boş liste mesajı artık duruma göre değişir ("süzgeçlere uyan dosya yok" ↔ "henüz dosya yüklenmedi")
• Alt bilgiye örnek kod kütüphanesi ve uygulama sayfası bağlantıları eklendi
• Alt bilgide sürüm numarası gösterilir

Mobil

• Dokunma hedefleri 44 px'e çıkarıldı (WCAG 2.5.5)
• Özet şeridi 2×2 ızgara, dosya kartları 2 sütun (≤380 px'te tek sütun)
• Süzgeçler satır satır ayrıldı; tür/klasör düğmeleri yatay kaydırmalı
• Pencereler, alt bilgi ve bildirimler dar ekrana uyarlandı
• @media (hover: none) ile dokunmatikte "takılı kalan" hover efektleri kapatıldı
• theme-color üst verisi eklendi (mobil adres çubuğu rengi)

Erişilebilirlik

• Küçük resimler klavyeyle de açılabilir (role="button" + Enter/Space)
• Arama, sıralama ve görünüm anahtarlarına aria-label / `` bağları eklendi

Kod

• APP_VERSION sabiti eklendi (system/config.php)
• fetch_files() artık search süzgecini destekler; % ve _ jokerleri kaçırılır

1.0.0

• İlk sürüm: katmanlı güvenlik savunması, tür/tarih klasörleme, indirme sayacı, ayarlar ekranı
• Ölçülmüş ve kapatılan açıklar: Content-Disposition başlık enjeksiyonu, getimagesize() baypası, yükleme klasöründe eksik güvenlik başlıkları, CSRF reddinin 500 dönmesi

---

Lisans

MIT — dilediğiniz gibi indirip kullanabilirsiniz.

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

github.com/CilginYazilim/secure-file-upload · 📚 Örnek Kod Kütüphanesi