تفكيك المحتوى وإعادة بنائه — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع المتعمّق لوحدة ⁨NextPDF\Enterprise\Security\Cdr⁩. تُفكّك الوحدة ملف ⁨PDF⁩ غير موثوق وتعيد بناء ملف نظيف من كائناته الآمنة. المسار هو: التحليل، والتحكّم في القبول، وكشف التهديدات، والترشيح، وتنظيف المراجع، وإعادة البناء. المخرجات إسقاط أمني للمدخلات، وليست نسخة إثباتية أبدًا. للإرشاد حول سير العمل، اقرأ صفحة قدرة CDR أولًا.

التوفّر والترخيص

تُشحن هذه القدرة ضمن ⁨NextPDF⁩ Enterprise (⁨nextpdf/enterprise⁩) وتُفعَّل بمظروف ترخيص من فئة Enterprise. النشر بدون هذا الاستحقاق لا يُحمّل أصناف القدرة. قارن الإصدارات واحصل على ترخيص.

سطح واجهة برمجة التطبيقات العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
CdrEngine::__construct	لا شيء	يُنشئ الكاشف والباني الداخليين	CdrEngine	لا شيء معلن	لا متعاونون قابلون للحقن
CdrEngine::sanitize	string $pdfData، ?CdrPolicy $policy = null	يشغّل المسار الكامل بموجب CdrPolicy::standard()	CdrResult	لا يرمي عند المدخلات العدائية؛ إخفاقات التحليل والقبول تُعيد نتيجة مرفوضة	تُبلّغ النتيجة عن الرفض بتمييز عن التعقيم
CdrPolicy::__construct	سبعة معاملات مسمّاة اختيارية، انظر الكتلة	مجموعة إزالة فارغة؛ allowUriActions بقيمة false؛ flattenIncrementalUpdates بقيمة true؛ الحدود 100000 كائن، و256 MiB بعد فك الضغط، و10000 صفحة، ونسبة تضخّم 1000.0	CdrPolicy	لا شيء معلن	final readonly؛ قائمة removeThreatTypes الفارغة لا تكشف شيئًا
CdrPolicy::standard	لا شيء	مجموعة التهديدات القديمة؛ إجراءات URI مُزالة؛ الحدود الافتراضية	self	لا شيء معلن	يستثني حالات Strip* السبع المُفقِدة
CdrPolicy::paranoid	لا شيء	مجموعة التهديدات القديمة بحدود أضيق: 50000 كائن، و128 MiB، و5000 صفحة، وتضخّم 100.0	self	لا شيء معلن	يستثني حالات Strip* السبع المُفقِدة
CdrPolicy::permissive	لا شيء	يُزيل فقط JavaScript وLaunchAction وNamedJavaScript وSubmitForm وImportData؛ يحفظ إجراءات URI	self	لا شيء معلن	مُخصّص للمصادر الموثوقة
CdrPolicy::allThreatTypes	لا شيء	يُعيد كل حالة ThreatType، بما في ذلك حالات Strip* المُفقِدة	list<ThreatType>	لا شيء معلن	اختيار صريح للتجريد الأقصى
CdrPolicy::legacyThreatTypes	لا شيء	يُعيد كل حالة عدا حالات Strip* السبع	list<ThreatType>	لا شيء معلن	مجموعة الإزالة الافتراضية لـ standard() وparanoid()
CdrPolicy::shouldRemove	ThreatType $type	اختبار عضوية مقابل removeThreatTypes	bool	لا شيء معلن	يُعيد false لـ UriAction عندما تكون allowUriActions بقيمة true
ThreatDetector::detect	PdfReader $reader، CdrPolicy $policy	يفحص كل كائن وكتالوج المذيّل بحثًا عن أنواع تهديدات السياسة	list<DetectedThreat>	لا يرمي؛ الكائن غير القابل للتحليل يصبح تهديد UnparseableObject	فحص الكتالوج يشمل شجرة /Names/JavaScript
CdrRebuilder::rebuild	PdfReader $reader، list<int> $safeObjNums، list<int> $removedObjNums، CdrPolicy $policy	يُسلسل الكائنات الآمنة في ملف %PDF-2.0 بمراجعة واحدة	string	لا شيء معلن؛ الكائنات التي تفشل في إعادة القراءة أو التحقق من /Length تُتخطّى	$policy محجوز لتعديلات تسلسل مستقبلية
DetectedThreat::__construct	ThreatType $type، int $objectNumber، string $description، string $location = ''	كائن قيمة غير قابل للتغيير يمثّل نتيجة	DetectedThreat	لا شيء معلن	الخصائص الأربع جميعها public readonly
ThreatType	تعداد مدعوم بسلسلة نصية	عشرون حالة: ثلاث عشرة قديمة زائد سبع حالات Strip* اختيارية	n/a	n/a	انظر جرد الحالات أدناه

