Merge pull request #434 from ameily/xenserver

XenServer Machinery

conf/xenserver.conf

@@ -0,0 +1,64 @@
+[xenserver]
+# Specify the XenServer username for authentication.
+user = root
+
+# Specify the XenServer password for authentionication.
+password = changeme
+
+# Specify the XenServer URL. The url is the XMLRPC location of the XenServer,
+# which can be either a hostname or IP address.
+url = https://xenserver
+
+# Specify a comma-separated list of available machines to be used. For each
+# specified ID you have to define a dedicated section containing the details
+# on the respective machine. (E.g. cuckoo1,cuckoo2,cuckoo3)
+machines = cuckoo1
+
+[cuckoo1]
+# Specify the virtual machine uuid.
+uuid = 00000000-0000-0000-0000-000000000000
+
+# Specify the snapshot uuid to use. Snapshots are not required, but if they are
+# not used, the virtual machine's disks must be configured to reset on boot.
+# Resetting the disks on boot ensures that samples cannot permanently modify the
+# analysis virtual machine past a shutdown. Refer to the "Saving the Virtual
+# Machine" section in the Cuckoo documentation for details on how to enable
+# disk resetting on boot.
+# Example:
+# snapshot = 00000000-0000-0000-0000-000000000000
+
+# Specify the operating system platform used by current machine
+# [windows/darwin/linux].
+platform = windows
+
+# Specify the IP address of the current virtual machine. Make sure that the
+# IP address is valid and that the host machine is able to reach it. If not,
+# the analysis will fail.
+ip = 192.168.54.111
+
+# (Optional) Specify the name of the network interface that should be used
+# when dumping network traffic from this machine with tcpdump. If specified,
+# overrides the default interface specified in cuckoo.conf
+# Example (virbr0 is the interface name):
+# interface = virbr0
+
+# (Optional) Specify the IP of the Result Server, as your virtual machine sees it.
+# The Result Server will always bind to the address and port specified in cuckoo.conf,
+# however you could set up your virtual network to use NAT/PAT, so you can specify here 
+# the IP address for the Result Server as your machine sees it. If you don't specify an
+# address here, the machine will use the default value from cuckoo.conf.
+# NOTE: if you set this option you have to set result server IP to 0.0.0.0 in cuckoo.conf.
+# Example:
+# resultserver_ip = 192.168.122.101
+
+# (Optional) Specify the port for the Result Server, as your virtual machine sees it.
+# The Result Server will always bind to the address and port specified in cuckoo.conf,
+# however you could set up your virtual network to use NAT/PAT, so you can specify here
+# the port for the Result Server as your machine sees it. If you don't specify a port
+# here, the machine will use the default value from cuckoo.conf.
+# Example:
+# resultserver_port = 2042
+
+# (Optional) Set your own tags. These are comma separated and help to identify
+# specific VMs. You can run samples on VMs with tag you require.
+# tags = windows_xp_sp3,32_bit,acrobat_reader_6

docs/book/src/installation/guest/saving.rst

@@ -30,7 +30,7 @@ restore it::
 KVM
 ===
 
-If decided to adopt KVM, you must fist of all be sure to use a disk format for
+If decided to adopt KVM, you must first of all be sure to use a disk format for
 your virtual machines which supports snapshots.
 By default libvirt tools create RAW virtual disks, and since we need snapshots
 you'll either have to use QCOW2 or LVM. For the scope of this guide we adopt QCOW2,
@@ -96,3 +96,65 @@ Where your_snapshot_name is the name you choose for the snapshot.
 After that power off the machine from the GUI or from the command line::
 
     $ vmrun stop "/your/disk/image/path/wmware_image_name.vmx" hard
+
+XenServer
+=========
+
+If you decided to adopt XenServer, the XenServer machinery supports starting
+virtual machines from either disk or a memory snapshot. Creating and reverting
+memory snapshots require that the Xen guest tools be installed in the
+virtual machine. The recommended method of booting XenServer virtual machines is
+through memory snapshots because they can greatly reduce the boot time of
+virtual machines during analysis. If, however, the option of installing the
+guest tools is not available, the virtual machine can be configured to have its
+disks reset on boot. Resetting the disk ensures that malware samples cannot
+permanently modify the virtual machine.
+
+Memory Snapshots
+----------------
+
+The Xen guest tools can be installed from the XenCenter application that ships
+with XenServer. Once installed, restart the virtual machine and ensure that the
+Cuckoo agent is running.
+
+Snapshots can be taken through the XenCenter application and the command line
+interface on the control domain (Dom0). When creating the snapshot from
+XenCenter, ensure that the "Snapshot disk and memory" is checked. Once created,
+right-click on the snapshot and note the snapshot UUID.
+
+To snapshot from the command line interface, run the following command::
+
+    $ xe vm-checkpoint vm="vm_uuid_or_name" new-name-label="Snapshot Name/Description"
+
+The snapshot UUID is printed to the screen once the command completes.
+
+Regardless of how the snapshot was created, save the UUID in the virtual
+machine's configuration section. Once the snapshot has been created, you can
+shutdown the virtual machine.
+
+Booting from Disk
+-----------------
+
+If you can't install the Xen guest tools or if you don't need to use memory
+snapshots, you will need to ensure that the virtual machine's disks are reset on
+boot and that the Cuckoo agent is set to run at boot time.
+
+Running the agent at boot time can be configured in Windows by adding a startup
+item for the agent.
+
+The following commands must be run while the virtual machine is powered off.
+
+To set the virtual machine's disks to reset on boot, you'll first need to list
+all the attached disks for the virtual machine. To list all attached disks, run
+the following command::
+
+    $ xe vm-disk-list vm="vm_name_or_uuid"
+
+Ignoring all CD-ROM and read-only disks, run the following command for each
+remaining disk to change it's behavior to reset on boot::
+
+    $ xe vdi-param-set uuid="vdi_uuid" on-boot=reset
+
+After the disk is set to reset on boot, no permanent changes can be made to the
+virtual machine's disk. Modifications that occur while a virtual machine is
+running will not persist past shutdown.

docs/book/src/installation/host/requirements.rst

@@ -61,7 +61,7 @@ To have MAEC support, you need to first install the Cybox and then the MAEC libr
 
 *Yara* and *Pydeep* will have to be installed manually, so please refer to their websites.
 
-If want to use KVM it's packaged too and you can install it with the following command::
+If you want to use KVM it's packaged too and you can install it with the following command::
 
     $ sudo apt-get install qemu-kvm libvirt-bin ubuntu-vm-builder bridge-utils
 
@@ -79,6 +79,10 @@ If want to use KVM it's packaged too and you can install it with the following c
 .. _MAEC Python bindings: https://pypi.python.org/pypi/maec/4.0.1.0
 .. _Chardet: https://pypi.python.org/pypi/chardet
 
+If you want to use XenServer you'll have to install the *XenAPI* Python package::
+
+    $ sudo pip install XenAPI
+
 Virtualization Software
 =======================