Content Disarm and Reconstruction — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi mendalam untuk modul NextPDF\Enterprise\Security\Cdr. Modul ini melucuti PDF tidak tepercaya dan merekonstruksi berkas bersih dari objek-objeknya yang aman. Pipeline-nya adalah: parse, kontrol penerimaan, deteksi ancaman, penyaringan, pembersihan referensi, rebuild. Outputnya adalah proyeksi keamanan dari input, bukan pernah salinan bukti. Untuk panduan alur kerja, baca dahulu halaman kapabilitas CDR.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan API publik

Symbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
CdrEngine::__construct	tidak ada	Membangun detector dan rebuilder internal	CdrEngine	Tidak ada yang dideklarasikan	Tidak ada kolaborator yang dapat di-inject
CdrEngine::sanitize	string $pdfData, ?CdrPolicy $policy = null	Menjalankan pipeline penuh di bawah CdrPolicy::standard()	CdrResult	Tidak melempar pada input berbahaya; kegagalan parse dan penerimaan mengembalikan hasil yang ditolak	Hasil melaporkan penolakan secara berbeda dari sanitisasi
CdrPolicy::__construct	tujuh named parameter opsional, lihat fence	Set penghapusan kosong; allowUriActions false; flattenIncrementalUpdates true; batas 100000 objek, 256 MiB decoded, 10000 halaman, 1000.0 inflation	CdrPolicy	Tidak ada yang dideklarasikan	final readonly; daftar removeThreatTypes kosong tidak mendeteksi apa pun
CdrPolicy::standard	tidak ada	Set ancaman legacy; URI action dihapus; batas default	self	Tidak ada yang dideklarasikan	Mengecualikan tujuh case Strip* yang lossy
CdrPolicy::paranoid	tidak ada	Set ancaman legacy dengan batas lebih ketat: 50000 objek, 128 MiB, 5000 halaman, 100.0 inflation	self	Tidak ada yang dideklarasikan	Mengecualikan tujuh case Strip* yang lossy
CdrPolicy::permissive	tidak ada	Hanya menghapus JavaScript, LaunchAction, NamedJavaScript, SubmitForm, ImportData; mempertahankan URI action	self	Tidak ada yang dideklarasikan	Ditujukan untuk sumber tepercaya
CdrPolicy::allThreatTypes	tidak ada	Mengembalikan setiap case ThreatType, termasuk case Strip* yang lossy	list<ThreatType>	Tidak ada yang dideklarasikan	Opt-in maximal-strip yang eksplisit
CdrPolicy::legacyThreatTypes	tidak ada	Mengembalikan setiap case kecuali tujuh case Strip*	list<ThreatType>	Tidak ada yang dideklarasikan	Set penghapusan default untuk standard() dan paranoid()
CdrPolicy::shouldRemove	ThreatType $type	Uji keanggotaan terhadap removeThreatTypes	bool	Tidak ada yang dideklarasikan	Mengembalikan false untuk UriAction ketika allowUriActions bernilai true
ThreatDetector::detect	PdfReader $reader, CdrPolicy $policy	Memindai setiap objek dan katalog trailer untuk jenis ancaman policy	list<DetectedThreat>	Tidak melempar; objek yang tidak dapat di-parse menjadi ancaman UnparseableObject	Pemindaian katalog mencakup name tree /Names/JavaScript
CdrRebuilder::rebuild	PdfReader $reader, list<int> $safeObjNums, list<int> $removedObjNums, CdrPolicy $policy	Men-serialize objek aman ke dalam berkas %PDF-2.0 single-revision	string	Tidak ada yang dideklarasikan; objek yang gagal re-read atau validasi /Length dilewati	$policy dicadangkan untuk penyesuaian serialisasi di masa depan
DetectedThreat::__construct	ThreatType $type, int $objectNumber, string $description, string $location = ''	Value object temuan yang immutable	DetectedThreat	Tidak ada yang dideklarasikan	Keempat properti bersifat public readonly
ThreatType	enum string-backed	Dua puluh case: tiga belas legacy plus tujuh case Strip* opt-in	n/a	n/a	Lihat inventaris case di bawah

Signature titik masuk

