Artisan güvenliği ve operasyonları

Bir bakışta

Köprü, güvenilmeyebilecek HTML’i Chrome’da, iki bağımsız ağ engeli ve katı bir içerik politikası arkasında işler. Chrome’un işletim sistemi sanal alanı, sınırları açıkça belirtilmiş ayrı ve isteğe bağlı bir denetimdir. Bu sayfa söz konusu sınırı belgeler; sınırın mutlak olduğunu ileri sürmez.

Kavramsal genel bakış

İşleme, sunucu tarafında istek yürütmektir: uygulamanız, varsayılan olarak kaynak getirebilen bir tarayıcı motoruna HTML teslim eder. Güvenilmeyen girdi, giden bir kaynak getirme işlemini yönlendirdiğinde risk sunucu tarafı istek sahteciliğidir (SSRF): Common Weakness Enumeration (CWE) kaydı CWE-918 bunu, bir sunucunun, isteğin beklenen hedefe ulaştığına dair yeterli güvence olmadan sağlanan bir URL’nin içeriğini alması olarak tanımlar. SSRF (CWE-918), bir CWE Top 25 zayıflığıdır. Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS), sunucu bileşenlerinden giden istekleri denetimsiz bırakmak yerine denetlemenizi gerektirir. OWASP SSRF Prevention Cheat Sheet, rastgele hedeflere yapılan çağrıların ağ katmanında reddedilmesini güçlü bir denetim olarak ele alır. Aşağıdaki varsayılan olarak reddeden ağ duruşu, köprünün bu gereksinime verdiği yanıttır. National Institute of Standards and Technology (NIST) Special Publication (SP) 800-53 SC-7, köprünün taşıma katmanında uyguladığı aynı tümünü reddet, istisnayla izin ver sınır ilkesini tanımlar.

Veri yerleşikliği ve PII önlemleri

Köprüye geçirilen HTML, tamamen süreç içinde ve yerel Chrome örneğinde işlenir. Köprü kendi adına hiçbir giden ağ çağrısı yapmaz ve Chrome’un herhangi bir çağrı yapmasını engeller (aşağıdaki ağ modeline bakın); böylece girdi içeriği, işleyici üzerinden ana makineyi terk etmez. Girdideki kişisel olarak tanımlanabilir bilgiler (PII), ürettiğiniz Portable Document Format (PDF) çıktısına işlenir; bu nedenle çıktıyı, girdiyle aynı yerleşiklik denetimleriyle ele alın. Köprü, girdiyi veya çıktıyı diske kalıcı olarak yazmaz; kalıcı saklama, çağıranın sorumluluğundadır.

Güvenli telemetri ve günlük arındırma

ChromeHtmlRenderer ve BrowserPool, isteğe bağlı bir PHP Standard Recommendation (PSR)-3 LoggerInterface kabul eder. Köprü yalnızca operasyonel meta verileri günlüğe kaydeder: girdi bayt uzunluğu, hedef genişlik ve yükseklik, çıktı bayt uzunluğu, ölçülen içerik yüksekliği, yapılandırılan ikili dosya yoluyla tarayıcı başlatma, işleme sayısıyla yeniden başlatma bildirimleri ve kapatma olayları. HTML içeriğini, işlenen baytları veya çıkarılan metni günlüğe kaydetmez. Bu yaklaşım, hassas yükleri günlüklerin dışında tutarken operasyonel olayları günlüğe kaydetme yönündeki NIST SP 800-92 kılavuzuyla uyumludur. İkili dosya yolu günlüğe kaydedilir. Bunu hassas olmayan dağıtım meta verisi olarak ele alın. Testler, günlük çağrısı biçimlerini tests/Unit/Artisan/ChromeHtmlRendererTest.php::renderLogsDebugWithSizeWidthHeightAndPdfSize ve tests/Unit/Artisan/BrowserPoolTest.php::getBrowserLogsInfoOnLaunchWithBinaryPath içinde doğrular.

Ağ yalıtımı modeli (derinlemesine savunma)

Köprü, bir atlatma durumunda ana makinenin açığa çıkmaması için iki bağımsız engel uygular:

