AntiSamy

Una librería para realizar una limpieza rápida y configurable de HTML proveniente de fuentes no confiables. Compatible con Java 8+.

Otra forma de decirlo podría ser: es una API que te ayuda a asegurarte de que los clientes no suministren código malicioso en el HTML que proporcionan para su perfil, comentarios, etc., que se persiste en el servidor. El término "código malicioso" en lo que respecta a aplicaciones web suele significar "JavaScript". Mayormente, las hojas de estilo en cascada solo se consideran maliciosas cuando invocan JavaScript. Sin embargo, hay muchas situaciones en las que el HTML y CSS "normales" pueden usarse de manera maliciosa.

¡IMPORTANTE! - Cambios que rompen la API en 1.7.0

A lo largo del desarrollo de la serie 1.6.x, hemos identificado y dejado obsoletas una serie de características y API. Todos estos elementos obsoletos se han eliminado en la versión 1.7.0. Estos cambios se registraron todos en el ticket: https://github.com/nahsra/antisamy/issues/195. Cada uno de los cambios se describe a continuación:

CssHandler tenía 2 constructores que omitían el parámetro LinkedList<URI> embeddedStyleSheets. Ambos constructores ahora crean una LinkedList<URI> interna vacía y el método getImportedStylesheetsURIList() se puede usar para obtener una referencia a ella, si es necesario. Esta característica rara vez se usa y, de hecho, la invocación directa de estos constructores también es rara, por lo que es poco probable que este cambio afecte a la mayoría de los usuarios de AntiSamy. Cuando se usa, normalmente se pasa una lista vacía como valor de este parámetro y esa lista nunca se vuelve a usar.

• La firma CssHandler(Policy, LinkedList<URI>, List<String>, ResourceBundle) se eliminó

  • Fue reemplazada por: CssHandler(Policy, List<String>, ResourceBundle)

• La firma CssHandler(Policy, LinkedList<URI>, List<String>, String, ResourceBundle) se eliminó

  • Fue reemplazada por: CssHandler(Policy, List<String>, ResourceBundle, String). NOTA: El orden de los últimos 2 parámetros de este método se invirtió.

• Se eliminó la compatibilidad con XHTML. AntiSamy ahora solo es compatible con HTML. Como creemos que era una característica poco utilizada, no esperamos que esto afecte a muchos usuarios de AntiSamy.

• Ahora se requiere validación de esquema XML en los archivos de política de AntiSamy y no se puede deshabilitar. Debe hacer que su archivo de política cumpla con el esquema para poder usarlo con AntiSamy.

• La directiva de política noopenerAndNoreferrerAnchors ahora está ACTIVADA de forma predeterminada. Si se deshabilita, AntiSamy emite un aviso, animándolo a activarla.

Descargos sobre el formato de salida

A lo largo del ciclo de vida de actualización de AntiSamy, la dependencia del analizador HTML ha experimentado cambios, lo que ha dado lugar a algunas diferencias en la salida que pueden surgir según el caso de uso. Considere esto si estaba usando ciertas versiones y obtiene salidas diferentes después de actualizar.

Esto también puede aplicarse al serializador de salida que transforma la representación HTML interna en la salida de texto final de la herramienta.

Obsolescencia de la compatibilidad con hojas de estilo externas

El equipo de AntiSamy ha decidido que admitir la capacidad de permitir CSS remoto incrustado es peligroso, por lo que estamos dejando obsoleta esta característica y se eliminará en una versión futura. Se espera que haya muy pocos usuarios, si acaso alguno, de esta característica.

Hemos añadido un WARNing de registro si se invoca esta característica. Si es su caso, deshabilite/elimine esta característica cambiando al constructor principal de CssScanner que no habilita esta característica.

Cómo Usar

1. Importar la dependencia

Primero, agregue la dependencia desde Maven:

<dependency>
   <groupId>org.owasp.antisamy</groupId>
   <artifactId>antisamy</artifactId>
   <version>LATEST_VERSION</version>
</dependency>

2. Elegir un archivo de política base