final class CdrEngine
{
    public function __construct()

    public function sanitize(string $pdfData, ?CdrPolicy $policy = null): CdrResult
}

final readonly class CdrPolicy
{
    public function __construct(
        public array $removeThreatTypes = [],
        public bool $allowUriActions = false,
        public bool $flattenIncrementalUpdates = true,
        public int $maxObjects = 100_000,
        public int $maxDecodedStreamBytes = 268_435_456,
        public int $maxPageCount = 10_000,
        public float $maxInflationRatio = 1000.0,
    )

    public static function standard(): self

    public static function paranoid(): self

    public static function permissive(): self

    public static function allThreatTypes(): array

    public static function legacyThreatTypes(): array

    public function shouldRemove(ThreatType $type): bool
}

final class ThreatDetector
{
    public function detect(PdfReader $reader, CdrPolicy $policy): array
}

final class CdrRebuilder
{
    public function rebuild(PdfReader $reader, array $safeObjNums, array $removedObjNums, CdrPolicy $policy): string
}

final readonly class DetectedThreat
{
    public function __construct(
        public ThreatType $type,
        public int $objectNumber,
        public string $description,
        public string $location = '',
    )
}

enum ThreatType: string

Inventaris case ThreatType

Tiga belas case legacy membentuk set penghapusan default. Case Strip* bersifat lossy secara desain dan tidak pernah masuk ke policy default.

Case	Nilai backing	Permukaan deteksi
ThreatType::JavaScript	javascript	Key /JS pada objek mana pun, atau action /S /JavaScript
ThreatType::AdditionalActions	additional-actions	Dictionary /AA pada objek mana pun
ThreatType::OpenAction	open-action	Key /OpenAction pada objek mana pun
ThreatType::LaunchAction	launch-action	Action /S /Launch
ThreatType::RemoteGoTo	remote-goto	Action /S /GoToR atau /S /GoToE
ThreatType::SubmitForm	submit-form	Action /S /SubmitForm
ThreatType::ImportData	import-data	Action /S /ImportData
ThreatType::EmbeddedFiles	embedded-files	Name tree /EmbeddedFiles atau dictionary /EF
ThreatType::RichMedia	rich-media	/Subtype /RichMedia
ThreatType::NamedJavaScript	named-javascript	Name tree katalog /Names/JavaScript
ThreatType::UriAction	uri-action	Action /S /URI; ditekan ketika allowUriActions bernilai true
ThreatType::Xfa	xfa	Key /XFA
ThreatType::UnparseableObject	unparseable-object	Objek atau katalog mana pun yang gagal di-parse
ThreatType::StripJavaScript	strip-javascript	Superset opt-in: key /JS, /S /JavaScript, atau /Subtype /JavaScript
ThreatType::StripEmbeddedFiles	strip-embedded-files	Opt-in: /Type /EmbeddedFile, /Type /Filespec, /EmbeddedFiles, atau /EF
ThreatType::StripFormFields	strip-form-fields	Opt-in: /Subtype /Widget, key /FT, atau key /AcroForm
ThreatType::StripAnnotationsRich	strip-annotations-rich	Subtype opt-in: Movie, Sound, FileAttachment, 3D, RichMedia, Screen
ThreatType::StripOcgNonDefault	strip-ocg-non-default	Opt-in: /Type /OCG dengan key /Usage atau /Visibility
ThreatType::StripDigitalSignaturesAtRebuild	strip-digital-signatures-at-rebuild	Opt-in: /Type /Sig, /FT /Sig, /DSS, /VRI, atau /ByteRange
ThreatType::Strip3dAndRichMedia	strip-3d-and-rich-media	Subtype opt-in: 3D, U3D, PRC, RMF, RichMedia, Sound, Movie

Kontrak perilaku

CdrEngine::sanitize menjalankan enam fase terurut dan tidak pernah melempar untuk input berbahaya.