توقيعات نقاط الدخول

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

جرد حالات ⁨ThreatType⁩

ثلاث عشرة حالة قديمة تُشكّل مجموعة الإزالة الافتراضية. حالات ⁨Strip*⁩ مُفقِدة بحكم التصميم ولا تدخل سياسة افتراضية أبدًا.

الحالة	القيمة الداعمة	سطح الكشف
ThreatType::JavaScript	javascript	مفتاح /JS على أي كائن، أو إجراء /S /JavaScript
ThreatType::AdditionalActions	additional-actions	قاموس /AA على أي كائن
ThreatType::OpenAction	open-action	مفتاح /OpenAction على أي كائن
ThreatType::LaunchAction	launch-action	إجراء /S /Launch
ThreatType::RemoteGoTo	remote-goto	إجراء /S /GoToR أو /S /GoToE
ThreatType::SubmitForm	submit-form	إجراء /S /SubmitForm
ThreatType::ImportData	import-data	إجراء /S /ImportData
ThreatType::EmbeddedFiles	embedded-files	شجرة أسماء /EmbeddedFiles أو قاموس /EF
ThreatType::RichMedia	rich-media	/Subtype /RichMedia
ThreatType::NamedJavaScript	named-javascript	شجرة أسماء /Names/JavaScript في الكتالوج
ThreatType::UriAction	uri-action	إجراء /S /URI؛ يُكبح عندما تكون allowUriActions بقيمة true
ThreatType::Xfa	xfa	مفتاح /XFA
ThreatType::UnparseableObject	unparseable-object	أي كائن أو كتالوج يفشل في التحليل
ThreatType::StripJavaScript	strip-javascript	مجموعة فائقة اختيارية: مفتاح /JS، أو /S /JavaScript، أو /Subtype /JavaScript
ThreatType::StripEmbeddedFiles	strip-embedded-files	اختياري: /Type /EmbeddedFile، أو /Type /Filespec، أو /EmbeddedFiles، أو /EF
ThreatType::StripFormFields	strip-form-fields	اختياري: /Subtype /Widget، أو مفتاح /FT، أو مفتاح /AcroForm
ThreatType::StripAnnotationsRich	strip-annotations-rich	أنواع فرعية اختيارية: Movie، Sound، FileAttachment، 3D، RichMedia، Screen
ThreatType::StripOcgNonDefault	strip-ocg-non-default	اختياري: /Type /OCG مع مفتاح /Usage أو /Visibility
ThreatType::StripDigitalSignaturesAtRebuild	strip-digital-signatures-at-rebuild	اختياري: /Type /Sig، أو /FT /Sig، أو /DSS، أو /VRI، أو /ByteRange
ThreatType::Strip3dAndRichMedia	strip-3d-and-rich-media	أنواع فرعية اختيارية: 3D، U3D، PRC، RMF، RichMedia، Sound، Movie

عقد السلوك

ينفّذ ⁨CdrEngine::sanitize⁩ ست مراحل مرتّبة ولا يرمي أبدًا مع المدخلات العدائية.

1. التحليل. فشل التحليل يُعيد نتيجة بقيمة ⁨admitted⁩ تساوي false وسبب رفض هو خطأ تحليل. تكون المخرجات المعقّمة فارغة في تلك الحالة.
2. التحكّم في القبول. يُفحَص عدد الكائنات، وإجمالي بايتات التدفّق بعد فك الضغط، ونسبة تضخّم كل تدفّق، وعدد الصفحات مقابل حدود السياسة. المستند الذي يتجاوز الحدّ يُرفَض ولا يُعقَّم. يُبلَّغ عن الرفض والتعقيم بتمييز.
3. الكشف. يفحص ⁨ThreatDetector::detect⁩ كل كائن وكتالوج المذيّل بحثًا عن أنواع تهديدات السياسة. تُسجَّل الكائنات غير القابلة للتحليل كنتائج ⁨ThreatType::UnparseableObject⁩ بدلًا من تخطّيها.
4. الترشيح. تُدرَج الكائنات الحاملة للنتائج في طابور الإزالة. لا يُزال كتالوج المستند أبدًا ككائن كامل. تُعالَج النتائج على مستوى الكتالوج (⁨OpenAction⁩ و⁨AdditionalActions⁩ و⁨NamedJavaScript⁩) بتجريد المفاتيح بدلًا من ذلك.
5. تنظيف المراجع. يُستبدل كل مرجع غير مباشر لكائن مُزال بـ ⁨null⁩ أثناء التسلسل.
6. إعادة البناء. يُنتج ⁨CdrRebuilder::rebuild⁩ ملف ⁨%PDF-2.0⁩ بمراجعة واحدة بكائنات مُعاد ترقيمها، وجدول مراجع تقاطعية كلاسيكي، ومذيّل جديد. تُنسخ بايتات التدفّق الآمنة بتطابق بايتي. يُسقط الكتالوج المُعاد بناؤه ⁨/OpenAction⁩ و⁨/AA⁩ و⁨/Names⁩؛ ويُسقط ⁨/AA⁩ من كل كائن.

