cleverhans-lab/cleverhansUma biblioteca de exemplos adversariais para construir ataques, desenvolver defesas e avaliar ambos.
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.
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.
Depois de cuidar das dependências, você pode instalar o CleverHans usando
pip ou clonando este repositório do Github.
pipSe 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
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 .
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).
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.
Contribuições são bem-vindas! Para acelerar o processo de revisão de código, pedimos que:
Black
em seus pull requests.Correções de bugs podem ser submetidas por meio de pull requests no Github.
tutorialsPara ajudar você a começar com as funcionalidades fornecidas por esta biblioteca, a
pasta tutorials/ vem com os seguintes tutoriais:
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.
examplesA 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/.
Ao reportar benchmarks, por favor:
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."
Se você usar o CleverHans em pesquisa acadêmica, é altamente recomendado (embora não obrigatório) citar o seguinte artigo:
@article{papernot2018cleverhans,
title={Technical Report on the CleverHans v2.1.0 Adversarial Examples Library},
author={Nicolas Papernot and Fartash Faghri and Nicholas Carlini and
Ian Goodfellow and Reuben Feinman and Alexey Kurakin and Cihang Xie and
Yash Sharma and Tom Brown and Aurko Roy and Alexander Matyasko and
Vahid Behzadan and Karen Hambardzumyan and Zhishuai Zhang and
Yi-Lin Juang and Zhi Li and Ryan Sheatsley and Abhibhav Garg and
Jonathan Uesato and Willi Gierke and Yinpeng Dong and David Berthelot and
Paul Hendricks and Jonas Rauber and Rujun Long},
journal={arXiv preprint arXiv:1610.00768},
year={2018}
}
O nome CleverHans é uma referência a uma apresentação de Bob Sturm intitulada “Clever Hans, Clever Algorithms: Are Your Machine Learnings Learning What You Think?" e à publicação correspondente, "A Simple Method to Determine if a Music Information Retrieval System is a 'Horse'." Clever Hans era um cavalo que parecia ter aprendido a responder perguntas de aritmética, mas na verdade só havia aprendido a ler sinais sociais que lhe permitiam dar a resposta correta. Em ambientes controlados, onde não podia ver os rostos das pessoas nem receber qualquer outro feedback, ele era incapaz de responder às mesmas perguntas. A história de Clever Hans é uma metáfora para sistemas de aprendizado de máquina que podem alcançar acurácia muito alta em um conjunto de teste extraído da mesma distribuição dos dados de treinamento, mas que não entendem de fato a tarefa subjacente e têm desempenho ruim em outras entradas.
Esta biblioteca é mantida coletivamente pelo CleverHans Lab na Universidade de Toronto. O ponto de contato atual é Jonas Guan. Ela foi anteriormente mantida por Ian Goodfellow e Nicolas Papernot.
Os seguintes autores contribuíram com 100 linhas ou mais (ordenados de acordo com a página de contribuidores do GitHub):
Copyright 2021 - Google Inc., OpenAI, Pennsylvania State University, University of Toronto.