{"id":13936660,"url":"https://github.com/GoSecure/malboxes","last_synced_at":"2025-07-19T22:31:27.013Z","repository":{"id":47572511,"uuid":"55251419","full_name":"GoSecure/malboxes","owner":"GoSecure","description":"Builds malware analysis Windows VMs so that you don't have to.","archived":false,"fork":false,"pushed_at":"2021-08-23T19:51:38.000Z","size":490,"stargazers_count":1030,"open_issues_count":27,"forks_count":134,"subscribers_count":68,"default_branch":"master","last_synced_at":"2024-11-21T10:52:40.068Z","etag":null,"topics":["hacktoberfest","malware-analysis","malware-research","packer","python3","vagrant","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoSecure.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","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":"2016-04-01T17:50:36.000Z","updated_at":"2024-11-14T09:30:42.000Z","dependencies_parsed_at":"2022-08-12T13:40:58.391Z","dependency_job_id":null,"html_url":"https://github.com/GoSecure/malboxes","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoSecure%2Fmalboxes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoSecure%2Fmalboxes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoSecure%2Fmalboxes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoSecure%2Fmalboxes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoSecure","download_url":"https://codeload.github.com/GoSecure/malboxes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226686729,"owners_count":17666928,"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":["hacktoberfest","malware-analysis","malware-research","packer","python3","vagrant","virtual-machine"],"created_at":"2024-08-07T23:02:53.618Z","updated_at":"2024-11-27T04:31:18.610Z","avatar_url":"https://github.com/GoSecure.png","language":"Python","readme":"= Malboxes\n:toc: preamble\n:toclevels: 2\n:twob: https://twitter.com/obilodeau\n:twhg: https://twitter.com/hugospns\n// github stuff\nifdef::env-github[:github:]\n\n\nifndef::github[]\n// local logo\nimage::docs/logos/main.svg[Malboxes Logo]\nendif::[]\n\n\nifdef::github[]\n// logo on github\nimage::https://raw.githubusercontent.com/GoSecure/malboxes/master/docs/logos/main.svg?sanitize=true[Malboxes Logo]\n\n.*Project health*\n// Travis Build Status\nimage:https://img.shields.io/travis/GoSecure/malboxes/master.svg[Build Status (Travis CI), link=https://travis-ci.org/GoSecure/malboxes]\n// BlackHat Arsenal 2017\nimage:https://raw.githubusercontent.com/toolswatch/badges/master/arsenal/usa/2017.svg?sanitize=true[Black Hat Arsenal, link=https://www.toolswatch.org/2017/06/the-black-hat-arsenal-usa-2017-phenomenal-line-up-announced/]\n// Gitter Chat\nimage:https://badges.gitter.im/malboxes_/Lobby.svg[link=\"https://gitter.im/malboxes_/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\"]\nendif::[]\n\n\nBuilds malware analysis Windows virtual machines so that you don't have to.\n\nhttps://github.com/gosecure/malboxes\n\n\n== Requirements\n\n* Python 3.3+\n* https://www.packer.io/docs/install/index.html[Packer]\n* vagrant: https://www.vagrantup.com/downloads.html\n* https://www.virtualbox.org/wiki/Downloads[VirtualBox] or an vSphere / ESXi server\n\n\n=== Minimum specs for the build machine\n\n* At least 5 GB of RAM\n* VT-X extensions strongly recommended\n\n=== Fedora\n\n    dnf install ruby-devel gcc-c++ zlib-devel\n    vagrant plugin install winrm winrm-fs\n\n=== Debian\n\n    apt install vagrant git python3-pip\n    \n=== Ubuntu\n\n    apt install git python3-pip\n\n=== ArchLinux\n\n    pacman -Sy vagrant packer python-pip git\n\n== Installation\n\n=== Linux/Unix\n\n* Install git and packer using your distribution's packaging tool\n  (packer is sometimes called packer-io)\n* Install vagrant from their website : https://www.vagrantup.com/downloads.html (Installing from some distributions' packaging tools have caused issues). \n* `pip install` malboxes:\n+\n    sudo pip3 install git+https://github.com/GoSecure/malboxes.git#egg=malboxes\n\n=== Windows\n\nNOTE: Starting with Windows 10 Hyper-V is always running below the operating\nsystem. Since VT-X needs to be operated exclusively by only one Hypervisor\nhttps://github.com/GoSecure/malboxes/issues/39[this causes VirtualBox (and\nmalboxes) to fail]. To disable Hyper-V and allow\nVirtualBox to run, issue the following command in an administrative command\nprompt then reboot: `bcdedit /set hypervisorlaunchtype off`\n\n==== Using Chocolatey\n\nThe following steps assume that you have https://chocolatey.org/[Chocolatey]\ninstalled. Otherwise, follow the \u003c\u003cManually,manual installation procedure\u003e\u003e.\n\n* Install dependencies:\n+\n    choco install python vagrant packer git virtualbox\n+\n* Refresh the console\n+\n    refreshenv\n+\n* Install malboxes:\n+\n    pip3 install setuptools\n    pip3 install -U git+https://github.com/GoSecure/malboxes.git#egg=malboxes\n\n==== Manually\n\n* Install https://www.virtualbox.org/wiki/Downloads[VirtualBox],\n  https://www.vagrantup.com/downloads.html[Vagrant] and\n  https://git-scm.com/downloads[git]\n* https://www.packer.io/downloads.html[Install Packer], drop the packer binary\n  in a folder in your user's PATH like `C:\\Windows\\System32\\`\n* https://www.python.org/downloads/[Install Python 3] (make sure to add\n  Python to your environment variables)\n* Open a console (Windows-Key + cmd)\n+\n    pip3 install setuptools\n    pip3 install -U git+https://github.com/GoSecure/malboxes.git#egg=malboxes\n\n=== To deploy on AWS (optional)\nRun this command after normal installation:\n    \n    vagrant plugin install vagrant-aws\n\nNOTE: The AWS feature has only been tested on Linux for the moment and EC2 does not support 32-bit desktop version of Windows 10.\n\n== Usage\n\n=== Box creation\n\nThis creates your base box that is imported in Vagrant. Afterwards you can\nre-use the same box several times per sample analysis.\n\nRun:\n\n    malboxes build \u003ctemplate\u003e\n\nYou can also list all supported templates with:\n\n    malboxes list\n\nThis will build a Vagrant box ready for malware investigation you can now\ninclude it in a Vagrantfile afterwards.\n\nFor example:\n\n    malboxes build win10_x64_analyst\n\n\u003c\u003c_configuration,The configuration section\u003e\u003e contains further information about\nwhat can be configured with malboxes.\n\n\n=== Per analysis instances\n\n    malboxes spin win10_x64_analyst \u003cname\u003e\n\nThis will create a `Vagrantfile` prepared to use for malware analysis. Move it\ninto a directory of your choice and issue:\n\n    vagrant up\n\nBy default the local directory will be shared in the VM on the Desktop. This\ncan be changed by commenting the relevant part of the `Vagrantfile`.\n\nFor example:\n\n    malboxes spin win7_x86_analyst 20160519.cryptolocker.xyz\n\n=== To deploy on AWS (optional)\n\nMalboxes can upload and interact with a VM on the Amazon Web serivces. To do so, follow these steps:\n\n. Malboxes will need a S3 bucket on AWS to upload the VM before converting it to an AMI (Amazon Machine Image). If you don't have one, \nlink:https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html[create one now.]\n\n. Your instance also requires a link:https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#CreatingSecurityGroups[security group] with at least a rule allowing inbound connections for WinRM (Type: WinRM-HTTP, Protocol: TCP, Port Range: 5985, Source: host's public IP).\n\n. Next, you need a `vmimport` service role configured.\n  Follow the section named _VM Import Service Role_ of https://docs.aws.amazon.com/vm-import/latest/userguide/vmimport-image-import.html[this guide].\n  These steps must be performed with an account that has `iam:CreateRole` and `iam:PutRolePolicy` permissions.\n\n. If the \u003c\u003c_configuration,default config\u003e\u003e is used, change the hypervisor to aws and fill the mandatory options related. Otherwise, be sure to add all the options about AWS to your custom config.\n\n. Finally, you can follow the same steps described in the \u003c\u003cBox creation\u003e\u003e and the \u003c\u003cPer analysis instances\u003e\u003e sections to launch your instance!\n\nNOTE: The AMI import can take a very long time (about an hour), however you can verify the status of the task by doing \u003c\u003cAMI import status, this\u003e\u003e. At the moment, only one AMI can be build per template.\n\n==== AMI import status\nInstall awscli using pip:\n\n    pip install awscli\n\nlink:https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#cli-quick-configuration[Configure] awscli with:\n\n    aws configure\n\nThen run:\n\n    aws ec2 describe-import-image-tasks \n\n==== RDP\n\nTo connect to an instance on the cloud using RDP, run this command at the same location of your `Vagrantfile`: \n\n    vagrant rdp -- /cert-ignore\n\nFor this to work, the instance will require a security group allowing RDP inbound connections (Type: RDP, Protocol: TCP, Port Range: 3389, Source: host's public IP).\n\nNOTE: You can safely ignore the following error because rsync is not yet implemented: `No host IP was given to the Vagrant core NFS helper. This is an internal error that should be reported as a bug.` \n\n\n==== Stopping an Instance\n\nTo stop an instance on the cloud, run this command at the same location of your `Vagrantfile`:\n\n    vagrant halt\n\n== Configuration\n\nMalboxes' configuration is located in a directory that follows usual operating\nsystem conventions:\n\n* Linux/Unix: `~/.config/malboxes/`\n* Mac OS X: `~/Library/Application Support/malboxes/`\n* Win 7+: `C:\\Users\\\u003cusername\u003e\\AppData\\Local\\malboxes\\malboxes\\`\n\nThe file is named `config.js` and is copied from an example file on first run.\nlink:malboxes/config-example.js[The example configuration] is documented.\n\n=== ESXi / vSphere support\n\nMalboxes uses virtualbox as a back-end by default but since version 0.3.0\nsupport for ESXi / vSphere has been added. Notes about the\nlink:docs/esx-setup.adoc[steps required for ESXi / vSphere support are\navailable]. Since everyone's setup is a little bit different do not hesitate\nto open an issue if you encounter a problem or improve our documentation via a\npull request.\n\n=== Profiles\n\nWe are exploring with the concept of _profiles_ which are stored separately\nthan the configuration and can be used to create files, alter the registry or\ninstall additional packages. See\nlink:malboxes/profile-example.js[profile-example.js] for an example\nconfiguration. This new capacity is experimental and subject to change as we\nexperiment with it.\n\n=== AWS security groups\n\nCurrently, Malboxes does not support the automatic creation of the security groups, so you'll have to use the AWS console to create yours. However, using the library link:https://boto3.amazonaws.com/v1/documentation/api/latest/index.html[Boto3] there should be a way to implement this.\n\n== More information\n\n=== Videos\n\nIntroduction video\n\nimage::https://img.youtube.com/vi/oq6N3WLAoe8/0.jpg[link=\"https://www.youtube.com/watch?v=oq6N3WLAoe8\"]\n\n=== Blog posts\n\n* Introductory blog post:\n  http://gosecure.net/2017/02/16/introducing-malboxes-a-tool-to-build-malware-analysis-virtual-machines/\n\n=== Presentations\n\nmalboxes was presented at\nhttps://www.nsec.io/2016/01/applying-devops-principles-for-better-malware-analysis/[NorthSec\n2016] in a talk titled _Applying DevOps Principles for Better Malware Analysis_\ngiven by link:{twob}[Olivier Bilodeau] and link:{twhg}[Hugo Genesse]\n\n* http://gosecure.github.io/presentations/2016-05-19_northsec/malboxes.html[Slides]\n  (HTML, best)\n* http://gosecure.github.io/presentations/2016-05-19_northsec/OlivierBilodeau_HugoGenesse-Malboxes.pdf[Slides]\n  (PDF, degraded)\n* https://www.youtube.com/watch?v=rfmUcYGGrls\u0026list=PLuUtcRxSUZUpg-z0MkDrFrwMiiFMVr1yI[Video]\n\n\n== License\n\nCode is licensed under the GPLv3+, see `LICENSE` for details. Documentation\nand presentation material is licensed under the Creative Commons\nAttribution-ShareAlike 4.0, see `docs/LICENSE` for details.\n\n\n== Credits\n\nAfter I had the idea for an improved malware analyst workflow based on what\nI've been using for development on Linux servers (Vagrant) I quickly Googled\nif someone was already doing something in that regard.\n\nI found the https://github.com/m-dwyer/packer-malware[packer-malware] repo on\ngithub by Mark Andrew Dwyer. Malboxes was boostrapped thanks to his work which\nhelped me especially around the areas of `Autounattend.xml` files.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoSecure%2Fmalboxes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGoSecure%2Fmalboxes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoSecure%2Fmalboxes/lists"}