💡 Повний робочий приклад доступний на GitHub: secure-untrusted-document-upload-conversion-dotnet
Виклик бухгалтерії: чому конвертація завантажень від постачальників ламається при масштабуванні
Ваш сервер конвертує рахунок; HTML постачальника вирішує, що ще читати. Безпечна конвертація завантажень від постачальників за допомогою GroupDocs.Conversion for .NET перетворює завантажений файл у PDF, не дозволяючи власним посиланням файлу визначати, що ваш сервер буде отримувати або читати далі.
Портал рахунків постачальника дозволяє будь-якому затвердженому постачальнику завантажити рахунок — зазвичай у вигляді HTML або PDF, іноді з прикріпленим SVG‑малюнком для об’єкта інфраструктури чи будівництва — і система бухгалтерії конвертує його у PDF для архівування та маршрутизації схвалення. HTML написав постачальник, а не ваша команда, і він може посилатися на будь‑що, що може посилатися веб‑сторінка: таблицю стилів, скрипт, зображення, розміщене на власному CDN постачальника, або — якщо обліковий запис постачальника був скомпрометований — адресу, яку ніколи не планувалося робити доступною з вашої мережі.
Обсяг постачальників лише зростає. Коли їх кількість переходить від кількох постачальників до сотень, папка завантажень, яка раніше містила файли однієї компанії, тепер містить файли всіх — і відносне посилання на зображення в рахунку одного постачальника може розв’язатися у файл, що належить іншому постачальнику, який знаходиться поруч.
Те, що насправді потрібна команді бухгалтерії, — це не правило мережевого брандмауера, а крок конвертації, який за замовчуванням розглядає кожне посилання у завантаженні як ненадійне, навмисно пропускає перевірений ресурс, наприклад логотип постачальника, і голосно повідомляє про помилку — а не мовчки — коли запис у білий список написаний неправильно.
Перевірка реальності: один тег
<img>, який вказує наhttp://169.254.169.254/latest/meta-data/iam/security-credentials/, змушує сервер конвертації викликати сервіс метаданих хмари — запит, який завантажувач ніколи не міг би здійснити ззовні. Це підробка запиту на боці сервера, і достатньо лише HTML‑завантаження.
Чому загальні виправлення не закривають цю прогалину
Команди бухгалтерії зазвичай вдаються до одного з цих рішень, перш ніж впроваджувати бібліотеку конвертації зі своєю політикою ресурсів:
- Блокування вихідного мережевого трафіку на хості конвертації: зупиняє віддалений запит, але нічого не робить щодо файлу в тій же папці, до якого може розв’язатися відносне посилання — саме те, що відбувається, коли завантаження конвертується безпосередньо зі збереженого шляху.
- Видалення тегів перед конвертацією: крихке щодо нових типів посилань (
<link>, SVG<image>, CSS@import) і потребує повторного аудиту щоразу, коли змінюється формат завантаження. - Довіра власному сканеру завантажень порталу постачальника: сканує на наявність сигнатур шкідливого ПЗ, а не на URL, який вказує на вашу інфраструктуру.
GroupDocs.Conversion закриває цю прогалину в найважливіший момент: коли документ завантажується для конвертації, ще до створення будь‑якого вихідного результату.
Рішення: GroupDocs.Conversion у робочому процесі рахунків постачальників
GroupDocs.Conversion for .NET 26.10 за замовчуванням забороняє зовнішні ресурси за допомогою SkipExternalResources, дозволяє точно вказати довірені місця через WhitelistedResources і надає зворотний виклик для кожного ресурсу через IExternalResourceHandler, який може підтвердити, перевизначити або безпосередньо надати байти ресурсу — тому перевірений логотип постачальника все ще може з’явитися у вихідному PDF без жодного мережевого запиту.
Щоб слідувати наведеній нижче реалізації, вам знадобиться:
- .NET 8.0 або новіше
- GroupDocs.Conversion for .NET (отримати безкоштовну пробну версію)
- Приклад HTML або SVG завантаження, яким ви не керуєте
dotnet add package GroupDocs.Conversion --version 26.10.0
Реалізація кроку конвертації завантажень від постачальника крок за кроком
Нижче наведений приклад відповідає реальній ситуації порталу постачальника: конвертація завантаженого рахунку (invoice-upload.html), який посилається на логотип, внутрішню адресу, локальний файл і файл, що знаходиться поруч.
Більшість фрагментів нижче передають об’єкт ResourceAudit — невеликий IExternalResourceHandler, який реєструє кожне рішення про завантаження і може надати байти довіреного ресурсу. Повний код знаходиться у Program.cs зразкового репозиторію.
Крок 1 — Завантаження та конвертація зі збереженого шляху завантаження
Так портал може конвертувати завантаження одразу після збереження його у спільну папку — і це крок, на якому може «просочитися» файл‑сиблінг.
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;
Завантаження безпосередньо з uploadPath включає всю папку рахунку у область дії, а не лише один файл у ній. Область, а не довіра, визначає, що завантажується. У цьому запуску кожне віддалене та file:/// посилання в рахунку блокується, але other-customer-signature.svg — інший файл, збережений у тій же папці — завантажується, оскільки SkipExternalResources виключає лише посилання поза цією папкою.
Крок 2 — Налаштування під вимоги завантажень від постачальника
Для завантажень від постачальника повністю видаліть базову папку, завантажуючи з потоку замість шляху:
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;
Чому це налаштування важливе для порталів постачальників:
- Вхідний потік: документ, конвертований з потоку, не має папки, тому відносне посилання всередині нього не може розв’язатися у файл іншого постачальника.
ExternalResourceHandler: все ще виконується для кожного ресурсу, тому ви зберігаєте запис про те, що саме запитувало кожне завантаження від постачальника.
Крок 3 — Виконання та захоплення перевіреного ресурсу
Логотип постачальника — це одне з посилань, яке ви, можливо, дійсно хочете залишити — надане з копії, якою ви керуєте, а не отримане з URL постачальника:
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;
Обробник ResourceAudit перевіряє запитаний URL проти словника довірених ресурсів; коли він збігається, він встановлює ExternalResourceLoadingArgs.Data у локальні байти і Skipped у false, тому логотип з’являється у вихідному PDF, тоді як інші п’ять посилань у рахунку залишаються заблокованими.
Крок 4 — Раннє відхилення неправильно налаштованого запису у білий список
Запис у білий список, який є лише ім’ям хоста, а не абсолютним префіксом URI, призводить до помилки конвертації замість тихого надмірного збігу:
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;
}
Передача cdn.example.com замість https://cdn.example.com/brand/ викликає InvalidLoadOptionsException з повідомленням: 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/'. Виявлення цього під час конвертації, під час перегляду конфігурації або перевірки запуску, значно дешевше, ніж виявлення помилки через неправильно збіглий ресурс у продакшені. Виявляйте це до випуску.
Чому запис у білий список URL може бути відхилений?
WhitelistedResources приймає лише абсолютні префікси URI, такі як https://cdn.example.com/brand/ або file:///C:/assets/. У попередніх версіях запис збігався де завгодно у URL, тому cdn.example.com також збігався з адресою зловмисника, яка лише містила ці слова. Починаючи з 26.10, такий запис не проходить завантаження і викликає InvalidLoadOptionsException, а останній метод зразка виводить точне повідомлення.
SVG‑вкладення від постачальника несуть той самий ризик
Малюнок інфраструктури, прикріплений до будівельного рахунку, все ще є лише SVG‑файлом, і він обробляється через SvgLoadOptions замість WebLoadOptions. Та ж контракт, інший елемент: ExternalResourceHandler застосовується до його посилань <image> так само, як він застосовувався до тегів <img> у рахунку, і будь‑який вбудований <script> у малюнку не виконується:
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;
Це саме сценарій будівельного рахунку з початку: малюнок, який виглядає лише як план поверху, все ще може містити посилання на ваш кінцевий пункт метаданих хмари, локальний файл або сервер зловмисника. У робочому зразку всі три блокуються, а підпис відображається точно так, як намальовано, оскільки прикріплений скрипт ніколи не виконується.
Поведінка до і після
| Перевірка | Конвертація безпосередньо зі збереженого шляху | Цей підхід |
|---|---|---|
| Файл‑сиблінг у тій же папці | Завантажується автоматично | Заблоковано — вхідний потік видаляє базову папку |
| Логотип постачальника | Заблоковано; PDF показує лише його alt‑текст | Надано з перевіреного локального файлу |
| Метадані хмари / внутрішня адреса | Заблоковано за замовчуванням | Заблоковано за замовчуванням |
| Запис у білий список лише з ім’ям хоста | Відхилено з InvalidLoadOptionsException |
Відхилено так само, виявлено під час перевірки запуску |
| Вбудований скрипт у завантаженні | Не виконується | Не виконується |
Змінюються два рядки: логотип і файл‑сиблінг. Файл‑сиблінг — це те, що мережевий перегляд ніколи не зможе виявити, оскільки не відбувається жодного мережевого запиту.
Інші сценарії документів від постачальників, де це застосовується
Те ж саме властивість ExternalResourceHandler існує у параметрах завантаження для кількох інших форматів, які зазвичай приймають портали постачальників, тому наведений вище шаблон не обмежується лише HTML та SVG:
- Вкладення Word або Excel, надані постачальником:
WordProcessingLoadOptionsтаSpreadsheetLoadOptionsнадають той самий контракт обробника. - Рахунки, надіслані електронною поштою:
EmailLoadOptionsнадає той самий обробник для віддалених зображень, на які посилається тіло листа. - Фінансові звіти XBRL:
FinanceLoadOptionsохоплює посилання на таксономії у XBRL‑документах, наданих постачальником.
Перші кроки у вашому конвеєрі завантажень від постачальника
Ви побачили, як GroupDocs.Conversion безпечно обробляє ненадійні завантаження від постачальників. Ось що робити далі:
- Start free: отримати тимчасову ліцензію to remove the evaluation limits
- Read the full resource policy: пропустити завантаження зовнішніх ресурсів covers
WhitelistedResources,IExternalResourceHandler, and script handling in detail - Check what touches the network at all: мережевий доступ та конфіденційність даних
- Follow the step-by-step guide: конвертувати ненадійні завантаження безпечно — випадок використання
- Browse the working sample: secure-untrusted-document-upload-conversion-dotnet на GitHub