VM Setup: Build and run Granary

So, you've set up a VM with an off-the-shelf Linux distribution, and now you want to make it so that Granary can instrument the kernel running in the VM.

Step 1: Get the kernel headers

Run the following command from within the guest VM:

sudo apt-get install linux-generic

Step 2: Copy the kernel headers out of the VM

In the guest, run the following command. This assumes that the sloth hostname has been correctly setup for SSHing from the guest (VM) into the host.

scp -r /usr/src/linux-headers-`uname -r` sloth:/tmp

When that completes, copy the headers to somewhere more permanent on the host:

mv /tmp/linux-headers-* ~/Code

Step 3: Tell Granary about your kernel headers

cd /path/to/granary
./scripts/make_linux_build_link.sh ~/Code/linux-headers-*

This will create a the dependencies/linux symbolic link to your local copy of the VM's Linux kernel headers.

Step 4: Build Granary

Get all necessary packages

Before your first compile of Granary, make sure that you have the right versions of the tools that Granary needs. Run the following commands to get those tools:

sudo apt-get install llvm libc++-src libc++1 clang-3.5 binutils

Compile Granary

make clean all GRANARY_WHERE=kernel GRANARY_KERNEL_DIR=/path/to/Granary/dependencies/linux

Step 5: Load Granary into the VM

./scripts/vmlaunch.sh
python scripts/vmload.py --remote slothvm

This step will copy the built granary.ko into the VM's /tmp directory, then try to insmod the module. If that succeeds, then it will then extract the address at which the Granary module was loaded along with the section information, and store copy that to /tmp/granary.syms on the host machine.

Step 6: Optionally attach gdb for debugging

If you want to debug Granary or your client(s), then now is a good time to attach gdb. To do so, execute the following commands:

cd /path/to/Granary
gdb

Granary's .gdbinit file has been created so that if no arguments are passed to gdb then it will try to target your VM, load vmlinux, and add the /tmp/granary.syms symbol file.

Make sure to follow the steps in listed here so that you have a proper debug setup.

Step 7: Initialize and attach Granary

Now, in the guest VM, execute the following command:

echo "init <granary options here>" > /dev/granary
echo attach > /dev/granary