يكشف ⁨CdrResult⁩ المُعاد البايتات المُعاد بناؤها، وقائمة التهديدات المُزالة، وكلا حجمَي البايت، وعلَم القبول، وسبب الرفض. إذا كان المصدر يحمل ⁨/Root⁩ قابلًا للحل وفقده المُخرَج المُعاد بناؤه، يرفض المحرّك المخرَج بدلًا من إعادة ملف مكسور بنيويًا. هذا ضمان إغلاق-عند-الفشل: قيمة ⁨admitted⁩ تساوي true تعني أن المخرَج ما يزال يحمل مرجعًا لكتالوج المستند.

التحديثات التزايدية لا تنجو أبدًا: تُسلسل إعادة البناء مراجعة واحدة تمامًا بموجب كل سياسة، لذا تُسطَّح المراجعات المتأخّرة من نمط الظلّ بحكم البناء. لا يمكن أن تبقى التواقيع الرقمية الأصلية صالحة عبر إعادة بناء، لأن نطاقات البايت لم تعد تطابق المخرَج.

خطّ أحمر معماري. إن CDR طبقة إسقاط أمني، لا طبقة حفظ. يجب ألّا يُستخدم المخرَج لحفظ الأدلة القانونية، أو مقارنة التجزئة مع الأصل، أو النسخ الأرشيفية.

الحالات الحدّية وأنماط الفشل

• السياسة ⁨null⁩ تُحلّ إلى ⁨CdrPolicy::standard()⁩. السياسة المُنشأة بقيمة ⁨removeThreatTypes⁩ الفارغة الافتراضية لا تكشف ولا تُزيل شيئًا.
• ضبط ⁨allowUriActions⁩ على ⁨true⁩ يكبح إزالة ⁨UriAction⁩ حتى عندما تكون الحالة موجودة في ⁨removeThreatTypes⁩.
• ⁨flattenIncrementalUpdates⁩ تصريحي في هذا الإصدار: تُنتج إعادة البناء مراجعة واحدة بموجب كل سياسة، بما في ذلك ⁨permissive()⁩ التي تضبط العلَم على ⁨false⁩.
• يعامل فحص نسبة التضخّم طول التدفّق الخام الصفري كواحد، فيبقى التدفّق المتضخّم من العدم مقيّدًا. عند عدم الاحتفاظ بأي صورة بعد فك الضغط، يُحتسب طول التدفّق الخام ضمن الميزانية الإجمالية.
• فحص قبول عدد الصفحات أفضل-جهد: فشل قراءة الكتالوج أو شجرة الصفحات لا يرفض المستند بذاته. تُفرَض دائمًا ميزانيتا عدد الكائنات وفك الضغط.
• الكائن الذي يختلف طول تدفّقه الخام مع قيمة ⁨/Length⁩ الصحيحة يُتخطّى وقت إعادة البناء (دفاع ضد الملفات المتعدّدة الصيغ). المرجع لمثل هذا الكائن المُتخطّى يحتفظ برقم كائنه المصدري وقد لا يُحَلّ في المخرَج. يرفض ⁨sanitize()⁩ النتائج المكسورة القابلة للكشف (غياب ⁨/Root⁩)، لكن على المستدعي الذي يقود ⁨CdrRebuilder::rebuild()⁩ منخفض المستوى مباشرةً أن يُعيد التحقّق من بنية المخرَج وسلامة المراجع بنفسه.
• عندما يحمل مذيّل المصدر ⁨/ID⁩، يحمل المذيّل المُعاد بناؤه ⁨/ID⁩ عشوائيًا مولّدًا حديثًا، لا الأصلي. المدخلات الأخرى في المذيّل، بما فيها ⁨/Info⁩، لا تُنقَل؛ يحمل المذيّل المُعاد بناؤه ⁨/Size⁩، و⁨/Root⁩ عند قابليته للحل، و⁨/ID⁩ المُعاد توليده.
• تُعاد كتابة بايتات الأسماء والمفاتيح بعد فك الضغط بمهارب سداسية عشرية للفواصل والمسافات البيضاء والبايتات غير القابلة للطباعة، فلا تستطيع الأسماء العدائية حقن صياغة قاموس في المخرَج.
• قيم السلاسل النصية تحت مفاتيح القاموس الخارجة عن المجموعة المعروفة ذات القيم الاسمية تُكتب بتحفّظ كسلاسل نصية حرفية.
• يعامل ⁨CdrPolicy::legacyThreatTypes()⁩ أي حالة تعداد مستقبلية على أنها مُزالة افتراضيًا ما لم تُسجَّل كحالة ⁨Strip*⁩، فلا تستطيع الحالات المُفقِدة الجديدة الدخول بصمت إلى السياسات الافتراضية.
• إن CDR ليست وحدة تشفيرية. استخدامها الوحيد للعشوائية هو ⁨/ID⁩ المذيّل المُعاد توليده. التحقّق من التواقيع خارج النطاق هنا؛ انظر المرجع المتعمّق للتواقيع.

