
يأخذ HTML من طرف ثالث وينتج HTML آمنًا لتضمينه في تطبيق الويب الخاص بك. سريع وسهل التكوين.
مُنقِّي HTML سريع وسهل الإعداد مكتوب بلغة Java، يتيح لك تضمين HTML من تأليف أطراف ثالثة في تطبيق الويب الخاص بك مع الحماية من XSS.
لا يحتوي ملف JAR الخاص بالمُنقِّي على أي تبعيات وقت التشغيل. تبعيته الوحيدة
عند وقت الترجمة هي spotbugs-annotations (بنطاق provided، للتعليقات التوضيحية فقط)؛
أما ملفات JAR الأخرى فهي مطلوبة فقط من قِبل مجموعة الاختبارات.
كُتب هذا الكود مع مراعاة أفضل ممارسات الأمان، ويمتلك مجموعة اختبارات موسّعة، وقد خضع لمراجعة أمنية عدائية.
يتضمن دليل البدء تعليمات حول كيفية البدء مع Maven أو بدونه.
يتطلب البناء JDK 11 أو أحدث. من جذر المستودع، ابنِ جميع وحدات Maven وشغّل اختباراتها باستخدام:
./mvnw clean verify
يقوم Maven wrapper بتثبيت إصدار Maven المطلوب. إذا اخترت وحدة نمطية
باستخدام -pl، فاستخدم أيضًا -am حتى يبني Maven الوحدات التي تعتمد عليها.
يمكنك استخدام السياسات المُعدّة مسبقًا:
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 = ...;