OWASP Java HTML Sanitizer

Um Sanitizador de HTML rápido e fácil de configurar, escrito em Java, que permite incluir HTML de autoria de terceiros em sua aplicação web enquanto protege contra XSS.

O JAR do sanitizador não possui dependências de tempo de execução. Sua única dependência de tempo de compilação é spotbugs-annotations (escopo provided, apenas anotações); os demais jars são necessários apenas para a suíte de testes.

Este código foi escrito com as melhores práticas de segurança em mente, possui uma extensa suíte de testes e passou por revisão de segurança adversarial.

Primeiros Passos

Primeiros Passos inclui instruções sobre como começar com ou sem Maven.

Estrutura do Repositório

A compilação requer JDK 11 ou mais recente. A partir da raiz do repositório, compile todos os módulos Maven e execute seus testes com:

./mvnw clean verify

O wrapper do Maven fixa a versão necessária do Maven. Se você selecionar um módulo com -pl, use também -am para que o Maven compile os módulos dos quais ele depende.

owasp-java-html-sanitizer/ contém a biblioteca publicada, seus testes e seu descritor de módulo Java.
java8-shim/ e java10-shim/ implementam código de compatibilidade que é empacotado no JAR da biblioteca.
examples/ contém políticas de exemplo para ler e copiar; é testado, mas não publicado.
empiricism/ contém os experimentos de navegador usados para gerar as tabelas de elementos HTML do sanitizer.
docs/ contém documentação de usuário, de segurança e histórica.

Políticas Pré-empacotadas

Você pode usar políticas pré-empacotadas:

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

Criando uma política

Os testes mostram como configurar sua própria política:

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

Políticas Personalizadas

Você pode escrever políticas personalizadas para fazer coisas como alterar h1s para divs com uma determinada 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);

Observe que os elementos "a", "font", "img", "input" e "span" precisam ser explicitamente incluídos na lista de permissões usando o método allowWithoutAttributes() se você quiser que eles sejam permitidos pelo filtro quando esses elementos não incluírem nenhum atributo.

As políticas de atributos também permitem a execução de código personalizado. Adicionar uma política de atributos não enfraquece nenhuma política padrão, como as verificações de atributos style ou de 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é-processadores

Os pré-processadores permitem inserir texto e realizar alterações estruturais em larga escala.

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

O pré-processamento ocorre antes da aplicação de uma política, portanto não pode afetar a segurança da saída.

java-html-sanitizer v20260921.1