Laravel’da güvenlik açıklarını tespit etmek için statik kontroller gerçekleştiren, yalnızca bir PHP dosyası içeren ve sıfır çalışma zamanı bağımlılığı olan laravel-audit aracı, jargona göre dar bir alanı hedef alıyor. Peki, bu yapı neden kapsamlı Laravel güvenlik çerçevelerinden daha üstün?
Laravel, yapılandırma seçenekleriyle oldukça cömerttir. Her yapılandırmanın güvenli bir varsayılanı, çevresel bir aşırı yazımı, belgelenmiş bir gerekçesi ve ulaşmanın üç yolu bulunur. Framework, genellikle bu kontrolleri tehlikeli bir pozisyonda çalıştırır ve çoğu zaman bunu bile uyarmadan gerçekleştirir. Üretim ortamında APP_DEBUG=true içeren bir .env.example dosyasıyla çalışan Laravel uygulamaları gördüm; bu ortam değişkeni, dev ortamı ileriye taşıyan bir geçiş sürecindeki ölü hataları kapatmak amacıyla 'strict' => false olarak ayarlandı; TLS bulunmadığından 'secure' => false olarak oturum çerezleri, bir Stripe webhook’un neden başarısız olduğunu anlayamayan bir geliştirici tarafından çözüldü. Beş dakikalık bir statik kontrol, bu yanlışlıkları tespit edebilirdi, fakat mevcut araçlar beş dakikalık araçlar değil.
laravel-audit, bu boşlukta var olmasını istediğim bir araçtır. Tek dosyalık bir PHP CLI (birkaç küçük kontrol sınıfı ile birlikte), projenizin dosyalarını Laravel’i başlatmadan okur, otomatik olarak GitHub Actions belirlemeleri çıkarır ve tam olarak 17 kontrol içerir.
On yedi. 170 değil. Bu sayı önemli.
GitHub: https://github.com/sen-ltd/laravel-audit
Laravel “çok fazla ip” problemi
Laravel’ın yapılandırma yüzeyi çok geniştir. config/app.php, config/session.php, config/database.php, config/logging.php, config/filesystems.php, config/auth.php, config/cache.php, config/queue.php, app/Http/Kernel.php (veya Laravel 11+’da bootstrap/app.php), ve bunların hepsini yönlendiren .env ve .env.example dosyası. Bu yerlerin her birinde yanlış bir yapılandırma ile güvenli olmayan bir ürün göndermenin belgelenmiş bir yolu vardır.
Son birkaç yılda gözlemlediğim bazı gerçek örnekler:
.env.exampledosyasınaAPP_DEBUG=trueeklenmesi, geliştirici “şu anda çalışsın” diye düşündü. Acele bir dağıtımda, birisi.env.example‘ı.env‘a kopyaladı veDB_*değerlerini ayarladı, fakatAPP_DEBUG’yu değiştirmeyi unuttu. Artık Laravel’in hata ayıklama ekranı, her türlü hatada ortam değişkenlerini ve yığın izlerini sızdırıyor.config/database.php‘da'strict' => falseolması. Bir geliştirici bunu altı ay önce “only_full_group_by” hatasını bastırmak için kapatmış, kimse tekrar açmamış ve artık uygulama, DATETIME sütunlarına boş tarihleri yazar.'same_site' => 'none'ayarınınconfig/session.php‘da olması, çünkü bir üçüncü taraf embed, çapraz-site çerezlere ihtiyaç duyuyordu ve kimse bunu ana site için geri almadı.VerifyCsrfToken::$except = ['*']ayarı, 419 hatası alırken Stack Overflow’da bulduğu bu çözüm yüzünden yapıldı.LOG_CHANNEL=singleüretimde mevcut, çünkü Laravel varsayılanıstackfakat eski bir.envdosyası güncellenmedi ve artık devamsız birlaravel.logher gece/var/log’u dolduruyor.DB_PASSWORD=password.env.exampleiçinde, ardından dağıtım betiği bunu değiştirmedi.
Her biri bir metin dosyasını okuyarak tespit edilebilir. Çalışma zamanı enstrümantasyonu, test takımı, bağlantı analizi yok — sadece dosyayı aç, anahtarı bul, değeri kontrol et.
“Büyük güvenlik çerçevesi” tuzağı
Enlightn ve Larastan gibi araçlar son derece yeteneklidir. Enlightn 120’den fazla kontrol içerir ve laravel-audit’in asla dokunmayacağı alanları kapsar; N+1 sorgu tespiti, Blade XSS taraması, performans analizi. Larastan, Eloquent modelleriniz üzerinde PHPStan seviyesinde tür çıkarımı yapar. Eğer zaten bunları CI’de çalıştırıyorsanız, geçiş yapmayın. Bu araçlar, laravel-audit’in yapamayacağı şeyleri yakalar.
Fakat bu araçların bir şekil sorunu var: “Sadece .env.example dosyasının APP_DEBUG=true olup olmadığını kontrol et” işini gerçekleştirirken. Enlightn’i çalıştırmak için bir Laravel uygulaması başlatmanız gerekir. Bu da demektir ki composer install, geçerli bir .env, çalışan bir veritabanı bağlantısı (veya taklit), ve genellikle birçok bağımlılığın yüklenmesi gerekir. Larastan da tam Composer ağını istiyor ve ayrıca bir PHPStan konfigürasyonu yoksa çalışamaz. Her ikisi de projeniz hakkında “lütfen yirmi şeyi kontrol et” ifadesinin çok ötesinde fikirlere sahiptir.
Bir çekim talebinde ön-ünlem CI bağlantısı için, bu yük bir vergi oluyor. Geliştiriciler bunu hissediyor, ekipler yavaş işleri devre dışı bırakıyor ve denetim katmanı sessizce bozuluyor.
17 el ile seçilmiş statik kontrol ve sıfır çalışma zamanı bağımlılığı olan bir araç, yeni bir yükleme sırasında bir saniyeden daha kısa sürede çalışabilir. Bu aracı, herhangi bir CI sisteminin pre-commit aşamasına entegre edebilir, her şeyden önce çalıştırabilir ve kontrol edilen her şeyi tek bir composer install yapmadan önce yürütebilirsiniz. Bu, başka tür bir araçtır ve büyük çerçevelerle birlikte var olur, bunları değiştirmez.
Tasarım
Bu aracın ana hatları dört hareketli parçadan oluşur: bir proje dedektörü, bir kontrol arayüzü, bir dizi kontrol sınıfı ve üç çıktı biçimlendirici.
Kontrol Arayüzü
namespace SenLtd\LaravelAudit;
interface CheckInterface
{
public function id(): string;
public function category(): string;
<span class="cd">/
* @return Finding[]
*/</span>
<span class="k">public</span> <span class="k">function</span> <span class="n">run</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$projectPath</span><span class="p">):</span> <span class="kt">array</span><span class="p">;</span>
}
Her kontrol, Finding nesne dizileri döndürmektedir. Bir Finding, bir kontrol kimliği, bir kategori, bir ciddiyet (error/warning/info/pass), bir başlık, ayrıntılı bir mesaj ve isteğe bağlı bir düzeltme ipucu içerir. İşte tüm kelime hazinesi.
final class Finding
{
public const SEVERITY_ERROR = 'error';
public const SEVERITY_WARNING = ;
public const SEVERITY_INFO = ;
public const = ;
<span class="k">public</span> <span class="k">function</span> <span class="n">__construct</span><span class="p">(</span>
<span class="k">public</span> <span class="k">readonly</span> <span class="kt">string</span> <span class="nv">$checkId</span><span class="p">,</span>
<span class="k">public</span> <span class="k">readonly</span> <span class="kt">string</span> <span class="nv">$category</span><span class="p">,</span>
<span class="k">public</span> <span class="k">readonly</span> <span class="kt">string</span> <span class="nv">$severity</span><span class="p">,</span>
<span class="k">public</span> <span class="k">readonly</span> <span class="kt">string</span> <span class="nv">$title</span><span class="p">,</span>
<span class="k">public</span> <span class="k">readonly</span> <span class="kt">string</span> <span class="nv">$message</span><span class="p">,</span>
<span class="k">public</span> <span class="k">readonly</span> <span class="kt">string</span> <span class="nv">$fixHint</span> <span class="o">=</span> <span class="s1>''</span><span class="p">,</span>
<span class="p">)</span> <span class="p">{}</span>
}
PHP 8.2 ile katı türler, yalnızca okunabilir özellikler kullanıldı. Yapıcı, bilinmeyen ciddiyetleri InvalidArgumentException ile reddeder, böylece yeni bir kontrolde bir yazım hatası sessizce rapor vermektense açık bir şekilde hata verir.
Geçersiz bulunanlar bulunmaktadır; çünkü her kontrol bir şey döndürmelidir — ya bir sorun ya da “bunu inceledim, her şey yolunda” dediğimiz bir rapor. CI çalıştırıcısı yalnızca --fail-on ile belirtilen ciddiyetlere göre hata verir, ancak rapor her zaman her kontrolü listeler, böylece göz atıldığında hangi kontrollerin yapıldığını görebilirsiniz. Sessiz kontroller bir denetim aracında tehlikeli. Temiz raporda saatlerimi harcadım; aslında temiz olduğu için değil, kontrol atlandığı için.
Belirli bir kontrol: APP_DEBUG
İlk yazdığım kontrolün tüm uygulaması şu şekildedir:
final class AppDebugCheck implements CheckInterface
{
public function id(): string{ return ; }
public function category(): string{ return ; }
<span class="k">public</span> <span class="k">function</span> <span class="n">run</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$projectPath</span><span class="p">):</span> <span class="kt">array</span><span class="p">
{</span>
<span class="nv">$env</span> <span class="o">=</span> <span class="nc">EnvFile</span><span class="o">::</span><span class="nf">load</span><span class="p">(</span><span class="nv">$projectPath</span> <span class="mf">.</span> <span class="s1>'/.env.example'</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="nv">$env</span> <span class="o">===</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">[</span><span class="k">new</span> <span class="nc">Finding</span><span class="p">(</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">id</span><span class="p">(),</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">category</span><span class="p">(),</span>
<span class="nc">Finding</span><span class="o">::</span><span class="no">SEVERITY_WARNING</span><span class="p">,</span>
<span class="s1>'APP_DEBUG: no .env.example'</span><span class="p">,</span>
<span class="s1>'Could not find .env.example to inspect APP_DEBUG default.'</span><span class="p">,</span>
<span class="s1>'Commit a .env.example with APP_DEBUG=false as the safe default.'</span><span class="p">,</span>
<span class="p">)];</span>
<span class="p">}</span>
<span class="nv">$value</span> <span class="o">=</span> <span class="nv">$env</span><span class="o">-></span><span class="nf">get</span><span class="p">(</span><span class="s1>'APP_DEBUG'</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="nv">$value</span> <span class="o">===</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">[</span><span class="k">new</span> <span class="nc">Finding</span><span class="p">(</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">id</span><span class="p">(),</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">category</span><span class="p">(),</span>
<span class="nc">Finding</span><span class="o">::</span><span class="no">SEVERITY_WARNING</span><span class="p">,</span>
<span class="s1>'APP_DEBUG: not set in .env.example'</span><span class="p">,</span>
<span class="s1>'APP_DEBUG is missing from .env.example. Developers may copy it without knowing to set it.'</span><span class="p">,</span>
<span class="s1>'Add APP_DEBUG=false to .env.example.'</span><span class="p">,</span>
<span class="p">)];</span>
<span class="p">}</span>
<span class="nv">$normalized</span> <span class="o">=</span> <span class="nb">strtolower</span><span class="p">(</span><span class="nv">$value</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="nv">$normalized</span> <span class="o">===</span> <span class="s1>'true'</span> <span class="o">||</span> <span class="nv">$normalized</span> <span class="o">===</span> <span class="s1>'1'</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">[</span><span class="k">new</span> <span class="nc">Finding</span><span class="p">(</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">id</span><span class="p">(),</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">category</span><span class="p">(),</span>
<span class="nc">Finding</span><span class="o">::</span><span class="no">SEVERITY_ERROR</span><span class="p">,</span>
<span class="s1>'APP_DEBUG=true in .env.example'</span><span class="p">,</span>
<span class="s1>'Committing APP_DEBUG=true as the default will leak stack traces and env values if used in prod.'</span><span class="p">,</span>
<span class="s1>'Set APP_DEBUG=false in .env.example.'</span><span class="p">,</span>
<span class="p">)];</span>
<span class="p">}</span>
<span class="k">return</span> <span class="p">[</span><span class="k">new</span> <span class="nc">Finding</span><span class="p">(</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">id</span><span class="p">(),</span>
<span class="nv">$this</span><span class="o">-></span><span class="nf">category</span><span class="p">(),</span>
<span class="nc">Finding</span><span class="o">::</span><span class="no">SEVERITY_PASS</span><span class="p">,</span>
<span class="s1>'APP_DEBUG default is safe'</span><span class="p">,</span>
<span class="s2">".env.example sets APP_DEBUG=</span><span class="si">{</span><span class="nv">$value</span><span class="si">}</span><span class="s2">."</span><span class="p">,</span>
<span class="p">)];</span>
<span class="p">}</span>
}
Projedeki her kontrolün yapısı bu şekildedir: bir dosyayı yükle, bir değeri incele, bir Finding döndür. Laravel servis konteyneri, yansıma, soyut baz sınıflar yok. On altııncı kontrolü istemiyorsanız bu dosyayı kopyalayıp yeni bir kimlik verip yeni bir anahtara yönlendirebilirsiniz. Alt sınıf oluşturmak veya yapılandırmak yok.
EnvFile yardımcı aracı 50 satırlık temel PHP kodudur — bir .env tarzı dosyayı satır satır okur, yorumları temizler, alıntılanmış değerlerle uğraşır ve ayrıştırılamayan satırları görmez. Denetim amaçları için, sadece geliştiricinin taahhüdü olan statik atamaları okumak istiyoruz ve bu kenar durumları, taahhüt edilen örnek dosyalarda görülmez.
Denetleyici çalıştırıcı
final class Auditor
{
public function __construct(private readonly array $checks) {}
<span class="k">public</span> <span class="k">static</span> <span class="k">function</span> <span class="n">withDefaults</span><span class="p">():</span> <span class="kt">self</span>
<span class="p">{</span>
<span class="k">return</span> <span class="k">new</span> <span class="nc">self</span><span class="p">([</span>
<span class="k">new</span> <span class="nc">Checks\AppDebugCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\AppEnvCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\AppKeyCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\EnvFileNotCommittedCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\SessionSecureCookieCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\SessionHttpOnlyCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\SessionSameSiteCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\DatabaseStrictCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\DatabasePasswordCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\LoggingChannelCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\LoggingLevelCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\ComposerLockCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\ComposerRequireCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\TrustProxiesCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\EncryptCookiesCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\CsrfMiddlewareCheck</span><span class="p">(),</span>
<span class="k">new</span> <span class="nc">Checks\StoragePermissionsCheck</span><span class="p">(),</span>
<span class="p">]);</span>
<span class="p">}</span>
<span class="k">public</span> <span class="k">function</span> <span class="n">run</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$projectPath</span><span class="p">,</span> <span class="kt">?array</span> <span class="nv">$onlyCategories</span> <span class="o">=</span> <span class="kc">null</span><span class="p">):</span> <span class="kt">array</span>
<span class="p">{</span>
<span class="nv">$findings</span> <span class="o">=</span> <span class="p">[];</span>
<span class="k">foreach</span> <span class="p">(</span><span class="nv">$this</span><span class="o">-></span><span class="n">checks</span> <span class="k">as</span> <span class="nv">$check</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nv">$onlyCategories</span> <span class="o">!==</span> <span class="kc">null</span> <span class="o">&&</span> <span class="o">!</span><span class="nb">in_array</span><span class="p">(</span><span class="nv">$check</span><span class="o">-></span><span class="nf">category</span><span class="p">(),</span> <span class="nv">$onlyCategories</span><span class="p">,</span> <span class="kc">true</span><span class="p">))</span> <span class="p">{</span>
<span class="k">continue</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">foreach</span> <span class="p">(</span><span class="nv">$check</span><span class="o">-></span><span class="nf">run</span><span class="p">(</span><span class="nv">$projectPath</span><span class="p">)</span> <span class="k">as</span> <span class="nv">$f</span><span class="p">)</span> <span class="p">{</span>
<span class="nv">$findings</span><span class="p">[]</span> <span class="o">=</span> <span class="nv">$f</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">return</span> <span class="nv">$findings</span><span class="p">;</span>
<span class="p">}</span>
}
Bu, tüm işleyiştir. Varsayılan kural seti, yeni bir kontrol eklemenin kolay bir inceleme alanına sahip olmasını istiyorum. YAML konfigürasyon dosyası “daha esnek” olabilirdi, fakat esneklik “tüm kural setini elli satırda görebilir miyim” özelliğine zarar veriyor, bu beklediğimden daha değerli çıkıyor.
--only bayrağı, kategoriye göre filtreler, kimliğe göre değil, bu yüzden --only session,database diyerek CI çalışmanızı, ilgili yapılandırmanın değiştiği kısma sınırlayabilirsiniz.
Değişim
Bu, “ne yapamayacağı” bölümü, çünkü küçük bir aracın sınırlı olmadığını söylemek, küçük araçların büyük çerçevelere dönüşmesine yol açıyor.
Çalışma zamanı yapılandırma denetimi yok. Laravel’ın yapılandırması .env → config/*.php → çalışma zamanı birleştirmeleri → önbellek. laravel-audit yalnızca dosyaları okur; config('session.secure') çalıştırmaz ve sonuç değerine bakmaz. Eğer config/session.php‘da, üç ortam değişkenine bağlı karmaşık bir mantık varsa, laravel-audit kaldıkları tam PHP ifadesini görecektir ve ya regexi eşleşip ya da durumu tamamen atlayacaktır. Her kontrol bir dize eşleşmesi veya dosya içeriği üzerine sığ bir regex’dir. Laravel’i başlatmamanın maliyeti budur.
Dosya arası analiz yok. Eğer bir yol, middleware’i grup haritasında yoksa kayıttan geçmez, laravel-audit bunu fark etmeyecektir. Çalışma zamanı session.php‘yi geçersiz kılan özel bir hizmet sağlayıcınız varsa bunları ayrıca tespit edemeyecektir. Enlightn, Laravel’ın tam hizmet konteynırına yüklü olduğu için bunları tespit eder.
Varsayılan olarak composer danışmanlık entegrasyonu yok. Bilerek laravel-audit‘yi composer audit ile entegre etmedim. Bu, denetim zamanında ya bir Composer kurulumunu gerektirir (bu “bozuk projede çalışabilir” özelliğini kırar) ya da bir ağ çağrısı gerektirir (bu da çevrimdışı CI’yi bozar). ComposerLockCheck sadece composer.lock dosyasının varlığını kontrol eder ve composer.json‘un içinde bir require bloğu olduğuna bakar. Bu, en ucuz yüksek-değerli bir sinyaldir.
Regex kırılganlığı. SessionSecureCookieCheck gibi bir kontrol, 'secure' => false arar ancak config/session.php‘da karşısına çıkan. Eğer birisi 'secure' => false yerine çift tırnak kullanırsa, regex bunu atlayacaktır. Burada gerçek bir yanlış negatif sınıfı vardır. Yaygın deyimleri kapsamaya çalıştım, ama eğer egzotik Laravel kodu yazıyorsanız, araç düşük rapor verecektir. Yanlış pozitiflerden daha iyi yanlış negatifleri göndermeyi tercih ederim — gürültülü bir linter devre dışı bırakılır, sessiz bir linter güvendi kazanır.
30 saniyede dene
Docker en kolay yoldur:
docker build -t laravel-audit https://github.com/sen-ltd/laravel-audit.git
docker run --rm -v $(pwd):/project laravel-audit /project
Görüntü 52 MB — çok aşamalı bir Alpine derlemesi php:8.2-cli-alpine ile başlıyor ve ince bir PHP yüklemesini normal alpine:3.19 runtime’a kopyalıyor. Composer ve PHPUnit yalnızca inşa eden aşamada bulunur; runtime görüntüsü yalnızca PHP, denetim kaynak ağacı ve testleri, belgeleri ve örtü aletlerini kaldırılmış vendor/ dizinini içerir.
Yerel geliştirme için:
git clone https://github.com/sen-ltd/laravel-audit.git
cd laravel-audit
composer install
vendor/bin/phpunit --no-coverage
php bin/laravel-audit /path/to/your/laravel/app
Binary, hedefte composer install gerektirmeden çalışır — bin/laravel-audit skripti kendi src/ dizinine yönlendiren küçük manuel bir PSR-4 otomatik yükleyici kaydeder. Composer yalnızca PHPUnit için gereklidir.
CI bağlantısı
GitHub Actions çıktı formatı, bu aracı inşa etmemin sebebidir:
- name: laravel-audit
run: |
git clone https://github.com/sen-ltd/laravel-audit.git /tmp/audit
php /tmp/audit/bin/laravel-audit . --format github --fail-on error
--format github parametresi, GitHub Actions’un alabileceği ::error title=...::... satırlarını çıkarır. Özel bir eyleme veya raporlayıcı eklentisine ihtiyacınız yok; bu, düz standart çıkıştır.
Gelecek için yapacaklarım
Eğer kontrol listemi genişletmeye gideceksem, sıradaki beş kontrolüm; config/cors.php için bir CORS konfigürasyonunun doğruluğunu kontrol etmek, çok sunuculu kurulumlarda CACHE_DRIVER=file ayarına bir önlem almak, üretime sızacak QUEUE_CONNECTION=sync uyumlu olup olmadığını görmek, depolama APP_URL ayarı için varsayılan http://localhost kontrolü yapmak ve alternatifi yapılandırılmadığı durumlarda bir MAIL_MAILER=log kontrolü gerçekleştirmek. Her biri gerçekten üretimde rastlaşılacak bir hatayı yakalayan küçük statik kontrol. Hiçbiri laravel-audit’i Enlightn yapmak için büyümeyecek.
Küçük araç küçük kalır. Ana fikir bu.
— SEN 合同会社
Kaynak: Orijinal Makale
