OWASP Java HTML Sanitizer

Un sanificatore HTML veloce e facile da configurare scritto in Java che ti consente di includere HTML creato da terze parti nella tua applicazione web proteggendoti da XSS.

La dipendenza esistente è su JSR 305. Gli altri jar servono solo per la suite di test. La dipendenza da JSR 305 è una dipendenza solo di compilazione, necessaria unicamente per le annotazioni.

Questo codice è stato scritto tenendo a mente le migliori pratiche di sicurezza, ha una suite di test estesa ed è stato sottoposto a revisione della sicurezza avversaria.

Indice

• Per iniziare
• Policy preconfigurate
• Creare una policy
• Policy personalizzate
• Preprocessori
• Telemetria
• Domande?
• Contribuire
• Crediti

Per iniziare

Per iniziare include istruzioni su come iniziare con o senza Maven.

Policy preconfigurate

Puoi usare policy preconfigurate:

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

Creare una policy

I test mostrano come configurare la tua policy:

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

Policy personalizzate

Puoi scrivere policy personalizzate per fare cose come trasformare gli h1 in div con una certa 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);

Si prega di notare che gli elementi "a", "font", "img", "input" e "span" devono essere esplicitamente inseriti nella whitelist usando il metodo allowWithoutAttributes() se si desidera che vengano lasciati passare dal filtro quando questi elementi non includono alcun attributo.

Le policy sugli attributi consentono anche di eseguire codice personalizzato. Aggiungere una policy sugli attributi non indebolirà alcuna policy predefinita come style o i controlli sugli attributi URL.

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

Preprocessori

I preprocessori consentono di inserire testo e modifiche strutturali su larga scala.

new HtmlPolicyBuilder = new HtmlPolicyBuilder()
    // Use a preprocessor to be backwards compatible with the
    // <plaintext> element which 
    .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);
            }
          };
        }
    .allowElement("a")
    ...
    .build()

La pre-elaborazione avviene prima dell'applicazione di una policy, quindi non può influire sulla sicurezza dell'output.

Telemetria

Quando una policy rifiuta un elemento o un attributo, notifica un HtmlChangeListener.

Puoi usarlo per tenere traccia delle tendenze delle violazioni delle policy e scoprire quando qualcuno sta tentando di violare la tua sicurezza.

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

String sanitizedHtml = myPolicyFactory.sanitize(
    unsanitizedHtml,
    new HtmlChangeListener<MyContextClass>() {
      @Override
      public void discardedTag(MyContextClass context, String elementName) {
        // ...
      }
      @Override
      public void discardedAttributes(
          MyContextClass context, String elementName, String... attributeNames) {
        // ...
      }
    },
    myContext);

Nota: Se una stringa viene sanificata senza notifiche di modifica, non è detto che la stringa in ingresso sia necessariamente sicura da usare. Usa solo l'output del sanificatore.

Il sanificatore garantisce che l'output sia in un sottoinsieme di HTML sul cui significato i parser HTML comunemente usati saranno d'accordo, ma l'assenza di notifiche non significa che l'input sia in tale sottoinsieme, solo che non contiene elementi o attributi che sono stati rimossi.