NextPDF Gotenberg güvenliği ve operasyonları

Genel bakış

Bu köprü, belgeleri uygulamanızdan ağ üzerinden harici bir hizmete gönderir. Bu da onu hem sunucu tarafı istek yüzeyi hem de aktarım güvenliği yüzeyi hâline getirir. Paket, her ikisi için de belirli ve doğrulanabilir denetimler uygular. Tüm sistemi tek başına güvenli hâle getirmez. Bu denetimler yalnızca Gotenberg’i uygun koruyucu önlemlerle dağıtıp işlettiğinizde çalışır. Bu sayfa, paketin uyguladığı denetimleri ve bunları tamamlayan operasyonel görevleri açıklar.

Buradaki hiçbir ifade garanti niteliği taşımaz. Her denetim, tanımlı sınırlara sahip ve testlerle kapsanmış belirli bir davranıştır.

İki ilke katmanı

Köprü, farklı katmanlarda iki ayrı güvenlik ilkesi uygular:

Aktarım ilkesi (GotenbergSecurityPolicy) — URL şeması zorlaması, sunucu tarafı istek sahteciliği (SSRF) taraması, etki alanı adı sistemi (DNS) yeniden bağlama savunması, giriş boyutu sınırları ve dosya adı taraması. Aşağıda ayrıntılı olarak belgelenen katman budur.
HTML ayrıştırma ilkesi — ayrıştırma katmanındaki bir içerik ilkesidir; varsayılan olarak NextPDF çekirdeğinin varsayılan ilkesine ayarlıdır ve içerik bir işleyiciye ulaşmadan önce çalışır. Aktarım ilkesini tamamlar ancak ondan bağımsızdır. Bu sayfa aktarım ilkesini kapsar.

Sunucu tarafı istek sahteciliği (SSRF) taraması

Köprü, süreçten herhangi bir bayt çıkmadan önce yapılandırılmış API URL’sini tarar. Denetimin üç bölümü vardır.

Şema zorlaması. Yalnızca https kabul edilir (büyük/küçük harfe duyarsız). Düz bir http:// URL’si reddedilir. Bu nedenle aktarım katmanı güvenliği (TLS), her dönüştürme ve sağlık yoklaması için zorunludur.

Adres taraması. Ana makine bir IP değişmeziyse, köprü onu özel veya ayrılmış bir aralığa giriyorsa reddeder. Ana makine bir ad ise, köprü A ve AAAA kayıtlarının tümünü çözer ve çözülen adreslerden herhangi biri özel veya ayrılmışsa isteği reddeder. Tek bir adres yerine tüm kayıt kümesini çözmek, genel bir adres de döndüren bir adın arkasına özel adres gizleyen saldırganı etkisiz kılan denetimdir. Bu, OWASP SSRF önleme rehberinin yaklaşımını izler: etki alanı adının arkasındaki her IP adresini alın (IPv4 ve IPv6 için A ve AAAA kayıtları) ve her birini bir izin listesine göre doğrulayın (OWASP Cheat Sheet Series, SSRF prevention, uygulama katmanı savunması; sayfanın RAG yan dosyasında sabitlenmiştir).

Denetim anı/kullanım anı (TOCTOU) yeniden denetimi. Köprü, istekten hemen önce, doğrulama sırasında yakalanan adres kümesini yeniden çözer ve karşılaştırır. Yeni bir adres görünürse, istek bir DNS yeniden bağlama hatasıyla iptal edilir. Bu, yeniden bağlama saldırısının aksi hâlde kötüye kullanacağı doğrulama ile bağlantı arasındaki pencereyi kapatır.

