= 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:sudo pip3 install git+https://github.com/GoSecure/malboxes.git#egg=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>>.
choco install python vagrant packer git virtualbox
refreshenv
pip3 install setuptools pip3 install -U git+https://github.com/GoSecure/malboxes.git#egg=malboxes
==== Manually
C:\Windows\System32\
pip3 install setuptools pip3 install -U git+https://github.com/GoSecure/malboxes.git#egg=malboxes
=== 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 <
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
Malboxes uses virtualbox as a back-end by default but since version 0.3.0 support for ESXi / vSphere has been added. Notes about the link:docs/esx-setup.adoc[steps required for ESXi / vSphere support are available]. Since everyone's setup is a little bit different do not hesitate to open an issue if you encounter a problem or improve our documentation via a pull request.
=== Profiles
We are exploring with the concept of profiles which are stored separately than the configuration and can be used to create files, alter the registry or install additional packages. See link:malboxes/profile-example.js[profile-example.js] for an example configuration. This new capacity is experimental and subject to change as we experiment with it.
=== AWS security groups
Currently, 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.
== More information
=== Videos
Introduction video
image::https://img.youtube.com/vi/oq6N3WLAoe8/0.jpg[link="https://www.youtube.com/watch?v=oq6N3WLAoe8"]
=== Blog posts
=== Presentations
malboxes was presented at https://www.nsec.io/2016/01/applying-devops-principles-for-better-malware-analysis/[NorthSec 2016] in a talk titled Applying DevOps Principles for Better Malware Analysis given by link:{twob}[Olivier Bilodeau] and link:{twhg}[Hugo Genesse]
== License
Code is licensed under the GPLv3+, see LICENSE
for details. Documentation
and presentation material is licensed under the Creative Commons
Attribution-ShareAlike 4.0, see docs/LICENSE
for details.
== Credits
After I had the idea for an improved malware analyst workflow based on what I've been using for development on Linux servers (Vagrant) I quickly Googled if someone was already doing something in that regard.
I found the https://github.com/m-dwyer/packer-malware[packer-malware] repo on
github by Mark Andrew Dwyer. Malboxes was boostrapped thanks to his work which
helped me especially around the areas of Autounattend.xml
files.