💡 Pełny działający przykład dostępny na GitHubie:
secure-untrusted-document-upload-conversion-dotnet
Wyzwanie działu rozliczeń: Dlaczego konwersja przesyłanych przez dostawców plików zawodzi przy dużej skali
Twój serwer konwertuje fakturę; HTML dostawcy decyduje, co jeszcze zostanie odczytane. Bezpieczna konwersja przesyłanych przez dostawcę plików z użyciem GroupDocs.Conversion for .NET zamienia przesłany plik w PDF, nie pozwalając, aby odwołania w samym pliku decydowały, co Twój serwer pobierze lub odczyta jako kolejne.
Portal faktur dostawcy pozwala każdemu zatwierdzonemu dostawcy przesłać fakturę – zazwyczaj w formacie HTML lub PDF, czasami z dołączonym rysunkiem SVG dotyczącym elementu instalacji lub budowy – a system rozliczeń konwertuje ją do PDF w celu archiwizacji i routingu zatwierdzeń. HTML napisał dostawca, a nie Twój zespół, i może odwoływać się do wszystkiego, co strona internetowa może odwoływać: arkusza stylów, skryptu, obrazu hostowanego w CDN dostawcy lub – jeśli konto dostawcy zostało przejęte – adresu, który nigdy nie miał być osiągalny z Twojej sieci.
Objętość dostawców stale rośnie. Gdy przechodzi od kilku dostawców do setek, folder „uploads”, który kiedyś zawierał pliki jednej firmy, teraz przechowuje pliki wszystkich – a względne odwołanie do obrazu w jednej fakturze może rozwiązać się do pliku należącego do innego dostawcy, znajdującego się tuż obok.
Co naprawdę potrzebuje zespół rozliczeń, to nie reguła zapory sieciowej, lecz krok konwersji, który traktuje każde odwołanie w przesłanym pliku jako niewiarygodne domyślnie, pozwala celowo przejść zweryfikowanemu zasobowi, takiemu jak logo dostawcy, i zgłasza błąd głośno – nie cicho – gdy wpis na białej liście jest niepoprawny.
Sprawdzenie rzeczywistości: pojedynczy znacznik
<img>wskazujący na
http://169.254.169.254/latest/meta-data/iam/security-credentials/zmusza serwer konwertujący do wywołania usługi metadanych chmury – żądania, którego nadawca nie mógłby wykonać z zewnątrz. To atak typu server‑side request forgery, a wystarczy przesłać HTML.
Dlaczego ogólne rozwiązania nie zamykają tej luki
Zespoły rozliczeń zazwyczaj sięgają po jedną z poniższych opcji przed przyjęciem biblioteki konwersji z własną polityką zasobów:
- Blokowanie wychodzącego ruchu sieciowego na hoście konwersji: zatrzymuje zdalne pobranie, ale nic nie robi w sprawie pliku w tym samym folderze, do którego może odwoływać się względny odnośnik – dokładnie to, co dzieje się, gdy przesył jest konwertowany bezpośrednio z zapisanego katalogu.
- Usuwanie znaczników przed konwersją: kruche wobec nowych typów odwołań (
<link>, SVG<image>, CSS@import) i wymaga ponownego audytu przy każdej zmianie formatu przesyłanego pliku. - Zaufanie własnemu skanerowi portalu dostawcy: skanuje pod kątem sygnatur malware, a nie pod kątem URL‑ów wskazujących na Twoją infrastrukturę.
GroupDocs.Conversion zamyka tę lukę w miejscu, które ma największe znaczenie: w momencie, gdy dokument jest ładowany do konwersji, zanim zostanie wygenerowane jakiekolwiek wyjście.
Rozwiązanie: GroupDocs.Conversion w przepływie faktur dostawcy
GroupDocs.Conversion for .NET 26.10 domyślnie odrzuca zasoby zewnętrzne poprzez SkipExternalResources, pozwala precyzyjnie określić zaufane lokalizacje za pomocą WhitelistedResources i udostępnia wywołanie zwrotne per‑zasób poprzez IExternalResourceHandler, które może potwierdzić, nadpisać lub dostarczyć bajty zasobu bezpośrednio – dzięki czemu zweryfikowane logo dostawcy może nadal pojawić się w wyjściowym PDF, bez wykonywania żadnego żądania sieciowego.
Aby podążać za poniższą implementacją, potrzebujesz:
- .NET 8.0 lub nowszy
- GroupDocs.Conversion for .NET (zdobądź darmowy trial)
- Przykładowy plik HTML lub SVG, którego nie kontrolujesz
dotnet add package GroupDocs.Conversion --version 26.10.0
Implementacja kroku konwersji przesyłanego przez dostawcę – krok po kroku
Poniższy przykład odzwierciedla rzeczywistą sytuację w portalu dostawcy: konwersję przesłanej faktury (invoice-upload.html), która odwołuje się do logo, wewnętrznego adresu, lokalnego pliku i pliku leżącego obok.
Większość fragmentów poniżej przekazuje obiekt ResourceAudit – mały IExternalResourceHandler, który rejestruje każdą decyzję o ładowaniu i może dostarczyć bajty zaufanego zasobu. Pełny kod znajduje się w
Program.cs przykładowego repozytorium.
Krok 1 – Ładowanie i konwersja z zapisanego katalogu przesyłu
Tak może wyglądać konwersja przesyłu natychmiast po zapisaniu go w udostępnionym folderze – i krok, w którym plik sąsiadujący może wyciec.
var audit = new ResourceAudit();
var loadOptions = new WebLoadOptions { ExternalResourceHandler = audit };
using (var converter = new Converter(uploadPath, (LoadContext _) => loadOptions))
{
converter.Convert(outputPath, new PdfConvertOptions());
}
return audit.Loaded;
Ładowanie bezpośrednio z uploadPath umieszcza cały folder faktury w zasięgu, nie tylko pojedynczy plik w nim zawarty. Zakres, a nie zaufanie, decyduje, co zostanie załadowane. W tym uruchomieniu każde zdalne i file:/// odwołanie w fakturze jest blokowane, ale other-customer-signature.svg – inny plik zapisany w tym samym folderze – zostaje załadowany, ponieważ SkipExternalResources wyklucza jedynie odwołania spoza tego folderu.
Krok 2 – Konfiguracja pod wymagania przesyłania przez dostawcę
Dla przesyłanych przez dostawcę plików usuń całkowicie folder bazowy, ładując z strumienia zamiast z ścieżki:
var audit = new ResourceAudit();
var loadOptions = new WebLoadOptions { ExternalResourceHandler = audit };
using (var converter = new Converter(
() => File.OpenRead(uploadPath), (LoadContext _) => loadOptions))
{
converter.Convert(outputPath, new PdfConvertOptions());
}
return audit.Loaded;
Dlaczego to ustawienie ma znaczenie dla portali dostawców:
- Wejście jako strumień: dokument konwertowany ze strumienia nie ma folderu, więc względne odwołanie wewnątrz niego nie może rozwiązać się do pliku innego dostawcy.
ExternalResourceHandler: nadal działa dla każdego zasobu, więc zachowujesz pełny zapis tego, o co każdy przesył od dostawcy prosił.
Krok 3 – Wykonanie i dostarczenie zweryfikowanego zasobu
Logo dostawcy to odwołanie, które możesz chcieć zachować – dostarczone z kopii, którą kontrolujesz, a nie pobrane z URL‑u dostawcy:
var trustedAssets = new Dictionary<string, byte[]>
{
[assetUrl] = File.ReadAllBytes(assetPath)
};
var audit = new ResourceAudit(trustedAssets);
var loadOptions = new WebLoadOptions { ExternalResourceHandler = audit };
using (var converter = new Converter(
() => File.OpenRead(uploadPath), (LoadContext _) => loadOptions))
{
converter.Convert(outputPath, new PdfConvertOptions());
}
return audit.Loaded;
Obsługa ResourceAudit sprawdza żądany URL względem słownika zaufanych zasobów; gdy znajdzie dopasowanie, ustawia ExternalResourceLoadingArgs.Data na lokalne bajty i Skipped na false, dzięki czemu logo pojawia się w wyjściowym PDF, a pozostałe pięć odwołań w fakturze pozostaje zablokowanych.
Krok 4 – Wczesne odrzucenie niepoprawnie skonfigurowanego wpisu na białej liście
Wpis na białej liście, który jest jedynie nazwą hosta, a nie absolutnym prefiksem URI, powoduje błąd konwersji zamiast cichego dopasowania zbyt szerokiego zakresu:
var loadOptions = new WebLoadOptions
{
WhitelistedResources = new List<string> { entry }
};
try
{
using var converter = new Converter(
() => File.OpenRead(uploadPath), (LoadContext _) => loadOptions);
converter.Convert(outputPath, new PdfConvertOptions());
return null;
}
catch (InvalidLoadOptionsException exception)
{
return exception.Message;
}
Podanie cdn.example.com zamiast https://cdn.example.com/brand/ powoduje wyrzucenie InvalidLoadOptionsException z komunikatem: Whitelisted resource 'cdn.example.com' is not valid. Expected an absolute URI prefix without a query, fragment or encoded '/', '\' or '.', such as 'https://cdn.example.com/assets/' or 'file:///C:/assets/'. Wykrycie tego w czasie konwersji, podczas przeglądu konfiguracji lub przy uruchamianiu aplikacji, jest znacznie tańsze niż odkrycie błędnego dopasowania w środowisku produkcyjnym. Złap to, zanim trafi do produkcji.
Dlaczego wpis na białej liście URL mógłby zostać odrzucony?
WhitelistedResources akceptuje wyłącznie absolutne prefiksy URI, takie jak https://cdn.example.com/brand/ lub file:///C:/assets/. Wcześniejsze wersje dopasowywały wpis wszędzie, gdzie pojawił się w URL, więc cdn.example.com pasował także do adresu atakującego, który jedynie zawierał te słowa. Od wersji 26.10 taki wpis kończy ładowanie z InvalidLoadOptionsException, a ostatnia metoda w przykładzie wypisuje dokładny komunikat.
Załączniki SVG od dostawcy niosą to samo ryzyko
Rysunek instalacji dołączony do faktury budowlanej to wciąż tylko plik SVG i przechodzi przez SvgLoadOptions zamiast WebLoadOptions. Ten sam kontrakt, inny element: ExternalResourceHandler stosuje się do jego odwołań <image> tak, jak do znaczników <img> w fakturze, a każdy wbudowany <script> w rysunku nie zostaje wykonany:
var audit = new ResourceAudit();
var loadOptions = new SvgLoadOptions { ExternalResourceHandler = audit };
using (var converter = new Converter(
() => File.OpenRead(uploadPath), (LoadContext _) => loadOptions))
{
converter.Convert(outputPath, new PdfConvertOptions());
}
return audit.Loaded;
To dokładnie ta sama sytuacja, co w otwarciu: rysunek, który wygląda jak zwykły plan piętra, może nadal zawierać odwołanie do Twojego punktu końcowego metadanych chmury, lokalnego pliku lub serwera atakującego. W działającym przykładzie wszystkie trzy są zablokowane, a podpis jest renderowany dokładnie tak, jak został narysowany, ponieważ dołączony skrypt nigdy się nie uruchamia.
Zachowanie przed i po
| Sprawdzenie | Konwersja bezpośrednio z zapisanego katalogu | To podejście |
|---|---|---|
| Plik sąsiadujący w tym samym folderze | Ładuje się automatycznie | Zablokowany – wejście jako strumień usuwa folder bazowy |
| Logo dostawcy | Zablokowane; PDF wyświetla tylko tekst alternatywny | Dostarczone z zweryfikowanego lokalnego pliku |
| Metadane chmury / wewnętrzny adres | Zablokowane domyślnie | Zablokowane domyślnie |
| Wpis na białej liście tylko z nazwą hosta | Odrzucony z InvalidLoadOptionsException |
Odrzucony w ten sam sposób, przechwycony przy uruchamianiu |
| Skrypt wbudowany w przesył | Nie uruchamia się | Nie uruchamia się |
Dwa wiersze ulegają zmianie: logo i plik sąsiadujący. Plik sąsiadujący to element, którego przegląd na poziomie sieci nigdy nie wykryje, ponieważ nie dochodzi do żądania sieciowego.
Inne scenariusze dokumentów dostawcy, w których to ma zastosowanie
Ta sama właściwość ExternalResourceHandler istnieje w opcjach ładowania dla kilku innych formatów, które portale dostawców często akceptują, więc przedstawiony wzorzec nie ogranicza się do HTML i SVG:
- Załączniki Word lub Excel od dostawcy:
WordProcessingLoadOptionsiSpreadsheetLoadOptionsudostępniają ten sam kontrakt obsługi. - Faktury przesyłane e‑mailem:
EmailLoadOptionsudostępnia tę samą obsługę dla zdalnych obrazów, które odwołuje treść e‑maila. - Sprawozdania finansowe XBRL:
FinanceLoadOptionsobejmuje odwołania do taksonomii w dokumentach XBRL dostarczonych przez dostawcę.
Rozpoczęcie pracy z Twoim potokiem przesyłania przez dostawcę
Widziałeś, jak GroupDocs.Conversion bezpiecznie obsługuje niewiarygodne przesyłane przez dostawcę pliki. Co zrobić dalej:
- Rozpocznij za darmo: zdobądź tymczasową licencję, aby usunąć ograniczenia wersji ewaluacyjnej
- Przeczytaj pełną politykę zasobów: pomijanie ładowania zasobów zewnętrznych opisuje
WhitelistedResources,IExternalResourceHandleroraz obsługę skryptów w szczegółach - Sprawdź, co w ogóle dotyka sieci: dostęp sieciowy i prywatność danych
- Postępuj zgodnie z przewodnikiem krok po kroku: bezpieczna konwersja niewiarygodnych przesyłów – przypadek użycia
- Przeglądaj działający przykład: secure-untrusted-document-upload-conversion-dotnet na GitHubie