Köprü, cURL ile sabitlenmiş aktarımı kullandığında, doğrulanan adres kümesi CURLOPT_RESOLVE ile bağlantıya bağlanır; böylece çekirdek, bağlantı anında yeni bir DNS aramasının döndürebileceği adrese değil, denetlenmiş adrese bağlanır. Bu aktarımda yönlendirme izleme devre dışıdır (CURLOPT_FOLLOWLOCATION kapalı, CURLOPT_MAXREDIRS sıfır); böylece bir 3xx yanıtı isteği sessizce denetlenmemiş bir ana makineye yönlendiremez. Bunun yerine yanıt ilke katmanına döner.

Operasyonel sonuç. SSRF koruması, özel ve ayrılmış adresleri tasarım gereği reddeder. Gotenberg’iniz özel bir ağda çalışıyorsa, köprüyü onun özel adresine yönlendiremezsiniz. Onu, korumanın kabul ettiği bir adres üzerinden açığa çıkarın ve o yolu, aşağıda dağıtım altında açıklandığı gibi ağ bölümlemesi ve kimlik doğrulamayla koruyun.

Aktarım güvenliği ve genel anahtar sabitleme

cURL ile sabitlenmiş aktarımda TLS eş ve ana makine doğrulaması her zaman açıktır (CURLOPT_SSL_VERIFYPEER true, CURLOPT_SSL_VERIFYHOST 2). Standart zincir doğrulamasına ek olarak, köprü SubjectPublicKeyInfo (SPKI) sabitlemesini destekler.

Her sabit, sunucunun SubjectPublicKeyInfo değerinin bir SHA-256 karmasıdır ve sha256/<base64> biçiminde ifade edilir. Köprü, bir sertifikanın SPKI karması birincil ve yedek sabitlerden oluşan birleşik kümedeki herhangi bir sabitle eşleştiğinde sertifikayı kabul eder. Bu yedek sabit modeli, RFC 7469 §4.3 bölümünü izler; bu bölüm bir yedek sabiti, yani ikincil ve henüz dağıtılmamış bir anahtar çiftinin parmak izini, istenmeyen bir sabit doğrulama hatasında birincil kurtarma yolu olarak tanımlar ve §2.5 bölümünü izler; bu bölüm de sabitlenmiş kümenin geçerli sertifika zincirinde bulunmayan en az bir sabit içermesini gerektirir (RFC 7469 §4.3 ve §2.5; sayfanın RAG yan dosyasında sabitlenmiştir). Köprünün kodu, en az bir yedek sabit ve birleşik küme kesişimi semantiği için RFC 7469 §2.1 ve §2.6 bölümlerini bildirir. Sabitleme isteğe bağlıdır: yapılandırılmış sabit olmadığında standart zincir doğrulaması geçerli olur ve sabitleme zorlanmaz.

Ayrıştırılamayan bir sabit, herhangi bir istek gönderilmeden önce bir yapılandırma hatası oluşturur. SPKI değeri yapılandırılmış hiçbir sabitle eşleşmeyen canlı bir sertifika, aktarımın isteği başarısız kılmasına yol açar; bu tasarım gereğidir.

Sabit döndürme yordamı

Hatalı bir döndürme, köprüyü hizmet dışı bırakır. Kesinti olmadan döndürün:

Sunucu anahtarını değiştirmeden önce, yeni anahtar için SPKI sabitini oluşturun ve yedek sabit listesine ekleyin. Bu yapılandırmayı dağıtın. Köprü artık hem geçerli hem de gelecekteki anahtarı kabul eder.
Yeni anahtarı kullanmak için sunucu sertifikasını veya anahtarını döndürün.
Dönüştürmelerin hâlâ başarılı olduğunu doğrulayın (yeni anahtar artık yedek sabitle eşleşir).
Yeni sabiti yedek listesinden birincil listeye taşıyın ve hizmet dışı bırakılan anahtarın sabitini kaldırın. Dağıtın.
Bir sonraki döndürme için yeni yedek sabiti oluşturup hazırlayın; böylece küme her zaman kullanılabilir bir yedek içerir.

