{"id":28100738,"url":"https://github.com/poloclub/jpeg-defense","last_synced_at":"2026-01-24T02:36:11.408Z","repository":{"id":29498352,"uuid":"120345934","full_name":"poloclub/jpeg-defense","owner":"poloclub","description":"SHIELD: Fast, Practical Defense and Vaccination for Deep Learning using JPEG Compression","archived":false,"fork":false,"pushed_at":"2023-03-24T22:38:55.000Z","size":1837,"stargazers_count":81,"open_issues_count":3,"forks_count":8,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-03-23T05:18:04.248Z","etag":null,"topics":["adversarial-machine-learning","attack","carlini-wagner","deep-learning","deepfool","defense","dnn","fgsm","georgia-tech","i-fgsm","imagenet-dataset","intel","jpeg-compression","paper","security","shield","tensorflow","vaccination","video-demo"],"latest_commit_sha":null,"homepage":"https://poloclub.github.io/jpeg-defense/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/poloclub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-05T18:42:21.000Z","updated_at":"2025-02-11T15:50:09.000Z","dependencies_parsed_at":"2023-01-14T15:15:21.281Z","dependency_job_id":null,"html_url":"https://github.com/poloclub/jpeg-defense","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fjpeg-defense","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fjpeg-defense/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fjpeg-defense/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poloclub%2Fjpeg-defense/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/poloclub","download_url":"https://codeload.github.com/poloclub/jpeg-defense/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254004925,"owners_count":21998146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adversarial-machine-learning","attack","carlini-wagner","deep-learning","deepfool","defense","dnn","fgsm","georgia-tech","i-fgsm","imagenet-dataset","intel","jpeg-compression","paper","security","shield","tensorflow","vaccination","video-demo"],"created_at":"2025-05-13T18:38:38.138Z","updated_at":"2026-01-24T02:36:06.367Z","avatar_url":"https://github.com/poloclub.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHIELD: Fast, Practical Defense and Vaccination for Deep Learning using JPEG Compression\n\n\n## Overview\n\nThis is the code repository for the [KDD 2018](http://www.kdd.org/kdd2018/) Applied Data Science paper: **[SHIELD: Fast, Practical Defense and Vaccination for Deep Learning using JPEG Compression](https://arxiv.org/abs/1802.06816)**. Visit our research group homepage [Polo Club of Data Science](https://poloclub.github.io) at [Georgia Tech](http://www.gatech.edu) for more related research!\n\nThe code included here reproduces our techniques (e.g. SLQ) presented in the paper, and also our experiment results reported, such as using various JPEG compression qualities to remove adversarial perturbation introduced by Carlini-Wagner-L2, DeepFool, I-FSGM, and FSGM.\n\n[![SHIELD overview YouTube video](readme/shield-youtube-thumbnail.jpg)](https://youtu.be/zUB2-i7rSb4)\n\n\n## Research Abstract\nThe rapidly growing body of research in adversarial machine learning has demonstrated that deep neural networks (DNNs) are highly vulnerable to adversarially generated images. \nThis underscores the urgent need for practical defense that can be readily deployed to combat attacks in real-time. \nObserving that many attack strategies aim to perturb image pixels in ways that are visually imperceptible, we place JPEG compression at the core of our proposed SHIELD defense framework, utilizing its capability to effectively \"compress away\" such pixel manipulation. \nTo immunize a DNN model from artifacts introduced by compression, SHIELD \"vaccinates\" a model by re-training it with compressed images, where different compression levels are applied to generate multiple vaccinated models that are ultimately used together in an ensemble defense. \nOn top of that, SHIELD adds an additional layer of protection by employing randomization at test time that compresses different regions of an image using random compression levels, making it harder for an adversary to estimate the transformation performed. \nThis novel combination of vaccination, ensembling, and randomization makes SHIELD a fortified, multi-pronged defense. \nWe conducted extensive, large-scale experiments using the ImageNet dataset, and show that our approaches eliminate up to 94% of black-box attacks and 98% of gray-box attacks delivered by the recent, strongest techniques, such as Carlini-Wagner's L2 and DeepFool. \nOur approaches are fast and work without requiring knowledge about the model.\n\n\n## Installation and Setup\n\n### Clone Repository\n\nTo clone this repository using `git`, simply run the following command:\n\n```bash\ngit clone https://github.com/poloclub/jpeg-defense.git\n```\n\n### Install Dependencies\n\nThis repository uses attacks from the [CleverHans](https://github.com/tensorflow/cleverhans) library, and the models are adapted from [tf-slim](https://github.com/tensorflow/models/tree/master/research/slim). We also use [Sacred](https://github.com/IDSIA/sacred) to keep track of the experiments.\nAll dependencies for this repository can be found in `requirements.txt`. To install these dependencies, run the following command from the `jpeg-defense` directory:\n```bash\npip install -r requirements.txt\n```\n\n### Setup ImageNet Dataset\n\nThe code expects the ImageNet validation dataset to be available in TFRecord format in the `data/validation` directory.\nTo provision the data, we have provided a script (`setup/get_imagenet.py`) that downloads, processes, and saves the entire ImageNet dataset in the required format.\nThis script can be run from the `setup` directory in the following manner:\n\n```bash\npython get_imagenet.py --local_scratch_dir=\"/path/to/jpeg-defense/data\"\n``` \n\nDownloading the entire dataset from the ImageNet website using this script may be very slow.\nOptionally, we recommend downloading the \n[`ILSVRC2012_img_train.tar`](http://academictorrents.com/details/a306397ccf9c2ead27155983c254227c0fd938e2) \nand [`ILSVRC2012_img_val.tar`](http://academictorrents.com/details/5d6d0df7ed81efd49ca99ea4737e0ae5e3a5f2e5)\nusing [Academic Torrents](http://academictorrents.com/), and placing these files into the `data/raw_data` directory.\nThen, you can run the following command to skip downloading the dataset and proceed with converting the data into TFRecord format:\n\n```bash\npython get_imagenet.py \\\n  --local_scratch_dir=\"/path/to/jpeg-defense/data\" \\\n  --provision_only=True\n```\n\n### Download Pre-trained Model Weights\nThis repository currently supports the [ResNet50-v2](https://arxiv.org/abs/1603.05027) and [Inception-v4](https://arxiv.org/abs/1602.07261) models from [tf-slim](https://github.com/tensorflow/models/tree/master/research/slim).\nRunning the following command from the `jpeg-defense` directory will download the pre-trained `.ckpt` files for these models into the `data/checkpoints` folder using the provided `setup/get_model_checkpoints.sh` script:\n\n```bash\nbash setup/get_model_checkpoints.sh data/checkpoints\n```\n\n\n## Example Usage\n\nThe **`main.py`** script in the `shield` package can be used to perform all the experiments using the `--perform=attack|defend|evaluate` flags.\n\n- *attack* - Attacks the specified model with the specified method and its parameters (see `shield/opts.py`).\n\n```bash\npython main.py with \\                               \n  perform=attack \\\n  model=resnet_50_v2 \\\n  attack=fgsm \\\n  attack_options=\"{'eps': 16}\"\n```\n\n- *defend* - Defends the specified attacked images with the specified defense and its parameters (see `shield/opts.py`).\nThe defense uses the attack parameters only to determine which images are loaded for preprocessing,\nas these parameters are not used by the preprocessing itself.\n\n```bash\npython main.py with \\                               \n  perform=defend \\\n  model=resnet_50_v2 \\\n  attack=fgsm \\\n  attack_options=\"{'eps': 16}\" \\\n  defense=jpeg \\\n  defense_options=\"{'quality': 80}\"\n```\n\n- evaluate - Evaluates the specified model with the specified attacked/defended version of the images.\n\n```bash\npython main.py with \\                               \n  perform=evaluate \\\n  model=resnet_50_v2 \\\n  attack=fgsm \\\n  attack_options=\"{'eps': 16}\"\n```\n\n\n## Video Demo\n[![YouTube video demo](readme/shield-demo-youtube-thumbnail.jpg)](https://youtu.be/W119nXS4xGE)\n\n\n## Paper PDF on arXiv\n[![Paper PDF on arXiv](http://www.arxiv-sanity.com/static/thumbs/1802.06816v1.pdf.jpg)](https://arxiv.org/abs/1802.06816)\n\n## Citation \n\n**SHIELD: Fast, Practical Defense and Vaccination for Deep Learning using JPEG Compression.**  \nNilaksh Das, Madhuri Shanbhogue, Shang-Tse Chen, Fred Hohman, Siwei Li, Li Chen, Michael E. Kounavis, Duen Horng Chau.  \n*ACM SIGKDD Conference on Knowledge Discovery and Data Mining (KDD) 2018*. London, UK. Aug 19-23, 2018.\n\n### BibTeX\n```\n@article{das2018shield, \n   title={SHIELD: Fast, Practical Defense and Vaccination for Deep Learning using JPEG Compression}, \n   author={Das, Nilaksh and Shanbhogue, Madhuri and Chen, Shang-Tse and Hohman, Fred and Li, Siwei and Chen, Li and Kounavis, Michael E and Chau, Duen Horng}, \n   booktitle={Proceedings of the 24nd ACM SIGKDD International Conference on Knowledge Discovery and Data Mining}, \n   year={2018}, \n   organization={ACM} \n}\n```\n\n\n## Researchers\n\n|  Name                 | Affiliation                     |\n|-----------------------|---------------------------------|\n| [Nilaksh Das](http://nilakshdas.com)           | Georgia Tech |\n| [Madhuri Shanbhogue](https://www.linkedin.com/in/madhuri-shanbhogue/)    | Georgia Tech |\n| [Shang-Tse Chen](https://www.cc.gatech.edu/~schen351/)        | Georgia Tech |\n| [Fred Hohman](http://fredhohman.com)           | Georgia Tech |\n| [Siwei Li](https://rsli.github.io)              | Georgia Tech |\n| [Li Chen](https://www.linkedin.com/in/li-chen-phd-b2a10289/)               | Intel Corporation               |\n| [Michael E. Kounavis](https://www.linkedin.com/in/michael-kounavis-5bbb599/)   | Intel Corporation               |\n| [Polo Chau](https://www.cc.gatech.edu/~dchau/)             | Georgia Tech |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoloclub%2Fjpeg-defense","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoloclub%2Fjpeg-defense","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoloclub%2Fjpeg-defense/lists"}