1. Content-Security-Policy. Her işleme, ChromeSecurityPolicy::wrapHtml() tarafından şu yönergeleri taşıyan bir belgeye sarılır:

   default-src 'none'; style-src 'unsafe-inline'; img-src data:;
   base-uri 'none'; form-action 'none'; frame-ancestors 'none';
   navigate-to 'none';

   Content Security Policy (CSP) yönergesi default-src 'none' tüm kaynak kökenlerini reddeder. img-src data: yalnızca satır içi görüntülere izin verir. navigate-to 'none' istemci tarafı gezinmeyi engeller. style-src 'unsafe-inline', Chrome printToPDF işlevinin satır içi stilleri uygulaması için gereken tek gevşetmedir. src/Artisan/ChromeSecurityPolicy.php içinde doğrulanmış ve ChromeSecurityPolicyTest::wrapHtmlIncludesNavigationCspDirectives tarafından test edilmiştir.

2. Chrome DevTools Protocol (CDP) taşıma engeli. İçerik yüklenmeden önce ChromeHtmlRenderer, Network.enable ve ardından Network.setBlockedURLs komutunu ['*'] deseniyle gönderir. Bu, CSP’den bağımsız olarak her alt kaynak URL’sini Chrome DevTools Protocol taşıma katmanında engeller. src/Artisan/ChromeHtmlRenderer::blockAllNetworkRequests() içinde doğrulanmış ve ChromeHtmlRendererTest::renderAutoFitsHeightAndBlocksNetworkRequests tarafından test edilmiştir (tam CDP yöntemi sırasını ve ['urls' => ['*']] parametresini denetler). Bu, OWASP SSRF kılavuzunun en güçlü denetim olarak önerdiği ağ katmanı engelidir ve NIST SP 800-53 SC-7 ile tutarlı, taşıma düzeyinde bir tümünü reddet engelidir.

Sonuç: girdideki uzak bir <img>, stil sayfası, yazı tipi, betik veya iframe URL’si yüklenmez. Köprü, bir etki alanı izin listesi veya özel IP filtresi uygulamaz; çünkü buna ihtiyacı yoktur: giden hiçbir alt kaynak getirme işlemine izin vermez.

Sapma notu: nextpdf/core içindeki writeHtmlChrome() belge bloğu, Chrome’un “dış kaynakları getireceğini” söyler ve “özel IP aralıklarını engellemek ve izin verilen etki alanlarını sınırlamak” için bir politika yapılandırmayı önerir. Bu, yapılandırılabilir bir izin listesi modelini tanımlar. Sürümle gönderilen Artisan ChromeSecurityPolicy bir izin listesi sunmaz; tüm alt kaynak isteklerini koşulsuz olarak engeller. Yetkili olan çekirdek belge bloğu değil, koddur. Bu sapma, çekirdek belge ekibi için kaydedilmiştir.

Girdi doğrulaması (Chrome öncesi)

ChromeSecurityPolicy::validate(), köprü Chrome’la iletişim kurmadan önce çalışır ve şunları reddeder:

Denetim	Sınır	Gerekçe
HTML boyutu	> maxHtmlSize (varsayılan 5 MB)	Kaynak tükenmesi sınırı (CWE Top 25 denetimsiz kaynak tüketimi)
Base64 veri URI’si	yakalama grubu >= 13_000_000 bayt	Açılma bombası sınırı
<meta http-equiv="refresh">	herhangi biri (büyük/küçük harf duyarsız, single/double tırnak)	Bir SSRF gezinme vektörü olan dahili uç noktalara istemci tarafı yönlendirmelerini engeller

Meta-refresh’in engellenmesi, açık bir SSRF güçlendirmesidir. Bu olmadan, saldırgan denetimindeki HTML, printToPDF öncesinde Chrome’u bir bulut meta veri uç noktasına yönlendirebilirdi. Sınır davranışı ChromeSecurityPolicyTest genelinde (validateThrowsOnOversizedHtml, validateRejectsMetaRefreshRedirect, validateRejectsMetaRefreshCaseInsensitive, validateRejectsMetaRefreshWithSingleQuotes, validateRejectsOversizedBase64DataUri, validateRejectsBase64DataUriAtExactThreshold) doğrulanmıştır.

Ayrıca, ChromeSecurityPolicy::wrapHtml(), bir stil bloğundan kaçışın betik bağlamına geçmesini önlemek için enjeksiyondan önce </style> öğesini defaultCss içinden çıkarır (ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss tarafından doğrulanmıştır).