Es probable que el caso de uso de AntiSamy en su sitio sea al menos aproximadamente comparable a uno de los archivos de política predefinidos. Cada uno representa un escenario "típico" para permitir a los usuarios proporcionar información de formato HTML (y posiblemente CSS). Veamos los diferentes archivos de política:

1. antisamy-slashdot.xml

Slashdot es un sitio de noticias tecnológicas que permite a los usuarios responder anónimamente a publicaciones de noticias con un marcado HTML muy limitado. Ahora bien, Slashdot no solo es uno de los sitios más geniales que existen, sino que también ha sido objeto de muchos ataques exitosos diferentes. Las reglas para Slashdot son bastante estrictas: los usuarios solo pueden enviar las siguientes etiquetas HTML y nada de CSS: <b>, <u>, <i>, <a>, <blockquote>.

En consecuencia, hemos creado un archivo de política que permite una funcionalidad bastante similar. Se han permitido todas las etiquetas de formato de texto que operan directamente sobre la fuente, el color o el énfasis.

2. antisamy-ebay.xml

eBay es el sitio de subastas en línea más popular del universo, hasta donde podemos decir. Es un sitio público, por lo que cualquiera puede publicar listados con contenido HTML enriquecido. No es sorprendente que, dada la atractividad de eBay como objetivo, haya sido objeto de algunos ataques XSS complejos. Se permite que los listados contengan contenido mucho más enriquecido que, digamos, Slashdot, por lo que su superficie de ataque es considerablemente mayor.

3. antisamy-myspace.xml

MySpace era, en el momento en que nació este proyecto, el sitio de redes sociales más popular. Se permitía a los usuarios enviar prácticamente todo el HTML y CSS que quisieran, siempre que no contuviera JavaScript. MySpace usaba una lista negra de palabras para validar el HTML de los usuarios, razón por la cual fueron objeto del infame gusano Samy. El gusano Samy, que usaba ataques de fragmentación combinados con una palabra que debería haber estado en la lista negra (eval), fue la inspiración para este proyecto.

4. antisamy-anythinggoes.xml

No conocemos un posible caso de uso para este archivo de política. Si desea permitir todos y cada uno de los elementos HTML y CSS válidos (pero sin JavaScript ni ataques de phishing relacionados con CSS descarados), puede usar este archivo de política. Ni siquiera MySpace fue tan extremo. Sin embargo, sirve como una buena referencia porque contiene reglas base para cada elemento, por lo que puede usarlo como base de conocimiento al adaptar los otros archivos de política.

Registro (Logging)

AntiSamy ahora incluye la librería slf4j-simple para su registro, pero los usuarios de AntiSamy pueden importar y usar una librería de registro alternativa compatible con slf4j si lo prefieren. También pueden excluir slf4j-simple si así lo desean.

ADVERTENCIA: El uso de slf4j-simple por parte de AntiSamy, sin ningún archivo de configuración, registra mensajes de manera almacenada en búfer en la salida estándar. Por lo tanto, algunos o todos estos mensajes de registro pueden perderse si se lanza una Exception, como una PolicyException. Esto probablemente se pueda corregir configurando slf4j-simple para que registre en el error estándar, o usando un registrador slf4j alternativo que lo haga.

3. Adaptar el archivo de política

Es posible que desee implementar AntiSamy con una configuración predeterminada, pero es igualmente probable que un sitio quiera tener reglas estrictas, impulsadas por el negocio, sobre lo que los usuarios pueden permitir. La discusión que decide la adaptación también debe considerar la superficie de ataque, que crece en proporción relativa al archivo de política.

Las políticas de ejemplo se pueden adaptar y probar según los requisitos de cada etiqueta. Las acciones de etiqueta admitidas que se pueden especificar son:

• filter: elimina las etiquetas, pero conserva el contenido.
• validate: conserva el contenido siempre que pase las reglas.
• remove: elimina la etiqueta y su contenido.
• truncate: elimina los atributos de la etiqueta y todas las etiquetas hijas, excepto su contenido de texto, si lo hay.
• encode: similar a filter, pero codifica la etiqueta para HTML a fin de preservarla como texto sin formato y sus hijos se mueven un nivel hacia arriba en la jerarquía.

