AntiSamy

مكتبة لإجراء تنقية سريعة وقابلة للتهيئة لوسوم HTML القادمة من مصادر غير موثوقة. تدعم Java 8+.

بطريقة أخرى يمكن القول: إنها API تساعدك على التأكد من أن العملاء لا يوفّرون حمولة تعليمات برمجية خبيثة في HTML التي يقدمونها لملفاتهم الشخصية أو تعليقاتهم وما إلى ذلك، والتي يتم حفظها على الخادم. مصطلح "التعليمات البرمجية الخبيثة" في سياق تطبيقات الويب يعني عادةً "JavaScript". في معظم الأحيان، لا تُعتبر أوراق الأنماط المتتالية (Cascading Stylesheets) خبيثة إلا عندما تستدعي JavaScript. ومع ذلك، هناك حالات عديدة يمكن فيها استخدام HTML وCSS "العادية" بطريقة خبيثة.

مهم! - تغييرات تكسر التوافق البرمجي في الإصدار 1.7.0

على مدار تطوير سلسلة الإصدارات 1.6.x، حددنا عددًا من الميزات وواجهات البرمجة وأوقفنا استخدامها. وقد تمت إزالة كل هذه العناصر الموقوفة في إصدار 1.7.0. كانت جميع هذه التغييرات مُتتبَّعة في التذكرة: https://github.com/nahsra/antisamy/issues/195. وفيما يلي وصف لكل تغيير:

كان للكائن CssHandler مُنشئان أسقطا المعامل LinkedList<URI> embeddedStyleSheets. الآن يُنشئ كلا المُنشئين LinkedList<URI> داخلية فارغة، ويمكن استخدام الدالة getImportedStylesheetsURIList() للحصول على مرجع إليها إذا لزم الأمر. نادرًا ما تُستخدم هذه الميزة، وفي الواقع الاستدعاء المباشر لهذين المُنشئين نادر أيضًا، لذلك من غير المرجح أن يؤثر هذا التغيير على معظم مستخدمي AntiSamy. عند استخدامها، عادةً ما يتم تمرير قائمة فارغة كقيمة لهذا المعامل ولا تُستخدم تلك القائمة مرة أخرى.

• تم إسقاط التوقيع CssHandler(Policy, LinkedList<URI>, List<String>, ResourceBundle)

  • واستُبدل بالتوقيع: CssHandler(Policy, List<String>, ResourceBundle)

• تم إسقاط التوقيع CssHandler(Policy, LinkedList<URI>, List<String>, String, ResourceBundle)

  • واستُبدل بالتوقيع: CssHandler(Policy, List<String>, ResourceBundle, String). ملاحظة: تم عكس ترتيب آخر معاملين في هذه الدالة.

• تم إسقاط دعم XHTML. يدعم AntiSamy الآن HTML فقط. ونظرًا لأننا نعتقد أن هذه الميزة كانت نادرة الاستخدام، فإننا لا نتوقع أن يؤثر ذلك على العديد من مستخدمي AntiSamy.

• التحقق من مخطط XML مطلوب الآن في ملفات سياسات AntiSamy ولا يمكن تعطيله. يجب أن تجعل ملف السياسة متوافقًا مع المخطط حتى تتمكن من استخدامه مع AntiSamy.

• توجيه السياسة noopenerAndNoreferrerAnchors مفعَّل الآن افتراضيًا. إذا تم تعطيله، يصدر AntiSamy تنبيهًا ملحًا يشجعك على تفعيله.

إخلاء مسؤولية بشأن تنسيق المخرجات

على مدار دورة ترقية AntiSamy، طرأت تغييرات على مُحلِّل HTML المعتمد، مما أدى إلى بعض الاختلافات في المخرجات التي قد تظهر اعتمادًا على حالة الاستخدام. ضع هذا في الاعتبار إذا كنت تستخدم إصدارات معينة وحصلت على مخرجات مختلفة بعد الترقية.

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

إيقاف دعم أوراق الأنماط الخارجية

قرر فريق AntiSamy أن دعم القدرة على السماح بدمج CSS عن بُعد أمر خطير، ولذلك نحن نوقف هذه الميزة وستتم إزالتها في إصدار مستقبلي. من المتوقع أن يكون هناك عدد قليل جدًا، إن وُجد، من مستخدمي هذه الميزة.

لقد أضفنا تحذيرًا في السجلات (WARN) إذا تم استدعاء هذه الميزة. إذا كنت تستخدمها، فيُرجى تعطيل/إزالة هذه الميزة بالتبديل إلى المُنشئ الأساسي CssScanner الذي لا يفعّل هذه الميزة.

طريقة الاستخدام

1. استيراد التبعية

أولاً، أضف التبعية من Maven:

<dependency>
   <groupId>org.owasp.antisamy</groupId>
   <artifactId>antisamy</artifactId>
   <version>LATEST_VERSION</version>
</dependency>

2. اختيار ملف سياسة أساسي

