💡 完整可運作的範例可在 GitHub 上取得: secure-untrusted-document-upload-conversion-dotnet
應付帳款挑戰:為何供應商上傳轉換在大規模時會失效
您的伺服器負責將發票轉換;供應商的 HTML 決定它還會讀取什麼。使用 GroupDocs.Conversion for .NET 進行安全的供應商上傳轉換,能將上傳的檔案轉成 PDF,同時防止檔案本身的參考自行決定伺服器接下來要抓取或讀取的內容。
供應商發票入口允許任何已核准的供應商上傳發票——通常是 HTML 或 PDF,有時會附帶 SVG 圖紙作為設施或建築項目——然後應付帳款系統會將其轉成 PDF 以供存檔與審批流程。這個 HTML 是供應商寫的,而非您的團隊,且它可以參考任何網頁能參考的資源:樣式表、腳本、供應商自有 CDN 上的圖片,或——如果供應商帳號被入侵——一個根本不應該從您的網路可達的位址。
供應商的數量只會不斷增加。當從少數幾家供應商成長到數百家時,原本只存放單一公司檔案的 uploads 資料夾現在會放滿所有人的檔案——而某個供應商發票內的相對圖片參考,可能會解析到屬於另一個供應商、正好與之相鄰的檔案。
應付帳款團隊真正需要的不是網路防火牆規則,而是一個在預設情況下將上傳內的每個參考視為不可信的轉換步驟,允許經過審核的資產(例如供應商的商標)通過,並在白名單條目寫錯時大聲失敗——而不是靜默失敗。
現實檢驗:一個指向
http://169.254.169.254/latest/meta-data/iam/security-credentials/的<img>標籤,會要求轉換伺服器呼叫雲端 metadata 服務——這是上傳者在外部永遠無法發出的請求。這是伺服器端請求偽造,而僅僅一次 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 of the sample repository。
步驟 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;
這正是開頭所描述的建築發票情境:看似僅是平面圖的圖紙仍可能攜帶指向雲端 metadata 端點、本機檔案或攻擊者伺服器的參考。於工作範例中,這三者皆被阻止,說明文字會如實呈現,因為附帶的腳本永遠不會執行。
前後行為比較
| 檢查項目 | 直接從已儲存路徑轉換 | 此方法 |
|---|---|---|
| 同資料夾的兄弟檔案 | 自動載入 | 阻止 – 串流輸入移除基礎資料夾 |
| 供應商商標 | 阻止;PDF 只顯示 alt 文字 | 從已審核的本機檔案提供 |
| 雲端 metadata / 內部位址 | 依預設阻止 | 依預設阻止 |
| 僅主機名稱的白名單條目 | 以 InvalidLoadOptionsException 拒絕 |
同樣以例外拒絕,並在啟動檢查時捕捉 |
| 上傳中的內嵌腳本 | 不會執行 | 不會執行 |
變動的兩列是:商標與兄弟檔案。兄弟檔案是網路層級的審查永遠抓不到的,因為根本不涉及網路請求。
其他適用於供應商文件的情境
ExternalResourceHandler 屬性同樣存在於多種供應商入口常見格式的載入選項中,因此上述模式並不限於 HTML 與 SVG:
- 供應商提交的 Word 或 Excel 附件:
WordProcessingLoadOptions與SpreadsheetLoadOptions皆提供相同的處理程式合約。 - 電子郵件發票:
EmailLoadOptions為電子郵件正文中遠端圖片提供相同的處理程式。 - XBRL 財務申報:
FinanceLoadOptions處理供應商提交的 XBRL 文件中的分類法參考。
開始建置您的供應商上傳管線
您已看到 GroupDocs.Conversion 如何安全處理不可信的供應商上傳。接下來的步驟:
- 免費開始: 取得臨時授權 以移除評估限制
- 閱讀完整資源政策: skip loading of external resources 內詳述
WhitelistedResources、IExternalResourceHandler與腳本處理方式 - 檢查所有可能觸及網路的項目: network access and data privacy
- 遵循步驟指南: convert untrusted uploads safely - use case
- 瀏覽完整範例: secure-untrusted-document-upload-conversion-dotnet on GitHub