الأمان والتشغيل — NextPDF على CodeIgniter 4

لمحة سريعة

تصف هذه الصفحة التهديدات التي يجب أن يقاومها هذا التكامل، والضوابط المُتحقَّق منها في مصدر الحزمة، والقواعد التشغيلية التي ينبغي اتباعها للنشر بأمان.

نموذج التهديدات

ينبغي أخذ ثلاثة أسطح يمكن للمهاجم التأثير فيها في الحسبان.

حمولة مهمة الطابور. يخزّن الطابور بيانات المهمة. ويمكن لمهاجم لديه وصول إلى الوسيط أن يغيّر تلك البيانات. عامِلها على أنها مدخلات غير موثوقة ومُفكَّكة من التسلسل.
اسم ملف الاستجابة. يمكن للمستخدم تحديد اسم ملف التنزيل. ويمكن لاسم خبيث أن يحقن محتوى في الترويسة.
مسارات الإعداد. يأتي مسار الخط ومسارات التوقيع من الإعداد. ويمكن لمسار خبيث أن يقرأ من موقع خاطئ أو يكتب إليه.

الضابط 1 — قائمة السماح لحمولة الطابور

تعامل مهمة الطابور حمولتها على أنها بيانات غير موثوقة ومُفكَّكة من التسلسل. ويقتضي معيار التحقق من أمان التطبيقات (⁨ASVS⁩) الصادر عن مشروع أمان تطبيقات الويب العالمي المفتوح (⁨OWASP⁩) معالجة آمنة للمدخلات الخاصة بالبيانات غير الموثوقة المُفكَّكة من التسلسل (⁨ASVS V1.5.2⁩).

الضوابط المُتحقَّق منها في GeneratePdfJob:

يجب أن يكون المُنشئ سلسلة نصية غير فارغة. ترفض المهمة أي نوع آخر.
يجب أن يطابق المُنشئ النمط App\PdfBuilders\<Class>::<method>. ترفض المهمة أي مساحة أسماء أخرى، والدوال غير المؤهلة، والحمولات التي تحمل بادئة أو لاحقة.
يجب أن يكون المُنشئ قابلاً للاستدعاء. ترفض المهمة سلسلة نصية تطابق النمط لكنها لا تُحلّ إلى هدف فعلي.

تمنع هذه القواعد مجتمعة تنفيذ تعليمات برمجية اعتباطية عبر حمولة طابور مُتلاعَب بها. وتتحقق اختبارات الحزمة من كل حالة رفض.

الضابط 2 — حصر مسار مخرجات الطابور

تكتب المهمة ملفاً إلى القرص. ويقتضي معيار ⁨OWASP ASVS⁩ معالجة آمنة للمسارات عندما ينشئ التطبيق مسارات ملفات لعمليات الملفات (⁨ASVS V5.3.2⁩).

الضوابط المُتحقَّق منها في GeneratePdfJob:

يجب أن يكون مسار المخرجات سلسلة نصية غير فارغة.
تُسوّي المهمة المسار قبل أي تحقق. فهي تحلّ مقاطع . و.. وتحوّل الفواصل.
يجب أن يقع المسار المُسوَّى داخل WRITEPATH/pdfs/. ترفض المهمة دليلاً شقيقاً يشترك معه في بادئة الاسم (pdfs-evil/).
يجب أن ينتهي المسار بـ .pdf (دون حساسية لحالة الأحرف).

تمنع هذه القواعد عمليات كتابة ملفات اعتباطية عبر حمولة مُتلاعَب بها.

الضابط 3 — تقوية ترويسات الاستجابة

يُرفِق PdfResponse مجموعة ثابتة ومُقوَّاة من الترويسات بكل استجابة بصيغة المستند المحمول (⁨PDF⁩):

الترويسة	القيمة
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`Content-Security-Policy`	`default-src 'none'`
`X-Robots-Tag`	`noindex, nofollow`
`Referrer-Policy`	`no-referrer`
`Cache-Control`	`private, max-age=0, must-revalidate`

تُنقّي الحزمة اسم الملف قبل وصوله إلى الترويسة. فهي تزيل فواصل المسار والبايتات الصفرية ورموز ⁨return/line feed⁩ (⁨CR/LF⁩). وتُهرّب علامات الاقتباس المزدوجة للصيغة المقتبسة. وتضيف وسيط filename*=UTF-8''… وفق طلب التعليقات (⁨RFC⁩) 5987 للأسماء غير المنتمية إلى ⁨ASCII.⁩ ويصبح الاسم الفارغ document.pdf.

الضابط 4 — التحقق من مسار الإعداد

