Guest Configuration for Linux

This page will detail how to properly configure a Linux guest for recording with REVEN.

IMPORTANT: We strongly recommend you start with one of the VMs available on tetrane's website. These are already properly configured and tested.

Guest system requirements

REVEN requires Linux guests to be running a compatible kernel: Linux 64-bit, versions 4.1 to 4.18.0 included.

  • Tested distributions:
    • Fedora 27 (kernel version 4.13)
    • OpenSUSE 15.1 (kernel version 4.12.14)
    • Debian 9 (kernel version 4.9)
    • Ubuntu 16.04 (kernel version 4.13)
    • CentOS 8 (kernel version 4.18.0)
  • Other untested distributions in the compatibility range:
    • OpenSUSE 15.0 (kernel version 4.12)
    • Ubuntu 17.10 (kernel version 4.13)
    • NixOS up to 18.09 (kernel version 4.14)
    • ...

NOTE: each distribution and version can have its own peculiarity, and require further configuration not descibed in this guide. Moreover, there could be specific set of patches that hinders the OSSI retrieval. Again, we recommend starting with a VM available on tetrane's website. Finally, you can contact the support if you cannot get OSSI when using a distribution from the list above.

Enabling the OSSI feature

In order to ensure the OS-Specific Information (OSSI) work on recorded scenario, you must:

  • Disable KASLR and PTI protections,
  • Install the kernel headers in the guest.

Disabling KASLR and PTI

You need to add the nopti and nokaslr options to your kernel command line. On most systems, the following procedure should work almost as-is:

  1. Edit the file /etc/default/grub.
  2. Find the variable GRUB_CMDLINE_LINUX_DEFAULT.
  3. Add the nopti and nokaslr options, making the line look like this: GRUB_CMDLINE_LINUX_DEFAULT="[...] nopti nokaslr"
  4. Regenerate your grub configuration:
    1. update-grub for Debian
    2. grub2-mkconfig -o /etc/grub2.cfg for CentOS
    3. Other distributions should work in a similar way.
  5. Reboot.
  6. Verify that you have the options present in /proc/cmdline.

Installing the kernel headers

For Debian-like distributions, this should be done with a command similar to this one: sudo apt install linux-headers-$(uname -r)

For RedHat-based distributions, the command is more like the following: sudo dnf install kernel-devel kernel-headers

Maximizing the symbol coverage

NOTE: 32-bit binaries are currently not supported by the OSSI feature for Linux.

You should install as many debug symbols on the guest as possible.

By default, symbols are searched within the binaries executed in a scenario. These production binaries usually contain very few symbols.

Most distributions provide a mechanism to download debug symbol packages, which the debuggers can then use to display more context to the user. REVEN can leverage those as well completely transparently, as long as you "prepare" the snapshot after installing them (see What preparing a snapshot is).

The process of recovering debug symbol packages will vary for each distribution, but here are a few pointers to get you started:

Debian-like distributions

You can follow the steps below:

  1. Install apt-file and grep-aptavail. 
    apt install apt-file dctrl-tools
  2. Add the debug package sources to your /etc/apt/sources.list. For debian: 
    deb http://deb.debian.org/debian-debug/ <your_release>-debug main
    where <your_release> is the codename of the target release of Debian (e.g. stretch, buster, bullseye)
  3. Update your apt and apt-file: 
    apt update
apt-file update
  4. Look for all the binaries on your system: 
    # https://unix.stackexchange.com/questions/40063/how-to-find-executable-filetypes/448075#448075
find /path -type f -exec sh -c "file {} | grep -Pi ': elf (32|64)-bit' > /dev/null" \; -print
  5. For Debian Buster and newer, you can use find-dbgsym-packages from the debian-goodies package on your binary: 
    find-dbgsym-packages <binary>
    And you're done!
  6. For other distributions, for each binary, look for its build id and debug link: 
    readelf -n <binary> | grep "Build ID"
readelf -p.gnu_debuglink
  7. If you have a build ID, you can use it with grep-aptavail to recover the debug package: 
    grep-aptavail --no-field-names --show-field Package --field Build-IDs <build_id>
    And you're done!
  8. Without a build ID, you can build debug paths for your binary from the debug link, and pass it to apt-file: 
    apt-file search "/usr/lib/debug/<binary_parent_dir>/<debug_link>"
apt-file search "<binary_parent_dir>/<debug_link>"
apt-file search "<binary_parent_dir>/.debug/<debug_link>"
    And you're done!

Once you recovered the debug package names, you can then install them using apt install.

More resources:

Fedora

You can use sudo dnf debuginfo-install <packagename> for all installed packages to get their debug counterparts.

More information:

Optimizing the guest for analysis

Linux system usually display far less background activity than a default Windows 10 installation, so there is no mandatory step in that regard.

Nevertheless, there are steps you can take to make the VM lighter still:

  1. If you don't need a GUI:
    1. Disable Xorg server when not needed,
    2. Disable the console framebuffer if not needed. For example, on Debian systems, in file /etc/default/grub, add the line: 
      GRUB_TERMINAL=console
  2. Install a light Desktop Manager, such as Xfce,
  3. Disable any unwanted background service.

Final touches

Finally, here are more general recommendations to make the experience better.

  1. Since REVEN supports a narrow set of kernel versions, you should inhibit kernel updates:
    1. On Fedora: add exclude=kernel* to /etc/dnf/dnf.conf
    2. On Ubuntu: run something akin to echo linux-image-xxx hold | dpkg --set-selections
  2. Don't forget to install your favorite tools: gcc, htop, etc.
©2019-2021 Tetrane