Yedek listesini birincil listeden ayrı tutmak, etkin sabite dokunmadan sonraki sabiti hazırlamanıza ve doğrulamanıza olanak tanır.

Kimlik doğrulama

Köprü, apiKey boş değilken onu dönüştürme isteğinde bir Authorization: Bearer başlığı olarak gönderir. Alan, #[\SensitiveParameter] olarak işaretlidir; böylece değer yığın izlerinden çıkarılır. Köprü gizli anahtarı sizin için yüklemez; onu süreç başlangıcında bir gizli anahtar yöneticisinden sağlayın ve asla sabit olarak gömmeyin. Belirteç istek günlüğüne yazılmaz; günlüğe kaydedilen hata ayıklama girdisi yalnızca URL’yi, dosya adını, biçimi ve içerik uzunluğunu içerir.

Yanıt güven sınırı

Bir yanıt yalnızca durum kodu 200 olduğunda, Content-Type başlığı application/pdf değerini içerdiğinde ve gövde %PDF imzasıyla başladığında kabul edilir. Bayt imzası denetimi önemlidir, çünkü bildirilen bir içerik türü tek başına baytların ne olduğunu kanıtlamaz. WHATWG MIME Sniffing standardı aynı mantığı, hesaplanan türü sağlanan türden değil öndeki bayt desenleriyle eşleşmeden türeten MIME sniffing algoritmasıyla ifade eder. OWASP dosya yükleme rehberi, buna karşılık gelen uygulama ilkesini belirtir: dosya türünü doğrulayın ve bildirilen Content-Type başlığına güvenmeyin, çünkü sahte olabilir (WHATWG MIME Sniffing §6.2.3; OWASP Cheat Sheet Series, file-upload validation; her ikisi de sayfanın RAG yan dosyasında sabitlenmiştir). Köprü, gelen tarafta buna savunmacı olarak denk bir denetim uygular: uyumsuzluk, türü belirli bir istisna oluşturur ve baytlar asla sonuç olarak döndürülmez.

Bu sınır, PSR-18 sözleşmesinin burada önemli olmasının da nedenidir. Bir PSR-18 istemcisi yalnızca isteği gönderemediğinde veya yanıtı bir PSR-7 nesnesine ayrıştıramadığında istisna fırlatır; bir hata durum kodunda istisna fırlatmaz. İyi biçimlendirilmiş bir 4xx/5xx yanıtı, çağırana normal şekilde döndürülür (PSR-18, “Exceptions”; sayfanın RAG yan dosyasında sabitlenmiştir). Bu nedenle köprü, döndürülen bir yanıtın başarılı olduğunu varsaymak yerine durumu, türü ve imzayı kendisi inceler. Bir content-type kısıtlaması ihlaline ilişkin HTTP semantiği, yani bir sunucunun desteklenmeyen bir biçimdeki içeriği reddettiği bir 415 (Unsupported Media Type) reddi, gelen denetimin model aldığı davranıştır (RFC 9110 §15.5.16; sayfanın RAG yan dosyasında sabitlenmiştir).

Kaynak sınırları

Köprüde süreç içi bir kaynak sınırı vardır: maxFileSize (varsayılan 52.428.800 bayt = 50 MiB). İstekten önce uygulanır; böylece aşırı büyük bir girdi hizmete asla ulaşmaz. Köprüde yerleşik bir eşzamanlılık sınırı, hız sınırı veya çıkış boyutu üst sınırı yoktur. Bunlar dağıtımın ve çağıran tarafın sorumluluğundadır (bkz. /integrations/gotenberg/production-usage/). maxFileSize değerini gerçek belgelerinizin gerektirdiği en küçük değere ayarlayın; daha sıkı bir üst sınır, hizmet engellemeye karşı daha ucuz bir denetimdir.

Gotenberg hizmetini dağıtma ve güvenceye alma

