Now that REVEN-Axion is installed on your server, it is time to customize its configuration, and more importantly to setup your own virtual machines.
Please read the entire configuration guide carefully, almost every step is mandatory.
REVEN's options are located in two configurations files:
To setup new virtual machines, you will have to create and configure them in VirtualBox first, following the recommendations below. Then you must create a snapshot for each of them. Finally, you'll tell REVEN which virtual machine it can use.
This section describes how to setup a virtual machine that will be suitable for scenario generation.
The REVEN virtual machine provider is based on VirtualBox, you can check if it is available on the REVEN server by issuing the following command:
apt-cache show reven-virtualbox
If no package is found, check your installation.
Virtual machine creation within VirtualBox is well documented (see http://virtualbox.org/manual/ch01.html) and it's exactly the same as with REVEN VirtualBox.
Note that while REVEN will help you connect to existing VM later on when creating scenarios, VM creation works only on the server side: nothing is provided by REVEN-Axion to help users create new VM from a distant machine. The easiest way to do so would be to connect via SSH to the server and forward X11 via the command ssh -Y
:
ssh -Y tetrane@REVEN.server.host <you are asked for a password> sux <you are asked for the root password> sux reven virtualbox
If sux isn't available, you should install it on the REVEN server (make sure you have enabled the contrib
debian repository):
apt-get install sux
Check the ssh man pages for further information.
Once a virtual machine is created, it needs a couple of modifications to be used for scenario generation.
You must add an IDE adapter called reven
to the vm configuration with a CD-ROM as primary master device.
This can be done through the Storage
section of virtual machine settings.
REVEN will try to restore the latest snapshot of the virtual machine when creating a scenario. This allows to keep a clean virtual machine state even after multiple scenario generations. Snapshots can be saved (whether the virtual machine is running or not) thought the Machine
menu or with the default shortcut HostKey+T
.
It is mandatory to create a snapshot. It is advised to do so when the virtual machine is in a convenient state (eg: unlocked desktop, etc.)
As REVEN will record the entire system execution, the user must disable any non essential system feature in order to reduce trace garbage and scenario size for faster analysis.
Some optimisation include:
GRUB_TERMINAL=console
in /etc/default/grub
)Reducing virtual machine RAM allows to reduce disk footprint, but this has no impact on analysis speed.
To avoid the need to manually launch the program inside the virtual machine (through VNC), the user can setup the guest os to automatically start the loaders when a disk is inserted:
Windows has an CD-ROM autorun feature wich simply needs to be enabled.
On Gnu/Linux systems, users need to add an entry into the /etc/fstab
file and launch a wait_cdrom.sh
script wich will try to automatically run the loader once a cdrom is inserted.
The fstab entry could be:
/dev/sr0 /media/cdrom0 udf,iso9660 user,noauto,exec 0 0
The wait_cdrom.sh script could be:
#! /bin/bash MOUNT_PATH=/media/cdrom0 while ! mount ${MOUNT_PATH} &> /dev/null do sleep 0.3 done echo "If the execution doesn't end, please run ${MOUNT_PATH}/stop_vm_x86 to end the scenario.". if [ -f ${MOUNT_PATH}/interactive ] then echo "You can type source ${MOUNT_PATH}/dump-core.sh to execute the core dump.". else source ${MOUNT_PATH}/dump-core.sh fi
The build.rc
file (by default located in /usr/share/reven
) stores the generic global configuration options of REVEN. The following options are available:
Option | Description |
---|---|
reven_default_config_path | The path of the default configuration. |
reven_user_config_path | The path of the user configuration. |
projects_path | The path of the REVEN project data |
Warning: It is not recommended to modify the files in /usr/share/reven
, as those files will be restored when REVEN is upgraded. Instead, you should override these options in your user configuration file (below).
The user configuration file location is defined in the build configuration file above. It is where you can customize and setup REVEN behavior. Options that are set in this file will override those located in the build configuration file.
You must edit your own user configuration file in order to setup virtual machines. Otherwise, you will not be able to generate scenarios. After changing these parameters, you will have to restart REVEN if you want the changes to be applied.
Here are the options you can set:
Within the [limits]
section you can set memory usage limits for REVEN processes. It is not recommended to change these unless you know exactly what you are doing.
The folowing options are available:
Option | Description |
---|---|
stack_limit | Maximum size of the stack for a REVEN process, in Mbytes |
heap_limit | Maximum size of the heap for a REVEN process, in Mbytes |
Within the [vbox]
section you can set wich virtual machines can be used for scenario generation.
Only one option is available:
Options | Description |
---|---|
vms | A comma separated list of virtual machines names to register in REVEN |
Each Virtual machine options are registered within their own arbitrary section, they specify scenario generation options.
Example for a section with a vbox_name
option set to vmdebian:
Option | Description |
---|---|
os | The operating system type. Can be 'windows' or 'linux' |
vbox_name | Optional. Name of the virtual machine on VirtualBox. If not set, the section name is used. |
display | The name displayed in the Axion client |
preloaders | Optional. A list of files deployed in the guest os, must includes loaders. See the example configuration below |
dynamic_launch | Optional. The dynamic executable loader. See the example configuration below |
static_launch | Optional. The static executable loader. See the example configuration below |
stopper | Optional. The program used to kill the vm from the guest os. See the example configuration below |
segment | The value of the userland code segement (cs) value |
vnc_password | Optional. The password used by the VirtualBox vnc server. Default is randomly generated and displayed in the scenario generation ui |
vnc_port | Optional. The port of the vnc server. In order to use multiple virtual machines at the same time, use different vnc ports. Default is 5900 |
pdb_path | Optional. The path used for importing windows symbols file, see MS Windows symbols. Default is none |
preloaders
, dynamic_launch
and static_launch
options are needed for automatic scenario generation. If they are not specified, the user will have to generate the scenario manually with VirtualBox key bindings.
Changes to the pdb_path
option will not be reflected on projects that have already been created. Check the project's input
directory content if you need to change this option.
[limits] stack_limit = 1024 heap_limit = 8096 [vbox] vms = debian_stable, windows_8 [debian_stable] os = linux vbox_name = vmdebian display = Debian wheezy preloaders = libpreload_x86.so, linux_static_loader_x86, dump_processes_x86 dynamic_launch = LD_PRELOAD=./libpreload_x86.so static_launch = ./linux_static_loader_x86 segment = 0x73 stopper = stop_vm_x86 vnc_port = 5900 vnc_password = passw0rd [windows_8] os = windows vbox_name = vmwin8 display = Windows 8 preloaders = loader.exe, dump_processes.exe dynamic_launch = loader.exe static_launch = loader.exe segment = 0x1b stopper = stop_vm.exe vnc_port = 5901 vnc_password = passw0rd pdb_path = /home/tetrane/pdb/windows8
This example describes two virtual machines, named vmdebian and vmwin8. Note that those virtual machines must have been previously created in VirtualBox, with those exact names.
REVEN can leverage Windows debugging symbols available as pdb files to enhance the execution trace readability. These files must be converted in our specific format first though: you can do so with the shipped pdb_dump
utility. You will also have to setup the windows virtual machines pdb_path
option in your user configuration file accordingly.
The pdb_dump utility take two arguments:
Argument | Description |
---|---|
pdb_directory | A directory containing MS Windows Pdb symbol files |
output_directory | A directory used to store REVEN symbol file, for instance same as pdb_path |
Most of the OS pdb files can be retrieved on the Microsoft website (MSDN pages) as a Windows Symbol Package.
REVEN can also use an API documentation xml file in order to provide advanced information such as parameter types, names and calling convention. This xml file can be generated by extracting and parsing the MS Windows help files:
In order to have a local copy of the MSDN documentation, download the Visual Studio SDK installer from the Microsoft website (tested with the SDK for Windows 7 and .NET 3.5 SP1
) and install the documentation packages.
Now you need to extract the HxS files, which can be done with an archive extractor like 7zip
:
On MS Windows, to extract the HxS files located in C:\Program Files\Microsoft SDKs\Windows\v7.0\Help\1033
(the default installation path) to the C:\extracted_hxs_files
directory, execute the following command:
cd "C:\extracted_hxs_files" FOR "C:\Program Files\Microsoft SDKs\Windows\v7.0\Help\1033" %I IN (*.hxs) DO "C:\Program Files\7zip\7z.exe" x "%I" -aou
Alternatively, on a Linux system, to extract the HxS files located in ~/hxs_files
into ~/extracted_hxs_files
, execute the following commmand:
cd ~/extracted_hxs_files for FILE in ~/hxs_files/*.hxs; do 7z x $FILE -aou; done
Once the HxS files have been extracted, the final xml file can be generated with the msdn-crawler.py
script shipped with REVEN (located in /usr/share/reven/scripts/
)
On MS Windows (supposing you copied the crawler script from an Axion installation)
C:\python27\python.exe msdn-crawler.py C:\extracted_hxs_files
On Linux
python /usr/share/reven/msdn-crawler.py ~/extracted_hxs_files
Finally, copy the generated msdn.xml
into the pdb_path
directory (see the virtual machine setup).
REVEN is designed to be used by multiple users simultaneously. By default, REVEN's installation creates a unique user named reven
.
Managing the available users is done directly on the server system by adding or removing subdirectories in the REVEN project data folder specified in the build.rc file.
For example, adding a new user named foo
with a project data folder setted to /home/reven/reven_data
can be done through the following commands:
mkdir /home/reven/reven_data/foo chown reven:reven /home/reven/reven_data/foo