يرفض سجل الخطوط قيمة fontsPath التي تحتوي على مُغلِّف دفق (://) أو بايت صفري. فهو يطلق خطأ وقت التشغيل. ويمنع هذا المسارات المُغلَّفة مثل php:// أو phar://.

الضابط 5 — تقليص سطح مُحدِّد موقع الخدمة

لا يوفّر ⁨CodeIgniter 4⁩ حاوية وفق توصية معايير ⁨PHP⁩ رقم 11 (⁨PSR-11⁩). بل يستخدم مُحدِّد موقع ⁨Services.⁩ يعدّ ⁨PSR-11⁩ §1.3 نمط مُحدِّد موقع الخدمة غير مُستحسَن (بصيغة ⁨SHOULD NOT⁩ الإلزامية). تُبقي الحزمة سطح المُحدِّد صغيراً: لكل خدمة دالة مصنع مُسمّاة واحدة. حُلّ الخدمات عند حدود وحدة التحكم، ومرّر الكائنات الفعلية إلى الداخل. لا تمرّر فئة Services إلى كود النطاق.

عمليات التوقيع و⁨TSA⁩ (⁨NextPDF Pro⁩ / ⁨Enterprise⁩)

تبقى خدمة التوقيع غير نشطة افتراضياً. ولا تُفعَّل إلا عندما تكون قيمة signature.enabled هي true وتكون signature.certificate غير فارغة. مستوى التوقيع الافتراضي للحزمة هو B-B. يوفّر ⁨NextPDF Pro⁩ توقيع خط الأساس ⁨B-B.⁩ أما التحقق طويل الأمد فهو قدرة منفصلة في إصدار ⁨Enterprise⁩، وموثّقة في مرجع ⁨Premium⁩ لا هنا.

القواعد التشغيلية:

أبقِ ملفات الشهادة والمفتاح خارج نظام إدارة المصدر. ووفّرها عبر .env أو مدير أسرار.
أبقِ tsa.allow_insecure_http مضبوطة على false في بيئة الإنتاج. قناة سلطة الطابع الزمني (⁨TSA⁩) بنص صريح غير مقبولة.
اضبط tsa.pinned_public_keys عندما تنشر ⁨TSA⁩ مفتاحاً ثابتاً. أبقِ tsa.warn_on_key_rotation مضبوطة على true.
احصر صلاحية قراءة ملف المفتاح بمستخدم التطبيق.

قائمة التحقق التشغيلية

ثبّت كل الإصدارات المُحلّة في composer.lock.
اشترط codeigniter4/queue في التطبيق الذي يشغّل العاملين.
شغّل عامل الطابور بصلاحيات مستخدم منخفضة. وامنحه صلاحية الكتابة إلى WRITEPATH/pdfs/ فقط.
امنح العامل امتدادات ⁨NextPDF⁩ نفسها التي تملكها طبقة الويب. يحتاج ملف ⁨PDF⁩ موقّع إلى ⁨NextPDF Pro⁩ أو ⁨Enterprise⁩ في بيئة العامل.
تأكّد من توفّر امتدادَي mbstring وzlib في كل بيئة تشغيل تبني ملف ⁨PDF.⁩
تأكّد من بقاء ترويسات الاستجابة بعد المرور عبر الوكيل العكسي.
سجّل توليد ملفات ⁨PDF⁩ مع السياق. لا تسجّل مادة الشهادة أو كلمات مرور المفتاح.

المطابقة

تتوافق معالجة حمولة الطابور مع ⁨OWASP ASVS V1.5.2.⁩
تتوافق معالجة مسار مخرجات الطابور مع ⁨OWASP ASVS V5.3.2.⁩
يتبع تصميم المُحدِّد إرشادات ⁨PSR-11⁩ §1.3.

السياق التجاري

نواة ⁨NextPDF⁩ مرخّصة بموجب ⁨Apache-2.0.⁩ تنطبق مراسي الثقة الخاصة بالتوقيع وتقوية ⁨TSA⁩ عند تثبيت ⁨NextPDF Pro⁩ أو ⁨Enterprise.⁩ تكشف حزمة ⁨CodeIgniter⁩ دوال الخدمة المقابلة، وتُرجع null إلى أن تُثبَّت حزمة ⁨Premium⁩ المطابقة. انظر </get-license/?intent=codeigniter-signing>.

انظر أيضاً

/⁨integrations/codeigniter/production-usage/⁩ — التسجيل الصحيح للطابور وإرساله.
/⁨integrations/codeigniter/configuration/⁩ — التوقيع و⁨TSA⁩ ومفاتيح المسارات.
/⁨integrations/codeigniter/troubleshooting/⁩ — رسائل الرفض المُتحقَّق منها.
/⁨integrations/codeigniter/overview/⁩ — سطح ⁨API⁩ الكامل.