OWASP Java HTML Sanitizer

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

A dependência existente é o JSR 305. Os outros jars são necessários apenas para a suíte de testes. A dependência JSR 305 é uma dependência apenas de compilação, necessária apenas para anotações.

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

Primeiros Passos

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

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 transformar h1s em divs com uma 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);

Por favor, note 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.

Políticas de atributos permitem executar código personalizado também. Adicionar uma política de atributos não enfraquecerá nenhuma política padrão, como verificações de atributos style ou 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()

Pré-processadores

Pré-processadores permitem inserir texto e fazer grandes alterações estruturais.

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

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

Telemetria

Quando uma política rejeita um elemento ou atributo, ela notifica um HtmlChangeListener.

Você pode usar isso para acompanhar tendências de violação de políticas e descobrir quando alguém está tentando quebrar sua segurança.

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 uma string for sanitizada sem notificações de alteração, isso não significa que a string de entrada seja necessariamente segura para uso. Use apenas a saída do sanitizador.

O sanitizador garante que a saída esteja em um subconjunto de HTML sobre o qual analisadores HTML comuns concordarão quanto ao significado, mas a ausência de notificações não significa que a entrada esteja nesse subconjunto, apenas que ela não contém elementos ou atributos que foram removidos.

Veja "Por que sanitizar quando você pode validar" para mais informações sobre este tópico.

Dúvidas?

Se você deseja relatar uma vulnerabilidade, consulte AttackReviewGroundRules.

Inscreva-se na lista de discussão para ser notificado sobre Vulnerabilidades conhecidas e atualizações importantes.

Contribuindo

Se você gostaria de contribuir, entre em contato com @mvsamuel ou @manicode.

Aceitamos relatos de problemas e PRs. PRs que alteram comportamento ou adicionam funcionalidades devem incluir tanto testes positivos quanto testes negativos.

Por favor, esteja ciente de que as contribuições estão sob a Licença Apache 2.0.

Créditos

Agradecemos a todos que ajudaram com críticas e código

Ler mais

java-html-sanitizer v20260921.1

Categorias