4. Llamar a la API de AntiSamy

Usar AntiSamy es fácil. Aquí hay un ejemplo de invocación de AntiSamy con un archivo de política:

import org.owasp.validator.html.*;

Policy policy = Policy.getInstance(POLICY_FILE_LOCATION);

AntiSamy as = new AntiSamy();
CleanResults cr = as.scan(dirtyInput, policy);

MyUserDAO.storeUserProfile(cr.getCleanHTML()); // some custom function

Hay algunas formas de crear un objeto Policy. El método getInstance() puede recibir cualquiera de los siguientes:

• un String con el nombre del archivo
• un objeto File
• un InputStream
• Los archivos Policy también se pueden referenciar por nombre de archivo pasando un segundo argumento al método AntiSamy#scan() como muestran los siguientes ejemplos:

AntiSamy as = new AntiSamy();
CleanResults cr = as.scan(dirtyInput, policyFilePath);

Finalmente, los archivos de política también se pueden referenciar mediante objetos File directamente en el segundo parámetro:

AntiSamy as = new AntiSamy();
CleanResults cr = as.scan(dirtyInput, new File(policyFilePath));

5. Analizar CleanResults

El objeto CleanResults proporciona muchas cosas útiles.

• getCleanHTML() - la salida HTML limpia y segura
• getCleanXMLDocumentFragment() - el XMLDocumentFragment limpio y seguro que se refleja en getCleanHTML()
• getErrorMessages() - una lista de mensajes de error String -- si esto devuelve 0, no significa que no hubo ataques!
• getNumberOfErrors() - el número de mensajes de error -- De nuevo, 0 no significa que la entrada fuera segura!
• getScanTime() - devuelve el tiempo de escaneo en segundos

Nota Importante: Ha habido mucha confusión sobre el método getErrorMessages(). El método getErrorMessages() (ni tampoco getNumberOfErrors()) no responde sutilmente a la pregunta "¿es esta entrada segura?" de manera afirmativa si devuelve una lista vacía. Siempre debe usar la entrada saneada y no hay forma de estar seguro de que la entrada proporcionada no tuviera ataques.

El proceso de serialización y deserialización que es crítico para la efectividad del saneador es deliberadamente con pérdida y filtrará ataques a través de una serie de vectores de ataque. Desafortunadamente, una de las desventajas de esta estrategia es que AntiSamy no siempre sabe en retrospectiva que se vio un ataque. Por lo tanto, las API getErrorMessages() y getNumberOfErrors() están ahí para ayudar a los usuarios a entender si su entrada bien intencionada cumple con los requisitos del sistema, no para ayudar a un desarrollador a detectar si hubo un ataque.

Otra Documentación

Documentación adicional está disponible en la página wiki de este proyecto de GitHub: https://github.com/nahsra/antisamy/wiki y en la Página del Proyecto OWASP AntiSamy: https://owasp.org/www-project-antisamy/

Contribuir a AntiSamy

¿Encontraste un Problema?

Si ha encontrado un error, cree un issue en el repositorio de AntiSamy: https://github.com/nahsra/antisamy/issues

¿Encontraste una Vulnerabilidad?

Si ha encontrado una vulnerabilidad en AntiSamy, primero busque en la lista de issues (ver arriba) para ver si ya ha sido reportada. Si no lo ha sido, comuníquese directamente con Dave Wichers (dave.wichers at owasp.org). Por favor, no reporte vulnerabilidades a través de los issues de GitHub, ya que deseamos mantener seguros a nuestros usuarios mientras se implementa y despliega un parche. Si desea ser reconocido por encontrar la vulnerabilidad, siga este proceso.

Hay más detalle disponible en el archivo: SECURITY.md.

Cómo Compilar

Puede compilar y probar desde el código fuente con bastante facilidad:

$ git clone https://github.com/nahsra/antisamy
$ cd antisamy
$ mvn package

Licencia

Publicado bajo la licencia BSD-3-Clause como se especifica aquí: LICENSE.