💡 Contoh lengkap yang berfungsi tersedia di GitHub:
secure-untrusted-document-upload-conversion-dotnet

Tantangan Akun-Payable: Mengapa Konversi Unggahan Vendor Gagal pada Skala Besar

Server Anda mengonversi faktur; HTML vendor menentukan apa lagi yang dibacanya. Konversi unggahan vendor yang aman dengan GroupDocs.Conversion untuk .NET mengubah file yang diunggah menjadi PDF tanpa membiarkan referensi file itu sendiri memilih apa yang server Anda ambil atau baca selanjutnya.

Portal faktur vendor memungkinkan pemasok yang disetujui mengunggah faktur — biasanya sebagai HTML atau PDF, kadang dengan gambar SVG terlampir untuk item fasilitas atau konstruksi — dan sistem akun-payable mengonversinya menjadi PDF untuk arsip dan alur persetujuan. HTML tersebut ditulis oleh vendor, bukan tim Anda, dan dapat merujuk apa saja yang dapat dirujuk halaman web: stylesheet, script, gambar yang dihosting di CDN vendor sendiri, atau — jika akun vendor telah dikompromikan — alamat yang tidak pernah dimaksudkan dapat dijangkau dari jaringan Anda.

Volume vendor hanya terus bertambah. Ketika jumlah pemasok meningkat dari beberapa menjadi ratusan, folder unggahan yang dulu hanya menyimpan file satu perusahaan kini menyimpan semua file — dan referensi gambar relatif dalam satu faktur vendor dapat terurai menjadi file milik vendor lain yang berada tepat di sebelahnya.

Apa yang sebenarnya dibutuhkan tim akun-payable bukanlah aturan firewall jaringan, melainkan langkah konversi yang memperlakukan setiap referensi dalam unggahan sebagai tidak tepercaya secara default, secara sengaja memperbolehkan aset yang telah ditinjau seperti logo vendor, dan gagal dengan suara keras — bukan diam — ketika entri whitelist ditulis salah.

Pemeriksaan realitas: sebuah tag <img> tunggal yang mengarah ke http://169.254.169.254/latest/meta-data/iam/security-credentials/ meminta server konversi memanggil layanan metadata cloud — permintaan yang tidak dapat dibuat pengunggah dari luar. Itu adalah server‑side request forgery, dan unggahan HTML saja sudah cukup.

Mengapa Perbaikan Umum Tidak Menutup Celah Ini

Tim akun-payable biasanya memilih salah satu dari berikut ini sebelum mengadopsi pustaka konversi dengan kebijakan sumber daya sendiri:

  • Pemblokiran egress jaringan pada host konversi: menghentikan pengambilan jarak jauh, tetapi tidak berpengaruh pada file dalam folder yang sama yang dapat terurai dari referensi relatif — persis seperti yang terjadi ketika unggahan dikonversi langsung dari path yang disimpan.
  • Menghapus tag sebelum konversi: rapuh terhadap tipe referensi baru (<link>, SVG <image>, CSS @import) dan harus diaudit ulang setiap kali format unggahan berubah.
  • Mempercayai pemindai unggahan portal vendor sendiri: memindai tanda tangan malware, bukan URL yang mengarah ke infrastruktur Anda sendiri.

GroupDocs.Conversion menutup celah ini pada titik yang paling penting: saat dokumen dimuat untuk konversi, sebelum output apa pun dihasilkan.

Solusi: GroupDocs.Conversion dalam Alur Kerja Faktur Vendor

GroupDocs.Conversion untuk .NET 26.10 menolak sumber daya eksternal secara default melalui SkipExternalResources, memungkinkan Anda menentukan secara tepat lokasi yang Anda percayai melalui WhitelistedResources, dan memberikan callback per‑sumber daya melalui IExternalResourceHandler yang dapat mengonfirmasi, menimpa, atau menyediakan byte sumber daya secara langsung — sehingga logo vendor yang telah ditinjau tetap dapat muncul di PDF output tanpa ada permintaan jaringan yang pernah dibuat untuknya.

Untuk mengikuti implementasi di bawah ini, Anda memerlukan:

  • .NET 8.0 atau lebih baru
  • GroupDocs.Conversion untuk .NET (get a free trial)
  • Contoh unggahan HTML atau SVG yang tidak Anda kontrol
dotnet add package GroupDocs.Conversion --version 26.10.0

Menerapkan Langkah Konversi Unggahan Vendor Secara Bertahap

Contoh di bawah ini mencerminkan skenario portal vendor nyata: mengonversi faktur yang diunggah (invoice-upload.html) yang merujuk ke logo, alamat internal, file lokal, dan file yang berada di sebelahnya.

Sebagian besar potongan kode di bawah ini melewatkan objek ResourceAudit — sebuah IExternalResourceHandler kecil yang mencatat setiap keputusan pemuatan dan dapat menyediakan byte aset tepercaya. Kode lengkapnya ada di Program.cs of the sample repository.

Langkah 1 - Muat dan Konversi Dari Path yang Disimpan Unggahan

Inilah cara portal mungkin mengonversi unggahan segera setelah menyimpannya ke folder bersama — dan langkah di mana file saudara dapat bocor.

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;