من المرجح أن حالة استخدام موقعك لـ AntiSamy قابلة للمقارنة تقريبًا على الأقل بأحد ملفات السياسات المعرّفة مسبقًا. يمثل كل منها سيناريو "نموذجيًا" للسماح للمستخدمين بتوفير معلومات تنسيق HTML (وربما CSS). دعنا نلقي نظرة على ملفات السياسات المختلفة:

1. antisamy-slashdot.xml

Slashdot هو موقع أخبار تقني يسمح للمستخدمين بالرد anonymously على المنشورات الإخبارية مع القليل جدًا من ترميز HTML. الآن، Slashdot ليس فقط أحد أروع المواقع حولك، بل هو أيضًا أحد المواقع التي تعرضت للعديد من الهجمات الناجحة المختلفة. قواعد Slashdot صارمة إلى حد ما: يمكن للمستخدمين إرسال وسوم HTML التالية فقط وبدون CSS: <b>، <u>، <i>، <a>، <blockquote>.

وبناءً على ذلك، قمنا ببناء ملف سياسة يسمح بوظائف مشابهة إلى حد ما. يُسمح بجميع وسوم تنسيق النصوص التي تعمل مباشرة على الخط أو اللون أو التركيز.

2. antisamy-ebay.xml

eBay هو موقع المزادات الأكثر شعبية على الإنترنت في العالم، على حد علمنا. إنه موقع عام لذا يُسمح لأي شخص بنشر قوائم بمحتوى HTML غني. ليس من المستغرب أنه نظرًا لجاذبية eBay كهدف، فقد تعرض لعدد من هجمات XSS المعقدة. يُسمح للقوائم بأن تحتوي على محتوى أكثر ثراءً بكثير من، على سبيل المثال، Slashdot -- لذا فإن سطح الهجوم فيها أكبر considerably.

3. antisamy-myspace.xml

كان MySpace، في الوقت الذي وُلد فيه هذا المشروع، موقع التواصل الاجتماعي الأكثر شعبية. كان يُسمح للمستخدمين بإرسال كل HTML وCSS تقريبًا يريدونه -- طالما أنه لا يحتوي على JavaScript. كان MySpace يستخدم قائمة كلمات محظورة (blacklist) للتحقق من HTML الخاص بالمستخدمين، ولهذا تعرضوا لدودة سامي الشهيرة. دودة سامي، التي استخدمت هجمات التجزئة (fragmentation attacks) مع كلمة كان يجب أن تكون محظورة (eval) -- كانت مصدر إلهام لهذا المشروع.

4. antisamy-anythinggoes.xml

لا نعرف حالة استخدام محتملة لملف السياسة هذا. إذا أردت السماح بكل عنصر HTML وCSS صالح (ولكن بدون JavaScript أو هجمات تصيد احتيالي واضحة متعلقة بـ CSS)، يمكنك استخدام ملف السياسة هذا. حتى MySpace لم يكن بهذا الجنون. ومع ذلك، فهو بمثابة مرجع جيد لأنه يحتوي على قواعد أساسية لكل عنصر، لذا يمكنك استخدامه كقاعدة معرفة عند تخصيص ملفات السياسات الأخرى.

التسجيل (Logging)

يتضمن AntiSamy الآن مكتبة slf4j-simple لتسجيلاته، ولكن يمكن لمستخدمي AntiSamy استيراد واستخدام مكتبة تسجيل بديلة متوافقة مع slf4j إذا فضلوا ذلك. يمكنهم أيضًا استبعاد slf4j-simple إذا أرادوا ذلك.

تحذير: استخدام AntiSamy لـ slf4j-simple، بدون أي ملف إعدادات، يسجل الرسائل بطريقة مخزنة مؤقتًا إلى المخرجات القياسية. ونتيجة لذلك، قد تُفقد بعض أو كل رسائل السجل هذه إذا تم طرح Exception، مثل PolicyException. من المحتمل أن يمكن تصحيح ذلك عن طريق إعداد slf4j-simple لتسجيل الرسائل إلى الخطأ القياسي بدلاً من ذلك، أو استخدام مسجّل slf4j بديل يفعل ذلك.

3. تخصيص ملف السياسة

قد ترغب في نشر AntiSamy بإعداد افتراضي، ولكن من المحتمل بنفس القدر أن يرغب موقع ما في وضع قواعد صارمة مدفوعة بأعماله بشأن ما يمكن للمستخدمين السماح به. يجب أن يأخذ النقاش الذي يقرر التخصيص في الاعتبار أيضًا سطح الهجوم - الذي ينمو بنسبة متناسبة مع ملف السياسة.

يمكن تكييف السياسات المثال واختبارها بناءً على متطلبات كل وسم. إجراءات الوسوم المدعومة التي يمكن تحديدها هي:

• filter: إزالة الوسوم، مع الاحتفاظ بالمحتوى.
• validate: الاحتفاظ بالمحتوى طالما اجتاز القواعد.
• remove: إزالة الوسم ومحتوياته.
• truncate: إزالة سمات الوسم وجميع الوسوم الفرعية باستثناء محتواه النصي إن وُجد.
• encode: مشابه لـ filter لكنه يرمّز (encode) الوسم بصيغة HTML للحفاظ عليه كنص خام، ويتم رفع أطفاله مستوى واحدًا في التسلسل الهرمي.

