Model zagrożeń silnika

W skrócie

Ta strona definiuje model zagrożeń dla podstawowego silnika NextPDF. Wymienia klasy ataków, które silnik uznaje za objęte zakresem, gdy przetwarza dane wejściowe kontrolowane przez atakującego: Hypertext Markup Language (HTML), Cascading Style Sheets (CSS), Scalable Vector Graphics (SVG), czcionki, obrazy oraz istniejące pliki Portable Document Format (PDF). Określa domyślne zachowanie każdej funkcji obsługującej zasoby zewnętrzne oraz wskazuje zabezpieczenie w kodzie łagodzące każdą z tych klas.

Granica. Model zagrożeń dokumentuje rozważone zagrożenia oraz zastosowane wobec nich środki zaradcze. Nie twierdzi, że podatności nie istnieją. Brak wzmianki o danej klasie nie dowodzi, że ona nie istnieje; może pozostawać poza obecnym zakresem modelu. Zanim niezaimplementowane funkcje trafią do wydania, przechodzą przez formalny przegląd zagrożeń. Traktuj tę stronę jako zapis świadomych decyzji projektowych, a nie jako dowód bezpieczeństwa.

Instalacja

composer require nextpdf/core:^3

Opisane tu zabezpieczenia są częścią pakietu podstawowego. Do ich włączenia nie jest potrzebna żadna dodatkowa zależność; są włączone domyślnie.

Przegląd koncepcyjny

