README.libvmi

# ** Build/run from dom0 **

# To build:
    sudo apt install gettext bcc iasl uuid-dev libyajl-dev libpixman-1.dev gcc-multilib g++-multilib zlib1g-dev libssl-dev libtool lib32ncurses5-dev python-dev texinfo byacc flex transfig libgtk2.0-dev liblzma-dev pkg-config libglib2.0-dev libaio-dev automake libfuse-dev git ghostscript make -y
    git clone https://github.com/libvmi/libvmi.git ; cd libvmi
    ./autogen.sh
    ./configure --disable-kvm
    make install

# You now need to obtain the offsets for the guest of interest to your config file. Generally, you need to launch a guest, then run copy over the kernel module located under libvmi/tools/linux-offset-finder/ or libvmi/tools/windows-offset-finder/.
# In the case of Linux, build the the module and insmod it. The output will be in dmesg. Place that information in dom0's filesystem under /etc/libvmi.conf or $HOME/etc/libvmi.conf. For example, this is the conf file for one of the guests that is predominantly in use for this project:

ubuntu-live-basic_guest_headers_build_tools {
    ostype = "Linux";
    sysmap = "/boot/System.map-4.8.0-36-generic";
    linux_name = 0x678;
    linux_tasks = 0x3c8;
    linux_mm = 0x418;
    linux_pid = 0x4c8;
    linux_pgd = 0x40;
}

# Each guest VM needs to have a separate entry for its particular name. More information is available here: http://libvmi.com/docs/gcode-install.html

# To run:
    cd dom0/libvmi/ ; make
    # Both introspection files will have been built.
        # Follow the domU guidance below to setup the ECR module and launch it (for memory timing).

        # For memory timing introspection:
            sudo ./xen-emulate-response <domU name> <address to emulate>
        # Shift the address by a page amount to observe timing differences across pages. Timing will substantially increase.

        # For cache timing introspection:
            sudo ./map-addr <domU name> <address to map>
        # Shift the address by 0x40, 0x80, 0x100, and 0x1000 to observe timing differences across the data set. Timing will decrease for the 64-byte cache line being mapped.
    

# ** Build/run from domU **

# Build the ECR package.
    git clone https://github.com/ainfosec/ecr_toolkit.git
    cd ecr_toolkit
    make

    # For memory timing introspection:
        sudo ./ecr.sh ecr.ko -m
        # Memory will be allocated. Use this address above for the xen-emulate-response address to emulate. Once it is running, press enter to obtain timing metrics. Repeat as necessary for different address offsets to observe variations across pages.

    # For cache timing introspection:
        sudo ./ecr.sh ecr.ko -l
        # Memory will be allocated. Use this address above for the map-addr address to map. Once it is running, press enter to obtain timing metrics. Repeat as necessary for different address offsets to observe variations and/or ensure granularity.

    # Note 1: Kernel memory allocation may fail. In this case, simply rerun the module.
    # Note 2: To obtain output in a CSV file, run with -c