Chrome sanal alan sınırı — açıkça belirtilmiştir

Chrome’un işletim sistemi sanal alanı, yukarıdaki ağ engellerinden ayrı bir denetimdir ve köprü bunu garanti etmez.

• Varsayılan olarak noSandbox değeri false olduğundan Chrome, kendi sanal alanı etkin olacak şekilde başlatılır. Köprü bu sanal alanı uygulamaz; ana makine çekirdeği desteğine bağlı olan Chrome ikili dosyasının sanal alanına dayanır.
• Değer noSandbox: true olarak ayarlandığında Chrome --no-sandbox ile başlatılır. Bu, Chrome süreç yalıtımı sanal alanını kaldırır. Sanal alanın başlatılamadığı kapsayıcılar için sağlanmıştır. Bu, yalıtımı gerçekten azaltır: bir işleyici ele geçirilmesi artık Chrome’un sanal alanı tarafından sınırlandırılmaz.
• Köprünün ağ engelleri (CSP + CDP engeli), sanal alanın etkin olup olmamasından bağımsız olarak yürürlükte kalır; ancak bunlar süreç yalıtımının yerini tutmaz. OWASP ASVS en az ayrıcalık kılavuzu geçerlidir: Chrome’u root olmayan bir kullanıcı olarak, kısıtlı bir kapsayıcı içinde çalıştırın, noSandbox seçeneğini yalnızca kaçınılmaz olduğu yerlerde kullanın ve bir --no-sandbox dağıtımını, girdiye daha yüksek güven duymayı gerektiren bir koşul olarak ele alın.

Bu belge, köprünün “varsayılan olarak güvenli” veya “kurcalamaya dayanıklı” olduğunu ileri sürmez. Sanal alanı devre dışı bırakmanın güvenli olduğunu da ileri sürmez. Mevcut denetimleri ve nerede sona erdiklerini belirtir. Sanal alanı destekleyen bir kapsayıcı sağlama, /integrations/artisan/chrome-renderer-setup/ sayfasında ele alınmıştır.

Hata modları

Bu hata modları src/Artisan/Exception/ ile render/transport kodundan çıkarılmıştır:

Koşul	Şu şekilde ortaya çıkar	Kaynak
chrome-php/chrome kitaplığı yok	ChromeNotAvailableException (kurulum komutuyla birlikte)	BrowserPool::getBrowser()
HTML şu sınırı aşıyor: maxHtmlSize	RuntimeException (“exceeds maximum allowed size”)	ChromeSecurityPolicy::validate()
Aşırı boyutlu base64 veri URI’si	RuntimeException (“oversized base64 data URI”)	ChromeSecurityPolicy::validate()
Yasaklanmış meta-refresh	RuntimeException (“forbidden meta refresh redirect”)	ChromeSecurityPolicy::validate()
Chrome başlatma / zaman aşımı / çökme	ChromeRenderException (nedeni sarmalayarak)	ChromeHtmlRenderer::render()
Chrome boş PDF döndürdü	ChromeRenderException (“returned empty data”)	ChromeHtmlRenderer::render()
Sayfanın içerik akışı yok	PdfParseException	PageImporter::import()

İşleme sırasında ChromeRenderException oluşturulursa, değiştirilmeden yeniden fırlatılır. Diğer her Throwable, önceki istisnayı koruyarak ChromeRenderException olarak sarmalanır (ChromeHtmlRendererTest::renderRethrowsChromeRenderExceptionWithoutWrapping ve ::renderWrapsUnexpectedThrowablesWithChromeRenderException tarafından doğrulanmıştır). Chrome sayfası, hata durumunda bile her zaman bir finally bloğu içinde kapatılır.

Kaynak sınırları

• Girdi boyutu: maxHtmlSize (varsayılan 5 MB) ve 13 MB base64 veri URI’si üst sınırı.
• Süre: renderTimeout saniye, hem içerik yüklemesini hem de CDP eşitleme çağrılarını sınırlar. CDP denetim komutları, sabit 5 saniyelik bir zaman aşımı kullanır.
• Süreç: BrowserPool, bellek artışını sınırlamak için Chrome’u her 100 işlemede bir yeniden başlatır ve süreci close() sırasında ya da yok edilirken kapatır.