Memuat langsung dari uploadPath menempatkan seluruh folder faktur dalam cakupan, bukan hanya satu file di dalamnya. Cakupan, bukan kepercayaan, yang menentukan apa yang dimuat. Pada eksekusi ini, setiap referensi remote dan file:/// dalam faktur diblokir, tetapi other-customer-signature.svg — file berbeda yang disimpan di folder yang sama — dimuat, karena SkipExternalResources hanya mengecualikan referensi di luar folder tersebut.

Langkah 2 - Konfigurasi untuk Persyaratan Unggahan Vendor

Untuk unggahan vendor, hapus folder dasar sepenuhnya dengan memuat dari stream alih‑alih dari path:

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;

Mengapa pengaturan ini penting untuk portal vendor:

  • Input stream: dokumen yang dikonversi dari stream tidak memiliki folder, sehingga referensi relatif di dalamnya tidak dapat terurai menjadi file vendor lain.
  • ExternalResourceHandler: tetap dijalankan untuk setiap sumber daya, sehingga Anda mencatat secara tepat apa yang diminta setiap unggahan vendor.

Langkah 3 - Eksekusi dan Tangkap Aset yang Telah Ditinjau

Logo vendor adalah satu referensi yang mungkin memang ingin Anda pertahankan — disediakan dari salinan yang Anda kontrol, bukan diambil dari URL vendor sendiri:

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;

Handler ResourceAudit memeriksa URL yang diminta terhadap kamus aset tepercaya; ketika cocok, ia mengatur ExternalResourceLoadingArgs.Data ke byte lokal dan Skipped ke false, sehingga logo muncul di PDF output sementara lima referensi lain dalam faktur tetap diblokir.

Langkah 4 - Tolak Entri Whitelist yang Salah Konfigurasi Secara Dini

Entri whitelist yang hanya berupa nama host, bukan prefiks URI absolut, menyebabkan konversi gagal alih‑alih diam‑diam mencocokkan terlalu banyak:

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;
}

Memberikan cdn.example.com alih‑alih https://cdn.example.com/brand/ memicu InvalidLoadOptionsException dengan pesan: 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/'. Menangkap ini pada saat konversi, dalam tinjauan konfigurasi atau pemeriksaan startup, jauh lebih murah daripada menemukannya dari sumber daya yang salah cocok di produksi. Tangkap sebelum dipublikasikan.

Mengapa Entri Whitelist URL Pernah Ditolak?

WhitelistedResources hanya menerima prefiks URI absolut, seperti https://cdn.example.com/brand/ atau file:///C:/assets/. Versi sebelumnya mencocokkan entri di mana saja dalam URL, sehingga cdn.example.com juga cocok dengan alamat penyerang yang hanya mengandung kata‑kata tersebut. Sejak 26.10 entri tersebut gagal dimuat dengan InvalidLoadOptionsException, dan metode terakhir contoh mencetak pesan persisnya.

Lampiran SVG Vendor Membawa Risiko yang Sama

Gambar fasilitas yang terlampir pada faktur konstruksi tetap hanyalah file SVG, dan diproses melalui SvgLoadOptions alih‑alih WebLoadOptions. Kontrak sama, elemen berbeda: ExternalResourceHandler berlaku untuk referensi <image>‑nya dengan cara yang sama seperti pada tag <img> faktur, dan setiap <script> inline yang dibawa gambar tidak dijalankan:

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;

Inilah skenario faktur konstruksi yang sama seperti pada pembukaan: gambar yang tampak hanya sebagai denah lantai masih dapat membawa referensi ke endpoint metadata cloud Anda, file lokal, atau server penyerang. Pada contoh yang berfungsi ketiganya diblokir, dan keterangan gambar ditampilkan persis seperti yang digambar, karena skrip yang terlampir tidak pernah dijalankan.

Perilaku Sebelum dan Sesudah

Pemeriksaan Mengonversi langsung dari path yang disimpan Pendekatan ini
File saudara dalam folder yang sama Dimuat secara otomatis Diblokir — input stream menghilangkan folder dasar
Logo vendor Diblokir; PDF hanya menampilkan teks alt Disediakan dari file lokal yang telah ditinjau
Metadata cloud / alamat internal Diblokir oleh default Diblokir oleh default
Entri whitelist hanya nama host Ditolak dengan InvalidLoadOptionsException Ditolak dengan cara yang sama, ditangkap oleh pemeriksaan startup
Skrip inline dalam unggahan Tidak dijalankan Tidak dijalankan

Dua baris berubah: logo dan file saudara. File saudara adalah hal yang tidak akan pernah terdeteksi oleh tinjauan tingkat jaringan, karena tidak ada permintaan jaringan yang terlibat.

Skenario Dokumen Vendor Lain yang Relevan

Properti ExternalResourceHandler yang sama ada pada opsi muat untuk beberapa format lain yang biasanya diterima portal vendor, sehingga pola di atas tidak terbatas pada HTML dan SVG:

  • Lampiran Word atau Excel yang dikirim vendor: WordProcessingLoadOptions dan SpreadsheetLoadOptions mengekspos kontrak handler yang sama.
  • Faktur yang dikirim lewat email: EmailLoadOptions mengekspos handler yang sama untuk gambar remote yang dirujuk dalam badan email.
  • Pengajuan keuangan XBRL: FinanceLoadOptions mencakup referensi taksonomi dalam dokumen XBRL yang dikirim vendor.

Memulai dengan Pipeline Unggahan Vendor Anda

Anda telah melihat bagaimana GroupDocs.Conversion menangani unggahan vendor yang tidak tepercaya dengan aman. Berikut langkah selanjutnya:

Resources