OWASP Java HTML Sanitizer

Un assainisseur HTML rapide et facile à configurer, écrit en Java, qui vous permet d'inclure du HTML rédigé par des tiers dans votre application web tout en vous protégeant contre les XSS.

Le JAR de l'assainisseur n'a aucune dépendance à l'exécution. Sa seule dépendance à la compilation est spotbugs-annotations (portée provided, annotations uniquement) ; les autres jars ne sont nécessaires que pour la suite de tests.

Ce code a été écrit en gardant à l'esprit les bonnes pratiques de sécurité, dispose d'une suite de tests étendue et a fait l'objet d'une revue de sécurité contradictoire.

Premiers pas

Premiers pas contient des instructions sur la façon de démarrer avec ou sans Maven.

Organisation du dépôt

La compilation nécessite JDK 11 ou une version plus récente. Depuis la racine du dépôt, compilez tous les modules Maven et exécutez leurs tests avec :

./mvnw clean verify

Le wrapper Maven fixe la version de Maven requise. Si vous sélectionnez un module avec -pl, utilisez également -am afin que Maven construise les modules dont il dépend.

owasp-java-html-sanitizer/ contient la bibliothèque publiée, ses tests et son descripteur de module Java.
java8-shim/ et java10-shim/ implémentent du code de compatibilité intégré au JAR de la bibliothèque.
examples/ contient des exemples de politiques à lire et à copier ; ils sont testés mais non publiés.
empiricism/ contient les expériences en navigateur utilisées pour générer les tables d'éléments HTML du sanitizer.
docs/ contient la documentation utilisateur, de sécurité et historique.

Politiques prépackagées

Vous pouvez utiliser les politiques prépackagées :

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

Création d'une politique

Les tests montrent comment configurer votre propre politique :

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

Politiques personnalisées

Vous pouvez écrire des politiques personnalisées pour effectuer des actions comme transformer les h1 en div avec une certaine classe :

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

Veuillez noter que les éléments "a", "font", "img", "input" et "span" doivent être explicitement ajoutés à la liste blanche à l'aide de la méthode allowWithoutAttributes() si vous souhaitez qu'ils soient autorisés à traverser le filtre lorsque ces éléments ne comportent aucun attribut.

Les politiques d'attributs permettent également d'exécuter du code personnalisé. L'ajout d'une politique d'attributs n'affaiblit aucune politique par défaut comme les vérifications d'attributs style ou d'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();

Préprocesseurs

Les préprocesseurs permettent d'insérer du texte et d'effectuer des modifications structurelles à grande échelle.

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

java-html-sanitizer v20260921.1