ForGeOSI is a wrapper for pyvbox, designed to be used in the education in computer forensics. It simplifies the creation of virtual machines and their automation, while providing a log and reasonable abstraction. The automation of guest systems supports modern Windows Versions with Powershell 2 or newer, while any modern Linux system should be supported in theory, only Ubuntu 12.04 and Ubuntu 13.10 are tested though.
##Requirements As host, a Linux system with VirtualBox 4.3 and the VirtualBox API is expected, Python 2.7 is required, while my software in theory should support Python 3 as well, vboxapi has some hiccups, so it is not advised. Further more, the following Python packets are required:
The Guest systems should be prepared with Guest Additions installed, further hints are given in the docstring documentation, standalone documentation can be generated with
you can either clone this repository, or install it using
pip install forgeosi.
##First Steps Lets start a virtual machine, without cloning it
>ipython In : import forgeosi In : print forgeosi.VboxInfo().list_vms() ubuntu-lts-base xubuntu-lts-base windows-8-base In : vbox = forgeosi.Vbox(mode=forgeosi.VboxMode.use, basename='ubuntu-lts-base') In : vbox.start(session_type=forgeosi.SessionType.gui) In : vbox.stop()
Generate input, open webbrowser, send keyboard shortcut, get log
In : import forgeosi In : vbox = forgeosi.Vbox(mode=forgeosi.VboxMode.use, basename='ubuntu-lts-base') In : vbox.start(session_type=forgeosi.SessionType.gui) #top secret password In : vbox.keyboard_input('12345\n') #needed to access os-specific and Guest Additions functionality In : vbox.create_guest_session() In : vbox.os.open_browser('github.com') In : vbox.keyboard_combination(['alt','f4']) In : vbox.stop() In : print vbox.log.get_pretty_log() LogVM: osType: Ubuntu_64 basename: ubuntu-lts-base vmname: testvm LogRawKeyboard: time_rate: 100 keyboard input: 12345\n up_time: 0 time: 1395224126.58 real_time: 1395224126.58 LogProcess: up_time: 0 stdout: process: <virtualbox.library.IGuestProcess object at 0x2a95d90> time_rate: 100 pid: 1843 key_input: path: /bin/bash stdin: arguments: [\'-c\', \'/usr/bin/firefox -new-tab github.com\'] stderr: time: 1395224228.1 real_time: 1395224228.1 LogRawKeyboard: time_rate: 100 keyboard input: makecode: alt up_time: 0 time: 1395224237.56 real_time: 1395224237.56 LogRawKeyboard: time_rate: 100 keyboard input: makecode: f4 up_time: 0 time: 1395224237.56 real_time: 1395224237.56 LogRawKeyboard: time_rate: 100 keyboard input: breakcode: alt up_time: 0 time: 1395224237.56 real_time: 1395224237.56 LogRawKeyboard: time_rate: 100 keyboard input: breakcode: f4 up_time: 0 time: 1395224237.56 real_time: 1395224237.56
Export virtual machine
In : import forgeosi In : vbox = forgeosi.Vbox(mode=forgeosi.VboxMode.us, basename='ubuntu-lts-base') In : vbox.export(path='/tmp/image.vdi')
##Hacking The basic architecture:
- VboxInfo Helper to get info about the VirtualBox instance
- VboxConfig Helper to configure the NAT Network feature
- Vbox Main class containing everything generic to manage virtual machines
- lib/logger.py Logger to provide a protocol of all actions
- lib/oslinux.py Linux guest specific code
- lib/oswindow.py Windows guest specific code
- lib/param.py Types for typesave parameters
Feel free to extend, I will accept pull requests on a reasonable base, especially additions to support a wider range of guest systems are welcome.
##Testing There are testcases to be found test/, but they are not portable and will need fixing to run on other systems. The tests further depend of following tools:
- Python 3
- The Sleuth Kit ver 4.1 or higher, including fiwalk
###Issues Please report issues on github
###Known bugs and limitations
- Python 3 compatibility needs to be tested
- raw-disk-export in the python API is broken, I'm using vboxmanage instead
- Running programs in Windows guests with '-' in arguments, breaks things, be careful with that.
- limited support for Windows hosts