{"id":38305218,"url":"https://github.com/juburr/bitcamo","last_synced_at":"2026-01-17T02:26:43.481Z","repository":{"id":191932296,"uuid":"472031016","full_name":"juburr/bitcamo","owner":"juburr","description":"An adversarial machine learning (AML) tool for modifying Windows PE files to evade detection by malware classifiers.","archived":false,"fork":false,"pushed_at":"2024-02-12T17:07:19.000Z","size":15878,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-02-13T05:37:14.175Z","etag":null,"topics":["adversarial-attacks","adversarial-examples","adversarial-machine-learning","antivirus-evasion","malware-research"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juburr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-03-20T16:06:11.000Z","updated_at":"2024-02-13T05:37:14.176Z","dependencies_parsed_at":"2023-09-01T16:09:57.054Z","dependency_job_id":null,"html_url":"https://github.com/juburr/bitcamo","commit_stats":null,"previous_names":["juburr/bitcamo"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/juburr/bitcamo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juburr%2Fbitcamo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juburr%2Fbitcamo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juburr%2Fbitcamo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juburr%2Fbitcamo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juburr","download_url":"https://codeload.github.com/juburr/bitcamo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juburr%2Fbitcamo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28492286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T00:50:05.742Z","status":"online","status_checked_at":"2026-01-17T02:00:07.808Z","response_time":85,"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":["adversarial-attacks","adversarial-examples","adversarial-machine-learning","antivirus-evasion","malware-research"],"created_at":"2026-01-17T02:26:43.403Z","updated_at":"2026-01-17T02:26:43.466Z","avatar_url":"https://github.com/juburr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eBitCamo\u003c/h1\u003e\n  \u003cimg align=\"center\" width=\"280\" src=\"https://github.com/juburr/bitcamo/raw/master/resources/bitcamo.png\" alt=\"EXE File\"\u003e\n  \u003cbr /\u003e\n  \u003cb\u003e\u003ci\u003eHiding malware in plain sight.\u003c/i\u003e\u003c/b\u003e\u003cbr /\u003e\u003cbr /\u003e\n  BitCamo is an adversarial machine learning (AML) tool for modifying executables with the goal of evading malware detection systems. The initial version of this tool alters Windows PE files with the goal of evading the EMBER-trained MalConv model. The tool is designed to assist security researchers, AI/ML red team operators, and AV vendors. New contributors are welcome.\u003cbr /\u003e\u003cbr /\u003e\n  \u003ca href=\"https://github.com/pralab/secml_malware\"\u003eSecML Malware\u003c/a\u003e and \u003ca href=\"https://github.com/bfilar/malware_rl\"\u003eMalwareRL\u003c/a\u003e are popular alternatives to this tool.\n\u003c/div\u003e\n\n## Demo\n\u003cvideo src=\"https://user-images.githubusercontent.com/20321959/160679943-9c90956f-6e82-44e8-84c9-3fc3086322c1.mp4\"\u003e\u003c/video\u003e\n\n## Attack Overview \n\nBitCamo is a gradient-based attack tool intended for use in whitebox attack scenarios. The current version is an implementation of Kreuk's FGSM overlay attack with greatly increased evasion rates and attack speeds. Selecting thousands of malicious samples (\u003c1 MB) uniformly at random from the [SOREL-20M](https://github.com/sophos-ai/SOREL-20M) dataset results in a 100% evasion rate against the EMBER-trained MalConv model while using payload sizes of only 300 bytes on average. Attacks complete in a mere one second when using fixed size payloads, offering a massive performance improvement over existing tools. See the remarks on limitations below.\n\n### PE File Modification\nMost bytes within a Windows PE file cannot be freely modified without breaking functionality. BitCamo will attempt to insert payloads at unused locations throughout the file. The current version of this tool will only target the file overlay. The ability to use other payload locations will be included in future releases.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg align=\"center\" width=\"65%\" src=\"https://github.com/juburr/bitcamo/raw/master/resources/bitcamo-attack-overview.png\" alt=\"Attack Overview\"\u003e\n\u003c/div\u003e\n\n### Adversarial Attack Explanation\nThe payload contains a specially crafted set of bytes designed to fool MalConv. In our white-box attack scenario, these bytes are determined mathematically using the Fast Gradient Sign Method (FGSM). Before running the gradient attack, users have the ability to specify how the payload should be initialized. Previous attacks in the research literature use a randomized method, whereas this tool fills the payload with byte value `0xBF` by default, maximizing the likelihood of a succesful evasion. A primary obstacle that must be overcome is MalConv's non-differentiable embedding layer. Other tools use an L2 distance metric to map backwards across this layer, whereas this tool uses K-D trees to offer blazing fast lookup speeds.\n\n### Limitations\nThe EMBER-trained MalConv model uses 1 MB input sizes. Although malware samples tend to be fairly small, note that BitCamo will not yet work against executables with larger file sizes, as it currently targets the file overlay. Future releases of the tool will target other sections of the PE file. Additional detection models will also be supported in future releases.\n\n## Acknowledgements\nThis tool would not be possible without the amazing contributions to the research literature from the teams listed below.   \n\nDefensive:\n- MalConv ([Raff et al, 2017](https://arxiv.org/abs/1710.09435))\n- EMBER-trained MalConv model ([Anderson \u0026 Roth, 2018](https://arxiv.org/abs/1804.04637))\n- Pre-Detection Mechanism ([Chen et al., 2019](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=8703786))\n\nOffensive:\n- Overlay attack ([Kolosnjaji et al., 2018](https://arxiv.org/abs/1803.04173))\n- FGSM overlay attack ([Kreuk et al., 2019](https://arxiv.org/abs/1802.04528))\n- One-shot FGSM slack attack ([Suciu et al., 2019](https://arxiv.org/abs/1810.08280))\n- DOS header attacks ([Demetrio et al., 2021](https://arxiv.org/abs/2008.07125))\n- K-D Tree reconstruction speedups ([Burr, 2022](https://scholar.dsu.edu/theses/378))\n- Payload initialization methods ([Burr, 2022](https://scholar.dsu.edu/theses/378))\n- Evasion of the pre-detection mechanism ([Burr, 2022](https://scholar.dsu.edu/theses/378))\n- Payload size minimization algorithm ([Burr, 2022](https://scholar.dsu.edu/theses/378))\n\n## Instructions\nThe provided Docker container is the quickest way for most users to get setup. Note that live malware samples are not included with the tool. You can download malware elsewhere at your own risk. Ten million malicious binaries are provided in the [SOREL-20M](https://github.com/sophos-ai/SOREL-20M) dataset by Sophos AI.\n\n### Running the attack code using Docker\nEnsure your machine has Docker installed and then follow the instructions below, being sure to replace `/host/malware/dir` with an absolute path to the directory containing your Windows PE malware samples.  \n```\ndocker pull ghcr.io/juburr/bitcamo:latest\ndocker run -v /host/malware/dir:/home/nonroot/samples -it --entrypoint /bin/bash ghcr.io/juburr/bitcamo:latest\nbitcamo.py samples/malicious_program.exe\n```\n\n### Running the attack code using Python virtual environments\nInstructions will vary depending on your Linux distribution. The tool was developed using Python 3.8.  \nFedora 35: `dnf install python3.8 python3-devel gcc-c++`\n```\ngit clone https://github.com/juburr/bitcamo.git\ncd bitcamo\npython3.8 -m venv .venv\nsource .venv/bin/activate\npython3.8 -m pip install --upgrade pip setuptools wheel\npython3.8 -m pip install -r requirements.txt\npython3.8 bitcamo.py samples/malicious_program.exe\n```\n\n### Tips and Helpful CLI Flags\n\nThe usage instructions above show an attack against a single file. BitCamo can also process datasets by specifying an entire directory instead:  \n`./bitcamo.py samples/malicious/sorel-20m`  \n\nA payload size of 900 bytes is used by default. This can be changed with the `-p` flag, specifying that all samples should be attacked using a fixed-sized payload:  \n`./bitcamo.py -p 1500 samples/malicious/sorel-20m`  \n\nIteratively increase the payload size in 50 bytes increments, to a maximum payload size of 2000 bytes. This is what allowed for a 100% evasion rate with only 300-byte payloads on average. Processing time will be increased from roughly 1 second to 5 seconds on average. Use the `-O` flag to optimize the payload size:  \n`./bitcamo.py -O -p 2000 samples/malicious/sorel-20m`  \n\nTry using a different payload initialization strategy by supplying the `-i` flag. By default BitCamo will initialize all bytes in the payload to 0xBF (191) before running FGSM. Other options include `random`, `psuedorandom`, and `weighted`. Previous research typically used the `random` technique. The `-i` flag will also work by supplying the integer representation of any byte value between 0-255.  For example, 0xAA (170) can be used by entering:  \n`./bitcamo.py -i 170 samles/malicious/sorel-20m`  \n\nThe tool works in both directions. BitCamo can process a benign file and make it appear malicious without actually introducing malicious code. Use the `-b` flag to specify that inputs are benign:  \n`./bitcamo.py -b samples/benign/windows-executables`  \n\nSpecify a different output directory using the `-o` flag:  \n`./bitcamo.py -o samples/output/sorel-20m samples/malicious/sorel-20m`  \n\nOther less important command line flags can be discovered in the help menu by supplying the `-h` or `--help` flags:  \n`./bitcamo.py --help`\n\n## References\n\nAnderson, H., \u0026 Roth, P. (2018). EMBER: An Open Dataset for Training Static PE Malware Machine Learning Models. doi:10.48550/arXiv.1804.04637\n\nBurr, J. (2022). Improving Adverarial Machine Learning Attacks Against MalConv (Doctoral dissertation). Retrieved from https://scholar.dsu.edu/theses/378/\n\nChen, B., Ren, Z., Yu, C., Hussain, I., \u0026 Liu, J. (2019). Adversarial Examples for CNN-Based Malware Detectors. *IEEE Access, 7*, 54360-54371. doi:10.1109/ACCESS.2019.2913439\n\nDemetrio, L., Coull, S., Biggio, B., Lagorio, G., Armando, A., \u0026 Roli, F. (2021). Adversarial EXEmples: A Survey and Experimental Evaluation of Practical Attacks on Machine Learning for Windows Malware Detection. *ACM Transactions on Privacy and Security, 24*(4), doi:10.1145/3473039\n\nKolosnjaji, B., Demontis, A., Biggio, B., Maiorca, D., Giacinto, G., Eckert, C., \u0026 Roli, F. (2018). Adversarial Malware Binaries: Evading Deep Learning for Malware Detection in Executables. doi:10.48550/arXiv.1803.04173\n\nKreuk, F., Barak, A., Aviv-Reuven, S., Baruch, M., Pinkas, B., \u0026 Keshet J. (2018). Deceiving End-to-End Deep Learning Malware Detectors using Adversarial Examples. doi:10.48550/arXiv.1802.04528\n\nRaff, E., Barker, J., Sylvester, J., Brandon, R., Cantanzaro, B., \u0026 Nicholas, C. (2017). Malware Detection by Eating a Whole EXE. doi:10.48550/arXiv.1710.09435\n\nSuciu, O., Coull, S., \u0026 Johns, J. (2019). Exploring Adversarial Examples in Malware Detection. doi:10.48550/arXiv.1810.08280\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuburr%2Fbitcamo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuburr%2Fbitcamo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuburr%2Fbitcamo/lists"}