💡 Полный рабочий пример доступен на 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 без какого‑либо сетевого запроса.

Чтобы следовать реализации ниже, вам понадобится:

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 безопасно обрабатывает недоверенные загрузки поставщиков. Что делать дальше:

Ресурсы