💡 Полный рабочий пример доступен на GitHub:
secure-untrusted-document-upload-conversion-dotnet
Проблема отдела бухгалтерии: почему конвертация загрузок поставщиков ломается при масштабировании
Ваш сервер конвертирует счёт‑фактуру; HTML‑страница поставщика решает, что ещё читать. Безопасная конвертация загрузок поставщиков с помощью GroupDocs.Conversion для .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 для .NET 26.10 по умолчанию запрещает внешние ресурсы через SkipExternalResources, позволяет точно указать доверенные места через WhitelistedResources и предоставляет обратный вызов для каждого ресурса через IExternalResourceHandler, который может подтвердить, переопределить или напрямую предоставить байты ресурса — так проверенный логотип поставщика может появиться в итоговом PDF без какого‑либо сетевого запроса.
Чтобы следовать реализации ниже, вам понадобится:
- .NET 8.0 или новее
- GroupDocs.Conversion для .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 безопасно обрабатывает недоверенные загрузки поставщиков. Что делать дальше:
- Начать бесплатно: получить временную лицензию для снятия ограничений оценки
- Прочитать политику ресурсов: пропуск загрузки внешних ресурсов подробно описывает
WhitelistedResources,IExternalResourceHandlerи обработку скриптов - Проверить, что вообще касается сети: сетевой доступ и конфиденциальность данных
- Следовать пошаговому руководству: конвертация недоверенных загрузок безопасно — случай использования
- Изучить рабочий пример: secure-untrusted-document-upload-conversion-dotnet на GitHub