Bunlar sınırlardır, kotalar değildir. Güvenilmeyen girdiye açık her yol için, CWE Top 25 kaynak tüketimi kılavuzuyla tutarlı şekilde, yine de ana makine düzeyinde bir kaynak sınırı (cgroup, ulimit, istek bütçesi) kullanın.

Gözlemlenebilirlik kancaları

İşleme başlangıcını (boyut, genişlik, yükseklik), işleme tamamlanmasını (çıktı boyutu, içerik yüksekliği), tarayıcı başlatmayı (ikili dosya yolu), tarayıcı yeniden başlatmayı (işleme sayısı) ve tarayıcı kapatmayı (işleme sayısı) yakalamak için bir PSR-3 günlükleyici ekleyin. Yayılan tek olaylar bunlardır ve hiçbir yük içeriği taşımazlar. Bunları, gecikmeye ilişkin hizmet düzeyi hedefleri (SLO’lar) ve yeniden başlatma oranı uyarıları için kullanın.

Uygunluk

İddia	Referans	clause_id	reference_id
Sunucu bileşenlerinden giden istekler denetlenmelidir	OWASP ASVS 5.0	§ (SSRF/giden denetimi)
SSRF = sunucu, hedefi doğrulamadan sağlanan bir URL’yi alır	CWE Top 25 2025 (CWE-918)	cwe_top25_2025#x28.x2.p2
SSRF (CWE-918) bir CWE Top 25 zayıflığıdır	CWE Top 25 2025	cwe_top25_2025#x1.p73
Denetimsiz kaynak tüketimi bir CWE Top 25 zayıflığıdır	CWE Top 25 2025 (CWE-400)	cwe_top25_2025#x19.x2.p2
Varsayılan olarak reddet sınır koruması (istisnayla izin ver)	NIST SP 800-53 Rev 5 SC-7	SC-7
Rastgele hedeflere yapılan çağrıların ağ katmanında reddi, güçlü SSRF denetimidir	OWASP Cheat Sheet Series (SSRF Prevention §Network layer)	owasp_cheatsheet_series#x132.x2
URL getiren bileşenleri SSRF’ye karşı koruyun	OWASP Cheat Sheet Series	§ (SSRF önleme, URL getirme araçları)
Güvenilmeyen içerik işlemeyi yalıtın, en az ayrıcalık	OWASP ASVS 5.0	§ (sanal alan / en az ayrıcalık)
Operasyonel olayları günlüğe kaydedin; yükleri günlüklerin dışında tutun	NIST SP 800-92	§ (günlük içeriği kılavuzu)

Alıntılar NextPDF uygunluk motoru üzerinden alınmıştır (korpus bildirimi 1d05b7c4…d790b6); madde metni anlamı korunarak aktarılmıştır, asla doğrudan alıntılanmamıştır.

Tehdit modeli

Tehdit	Denetim	Artık risk
Uzak alt kaynak yoluyla SSRF	CSP default-src 'none' + CDP setBlockedURLs('*')	Her iki engeli de aşan bir Chrome motoru hatası (derinlemesine savunma riski azaltır ancak ortadan kaldırmaz)
Meta-refresh gezinmesi yoluyla SSRF	Chrome öncesi doğrulama etiketi reddeder	Desenle eşleşmeyen yeni bir gezinme vektörü
Kaynak tükenmesi	Girdi boyutu + base64 üst sınırları + zaman aşımı + 100 işlemede yeniden başlatma	Ana makine başına kota yok; cgroup/ulimit ile birlikte kullanın
İşleyici sürecinin ele geçirilmesi	Chrome sanal alanı etkin olduğunda	noSandbox: true bu denetimi tamamen kaldırır
Stil kaçışı / enjeksiyon	</style> öğesinin defaultCss içinden çıkarılması; CSP betiği engeller	Çıkarılmayan, gelecekteki bir vektör yoluyla enjeksiyon

FIPS modu davranışı

Köprü hiçbir kriptografik işlem yapmaz. Chrome aracılığıyla PDF baytları üretir ve bunları gömer. İmzalama, şifreleme ve Federal Information Processing Standards (FIPS) modu davranışı çekirdek/Premium konularıdır ve Artisan tarafından etkilenmez.

Ayrıca bakın

• /integrations/artisan/configuration/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/production-usage/
• /integrations/artisan/overview/