EmuBox uses the Flask python microframework as the web server gateway interface (WSGI) application. This provides similar functionality as a fast common gateway interface (FCGI) application that allows multiple, concurrent connections to the web application.
Gevent is used to host the standalone flask WSGI container. This handles the concurrent WSGI behavior. It uses greenlet to provide high-level synchronous API on top of libev event loop.
EmuBox is composed of two main components: The Workshop Creator and the Workshop Manager.
EmuBox has been tested on:
- Windows 7+ (32 and 64-bit), Windows Server 2012 (64-bit)
- Ubuntu 16.04 LTE (64-bit)
You must install the following manually:
- Python 2.x (tested with v2.7)
- VirtualBox > 5.0 and matching VirtualBox API and Extensions Pack (tested with v5.1.10)
These are automatically installed with the included install script
- VirtualEnv v15.1.0
- LXML v4.0.0
- Flask v0.12
- PyGI based on this Windows Installer
In the directory where you extracted EmuBox:
cd workshop-creator
./install_win.bat
To create and run a workshop, proceed to Create and Run a Workshop.
In the directory where you extracted EmuBox:
sudo -s
cd workshop-creator
Set the following environment variables
- VBOX_INSTALL_PATH
- VBOX_SDK_PATH
- VBOX_PROGRAM_PATH
For example,
export VBOX_INSTALL_PATH=$(which virtualbox)
export VBOX_SDK_PATH=`pwd`/bin/VirtualBoxSDK-5.1.20-114628/sdk/
export VBOX_PROGRAM_PATH=/usr/lib/virtualbox/
Now run the installer
source ./install_linux.sh
To create and run a workshop, proceed to Create and Run a Workshop.
EmuBox runs on a flask webserver and a backend monitor for virtualbox VMs. Before starting, install Emubox as described here.
-
Ensure that you have one or more virtual machines installed and that they have at least one snapshot (only the latest is used).
Note: On Linux, you must install VMs with administrator priviledges (i.e., instantiate VirtualBox as root or using sudo), otherwise remote display and other features will not work.
-
Start the GUI by executing the following commands in a terminal:
Windows:
cd workshop-creator start_creator.batLinux:
sudo -s cd workshop-creator ./start_creator.sh -
Right-click in the Workshops pane and select "New Workshop" and then enter a workshop name.
-
Select a virtual machine from the list and click the OK button. This will add a new entry in the Workshops pane.
-
Add any additional VMs and Materials by selecting your workshop and using the context (right-click) menu.
-
Configure workshop settings on the right Panel to include the number of clones, usage of linked clones (true value is recommended), and the IP address where users will connect to access the workshop.
-
Expand the Workshop entry and select a specific VM or Material to configure settings such as VRDP, internal network names, display ports.
-
Ensure that at least one VM in your workshop has VRDP enabled.
-
Right click on your workshop and select the Create Clones option.
-
Right click on your workshop and select the Start VMs option.
-
Click on the Manager tab and toggle the Manager switch to ON.
-
Open a browser and navigate to the following URL:
http://localhost:8080
If accessing the EmuBox server from the network (e.g., when hosting workshops for participants), from the remote machine's browser, substitute localhost for the IP address of the machine running the server.
A live disc pre-installed with EmuBox is available here. The following are the steps for running EmuBox on the live disc.
The DHCP service is pre-configured. To enable the DHCP server execute the following steps:
- If needed, modify the following files to assign the dhcp server interface and network range (enp0s3 is the default interface):
/etc/dhcp/dhcpd.conf
/etc/default/isc-dhcp-server
- If needed, modify the following file to set a static IP address to the interface serving DHCP:
/etc/network/interfaces
- Start the dhcp service:
sudo service isc-dhcp-server start
To enable the pre-installed Ubuntu VNC server follow instructions here
To enable the SSH service execute the following steps:
- Start the ssh server
sudo service ssh start
The VPN server is pre-configured. To enable the PPTPD VPN server execute the following steps:
- If needed, change the IP addresses assigned to the server node and connected clients by modifying the following
/etc/pptpd.conf
- If needed, change the DNS entries (lines with ms-dns) by modifying IP addresses in the following file
/etc/ppp/pptpd-options
- Specify users, credentials, and IP address mappings in the following file:
/etc/ppp/chap-secrets
- Start the pptpd service:
sudo service pptpd start
- Open a terminal window and execute the following commands:
sudo -s
cd /root/emubox/workshop-creator
./start_creator.sh
To create and run a workshop, proceed to Create and Run a Workshop.
The Workshop Creator automates the creation of workshop units (sets of VMs that compose a cybersecurity scenario). This includes the cloning process. During the cloning process, this component adjusts VRDP ports and internal network adapter names so that each group is isolated and uniquely accessible by participants.
The Workshop Creator GUI provides a graphical interface to design workshop units and modify their parameters. The user can then run the Workshop Creator script via the interface, eliminating the need to set command line parameters manually.
To run the Workshop Creator GUI, first install it by following instruction below. Afterwards, open a terminal and type the following command:
Windows:
cd workshop-creator
start_creator.bat
Linux:
cd workshop-creator
./start_creator.sh
The Workshop Creator can also be used without the graphical interface by running the various scripts in the following scripts:
workshop-creator/bin/workshop-creator.py (clones VMs and groups them into Workshop Units)
workshop-creator/bin/workshop-start.py (starts (headless mode) VMs in Workshop Units)
workshop-creator/bin/workshop-rdp.py (creates Remote Desktop files for VRDP-enabled VMs in Workshop Units)
workshop-creator/bin/workshop-poweroff.py (turns off VMs in Workshop Units)
workshop-creator/bin/workshop-restore.py (restores most recent snapshot of VMs in Workshop Units - only those not in a run state)
Note: All of these scripts read a standard XML file as input (samples are provided in the workshop-creator/sample_configs folder.
The Workshop Manager component of EmuBox is a multi-threaded process that monitors VRDP connections for each workshop unit. It also contains a web service with a simple front-end that is implemented using the Flask micro web development framework. When participants navigate to the front-end they are shown the VRDP-enabled workshop units (those that are available and not currently in use). The front-end also provides participants with a unique connection string (IP address and VRDP port pair) to use in a remote desktop client, such as MS-RDP on Windows, Mac OS, iOS, and rdesktop on Linux.
When a participant connects to a a unit, it becomes unavailable and will no longer be shown in the web interface. After a participant disconnects from the unit, the system will automatically restore the associated VMs from snapshot and make it available once again.
The Workshop Manager is integrated into the workshop creator GUI, but it can also be instantiated without the graphical interface by executing the following commands:
Windows:
cd workshop-manager
start_manager.bat
Linux:
sudo -s
cd workshop-manager
./start_manager.sh
The EmuBox uses the VirtualBox API to monitor and update groups of VMs (that compose a workshop unit). Users may connect to these units using remote desktop. When a user disconnects, EmuBox will restore all VMs in a unit from the most recent snapshot.