المطابقة

الادعاء	المعيار	البند
استدعاء إجراء ECMAScript يجعل معالج PDF ينفّذ السكربت المضمّن.	ISO 32000-2	§12.6.4.17
سكربتات مستوى المستند في شجرة أسماء JavaScript تُنفَّذ جميعها عند فتح المستند.	ISO 32000-2	§12.6.4.17
قد يحمل قاموس أسماء الكتالوج شجرة أسماء JavaScript لإجراءات سكربت على مستوى المستند.	ISO 32000-2	§7.7.4 (Table 32)
إجراء الإطلاق يُطلق تطبيقًا، أو يفتح مستندًا أو يطبعه.	ISO 32000-2	§12.6.4.6
قواميس الإجراءات الإضافية /AA تُوسّع أحداث التشغيل على التعليقات التوضيحية والصفحات والحقول والكتالوج.	ISO 32000-2	§12.6.3
يجب أن يُقيّد استقبال الملفات غير الموثوقة وجود الملفات الواردة وحجمها ومحتواها.	OWASP ASVS 5.0	§5.2
ينبغي أن تمنع الأنظمة التنفيذ غير الملائم للملفات المرفوعة وتكشف المحتوى الخطير.	OWASP ASVS 5.0	§5.3

كل البنود مُعاد صياغتها؛ لا تُعيد ⁨NextPDF⁩ إنتاج النص المعياري. لا تقدّم ⁨NextPDF⁩ أي ادعاء اعتماد. يُزيل CDR أسطح المحتوى النشط المُعدّدة في ⁨ThreatType⁩ بموجب السياسة المُهيّأة؛ وهو قدرة، لا مُعقِّم معتمَد. إن CDR ليس ماسحًا مضادًا للفيروسات ولا يكشف بصمات البرمجيات الخبيثة؛ وهو يُكمّل ضوابط مثل فحص مكافحة الفيروسات في OWASP ASVS ⁨5.4.3⁩ ولا يفي بها. وتبقى مقبولية ملف مُفكَّك لخط استقبال معيّن قرارَ مخاطرة يعود للمشغّل.

ملاحظات التطوير

• يحمل مصدر الوحدة ⁨@since 1.9.0⁩؛ يوثّق هذا المرجع السطح كما شُحن في ⁨nextpdf/enterprise⁩ 3.1.0.
• كل شيء يعمل داخل العملية على مضيفك. لا يحدث أي وصول للشبكة أثناء التعقيم.
• ⁨CdrPolicy⁩ و⁨DetectedThreat⁩ من نوع ⁨final readonly⁩؛ أنشئ نسخة سياسة جديدة لتغيير الحدود.
• يُنشئ ⁨CdrEngine⁩ كاشفه وبانيه داخليًا. يبقى ⁨ThreatDetector⁩ و⁨CdrRebuilder⁩ قابلين للاستخدام مباشرةً في المسارات المرحلية التي توفّر ⁨PdfReader⁩ خاصًا بها.
• معامل ⁨$policy⁩ في ⁨CdrRebuilder::rebuild⁩ محجوز حاليًا؛ يوثّقه المصدر بأنه مُبقى لتوافق مواقع الاستدعاء وتعديلات تسلسل مستقبلية حسب السياسة.
• المخرَج قابل لإعادة الإنتاج بنيويًا، لا بتيًا: يختلف ⁨/ID⁩ المُعاد توليده في كل تشغيل عندما يحمله المصدر.
• نوع النتيجة ⁨CdrResult⁩ (القيمة المُعادة من ⁨sanitize()⁩) مُغطّى سلوكيًا أعلاه؛ حقوله ⁨public readonly⁩، مع ⁨hadThreats()⁩ و⁨threatCount()⁩ كوسائل تيسير.

انظر أيضًا

• تفكيك المحتوى وإعادة بنائه (CDR) — صفحة القدرة مع إرشاد سير العمل والسياسة.
• الأمان — مرجع متعمّق
• التحقّق — مرجع متعمّق
• التحليل الجنائي — مرجع متعمّق

حدّ النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح واجهة البرمجة العامة المدعوم فقط. مسارات فضاءات الأسماء الداخلية، وأصناف المساعدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر خارج النطاق.