OWASP Java HTML Sanitizer

Ein schneller und einfach zu konfigurierender HTML-Sanitizer, geschrieben in Java, mit dem du HTML von Drittanbietern in deine Webanwendung einbinden kannst, während du dich gegen XSS schützt.

Das Sanitizer-JAR hat keine Laufzeitabhängigkeiten. Seine einzige Kompilierzeit-Abhängigkeit ist spotbugs-annotations (provided scope, nur Annotationen); die anderen JARs werden nur von der Testsuite benötigt.

Dieser Code wurde unter Berücksichtigung von Sicherheits-Best-Practices geschrieben, verfügt über eine umfangreiche Testsuite und wurde einem adversarialen Sicherheitsreview unterzogen.

Erste Schritte

Erste Schritte enthält Anweisungen dazu, wie du mit oder ohne Maven loslegen kannst.

Repository-Layout

Zum Bauen ist JDK 11 oder neuer erforderlich. Vom Repository-Stamm aus baust du alle Maven- Module und führst ihre Tests aus mit:

./mvnw clean verify

Der Maven-Wrapper legt die erforderliche Maven-Version fest. Wenn Sie ein Modul mit -pl auswählen, verwenden Sie zusätzlich -am, damit Maven die Module baut, von denen es abhängt.

owasp-java-html-sanitizer/ enthält die veröffentlichte Bibliothek, ihre Tests und ihren Java-Moduldeskriptor.
java8-shim/ und java10-shim/ implementieren Kompatibilitätscode, der in das Bibliotheks-JAR eingebunden wird.
examples/ enthält Beispielrichtlinien zum Lesen und Kopieren; es wird getestet, aber nicht veröffentlicht.
empiricism/ enthält die Browser-Experimente, die zur Erzeugung der HTML-Elementtabellen des Sanitizers verwendet werden.
docs/ enthält Benutzer-, Sicherheits- und historische Dokumentation.

Vorgepackte Richtlinien

Sie können vorgepackte Richtlinien verwenden:

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

Eine Policy erstellen

Die tests zeigen, wie Sie Ihre eigene policy konfigurieren:

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

Benutzerdefinierte Richtlinien

Sie können benutzerdefinierte Richtlinien schreiben, um Dinge zu tun wie h1s in divs mit einer bestimmten Klasse zu ändern:

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);

Bitte beachten Sie, dass die Elemente "a", "font", "img", "input" und "span" explizit über die Methode allowWithoutAttributes() auf die Whitelist gesetzt werden müssen, wenn sie durch den Filter zugelassen werden sollen, obwohl diese Elemente keine Attribute enthalten.

Attributrichtlinien erlauben ebenfalls die Ausführung von benutzerdefiniertem Code. Das Hinzufügen einer Attributrichtlinie schwächt keine Standardrichtlinie wie style oder URL-Attributprüfungen ab.

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();

Präprozessoren

Präprozessoren ermöglichen das Einfügen von Text und strukturelle Änderungen in großem Umfang.

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();

Die Vorverarbeitung erfolgt, bevor eine Richtlinie angewendet wird, und kann daher die Sicherheit der Ausgabe nicht beeinflussen.

java-html-sanitizer v20260921.1