Köprü, yalnızca çağırdığı hizmet kadar güvenlidir. Bu hizmeti siz işletirsiniz; aşağıdaki görevler yukarıdaki denetimleri tamamlar.

Gotenberg’in önünde TLS sonlandırması yapın. Gotenberg’in kapsayıcısı varsayılan olarak düz HTTP ile iletişim kurar. Köprü HTTPS gerektirir; bu nedenle Gotenberg’i TLS sonlandırması yapan bir ters proxy, ingress veya hizmet ağının arkasına yerleştirin ve köprüyü HTTPS uç noktasına yönlendirin. Sabitlemeyi etkinleştirirseniz proxy’nin SPKI değerini sabitleyin.
Gotenberg’i herkese açık biçimde açığa çıkarmayın. Belge dönüştürmeyi LibreOffice ve Chromium sınıfı motorlarla gerçekleştirir ve internete dönük bir hizmet değildir. Gelen trafiği, ağ ilkesi veya güvenlik duvarı kuralları kullanarak yalnızca onu çağıran uygulama ana makineleriyle sınırlayın.
Yol üzerinde kimlik doğrulamayı zorunlu kılın. Köprü, yapılandırıldığında bir taşıyıcı belirteç gönderir; kimliği doğrulanmamış bir istek dönüştürme motoruna ulaşamasın diye onu (veya karşılıklı TLS’yi) proxy’de zorunlu kılın.
Belirli bir hizmet sürümünü sabitleyin. Köprü tam olarak iki hizmet yolu varsayar — /forms/libreoffice/convert ve /health. Gotenberg imajını belirli bir yama etiketine sabitleyin, bu iki yolu dağıttığınız sürümde doğrulayın ve her yükseltmede yeniden doğrulayın.
Dönüştürme kapasitesini bilinçli olarak boyutlandırın. Her dönüştürme, istek süresince bir çalışanı meşgul tutar. Gotenberg dağıtımını en yüksek eşzamanlı dönüştürme hızınıza göre boyutlandırın ve buna uyacak şekilde devam eden dönüştürmeleri çağıran tarafta sınırlayın. Kapasite, bu paketin değil, dağıtımınızın bir özelliğidir.
Dönüştürme girişlerini güvenilmez olarak değerlendirin. Dönüştürülen belgeler karmaşık motorlar tarafından işlenir. maxFileSize değerini kısıtlayın, Gotenberg dağıtımını yalıtın (kendi ağ bölümü, asgari çıkış trafiği, iç hizmetlere erişim yok) ve motorun yamalarını güncel tutun.

Bu paketin iddia etmediği şeyler

“Varsayılan olarak güvenli” değildir: denetimler somuttur, ancak doğru dağıtıma ve yapılandırmaya bağlıdırlar.
Dönüştürmeyi “kurcalamaya dayanıklı” veya çıktıyı “sertifikalı” yapmaz. Aktarımı ve yanıt biçimini doğrular; belge içeriğini onaylamaz.
İmzalama, zaman damgalama veya uzun süreli doğrulama sağlamaz. Bunlar işlem sonrası konulardır. Pro sürümünün PAdES desteği yalnızca B-B temel düzeyidir ve B-T, B-LT veya B-LTA içermez; bu köprüdeki hiçbir şey bir zaman damgası veya LTV yeteneği ima etmez.
“Tüm Office dosyalarını” desteklemez. Listelenen altı biçimi destekler ve diğer her şeyi herhangi bir istekten önce reddeder.

Ayrıca bkz.

/integrations/gotenberg/configuration/ — aktarım seçimi kuralları ve tam sabitleme modeli.
/integrations/gotenberg/production-usage/ — yeniden denemeler, zaman aşımları, eşzamanlılık ve gözlemlenebilirlik.
/integrations/gotenberg/troubleshooting/ — her güvenlik istisnası ve tetikleyicisi.
/integrations/gotenberg/overview/ — dönüştürme akışı ve bağımlılık modeli.