💡 مثال کامل قابل اجرا در GitHub موجود است:
merge-untrusted-html-uploads-dotnet
ادغام ایمن اسناد HTML غیرقابل اعتماد یک جریان کاری GroupDocs.Merger برای .NET است که منابع خارجی که یک بارگذاری به آنها ارجاع میدهد — URLهای ریموت، مسیرهای UNC و فایلهای محلی — را مگر آنکه صراحتاً اجازه دهید، رد میکند.
روش قدیمی دردناک بود
تصور کنید پورتال صدور فاکتور شما بارگذاری فاکتور مشتری را همراه با یادداشت تحویل از همان سفارش در یک سند HTML برای بایگانی ترکیب میکند. فاکتور یک HTML ساده است — یک لینک به stylesheet، یک تصویر لوگو، چند پاراگراف — به جز این که شما آن را ننوشتهاید، مرورگر یا ابزار خروجی مشتری آن را ساخته است. پیش از GroupDocs.Merger 26.10، ادغام منابع خارجی که HTML به آنها ارجاع میداد — stylesheetهای ریموت، تصویرهای ریموت، مسیرهای مطلق فایل محلی — را بارگذاری میکرد و هیچ گزینهای برای متوقف کردن این کار وجود نداشت.
این مسأله زمانی که بارگذاری کاملاً مورد اعتماد نباشد، مشکلساز میشود. یک URL stylesheet میتواند یک پیکسل ردیابی باشد. یک src تصویر میتواند به http://169.254.169.254/latest/meta-data/iam/security-credentials/ — یک آدرس متادیتای ابری — اشاره کند و مرحله ادغام شما آن را به نیابت از بارگذار درخواست میکند. یک مسیر مطلق file:/// نیز خوانده میشد، بنابراین ارجاعی به بارگذاری مشتری دیگر میتوانست آن فایل را به خروجی ترکیبی بکشاند.
هزینه واقعی ادغام کورکورانه: یک کار ادغام که هر آنچه بارگذاری میخواهد دریافت میکند، سرور شما را به یک پراکسی برای SSRF تبدیل میکند و یک ارجاع
file:///راهی برای خواندن فایل یک مشتری توسط ادغام مشتری دیگر میشود.
راه بهتر وجود دارد
GroupDocs.Merger برای .NET این مشکل را بهصورت پیشفرض رفع میکند. از نسخه 26.10 به بعد، هر سازنده LoadOptions مقدار SkipExternalResources = true را تنظیم میکند و یک Merger که بدون گزینههای بارگذاری ساخته میشود، همان مقدار پیشفرض را استفاده میکند — هیچ منبع خارجیای بارگذاری نمیشود مگر این که صراحتاً بگویید.
پیشنیازها:
- .NET (هر یک از چهار چارچوب هدف که GroupDocs.Merger برای .NET پشتیبانی میکند)
- GroupDocs.Merger برای .NET 26.10 یا بالاتر (دریافت یک لایسنس موقت)
- دو سند HTML برای ترکیب، حداقل یکی از منبعی که کاملاً به آن اعتماد ندارید
نصب با یک فرمان:
dotnet add package GroupDocs.Merger --version 26.10.0
روش جدید: ادغام HTML بدون اعتماد به آن
در اینجا نحوه ترکیب دو بارگذاری HTML با پیشفرضهای ایمن، یک هندلر که هر تصمیم را ثبت میکند، و — در یک عبور دوم — یک هندلر که یک منبع مورد اعتماد را فراهم میکند، نشان داده شده است.
Step 1 - Create Load Options for the Format
LoadOptions سازنده بدون پارامتر ندارد و از نسخه 26.10 به بعد sealed است؛ نمونه کد فرمت را بهصورت صریح نام میبرد.
// LoadOptions(FileType.HTML) already denies everything external by default
var audit = new ResourceAudit();
var loadOptions = new LoadOptions(FileType.HTML) { ExternalResourceHandler = audit };
Step 2 - Join the Uploads and Inspect the Decisions
// Both uploads follow the options of the Merger they are joined to
using (var merger = new Merger(firstUpload, loadOptions))
{
merger.Join(secondUpload);
merger.Save(outputPath);
}
foreach (string decision in audit.Decisions)
{
Console.WriteLine(decision);
}
نکات کلیدی:
SkipExternalResources: بهطور ضمنی اینجاtrueاست، بنابراین هر URL ریموت، مسیر UNC و ارجاع به فایل محلی رد میشود، حتی فایلی که در پوشه بارگذاری خودش قرار دارد.- یک
LoadOptionsبرای هر ترکیب: بارگذاری دوم گزینههای خود را دریافت نمیکند — گزینههایی کهMergerساختهشده با آن ترکیب شده است، به ارث میبرد.
Step 3 - Allow Exactly One Trusted Resource
// Supply the logo's bytes directly instead of requesting it over the network
var trustedAssets = new Dictionary<string, byte[]>
{
[logoUrl] = File.ReadAllBytes(logoPath)
};
var audit = new ResourceAudit(trustedAssets);
var loadOptions = new LoadOptions(FileType.HTML) { ExternalResourceHandler = audit };
متد OnLoading هندلر مقدار args.Skipped = false و args.Data را به بایتهای موردنظر تنظیم میکند وقتی URI درخواستشده مطابقت داشته باشد، بنابراین سند لوگو را بدون اینکه GroupDocs.Merger در جایی درخواست بفرستد، دریافت میکند.
زمانی که ادغام پیشفرض را بر روی بارگذاریهای فاکتور و یادداشت تحویل اجرا کردیم، تمام هفت ارجاع خارجی در هر دو فایل مسدود شد — stylesheet ریموت، لوگوی ریموت، URL سبک‑متادیتا، تصویر پوشه‑همسایه، مسیر file:///، مسیر UNC و URL ردیابی با رشتهٔ پرسوجو. joined.html متن هر دو بارگذاری را نگه میدارد؛ یک جایگزین برای هر تصویر مسدود شده قرار میگیرد. با افزودن هندلر لوگوی مورد اعتماد، لوگو «تأمین» شد و شش مورد دیگر «مسدود» ماندند.
مقایسهٔ کنار هم: قبل vs. بعد
| قبل (بدون گزینه) | بعد (GroupDocs.Merger 26.10) | |
|---|---|---|
| درخواستهای خارجی | هر ارجاعی بهصورت خودکار بارگذاری میشد | تا زمانی که صراحتاً اجازه داده نشود، رد میشود |
| مسیرهای مطلق فایل محلی | به خروجی بارگذاری میشد | مانند هر ارجاع دیگری رد میشود |
| استثناهای مورد اعتماد | نیازی نبود — همه بارگذاری میشدند | یک منبع از طریق هندلر یا پیشوند سفید‑لیست شده |
| ورودی نادرست در سفید‑لیست | سفید‑لیست وجود نداشت | در زمان ساخت با ArgumentException رد میشود |
| کد مورد نیاز | راهی برای محدود کردن بارگذاری نبود | چند خط کد در LoadOptions |
تفاوت در آنچه ممکن است، نه فقط در آنچه راحت است: قبل از 26.10 هیچ تنظیمی برای متوقف کردن بارگذاری وجود نداشت؛ پس از آن، رد کردن بهصورت پیشفرض است و هر استثنا بهصورت صریح تعریف میشود.
آیا این باعث میشود HTML که قبلاً به بارگذاری تصویرهای ریموت وابسته بود، خراب شود؟
اگر آن HTML هنوز با LoadOptions پیشفرض ادغام شود، بله — تصاویر بارگذاری نمیشوند و یک جایگزین در خروجی جایگزین آنها میشود. رفع مشکل صریح است، نه یک راهحل موقت: منابع مورد اعتماد را در WhitelistedResources فهرست کنید یا یک IExternalResourceHandler متصل کنید که داراییهای خاصی را که هنوز میخواهید رندر کنید، فراهم میکند. به هر حال، ادغام ادامه مییابد؛ فقط بارگیری هر چیزی که نام نیاوردهاید، متوقف میشود.
مثال دنیای واقعی: تجمیع فاکتور و یادداشت تحویل
یک خط لولهٔ سند که HTML ارسالشده توسط مشتری را به یک نسخهٔ بایگانی ترکیب میکند، دقیقاً سناریویی است که پروژهٔ نمونهٔ این صفحه مدلسازی میکند: یک بارگذاری فاکتور و یک یادداشت تحویل از همان سفارش، که به یک فایل ترکیب میشوند. هیچیک از این بارگذاریها توسط تیم خود خط لوله نوشته نشدهاند، بنابراین نمیتوان آنها را بهصورت مطلق امن فرض کرد. فاکتور مبلغی بدهکار و مشتریای به نام Northwind Traders را نام میبرد و شامل ارجاع به لوگو، stylesheet ردیابی، URL سبک‑متادیتا ابری، ارجاع به تصویر در همان پوشه و مسیر file:/// است — هفت ارجاع خارجی بین دو بارگذاری، که هیچیک نباید توسط خط لولهٔ بایگانی به نیابت از مشتری فراخوانی شود.
قبل از اینکه کار ادغام بهصورت زنده اجرا شود، ارزش دارد که بهصورت سند به سند تصمیم بگیرید آیا بههیچ استثنایی نیاز است یا خیر. سناریوی نمونهٔ فاکتوردهی دقیقاً یک استثنا نیاز داشت: لوگوی شرکت که از فایلی که از قبل روی دیسک موجود است، سرو میشد نه از URL ریموتی که HTML نام میبرد. بقیه موارد — stylesheet ردیابی، آدرس سبک‑متادیتا، فایل همسایه، مسیرهای UNC و file:/// — هیچ دلیل مشروعی برای فراخوانی نداشتند، بنابراین پیشفرضها به تنهایی پاسخ صحیح بودند.
// Reject a whitelist entry that is not an absolute URI prefix
var loadOptions = new LoadOptions(FileType.HTML)
{
WhitelistedResources = new List<string> { "cdn.example.com" }
};
ارسال یک نام میزبان ساده بهجای یک پیشوند مطلق مانند https://cdn.example.com/brand/ باعث پرتاب استثنا میشود، با پیام Whitelisted resource 'cdn.example.com' must be an absolute URI without a query, fragment or encoded '/', '\' or '.'. (Parameter 'WhitelistedResources') — قبل از اینکه هر بارگذاری حتی باز شود. کشف یک سفید‑لیست پیکربندیشده نادرست در زمان راهاندازی، ارزش بیشتری نسبت به کشف آن پس از اینکه منبعی بهصورت ساکت در تولید بارگذاری نشد، دارد.
دیگر چه کارهایی میتوانید با GroupDocs.Merger برای .NET انجام دهید؟
- اعتبارسنجی زودهنگام ورودیهای سفید‑لیست: یک ورودی
WhitelistedResourcesنادرست در زمان ساختMergerشکست میخورد، بنابراین بررسیهای راهاندازی استقرار قبل از پردازش هر سند آن را میگیرد. - تأمین داراییهای مورد اعتماد از دیسک:
IExternalResourceHandlerمیتواند به درخواست با بایتهایی که از پیش دارید پاسخ دهد، بدون هیچ دسترسی شبکهای. - اعمال یک سیاست بر تمام اسناد ترکیبشده:
LoadOptionsیکبار رویMergerتنظیم میشود و هر سندی که بعداً به آن اضافه میشود، همان قوانین را دنبال میکند. - پوشش بیش از HTML: پردازش متن، HTML/MHTML، ارائهها، صفحات گسترده، SVG و اسناد EPUB همگی همان گزینهها را رعایت میکنند.
نتیجهگیری
ادغام HTML که شما ننوشتهاید دیگر به معنای اعتماد به تمام محتوای آن نیست. GroupDocs.Merger برای .NET از نسخه 26.10 بهصورت پیشفرض منابع خارجی را رد میکند و دو روش برای اعطای استثنا — یک هندلر دارایی‑مورد‑اعتماد و WhitelistedResources — دقیقاً همان دسترسی را که یک خط لولهٔ خاص نیاز دارد، فراهم میکند و نه بیشتر.
آمادهاید خودتان امتحان کنید؟
- دریافت لایسنس موقت رایگان
- مطالعهٔ چگونه بارگذاری منابع خارجی را نادیده بگیرید
- یادگیری زمانی که GroupDocs.Merger به شبکه دسترسی پیدا میکند
- مرور راهنمای گامبهگام موارد استفاده
- بررسی پروژهٔ نمونه در GitHub