4. استدعاء واجهة برمجة تطبيقات AntiSamy

استخدام AntiSamy سهل. إليك مثال على استدعاء AntiSamy مع ملف سياسة:

import org.owasp.validator.html.*;

Policy policy = Policy.getInstance(POLICY_FILE_LOCATION);

AntiSamy as = new AntiSamy();
CleanResults cr = as.scan(dirtyInput, policy);

MyUserDAO.storeUserProfile(cr.getCleanHTML()); // some custom function

هناك عدة طرق لإنشاء كائن Policy. يمكن للدالة getInstance() أن تأخذ أيًا مما يلي:

• اسم ملف String
• كائن File
• InputStream
• يمكن أيضًا الإشارة إلى ملفات Policy بواسطة اسم الملف عن طريق تمرير وسيط ثانٍ إلى الدالة AntiSamy#scan() كما توضح الأمثلة التالية:

AntiSamy as = new AntiSamy();
CleanResults cr = as.scan(dirtyInput, policyFilePath);

أخيرًا، يمكن أيضًا الإشارة إلى ملفات السياسات بواسطة كائنات File مباشرة في المعامل الثاني:

AntiSamy as = new AntiSamy();
CleanResults cr = as.scan(dirtyInput, new File(policyFilePath));

5. تحليل CleanResults

يوفر كائن CleanResults الكثير من الأشياء المفيدة.

• getCleanHTML() - مخرجات HTML النظيفة والآمنة
• getCleanXMLDocumentFragment() - جزء مستند XMLDocumentFragment النظيف والآمن الذي ينعكس في getCleanHTML()
• getErrorMessages() - قائمة برسائل الخطأ النصية -- إذا أعادت هذه القائمة 0 فهذا لا يعني عدم وجود هجمات!
• getNumberOfErrors() - عدد رسائل الخطأ -- مرة أخرى، القيمة 0 لا تعني أن الإدخال كان آمنًا!
• getScanTime() - يعيد وقت الفحص بالثواني

ملاحظة مهمة: كان هناك الكثير من الالتباس حول الدالة getErrorMessages(). الدالة getErrorMessages() (ولا getNumberOfErrors()) لا تجيب بشكل خفي عن سؤال "هل هذا إدخال آمن؟" بالإيجاب إذا أعادت قائمة فارغة. يجب عليك دائمًا استخدام الإدخال المنقى، ولا توجد طريقة للتأكد من أن الإدخال المُمرَّر لم يتعرض لأي هجمات.

إن عملية التسلسل وإلغاء التسلسل الضرورية لفعالية أداة التنقية هي خاسرة عن قصد وستقوم بتصفية الهجمات عبر عدد من نواقل الهجوم. لسوء الحظ، أحد المفاضلات في هذه الاستراتيجية هو أن AntiSamy لا يعرف دائمًا بأثر رجعي أنه تم رؤية هجوم. وبالتالي، فإن واجهتي getErrorMessages() وgetNumberOfErrors() موجودتان لمساعدة المستخدمين على فهم ما إذا كان إدخالهم حسن النية يلبي متطلبات النظام، وليس لمساعدة المطور على اكتشاف ما إذا كان الهجوم موجودًا.

وثائق أخرى

الوثائق الإضافية متاحة على صفحة الويكي لمشروع GitHub هذا: https://github.com/nahsra/antisamy/wiki وصفحة مشروع OWASP AntiSamy: https://owasp.org/www-project-antisamy/

المساهمة في AntiSamy

وجدت مشكلة؟

إذا وجدت خطأ برمجيًا، فأنشئ مشكلة (issue) في مستودع AntiSamy: https://github.com/nahsra/antisamy/issues

وجدت ثغرة أمنية؟

إذا وجدت ثغرة أمنية في AntiSamy، فابحث أولاً في قائمة المشكلات (أعلاه) لترى ما إذا تم الإبلاغ عنها بالفعل. إذا لم يتم الإبلاغ عنها، فيرجى الاتصال بـ Dave Wichers (dave.wichers at owasp.org) مباشرة. يرجى عدم الإبلاغ عن الثغرات الأمنية عبر مشكلات GitHub لأننا نرغب في الحفاظ على أمان مستخدمينا أثناء تنفيذ ونشر التصحيح. إذا كنت ترغب في الحصول على شكر وتقدير لاكتشاف الثغرة الأمنية، فيرجى اتباع هذه العملية.

مزيد من التفاصيل متاحة في الملف: SECURITY.md.

كيفية البناء

يمكنك البناء والاختبار من المصدر بسهولة تامة:

$ git clone https://github.com/nahsra/antisamy
$ cd antisamy
$ mvn package

الترخيص

صدر بموجب ترخيص BSD-3-Clause كما هو محدد هنا: LICENSE.