1. Parse. Kegagalan parse mengembalikan hasil dengan admitted false dan alasan penolakan berupa parse-error. Output tersanitisasi kosong dalam kasus tersebut.
2. Kontrol penerimaan. Jumlah objek, agregat byte stream decoded, rasio inflation per-stream, dan jumlah halaman diperiksa terhadap batas policy. Dokumen yang melampaui batas ditolak, bukan disanitisasi. Penolakan dan sanitisasi dilaporkan secara berbeda.
3. Deteksi. ThreatDetector::detect memindai setiap objek dan katalog trailer untuk jenis ancaman policy. Objek yang tidak dapat di-parse dicatat sebagai temuan ThreatType::UnparseableObject alih-alih dilewati.
4. Penyaringan. Objek yang membawa temuan diantrikan untuk dihapus. Katalog dokumen tidak pernah dihapus sebagai objek utuh. Temuan tingkat katalog (OpenAction, AdditionalActions, NamedJavaScript) diremediasi dengan penghapusan key alih-alih.
5. Pembersihan referensi. Setiap referensi tidak langsung ke objek yang dihapus digantikan dengan null selama serialisasi.
6. Rebuild. CdrRebuilder::rebuild menghasilkan berkas %PDF-2.0 single-revision dengan objek yang dinomori ulang, tabel cross-reference klasik, dan trailer baru. Byte stream yang aman disalin secara byte-identik. Katalog hasil rebuild membuang /OpenAction, /AA, dan /Names; /AA dibuang dari setiap objek.

CdrResult yang dikembalikan mengekspos byte hasil rebuild, daftar ancaman yang dihapus, kedua ukuran byte, flag penerimaan, dan alasan penolakan. Jika sumber memiliki /Root yang dapat diresolusi dan output hasil rebuild kehilangannya, engine menolak output alih-alih mengembalikan berkas yang rusak secara struktural. Ini adalah jaminan fail-closed: admitted true menyiratkan output masih membawa referensi katalog dokumen.

Incremental update tidak pernah bertahan: rebuild men-serialize tepat satu revisi di bawah setiap policy, sehingga revisi terlambat bergaya shadow diratakan secara konstruksi. Signature digital asli tidak dapat tetap valid melintasi rebuild, karena byte range tidak lagi cocok dengan output.

Garis merah arsitektur. CDR adalah lapisan proyeksi keamanan, bukan lapisan preservasi. Output tidak boleh digunakan untuk preservasi bukti legal, perbandingan hash dengan aslinya, atau salinan arsip.

Edge case & mode kegagalan

• Policy null diresolusi menjadi CdrPolicy::standard(). Policy yang dibangun dengan removeThreatTypes default yang kosong tidak mendeteksi maupun menghapus apa pun.
• allowUriActions yang diset true menekan penghapusan UriAction bahkan ketika case tersebut hadir dalam removeThreatTypes.
• flattenIncrementalUpdates bersifat deklaratif pada rilis ini: rebuild menghasilkan satu revisi di bawah setiap policy, termasuk permissive(), yang menyetel flag ke false.
• Pemeriksaan rasio inflation memperlakukan panjang stream mentah nol sebagai satu, sehingga stream yang membengkak dari ketiadaan tetap terbatas. Ketika tidak ada bentuk decoded yang dipertahankan, panjang stream mentah dihitung terhadap anggaran agregat.
• Pemeriksaan penerimaan jumlah halaman bersifat best-effort: kegagalan membaca katalog atau page-tree tidak menolak dokumen dengan sendirinya. Anggaran jumlah objek dan dekompresi selalu ditegakkan.
• Objek yang panjang stream mentahnya tidak sesuai dengan entri integer /Length-nya dilewati saat rebuild (pertahanan polyglot). Referensi ke objek yang dilewati tersebut mempertahankan nomor objek sumbernya dan mungkin tidak teresolusi dalam output. sanitize() menolak hasil yang terdeteksi rusak (/Root yang hilang), tetapi pemanggil yang mengendalikan CdrRebuilder::rebuild() tingkat rendah secara langsung harus memvalidasi ulang struktur output dan integritas referensi sendiri.
• Ketika trailer sumber membawa /ID, trailer hasil rebuild membawa /ID acak yang baru dibuat, bukan yang asli. Entri trailer lain, termasuk /Info, tidak dibawa serta; trailer hasil rebuild menyimpan /Size, /Root ketika dapat diresolusi, dan /ID yang diregenerasi.
• Byte nama dan key yang telah didecode dipancarkan ulang dengan escape heksadesimal untuk delimiter, whitespace, dan byte non-printable, sehingga nama berbahaya tidak dapat menyuntikkan sintaks dictionary ke dalam output.
• Nilai string di bawah key dictionary di luar himpunan name-valued yang dikenal secara konservatif dipancarkan sebagai literal string.
• CdrPolicy::legacyThreatTypes() memperlakukan setiap case enum di masa depan sebagai default-removed kecuali terdaftar sebagai case Strip*, sehingga case lossy baru tidak dapat secara diam-diam masuk ke policy default.
• CDR bukan modul kriptografi. Satu-satunya penggunaan keacakannya adalah /ID trailer yang diregenerasi. Validasi signature berada di luar cakupan di sini; lihat Referensi mendalam Signature.

