OWASP Java HTML Sanitizer

مُنقِّي HTML سريع وسهل الإعداد مكتوب بلغة Java، يتيح لك تضمين HTML من تأليف أطراف ثالثة في تطبيق الويب الخاص بك مع الحماية من XSS.

لا يحتوي ملف JAR الخاص بالمُنقِّي على أي تبعيات وقت التشغيل. تبعيته الوحيدة عند وقت الترجمة هي spotbugs-annotations (بنطاق provided، للتعليقات التوضيحية فقط)؛ أما ملفات JAR الأخرى فهي مطلوبة فقط من قِبل مجموعة الاختبارات.

كُتب هذا الكود مع مراعاة أفضل ممارسات الأمان، ويمتلك مجموعة اختبارات موسّعة، وقد خضع لمراجعة أمنية عدائية.

جدول المحتويات

• البدء
• تخطيط المستودع
• السياسات المُعدّة مسبقًا
• صياغة سياسة
• السياسات المخصصة
• المعالجات المسبقة
• القياس عن بُعد
• أسئلة\؟
• المساهمة
• الترخيص
• شكر وتقدير

البدء

يتضمن دليل البدء تعليمات حول كيفية البدء مع Maven أو بدونه.

تخطيط المستودع

يتطلب البناء JDK 11 أو أحدث. من جذر المستودع، ابنِ جميع وحدات Maven وشغّل اختباراتها باستخدام:

./mvnw clean verify

يقوم Maven wrapper بتثبيت إصدار Maven المطلوب. إذا اخترت وحدة نمطية باستخدام -pl، فاستخدم أيضًا -am حتى يبني Maven الوحدات التي تعتمد عليها.

• يحتوي owasp-java-html-sanitizer/ على المكتبة المنشورة، واختباراتها، وواصف وحدة Java الخاص بها.
• يوفّر java8-shim/ و java10-shim/ شيفرة التوافق التي تُضمَّن في ملف JAR الخاص بالمكتبة.
• يحتوي examples/ على سياسات نموذجية للقراءة والنسخ؛ وهي مُختبَرة ولكن غير منشورة.
• يحتوي empiricism/ على تجارب المتصفح المستخدمة لإنشاء جداول عناصر HTML الخاصة بالمنقّي.
• يحتوي docs/ على وثائق المستخدم والأمان والوثائق التاريخية.

السياسات المُعدّة مسبقًا

يمكنك استخدام السياسات المُعدّة مسبقًا:

PolicyFactory policy = Sanitizers.FORMATTING.and(Sanitizers.LINKS);
String safeHTML = policy.sanitize(untrustedHTML);

إنشاء سياسة

تُظهر الاختبارات كيفية تكوين سياسة خاصة بك:

PolicyFactory policy = new HtmlPolicyBuilder()
    .allowElements("a")
    .allowUrlProtocols("https")
    .allowAttributes("href").onElements("a")
    .requireRelNofollowOnLinks()
    .toFactory();
String safeHTML = policy.sanitize(untrustedHTML);

سياسات مخصصة

يمكنك كتابة سياسات مخصصة للقيام بأشياء مثل تغيير عناصر h1 إلى عناصر div بفئة معينة:

PolicyFactory policy = new HtmlPolicyBuilder()
    .allowElements("p")
    .allowElements(
        (String elementName, List<String> attrs) -> {
          // Add a class attribute.
          attrs.add("class");
          attrs.add("header-" + elementName);
          // Return elementName to include, null to drop.
          return "div";
        }, "h1", "h2", "h3", "h4", "h5", "h6")
    .toFactory();
String safeHTML = policy.sanitize(untrustedHTML);

يُرجى ملاحظة أن العناصر "a" و"font" و"img" و"input" و"span" تحتاج إلى إدراجها صراحةً في القائمة البيضاء باستخدام الدالة allowWithoutAttributes() إذا كنت تريد السماح لها بالمرور عبر عامل التصفية عندما لا تتضمن هذه العناصر أي سمات.

تسمح سياسات السمات بتشغيل تعليمات برمجية مخصصة أيضًا. لن تؤدي إضافة سياسة سمات إلى إضعاف أي سياسة افتراضية مثل style أو فحوصات سمات URL.

PolicyFactory myPolicy = new HtmlPolicyBuilder()
    .allowElements("div", "span")
    .allowAttributes("data-foo")
        .matching(
            (String elementName, String attributeName, String value) -> {
              // Return value for the attribute or null to drop.
              return value;
            })
        .onElements("div", "span")
    .toFactory();

المعالجات المسبقة

تسمح المعالجات المسبقة بإدراج النصوص وإجراء تغييرات هيكلية واسعة النطاق.

PolicyFactory myPolicy = new HtmlPolicyBuilder()
    .withPreprocessor(
        (HtmlStreamEventReceiver r) -> {
          // Provide user with info about links before they click.
          // Before:                       <a href="https://example.com/...">
          // After:  (https://example.com) <a href="https://example.com/...">
          return new HtmlStreamEventReceiverWrapper(r) {
            @Override public void openTag(String elementName, List<String> attrs) {
              if ("a".equals(elementName)) {
                for (int i = 0, n = attrs.size(); i < n; i += 2) {
                  if ("href".equals(attrs.get(i))) {
                    String url = attrs.get(i + 1);
                    String origin;
                    try {
                      URI uri = new URI(url);
                      String scheme = uri.getScheme();
                      String authority = uri.getRawAuthority();
                      if (scheme == null && authority == null) {
                        origin = null;
                      } else {
                        origin = (scheme != null ? scheme + ":" : "")
                               + (authority != null ? "//" + authority : "");
                      }
                    } catch (URISyntaxException ex) {
                      origin = "about:invalid";
                    }
                    if (origin != null) {
                      text(" (" + origin + ") ");
                    }
                  }
                }
              }
              super.openTag(elementName, attrs);
            }
          };
        })
     .allowElements("a")
     .allowAttributes("href").onElements("a")
     .allowStandardUrlProtocols()
    ...
    .toFactory();

تحدث المعالجة المسبقة قبل تطبيق السياسة، لذا لا يمكنها التأثير على أمان المخرجات.

القياس عن بُعد

عندما ترفض سياسة ما عنصرًا أو سمة، فإنها تُخطر HtmlChangeListener.

يمكنك استخدام ذلك لتتبّع اتجاهات انتهاكات السياسة ومعرفة متى يحاول شخص ما اختراق أمانك.

PolicyFactory myPolicyFactory = ...;
// If you need to associate reports with some context, you can do so.
MyContextClass myContext = ...;