Model opiera się na procesie modelowania zagrożeń Open Worldwide Application Security Project (OWASP) (owasp_threat_modeling#x1.x11.p6): podziel system na punkty, w których niezaufane dane wejściowe przekraczają granicę zaufania, wylicz zagrożenia na każdej z tych granic i zapisz środki zaradcze.

Główną granicą zaufania silnika jest wczytywanie dokumentów: każde miejsce, w którym treść utworzona gdzie indziej — zdalny arkusz stylów, źródło @font-face, element <image href>, osadzona faktura w formacie Extensible Markup Language (XML) lub plik PDF do sprawdzenia — może skłonić silnik do pobrania, przeanalizowania lub zdekompresowania danych. Zasadą nadrzędną jest domyślna odmowa: każda funkcja obsługująca zasoby zewnętrzne jest wyłączona, dopóki nie zostanie jawnie włączona za pomocą obiektu polityki. W ten sposób bazowa zasada minimalnej funkcjonalności z National Institute of Standards and Technology (NIST) SP 800-53 Rev. 5 CM-7 (nist_sp_800_53r5#x4.x182.p14) zostaje zastosowana do silnika renderującego: wartość domyślna konstruktora jest najbardziej restrykcyjnym ustawieniem. Otwarcie danej funkcji jest jawną decyzją.

Powierzchnia API

Model zagrożeń nie jest interfejsem programistycznym aplikacji (API). Obiekty polityki, które go wyrażają, są udokumentowane na stronach modułów. Istotnymi z punktu widzenia zaufania punktami wejścia są kontrakt polityki zasobów zewnętrznych (ExternalResourcePolicyInterface, z DefaultExternalResourcePolicy jako domyślną implementacją odmawiającą wszystkiego) oraz zabezpieczenia adresów Uniform Resource Locator (URL) i XML (UrlValidator, XmlGuard). Ta strona odwołuje się do ich działania; nie powtarza ich sygnatur.

Przykład kodu — szybki start

Bezpieczna postawa jest ustawieniem domyślnym. Do jej uzyskania nie jest potrzebny żaden kod:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Html\DefaultExternalResourcePolicy;

// Out of the box: @font-face blocked, @import blocked, background-image
// blocked, SVG external refs blocked. A document that tries to fetch a
// remote resource gets a system-font fallback or an ignored rule — not an
// outbound request.
$policy = new DefaultExternalResourcePolicy();

Przykład kodu — środowisko produkcyjne

Włączenie danej funkcji jest świadome i ma wąski zakres. Jeśli w środowisku produkcyjnym trzeba zezwolić na czcionkę internetową hostowaną w sieci dostarczania treści (CDN) przez Hypertext Transfer Protocol Secure (HTTPS), włącz obsługę jawnie i zawęź zakres:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Html\DefaultExternalResourcePolicy;

// Explicit, scoped opt-in. The HTTPS scheme is required; size and glyph
// caps still apply; the URL still passes the SSRF guard before any fetch.
$policy = (new DefaultExternalResourcePolicy())
    ->withFontFaceAllowed(['https']);

Przypadki brzegowe i pułapki

Niezaimplementowane nie znaczy bezpieczne przez przypadek. Funkcje takie jak CSS background-image url() nie są zaimplementowane, więc obecnie nie mają żadnej powierzchni ataku. Mimo to są udokumentowane jako wymagające formalnej bramki przeglądu zagrożeń przed jakąkolwiek przyszłą implementacją. Brak kodu jest obecnym środkiem zaradczym, a nie trwałą gwarancją.
Ponowne wiązanie Domain Name System (DNS) pozostaje ruchomym celem. UrlValidator rozwiązuje nazwę hosta i zwraca uzyskany adres Internet Protocol (IP), aby wywołujący mógł przypiąć połączenie (CURLOPT_RESOLVE), zamykając okno między walidacją a pobraniem, czyli między czasem sprawdzenia a czasem użycia (TOCTOU). To obrona realizowana z należytą starannością, lecz nie absolutna. Operator działający za zbyt liberalnym serwerem proxy ruchu wychodzącego nadal może dotrzeć do hostów wewnętrznych, których biblioteka nie widzi.
Bity uprawnień nie są kontrolą dostępu. Dokument, który „blokuje kopiowanie”, opiera się na współpracy czytnika, a nie na wymuszeniu. Jest to omówione w sekcji model bezpieczeństwa. Wspominamy o tym, ponieważ jest to częste nieporozumienie dotyczące modelu zagrożeń.

Wydajność

Zabezpieczenia szybko kończą odmową i ograniczają wykonywaną pracę: zabezpieczenie XML odrzuca deklarację typu dokumentu (DOCTYPE) przed parsowaniem i ogranicza rozmiar danych wejściowych; ścieżka obrazów wymusza górny limit megapikseli i bajtów przed dekompresją; zabezpieczenie adresów URL odrzuca żądanie na podstawie schematu i hosta, zanim zostanie otwarte jakiekolwiek gniazdo. Kosztem bezpiecznej wartości domyślnej jest odrzucone żądanie, a nie spowolnione.

Uwagi dotyczące bezpieczeństwa

Poniżej znajdują się rozważone klasy ataków i odpowiadające im środki zaradcze w kodzie, wraz z odniesieniami do Common Weakness Enumeration (CWE) i OWASP tam, gdzie mają zastosowanie:

Klasa zagrożenia (CWE / OWASP)	Wektor w silniku PDF	Zabezpieczenie w kodzie
Fałszowanie żądań po stronie serwera (SSRF) (OWASP Top 10 2025; `owasp_top10_2025#x3.x1.p26`)	`@font-face`/`@import`/`url()` wskazujące na `169.254.169.254` lub host wewnętrzny; mechanizmy pobierania danych z urzędu znaczników czasu (TSA), Online Certificate Status Protocol (OCSP) oraz listy unieważnionych certyfikatów (CRL)	`UrlValidator::validateExternalUrl()` blokuje zakresy prywatne, zarezerwowane, pętli zwrotnej i lokalne dla łącza oraz punkty końcowe metadanych chmury; odrzuca niebezpieczne schematy; rozwiązuje DNS i zwraca adres IP do przypięcia połączenia
Zewnętrzna encja XML (XXE) (`cwe_top25_2025#x28.x2.p42`)	Zewnętrzne encje lub DOCTYPE w osadzonej fakturze XML lub pakiecie Extensible Metadata Platform (XMP)	`XmlGuard::loadXml()` wymusza `LIBXML_NONET`, bezwarunkowo odrzuca każdą deklarację DOCTYPE, odrzuca zabronione znaki sterujące XML 1.0 oraz stosuje limit rozmiaru danych wejściowych
Bomba dekompresyjna	Obraz 1×1 maskujący ładunek 100 MP; nadmiernie duży plik Web Open Font Format 2 (WOFF2)	Ścieżka obrazów wymusza górny limit megapikseli i limit bajtów przed dekompresją; ścieżka czcionek ogranicza rozmiar pliku i liczbę glifów
Przechodzenie po ścieżkach	`file:///etc/passwd` przez atrybut `src` czcionki lub SVG	Polityka zasobów zewnętrznych domyślnie odmawia wszystkiego; ścieżki plików lokalnych są rozwiązywane za pomocą `realpath()` względem listy dozwolonych katalogów, gdy jest to jawnie włączone
Wstrzykiwanie treści	Spreparowany ciąg znaków wyłamujący się z operatora PDF; atrybut href `data:`/`javascript:`	Sekwencjonowanie ciągów PDF przy emisji; lista dozwolonych schematów i sanityzacja atrybutu href w adnotacjach

Wartości domyślne tworzą zasadę odmowy dla wszystkich zasobów zewnętrznych: czcionki, @import, background-image oraz zewnętrzne odniesienia SVG pozostają wyłączone, dopóki nie zostaną włączone dla danego schematu, zgodnie z opisem w utrzymywanej razem z kodem macierzy pokrycia właściwości bezpieczeństwa.

Ta strona dokumentuje rozważone zagrożenia. Nie jest raportem z testów penetracyjnych i nie twierdzi, że wymienione środki zaradcze są kompletne ani że żadna inna klasa słabości nie ma zastosowania.

Zgodność

To nie jest profil zgodności. Model zagrożeń opiera się na procesie modelowania zagrożeń OWASP oraz na taksonomii słabości CWE Top 25 (cwe_top25_2025#x28.x2.p42); nie deklaruje zgodności z żadnym schematem certyfikacji bezpieczeństwa. Niezależna ocena jest zadaniem audytu, a nie tego dokumentu.