Konformansi

Klaim	Standar	Klausul
Menjalankan action ECMAScript membuat prosesor PDF mengeksekusi skrip yang tertanam.	ISO 32000-2	§12.6.4.17
Skrip tingkat dokumen dalam name tree JavaScript semuanya dieksekusi ketika dokumen dibuka.	ISO 32000-2	§12.6.4.17
Name dictionary katalog dapat menyimpan name tree JavaScript berisi action skrip tingkat dokumen.	ISO 32000-2	§7.7.4 (Table 32)
Sebuah launch action menjalankan aplikasi, atau membuka atau mencetak dokumen.	ISO 32000-2	§12.6.4.6
Dictionary additional-actions /AA memperluas event pemicu pada anotasi, halaman, field, dan katalog.	ISO 32000-2	§12.6.3
Intake berkas tidak tepercaya harus membatasi keberadaan, volume, dan konten berkas yang masuk.	OWASP ASVS 5.0	§5.2
Sistem harus mencegah eksekusi berkas yang diunggah secara tidak semestinya dan mendeteksi konten berbahaya.	OWASP ASVS 5.0	§5.3

Semua klausul diparafrasekan; NextPDF tidak mereproduksi teks normatif. NextPDF tidak membuat klaim sertifikasi. CDR menghapus permukaan konten aktif yang dienumerasi oleh ThreatType di bawah policy yang dikonfigurasi; ini adalah kapabilitas, bukan sanitizer bersertifikat. CDR bukan pemindai antivirus dan tidak mendeteksi signature malware; ia melengkapi, dan tidak memenuhi, kontrol seperti pemindaian antivirus OWASP ASVS 5.4.3. Apakah sebuah berkas yang telah dilucuti dapat diterima untuk suatu pipeline intake tertentu tetap merupakan keputusan risiko operator.

Catatan pengembangan

• Sumber modul membawa @since 1.9.0; referensi ini mendokumentasikan permukaan sebagaimana dikirimkan dalam nextpdf/enterprise 3.1.0.
• Semuanya berjalan in-process pada host Anda. Tidak ada akses jaringan yang terjadi selama sanitisasi.
• CdrPolicy dan DetectedThreat bersifat final readonly; bangun instance policy baru untuk mengubah batas.
• CdrEngine membangun detector dan rebuilder-nya secara internal. ThreatDetector dan CdrRebuilder tetap dapat digunakan langsung untuk pipeline bertahap yang menyediakan PdfReader-nya sendiri.
• Parameter $policy dari CdrRebuilder::rebuild saat ini dicadangkan; sumber mendokumentasikannya sebagai dipertahankan untuk kompatibilitas call-site dan penyesuaian serialisasi per-policy di masa depan.
• Output dapat direproduksi secara struktural, bukan secara bitwise: /ID yang diregenerasi berbeda pada setiap run ketika sumber membawanya.
• Tipe hasil CdrResult (nilai kembalian sanitize()) telah dibahas secara perilaku di atas; field-fieldnya bersifat public readonly, dengan hadThreats() dan threatCount() sebagai kemudahan.

Lihat juga

• Content Disarm and Reconstruction (CDR) — halaman kapabilitas dengan panduan alur kerja dan policy.
• Security — Referensi Mendalam
• Validation — Referensi Mendalam
• Forensics — Referensi Mendalam

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.