CleverHans (última versão: v4.0.0)

Este repositório contém o código-fonte do CleverHans, uma biblioteca Python para avaliar (benchmark) a vulnerabilidade de sistemas de aprendizado de máquina a exemplos adversários. Você pode aprender mais sobre essas vulnerabilidades no blog.

A biblioteca CleverHans está em desenvolvimento contínuo, sempre recebendo contribuições dos ataques e defesas mais recentes. Em particular, sempre recebemos ajuda para resolver as issues atualmente em aberto.

Desde a v4.0.0, o CleverHans suporta 3 frameworks: JAX, PyTorch e TF2. Atualmente estamos priorizando a implementação de ataques em PyTorch, mas recebemos com muito prazer contribuições para os 3 frameworks. Nas versões v3.1.0 e anteriores, o CleverHans suportava TF1; o código da v3.1.0 pode ser encontrado em cleverhans_v3.1.0/ ou fazendo o checkout de uma release anterior do Github.

A biblioteca tem como foco fornecer implementações de referência de ataques contra modelos de aprendizado de máquina para ajudar no benchmarking de modelos contra exemplos adversários.

A estrutura de diretórios é a seguinte: cleverhans/ contém as implementações de ataques, tutorials/ contém scripts que demonstram os recursos do CleverHans, e defenses/ contém as implementações de defesas. Cada framework tem seu próprio subdiretório dentro dessas pastas, ex.: cleverhans/jax.

Configurando o CleverHans

Dependências

Esta biblioteca usa Jax, PyTorch ou TensorFlow 2 para acelerar os cálculos de grafo realizados por muitos modelos de aprendizado de máquina. Portanto, instalar uma dessas bibliotecas é um pré-requisito.

Instalação

Depois de cuidar das dependências, você pode instalar o CleverHans usando pip ou clonando este repositório do Github.

Instalação via pip

Se você estiver instalando o CleverHans usando pip, execute o seguinte comando:

pip install cleverhans

Isso instalará a última versão enviada ao Pypi. Se você preferir instalar a versão mais recente (bleeding edge), use:

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

Instalação para desenvolvimento

Se você quiser fazer uma instalação editável do CleverHans para poder desenvolver a biblioteca e contribuir com alterações, primeiro faça um fork do repositório no GitHub e depois clone seu fork para um diretório de sua escolha:

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

Em seguida, você pode instalar o pacote local no modo "editable" (editável) para adicioná-lo ao seu PYTHONPATH:

cd cleverhans
pip install -e .

Configurações atualmente suportadas

Embora o CleverHans provavelmente funcione em muitas outras configurações de máquina, atualmente o testamos com Python 3.6, Jax 0.2, PyTorch 1.7 e Tensorflow 2.4 no Ubuntu 18.04 LTS (Bionic Beaver).

Obtendo suporte

Se você tiver uma solicitação de suporte, faça uma pergunta no StackOverflow em vez de abrir uma issue no rastreador do GitHub. O rastreador de issues do GitHub deve ser usado apenas para relatar bugs ou fazer solicitações de recursos.

Contribuindo

Contribuições são bem-vindas! Para acelerar o processo de revisão de código, pedimos que:

• Novos esforços e recursos sejam coordenados no fórum de discussões.
• Ao fazer contribuições de código para o CleverHans, você deve seguir o estilo de codificação do Black em seus pull requests.
• Não aceitamos pull requests que adicionem submódulos git por causa dos problemas que surgem ao manter submódulos git.

Correções de bugs podem ser submetidas por meio de pull requests no Github.

Tutoriais: diretório tutorials

Para ajudar você a começar com as funcionalidades fornecidas por esta biblioteca, a pasta tutorials/ vem com os seguintes tutoriais:

• MNIST com FGSM e PGD (jax, tf2: este tutorial aborda como treinar um modelo MNIST e criar exemplos adversários usando o método do sinal do gradiente rápido e a descida do gradiente projetada.
• CIFAR10 com FGSM e PGD (pytorch, tf2): este tutorial aborda como treinar um modelo CIFAR10 e criar exemplos adversários usando o método do sinal do gradiente rápido e a descida do gradiente projetada.

NOTA: os tutoriais são mantidos com cuidado, no sentido de que usamos integração contínua para garantir que continuem funcionando. Eles não são considerados parte da API e podem mudar a qualquer momento sem aviso. Você não deve escrever código de terceiros que importe os tutoriais esperando que a interface não seja quebrada. Apenas a biblioteca principal está sujeita à nossa regra de aviso de descontinuação de interface com seis meses de antecedência.

NOTA: por favor, abra um tópico no fórum de discussões antes de escrever um novo tutorial. Como cada novo tutorial envolve uma grande quantidade de código duplicado em relação aos tutoriais existentes, e como cada linha de código exige testes e manutenção contínuos indefinidamente, geralmente preferimos não adicionar novos tutoriais. Cada tutorial deve demonstrar uma maneira extremamente diferente de usar a biblioteca. Apenas usar um ataque, modelo ou conjunto de dados diferente não é suficiente para justificar a manutenção de um tutorial paralelo.

Exemplos: diretório examples

A pasta examples/ contém scripts adicionais para demonstrar diferentes usos da biblioteca CleverHans ou ajudar você a começar a competir em diferentes competições de exemplos adversários. Não oferecemos nem de longe tanta manutenção contínua ou suporte para este diretório quanto para o restante da biblioteca, e se o código aqui for quebrado, podemos simplesmente excluí-lo sem aviso.

Como recentemente descontinuamos o suporte ao TF1, a pasta examples/ está atualmente vazia, mas você é bem-vindo a enviar seus usos por meio de um pull request :)

Exemplos antigos do CleverHans v3.1.0 e anteriores podem ser encontrados em cleverhans_v3.1.0/examples/.

Reportando benchmarks

Ao reportar benchmarks, por favor:

• Use uma release versionada do CleverHans. Você pode encontrar uma lista das versões publicadas aqui.
• Use a versão mais recente ou, se estiver comparando com uma publicação anterior, use a mesma versão da publicação anterior.
• Informe qual método de ataque foi usado.
• Informe quaisquer variáveis de configuração usadas para determinar o comportamento do ataque.

Por exemplo, você pode relatar "Avaliamos a robustez do nosso método contra ataques adversários usando a v4.0.0 do CleverHans. Em um conjunto de teste modificado pelo FastGradientMethod com uma norma máxima eps de 0,3, obtivemos uma acurácia de 71,3% no conjunto de teste."

Como citar este trabalho