CleverHans (última versión: v4.0.0)

Este repositorio contiene el código fuente de CleverHans, una biblioteca de Python para evaluar la vulnerabilidad de los sistemas de aprendizaje automático a los ejemplos adversariales. Puedes aprender más sobre estas vulnerabilidades en el blog adjunto.

La biblioteca CleverHans está en continuo desarrollo, y siempre recibe contribuciones de los últimos ataques y defensas. En particular, siempre agradecemos ayuda para resolver los issues actualmente abiertos.

Desde v4.0.0, CleverHans soporta 3 frameworks: JAX, PyTorch y TF2. Actualmente priorizamos la implementación de ataques en PyTorch, pero agradecemos mucho las contribuciones para los 3 frameworks. En las versiones v3.1.0 y anteriores, CleverHans soportaba TF1; el código para v3.1.0 se puede encontrar en cleverhans_v3.1.0/ o revisando una versión anterior de Github.

La biblioteca se centra en proporcionar una implementación de referencia de ataques contra modelos de aprendizaje automático para ayudar a evaluar los modelos frente a ejemplos adversariales.

La estructura de directorios es la siguiente: cleverhans/ contiene implementaciones de ataques, tutorials/ contiene scripts que demuestran las funcionalidades de CleverHans, y defenses/ contiene implementaciones de defensas. Cada framework tiene su propio subdirectorio dentro de estas carpetas, p. ej., cleverhans/jax.

Configuración de CleverHans

Dependencias

Esta biblioteca utiliza Jax, PyTorch o TensorFlow 2 para acelerar los cálculos de grafos realizados por muchos modelos de aprendizaje automático. Por lo tanto, instalar una de estas bibliotecas es un requisito previo.

Instalación

Una vez que las dependencias hayan sido gestionadas, puedes instalar CleverHans usando pip o clonando este repositorio de Github.

Instalación con pip

Si estás instalando CleverHans usando pip, ejecuta el siguiente comando:

pip install cleverhans

Esto instalará la última versión subida a Pypi. Si prefieres instalar la versión más avanzada, usa:

pip install git+https://github.com/cleverhans-lab/cleverhans.git#egg=cleverhans

Instalación para desarrollo

Si quieres hacer una instalación editable de CleverHans para poder desarrollar la biblioteca y contribuir con cambios, primero haz un fork del repositorio en GitHub y luego clona tu fork en un directorio de tu elección:

git clone https://github.com/<your-org>/cleverhans

Luego puedes instalar el paquete local en modo "editable" para añadirlo a tu PYTHONPATH:

cd cleverhans
pip install -e .

Configuraciones actualmente soportadas

Aunque es probable que CleverHans funcione en muchas otras configuraciones de máquina, actualmente lo probamos con Python 3.6, Jax 0.2, PyTorch 1.7 y Tensorflow 2.4 en Ubuntu 18.04 LTS (Bionic Beaver).

Obtención de soporte

Si tienes una solicitud de soporte, por favor haz una pregunta en StackOverflow en lugar de abrir un issue en el rastreador de GitHub. El rastreador de issues de GitHub debe solo utilizarse para reportar errores o hacer solicitudes de funciones.

Contribuciones

¡Las contribuciones son bienvenidas! Para acelerar el proceso de revisión de código, pedimos que:

• Los nuevos esfuerzos y funciones se coordinen en el foro de discusión.
• Al hacer contribuciones de código a CleverHans, sigas el estilo de codificación Black en tus pull requests.
• No aceptamos pull requests que añadan submódulos de git debido a los problemas que surgen al mantener submódulos de git.

Las correcciones de errores pueden iniciarse mediante pull requests de Github.

Tutoriales: directorio tutorials

Para ayudarte a comenzar con las funcionalidades que proporciona esta biblioteca, la carpeta tutorials/ incluye los siguientes tutoriales:

• MNIST con FGSM y PGD (jax, tf2: este tutorial cubre cómo entrenar un modelo MNIST y crear ejemplos adversariales usando el método del signo del gradiente rápido y el descenso de gradiente proyectado.
• CIFAR10 con FGSM y PGD (pytorch, tf2): este tutorial cubre cómo entrenar un modelo CIFAR10 y crear ejemplos adversariales usando el método del signo del gradiente rápido y el descenso de gradiente proyectado.

NOTA: los tutoriales se mantienen cuidadosamente, en el sentido de que utilizamos integración continua para asegurarnos de que sigan funcionando. No se consideran parte de la API y pueden cambiar en cualquier momento sin previo aviso. No debes escribir código de terceros que importe los tutoriales y esperar que la interfaz no se rompa. Solo la biblioteca principal está sujeta a nuestra regla de aviso de desaprobación de interfaces con seis meses de antelación.

NOTA: por favor, inicia un hilo en el foro de discusión antes de escribir un nuevo tutorial. Debido a que cada nuevo tutorial implica una gran cantidad de código duplicado en relación con los tutoriales existentes, y porque cada línea de código requiere pruebas y mantenimiento continuos indefinidamente, generalmente preferimos no añadir nuevos tutoriales. Cada tutorial debe mostrar una forma extremadamente diferente de usar la biblioteca. Simplemente usar un ataque, modelo o conjunto de datos diferente no es suficiente para justificar el mantenimiento de un tutorial paralelo.

Ejemplos : directorio examples

La carpeta examples/ contiene scripts adicionales para mostrar diferentes usos de la biblioteca CleverHans o para ayudarte a comenzar a competir en diferentes concursos de ejemplos adversariales. No ofrecemos ni mucho menos el mismo mantenimiento o soporte continuo para este directorio que para el resto de la biblioteca, y si el código aquí se rompe, podríamos simplemente eliminarlo sin previo aviso.

Dado que recientemente descontinuamos el soporte para TF1, la carpeta examples/ está actualmente vacía, ¡pero puedes enviar tus usos mediante un pull request :)

Los ejemplos antiguos para CleverHans v3.1.0 y anteriores se pueden encontrar en cleverhans_v3.1.0/examples/.

Informe de benchmarks

Al reportar benchmarks, por favor:

• Usa una versión publicada de CleverHans. Puedes encontrar una lista de versiones publicadas aquí.
• Usa la última versión o, si comparas con una publicación anterior, usa la misma versión que la publicación anterior.
• Informa qué método de ataque se utilizó.
• Informa cualquier variable de configuración utilizada para determinar el comportamiento del ataque.