
OWASP Java Encoder هو فئة ترميز عالية الأداء وسهلة الاستخدام للغة Java 1.5+، تُضاف مباشرةً إلى المشروع (drop-in) دون أي اعتماديات خارجية وبدون تعقيدات إضافية. سيساعد هذا المشروع مطوّري تطبيقات الويب بلغة Java على الدفاع ضد هجمات البرمجة النصية عبر المواقع (Cross Site Scripting)!
ترميز المخرجات حسب السياق لـ Java 8+. اختر مُرمِّزًا لسياق المحلّل الذي يستقبل نصًا غير موثوق: HTML أو JavaScript أو CSS أو XML أو أحد مكوّنات URL. لا تحتوي النواة على أي تبعيات وقت التشغيل؛ بينما توفّر محوّلات JSP وJakarta الاختيارية ارتباطات لطبقة العرض. يُعدّ الترميز جزءًا واحدًا من [منع XSS][xss]، إلى جانب القوالب الآمنة والتحقق من صحة URL وغيرها من ضوابط التطبيق.
الإصدار 1.6.0 متاح من Maven Central. يقلّل هذا الإصدار الثانوي من الترميز غير الضروري لحروف JavaScript مع الحفاظ على الحماية المعروفة لرموز HTML عبر الشظايا الموثوقة. تتغيّر البايتات المُرمَّزة وسلوك البث؛ راجع ملاحظات الإصدار و التحقق من النشر.
تظل إصلاحات الأمان الخاصة بحدود المحلّل التي أُدخلت في 1.5.0 سارية المفعول؛ أما الإصدارات حتى 1.4.1 فلا تحتوي على تلك الإصلاحات. راجع الإشعار الأمني وVERIFYING.md.
اختر التبعية التي تحتاجها.
تستخدم الحزم الثلاث المدعومة معرّف المجموعة org.owasp.encoder:
| معرّف الحزمة | الغرض وتبعيات وقت التشغيل |
|---|---|
encoder | واجهة String/Writer الأساسية؛ بلا تبعيات وقت تشغيل |
encoder-jsp | وسوم JSP ودوال EL القديمة javax؛ النواة بالإضافة إلى واجهة JSP API التي يوفّرها الحاوية |
encoder-jakarta-jsp | وسوم JSP ودوال EL الخاصة بـ Jakarta؛ النواة بالإضافة إلى واجهة Jakarta JSP API التي يوفّرها الحاوية |
<dependency>
<groupId>org.owasp.encoder</groupId>
<artifactId>encoder</artifactId>
<version>1.6.0</version>
</dependency>
استبدل encoder بمعرّف قطعة أثرية واحد لمهايئ الترميز عند الحاجة؛ كل مهايئ يجلب
النواة معه. حافظ على توافق إصدارات النواة والمهايئات المُدارة بشكل منفصل. استخدم واحدًا فقط من
ملفات JAR الخاصة بـ javax أو Jakarta taglib: فهي تشترك في org.owasp.encoder.tag ويجب ألا تتواجد معًا
على نفس مسار الفئات (classpath) أو مسار الوحدات (module path). راجع مصفوفة وقت التشغيل و
جرد التبعيات/التراخيص.
تم إيقاف encoder-esapi بعد الإصدار 1.4.1 وهو غير مُضمَّن أو مدعوم في
1.5.x أو 1.6.0. يجب على التطبيقات التي تستخدمه أن تنتقل بعيدًا عن المهايئ.
توثيق واجهة برمجة التطبيقات المنشور للإصدار 1.6.0 (قد تتأخر الفهرسة المستضافة عن النشر): النواة، javax JSP و Jakarta JSP.
import org.owasp.encoder.Encode;
out.write("<p>");
Encode.forHtmlContent(out, userText); // Writer overload; no intermediate String
out.write("</p>");
استدعاء String المكافئ هو Encode.forHtmlContent(userText). يوفّر المستدعون
الصياغة المحيطة الموثوقة وعلامات الاقتباس الخاصة بالسمات. رمّز البيانات الخام مرة واحدة، عند
حدود الإخراج؛ واحتسب أي تهريب (escaping) يقوم محرك القوالب لديك بتنفيذه مسبقًا.
| الوجهة | واجهة API والقيود |
|---|---|
| نص HTML، بما في ذلك محتوى textarea | forHtmlContent؛ ويغطي forHtml أيضًا سمات النص العادية المُقتبسة |
| سمة نص HTML مُقتبسة | forHtmlAttribute؛ وليست تعبير معالج حدث ولا مُدقّق URL |
| مكوّن URL خام واحد | forUriComponent؛ جمّعه بفواصل موثوقة، ودقّق URL، ثم رمّز لسمة HTML المحيطة |
| سلسلة JavaScript | forJavaScript؛ وفّر علامات اقتباس مفردة/مزدوجة. يتطلب نص القالب الحرفي العادي غير الموسوم 1.5. لا تستخدمه أبدًا في القوالب الموسومة أو أجسام التعبيرات أو JSON أو عناوين URL الخاصة بالسكربت |
| محتوى سلسلة JSON | forJson (1.5)؛ وفّر علامات اقتباس مزدوجة. يُفضّل استخدام مُسلسِل (serializer) لمستند كامل |
سلسلة CSS مُقتبسة / قيمة CSS url(...) | forCssString / forCssUrl؛ دقّق عناوين URL والتزم بقواعد السياق المحيط الخاصة بالدالة |
| نص XML 1.0 / سمة مُقتبسة | forXmlContent / forXmlAttribute؛ ويغطي forXml كليهما |
| نص XML 1.1 / سمة مُقتبسة | forXml11Content / forXml11Attribute (النواة 1.4+)؛ يتطلب مستند/محلّل XML 1.1، وليس HTML |
| CDATA / تعليق XML | forCDATA / forXmlComment؛ وليس تعليقات HTML |
| حرفية سلسلة مصدر Java | forJava؛ يوفّر المستدعي علامات الاقتباس؛ قد لا تُترجم البدائل غير المزدوجة (unpaired surrogates) |
كل طريقة واجهة (facade) مدرجة لها تحميلات (overloads) من نوع String وWriter. يشرح دليل السياقات التداخل وسلوك null/Unicode، ومتغيرات JavaScript، وحدود القوالب، وJSON والسياقات غير الآمنة. تُظهر أمثلة Java/JSP الصياغة المحيطة الكاملة.
لا يقوم الترميز بتعقيم HTML، ولا التحقق من صحة المدخلات/عناوين URL، ولا تسلسل مستندات JSON، ولا إجراء معاملات SQL، ولا فك ترميز/تقنين البيانات. استخدم مُعقّم HTML عندما يجب السماح بالترميز (markup)؛ واستخدم استعلامات مُعاملة (parameterized) لـ SQL. راجع [دليل مكتبة أمان Java من OWASP][java-libraries] لهذه الأدوار المتميزة.
معرّفات URI الخاصة بـ Taglib هي معرّفات، وليست عناوين URL يجب أن تُفتح في متصفح:
| المحوّل (Adapter) | المعرّف الأساسي | المعرّف المتقدم |
|---|---|---|
| Jakarta | owasp.encoder.jakarta | owasp.encoder.jakarta.advanced |
| javax JSP | https://www.owasp.org/index.php/OWASP_Java_Encoder_Project | نفس المعرّف مع إلحاق #advanced |
<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" isELIgnored="false" %>
<%@ taglib prefix="e" uri="owasp.encoder.jakarta" %>
<p>${e:forHtmlContent(param.message)}</p>
استخدم معرّف javax لحاوية javax. تستخدم الوسوم جسمًا فارغًا وسمة value مطلوبة، على سبيل المثال <e:forHtmlContent value="${param.message}" />. راجع bindings and EL evaluation للاطلاع على الطرق الأساسية مقابل المتقدمة وإعدادات النشر الحساسة للإصدار. في 1.5، تكشف مكتبات الوسوم المتقدمة كل سياق Encode.forX(String) باستثناء forJava؛ فتوليد مصدر Java ليس سياق JSP. روابط XML 1.1 جديدة في 1.5.
أصبح Encode.forUri مهملًا في واجهة API الصادرة. يوسّع الإصدار 1.5.0 هذا الإهمال ليشمل Encoders.URI وكلا صنفي ForUriTag وتوثيق الوسم/الدالة forUri. تُحتفظ بجميع نقاط الدخول هذه طوال سلسلة 1.x. ترميز URI كامل لا يتحقق من صحته:
forUri("javascript:alert(1)") يعيده دون تغيير. تُرمَّز علامات % الموجودة مسبقًا مرة أخرى. استخدم forUriComponent لاسم/قيمة معامل خام واحد، أو مقطع مسار، أو جزء؛ وتحقق من عناوين URL الكاملة بشكل منفصل، ثم استخدم forHtmlAttribute عند وضع أحدها في سمة HTML محاطة بعلامات اقتباس. التحليل باستخدام java.net.URI وحده لا يثبت السلامة. راجع مثال URL العملي.
تتطلب إزالة واجهة API الأساسية/الوسوم المهملة قرارًا مستقبليًا رئيسيًا يُراجَع بشكل منفصل؛ فالإهمال ليس جدولًا زمنيًا للإزالة. يُسحب محوّل ESAPI التاريخي المنفصل بدلًا من نقله إلى 1.5.0.