gosecure/malboxesBuilds malware analysis Windows VMs so that you don't have to.
= Malboxes :toc: preamble :toclevels: 2 :twob: https://twitter.com/obilodeau :twhg: https://twitter.com/hugospns // github stuff ifdef::env-github[:github:]
ifndef::github[] // local logo image::docs/logos/main.svg[Malboxes Logo] endif::[]
ifdef::github[] // logo on github image::https://raw.githubusercontent.com/GoSecure/malboxes/master/docs/logos/main.svg?sanitize=true[Malboxes Logo]
.Project health // Travis Build Status image:https://img.shields.io/travis/GoSecure/malboxes/master.svg[Build Status (Travis CI), link=https://travis-ci.org/GoSecure/malboxes] // BlackHat Arsenal 2017 image: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/] // Gitter Chat image:https://badges.gitter.im/malboxes_/Lobby.svg[link="https://gitter.im/malboxes_/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"] endif::[]
Builds malware analysis Windows virtual machines so that you don't have to.
https://github.com/gosecure/malboxes
== Requirements
=== Minimum specs for the build machine
=== Fedora
dnf install ruby-devel gcc-c++ zlib-devel
vagrant plugin install winrm winrm-fs
=== Debian
apt install vagrant git python3-pip
=== Ubuntu
apt install git python3-pip
=== ArchLinux
pacman -Sy vagrant packer python-pip git
== Installation
=== Linux/Unix
pip install malboxes:=== Windows
NOTE: Starting with Windows 10 Hyper-V is always running below the operating
system. Since VT-X needs to be operated exclusively by only one Hypervisor
https://github.com/GoSecure/malboxes/issues/39[this causes VirtualBox (and
malboxes) to fail]. To disable Hyper-V and allow
VirtualBox to run, issue the following command in an administrative command
prompt then reboot: bcdedit /set hypervisorlaunchtype off
==== Using Chocolatey
The following steps assume that you have https://chocolatey.org/[Chocolatey] installed. Otherwise, follow the <<Manually,manual installation procedure>>.
==== Manually
C:\Windows\System32\=== To deploy on AWS (optional) Run this command after normal installation:
vagrant plugin install vagrant-aws
NOTE: The AWS feature has only been tested on Linux for the moment and EC2 does not support 32-bit desktop version of Windows 10.
== Usage
=== Box creation
This creates your base box that is imported in Vagrant. Afterwards you can re-use the same box several times per sample analysis.
Run:
malboxes build <template>
You can also list all supported templates with:
malboxes list
This will build a Vagrant box ready for malware investigation you can now include it in a Vagrantfile afterwards.
For example:
malboxes build win10_x64_analyst
<<_configuration,The configuration section>> contains further information about what can be configured with malboxes.
=== Per analysis instances
malboxes spin win10_x64_analyst <name>
This will create a Vagrantfile prepared to use for malware analysis. Move it
into a directory of your choice and issue:
vagrant up
By default the local directory will be shared in the VM on the Desktop. This
can be changed by commenting the relevant part of the Vagrantfile.
For example:
malboxes spin win7_x86_analyst 20160519.cryptolocker.xyz
=== To deploy on AWS (optional)
Malboxes can upload and interact with a VM on the Amazon Web serivces. To do so, follow these steps:
. 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, link:https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html[create one now.]
. 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).
. Next, you need a vmimport service role configured.
Follow the section named VM Import Service Role of https://docs.aws.amazon.com/vm-import/latest/userguide/vmimport-image-import.html[this guide].
These steps must be performed with an account that has iam:CreateRole and iam:PutRolePolicy permissions.
. If the <<_configuration,default config>> 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.
. Finally, you can follow the same steps described in the <> and the <> sections to launch your instance!
NOTE: The AMI import can take a very long time (about an hour), however you can verify the status of the task by doing <<AMI import status, this>>. At the moment, only one AMI can be build per template.
==== AMI import status Install awscli using pip:
pip install awscli
link:https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#cli-quick-configuration[Configure] awscli with:
aws configure
Then run:
aws ec2 describe-import-image-tasks
==== RDP
To connect to an instance on the cloud using RDP, run this command at the same location of your Vagrantfile:
vagrant rdp -- /cert-ignore
For 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).
NOTE: 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.
==== Stopping an Instance
To stop an instance on the cloud, run this command at the same location of your Vagrantfile:
vagrant halt
== Configuration
Malboxes' configuration is located in a directory that follows usual operating system conventions:
~/.config/malboxes/~/Library/Application Support/malboxes/C:\Users\<username>\AppData\Local\malboxes\malboxes\The file is named config.js and is copied from an example file on first run.
link:malboxes/config-example.js[The example configuration] is documented.
=== ESXi / vSphere support