{"id":32807675,"url":"https://github.com/jonasgeiping/breaching","last_synced_at":"2025-11-06T16:02:54.340Z","repository":{"id":41199811,"uuid":"459786590","full_name":"JonasGeiping/breaching","owner":"JonasGeiping","description":"Breaching privacy in federated learning scenarios for vision and text","archived":false,"fork":false,"pushed_at":"2025-08-18T14:58:37.000Z","size":175772,"stargazers_count":304,"open_issues_count":0,"forks_count":69,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-22T11:02:04.714Z","etag":null,"topics":["decentralized-learning","federated-learning","machine-learning","privacy-audit","pytorch","security"],"latest_commit_sha":null,"homepage":"","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/JonasGeiping.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-02-15T23:39:59.000Z","updated_at":"2025-09-05T08:06:55.000Z","dependencies_parsed_at":"2024-04-17T13:50:01.595Z","dependency_job_id":null,"html_url":"https://github.com/JonasGeiping/breaching","commit_stats":{"total_commits":602,"total_committers":17,"mean_commits":"35.411764705882355","dds":"0.12624584717607978","last_synced_commit":"a51fba6b637207adbfbbde3a117eed2391c515ce"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JonasGeiping/breaching","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasGeiping%2Fbreaching","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasGeiping%2Fbreaching/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasGeiping%2Fbreaching/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasGeiping%2Fbreaching/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JonasGeiping","download_url":"https://codeload.github.com/JonasGeiping/breaching/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonasGeiping%2Fbreaching/sbom","scorecard":{"id":74082,"data":{"date":"2025-08-11","repo":{"name":"github.com/JonasGeiping/breaching","commit":"8bd99d52cdb8c38d6b12a191e620d11d275a8d45"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":0,"reason":"Found 1/28 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Info: FSF or OSI recognized license: MIT License: LICENSE.md:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 3 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-15T04:27:19.047Z","repository_id":41199811,"created_at":"2025-08-15T04:27:19.047Z","updated_at":"2025-08-15T04:27:19.047Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283037048,"owners_count":26768591,"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","status":"online","status_checked_at":"2025-11-06T02:00:06.180Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["decentralized-learning","federated-learning","machine-learning","privacy-audit","pytorch","security"],"created_at":"2025-11-06T16:02:22.270Z","updated_at":"2025-11-06T16:02:54.330Z","avatar_url":"https://github.com/JonasGeiping.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Breaching - A Framework for Attacks against Privacy in Federated Learning\n\nThis PyTorch framework implements a number of gradient inversion attacks that *breach* privacy in federated learning scenarios,\ncovering examples with small and large aggregation sizes and examples both in vision and in text domains.\n\n\n![](examples/teaser_breaching.png)\n\nThis includes implementations of recent work such as:\n* Malicious-model attacks as described in \"Robbing The Fed\" https://openreview.net/forum?id=fwzUgo0FM9v\n* Attacks against transformer architectures described in \"Decepticons\" https://arxiv.org/abs/2201.12675\n* Fishing attacks that breach arbitrary aggregations described in https://arxiv.org/abs/2202.00580\n\nBut also a range of implementations of other attacks from optimization attacks (such as \"Inverting Gradients\" and \"See through Gradients\") to recent analytic and recursive attacks. Jupyter notebook examples for these attacks can be found in the `examples/` folder.\n\n## Overview:\nThis repository implements two main components. A list of modular attacks under `breaching.attacks` and a list of relevant use cases (including server threat model, user setup, model architecture and dataset) under `breaching.cases`. All attacks and scenarios are highly modular and can be customized and extended through the configuration at `breaching/config`.\n\n### Installation\nEither download this repository (including notebooks and examples) directly using `git clone` or install the python package via `pip install breaching` for easy access to key functionality.\n\nBecause this framework covers several use cases across vision and language, it also accumulates a kitchen-sink of dependencies. The full list of all dependencies can be found at `environment.yml` (and installed with conda by calling `conda env create --file environment.yml `), but the full list of dependencies not installed by default. Install these as necessary (for example install huggingface packages only if you are interested in language applications).\n\nYou can verify your installation by running `python simulate_breach.py dryrun=True`. This tests the simplest reconstruction setting with a single iteration.\n\n\n### Usage\nYou can load any use case by\n```\ncfg_case = breaching.get_case_config(case=\"1_single_imagenet\")\nuser, server, model, loss = breaching.cases.construct_case(cfg_case)\n```\nand load any attack by\n```\ncfg_attack = breaching.get_attack_config(attack=\"invertinggradients\")\nattacker = breaching.attacks.prepare_attack(model, loss, cfg_attack)\n```\n\nThis is a good spot to print out an overview over the loaded threat model and setting, maybe you would want to change some settings?\n```\nbreaching.utils.overview(server, user, attacker)\n```\n\nTo evaluate the attack, you can then simulate an FL exchange:\n```\nshared_user_data, payloads, true_user_data = server.run_protocol(user)\n```\nAnd then run the attack (which consumes only the user update and the server state):\n```\nreconstructed_user_data, stats = attacker.reconstruct(payloads, shared_user_data)\n```\n\nFor more details, have a look at the notebooks in the `examples/` folder, the cmd-line script `simulate_breach.py` or the minimal examples in `minimal_example.py` and `minimal_example_robbing_the_fed.py`.\n\n### What is this framework?\nThis framework is modular collections of attacks against federated learning that breach privacy by recovering user data from their updates sent to a central server. The framework covers gradient updates as well as updates from multiple local training steps and evaluates datasets and models in language and vision. Requirements and variations in the threat model for each attack (such as the existence of labels or number of data points) are made explicit. Modern initializations and label recovery strategies are also included.\n\nWe especially focus on clarifying the threat model of each attack and constraining the `attacker` to only act based on the `shared_user_data` objects generated by the user. All attacks should be as use-case agnostic as possible based only on these limited transmissions of data and implementing a new attack should require no knowledge of any use case. Likewise implementing a new use case should be entirely separate from the attack portion. Everything is highly configurable through `hydra` configuration syntax.\n\n### What does this framework not do?\nThis framework focuses only on attacks, implementing no defense aside from user-level differential privacy and aggregation. We wanted to focus only on attack evaluations and investigate the questions \"where do these attacks work currently\", and \"where are the limits\". Accordingly, the FL simulation is \"shallow\". No model is actually trained here and we investigate fixed checkpoints (which can be generated somewhere else). Other great repositories, such as https://github.com/Princeton-SysML/GradAttack focus on defenses and their performance during a full simulation of a FL protocol.\n\n\n### Attacks\nA list of all included attacks with references to their original publications can be found at `examples/README.md`.\n\n### Datasets\nMany examples for vision attacks show `ImageNet` examples. For this to work, you need to download the *ImageNet ILSVRC2012* dataset **manually**. However, almost all attacks require only the small validation set, which can be easily downloaded onto a laptop and do not look for the whole training set. If this is not an option for you, then the `Birdsnap` dataset is a reasonably drop-in replacement for ImageNet. By default, we further only show examples from `ImageNetAnimals`, which are the first 397 classes of the ImageNet dataset. This reduces the number of weird pictures of actual people substantially. Of course `CIFAR10` and `CIFAR100` are also around.\nFor these vision datasets there are several options in the literature on how to partition them for a FL simulation. We implement a range of such partitions with `data.partition`, ranging from `random` (but replicable and with no repetitions of data across users), over `balanced` (separate classes equally across users) to `unique-class` (every user owns data from a single class). When changing the partition you might also have to adjust the number of expected clients `data.default_clients` (for example, for `unique_class` there can be only `len(classes)` many users).\n\nFor language data, you can load `wikitext` which we split into separate users on a per-article basis, or the `stackoverflow` and `shakespeare` FL datasets from tensorflow federated, which are already split into users (installing `tensorflow-cpu` is required for these tensorflow-federated datasets).\n\nFurther, nothing stops you from skipping the `breaching.cases` sub-module and using your own code to load a model and dataset. An example can be found in `minimal_example.py`.\n\n## Metrics\n\nWe implement a range of metrics which can be queried through `breaching.analysis.report`. Several metrics (such as CW-SSIM and R-PSNR) require additional packages to be installed - they will warn about this. For language data we hook into a range of huggingface metrics. Overall though, we note that most of these metrics give only a partial picture of the actual severity of a breach of privacy, and are best handled with care.\n\n## Additional Topics\n\n### Benchmarking\nA script to benchmark attacks is included as `benchmark_breaches.py`. This script will iterate over the first valid `num_trials` users, attack each separately and average the resulting metrics. This can be useful for quantitative analysis of these attacks. The default case takes about a day to benchmark on a single GTX2080 GPU for optimization-based attacks, and less than 30 minutes for analytic attacks.\nUsing the default scripts for benchmarking and cmd-line executes also includes a bunch of convenience based mostly on `hydra`. This entails the creation of separate sub-folders for each experiment in `outputs/`. These folders contain logs, metrics and optionally recovered data for each run. Summary tables are written to `tables/`.\n\n### System Requirements\nAll attacks can be run on both CPU/GPU (any `torch.device` actually). However, the optimization-based attacks are very compute intensive and using a GPU is highly advised. The other attacks are cheap enough to be run on CPUs (The Decepticon attack for example does most of the heavy lifting in assignment problems on CPU anyway, for example).\n\n### Options\nIt is probably best to have a look into `breaching/config` to see all possible options.\n\n### Citation\nFor now, please cite the respective publications for each attack and use case and note in your appendix / supplementary material that you used this framework.\n\n\n### License\nWe integrate several snippets of code from other repositories and refer to the licenses included in those files for more info.\nWe're especially thankful for related projects such as https://www.tensorflow.org/federated, https://github.com/NVlabs/DeepInversion, https://github.com/JunyiZhu-AI/R-GAP, https://github.com/facebookresearch/functorch, https://github.com/ildoonet/pytorch-gradual-warmup-lr and https://github.com/nadavbh12/VQ-VAE from which we incorporate components.\n\nFor the license of our code, refer to `LICENCE.md`.\n\n### Authors\nThis framework was built by me ([Jonas Geiping](https://github.com/JonasGeiping)), [Liam Fowl](https://github.com/lhfowl) and [Yuxin Wen](https://github.com/YuxinWenRick) while working at the University of Maryland, College Park.\n\n### Contributing\nIf you have an attack that you are interested in implementing in this framework, or a use case that is interesting to you, don't hesitate to contact us or open a pull-request.\n\n### Contact\nIf you have any questions, also don't hesitate to open an issue here on github or write us an email.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasgeiping%2Fbreaching","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonasgeiping%2Fbreaching","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonasgeiping%2Fbreaching/lists"}