Projects 1-4 Common VMWinter 2021

Each of the five projects of EECS 388 requires a set of software as a prerequisite, and/or is sensitive to differences in the computing environment (e.g. operating system and package versions). For your convenience and impartiality in grading, EECS 388 distributes a virtual machine (VM) to be used for projects 1 through 4. Project 5, due to it being a forensics project, will ship with its own VM. Do not update the software in the VM! Doing so may change the behavior of your project code.

The course staff strongly encourage you to implement and test your projects in the provided VM. In case of a grading dispute, the result of your submission executed in the VM will take precedence over all other platforms. Furthermore, the course staff are not able to provide assistance on running any component of the course projects on any other platform, such as your computer's host operating system.

It is your responsibility to set enough disk space aside on your personal device for all course material, including this VM, and to make regular backups of your data (snapshots in VirtualBox will be covered subsequently in this tutorial). If disk space is scarce, you may want to consider migrating your data to the cloud (umich.edu Google accounts provide unlimited storage), or to an external storage medium. Except in the most extenuating circumstances, the course staff are not able to provide accommodations due to a lack of space and/or loss of data.

Last but not least, if you run into any problems while reading this guide, there are a number of sections addressing troubleshooting at the bottom of this document. We will update this document continually as we encounter new problems or parts where many people are struggling on.

Step 1 - Install VirtualBox

The VM appliance is slightly more than 4 gigabytes in size. Therefore, it may be felicitous to start the download before proceeding to the rest of the instructions. Download the VM appliance (eecs388_w21_vm.ova) from here. (U-M login required) Its SHA-256 checksum, which you can compute by running sha256sum eecs388_w21_vm.ova in a terminal, is 2e926b8d002effa61561d631e80caf71784338e9a99675ca69f7eb040c523fc1.

Our VM is based on Kali Linux 2020.3, a distribution geared towards digital forensics and penetration testing (an authorized attack on a system, done as a security evaluation). On top of Kali, the VM has all dependencies you will need to run projects 1 through 4.

You will use VirtualBox to run the aforementioned VM. Download the latest version for your host operating system here. Once installed, download the Oracle VM VirtualBox Extension Pack from the same link. The extension pack lets USB devices be recognized from the VM, which may come in handy for making backups. Setting up USB for your VM is completely optional, but the VM may not run without the extension pack - this is an unfortunate limitation from the base image of Kali Linux which the VM is built from. You can verify if the extension pack is loaded by navigating to File, Preferences, and Extensions. The popup should look like this:

VirtualBox is, and should be able to, detect USB devices out-of-the-box on Windows and macOS hosts. However, on some Linux distributions, you will have to add your user account to the vboxusers group. Run, and then reboot:

$ sudo usermod -aG vboxusers $USER

Step 2 - Import the VM Appliance

In VirtualBox's main menu, navigate to Tools, and then Import. Select the VM appliance file (eecs388_w21_vm.ova) which you downloaded, and continue to click the Next button until you are no longer prompted; you do not need to modify any settings. Simply verify that your default settings look like the image below: (Ignore the extra 1 at the end of the name. Trivially, it's fine if the base folder is different.)

The import process may take several minutes. Once complete, run the VM. If all goes well, you will be greeted with a login screen. Enter kali for both the username and password. When you get to the desktop, power off the VM for now - there is an important step.

VirtualBox lets you save the state of your VM at a point in time with snapshots. When the EECS 388 Projects 1-4 VM is selected in the VirtualBox manager, you should see an icon with 'Take' inscribed below. Proceed and take a snapshot; should you make an irrevocable mistake, you can always revert to this initial snapshot instead of downloading the VM appliance again. Ensure that your snapshot is visible above Current State, like the screenshot below.

Step 3 - Conveniences

This part is optional. It is not absolutely necessary to run the VM, but you might find some features convenient to use.

The VM ships with VirtualBox Guest Additions, which supports automatic window resizing, shared clipboard, and drag and drop. It also supports shared folders, but you must specify which folder(s) on your host operating system you would like to share. With the VM selected in the VirtualBox manager, navigate to Settings and then Shared Folders. Create a shared folder by clicking the folder icon with a green + sign by first choosing a path and then checking the Auto-mount box.

Moreover, in the VM settings pane, you should be able to find USB. In a similar manner to shared folders, you can click the icon with a USB plug and a green + sign to let the VM recognize your USB device (a dropdown will appear). The VM defaults to a USB 3.0 controller; if you have older hardware, you may have to select USB 2.0 instead.

Using the VM for Projects

Please treat the VM as your work environment for projects in EECS 388. That is, you can minimize the risk of things going awry by cloning the GitHub Classroom repo, implementing the projects, and pushing your commits all inside the VM. The VM shares its network connection with your host machine, which makes all of the above possible. If the VM is running slow, feel free to provide it more processor cores or memory. (but don't overwhelm your host OS!)

Feel free to install your text editor or IDE of choice to the VM. EECS 388's projects are not code-heavy or large enough as to make an IDE a better choice over a simple text editor, though; while implementation is definitely a part, a conceptual understanding of the attack or exploit will be crucial. Kali Linux is based on Debian, and therefore you can use its systems for package management. If you are familiar with Ubuntu, another Debian derivative, Kali's learning curve will be much lower.

Kali ships with the apt package manager, as well as the dpkg tool. You can install some text editors directly with the former, sudo apt install vim being an example. Most larger and more modern editors, such as Atom and Visual Studio Code, distribute packages with the extension .deb from their websites. Once downloaded, you can install them with sudo dpkg -i filename.deb.

Visual Studio Code Remote Mode

If you're accustomed to using Visual Studio Code, you might want to take advantage of its "remote" mode, which allows the instance of VSCode running on your computer to connect to other computers while maintaining the feel of editing on your local machine. Remote mode allows you to edit files, run debuggers, open terminals, and perform essentially any other operations you'd usually perform on your local machine. This works for machines accessible over SSH like a server or even CAEN, and with a few tweaks we can allow SSH connections into the virtual machine, meaning you can nearly forget that you're working inside of a VM!

1. The first step to enabling this support is to allow connections from the host machine (your computer) to the guest (the virtual machine). Open the settings for your virtual machine, and under the "network" tab, make sure that the "attached to" selection box has "Bridged Adapter" selected—this usually defaults to "NAT". Now, open up the VM, and inside a terminal type ip a, which will list the IP addresses assigned to the interfaces of the virtual machine. Look for the eth0 heading and under it look for inet; next to that you'll see an IPv4 address, which is four numbers separated by periods. (We'll find out what that /24 means in the networking section of the course!)

   

   Note that this address will probably be different for you; you'll need to keep track of that address for the next part.

2. Next, we'll need to enable the SSH server inside the VM. Kali comes with an SSH server pre-installed, but disabled for security reasons. You can enable the SSH server with sudo systemctl start ssh, and change it to start every time the VM starts up with sudo systemctl enable ssh. We're now done in the VM, so let's hop over to VSCode!

3. Inside VSCode, you'll want to search the extensions marketplace for "Remote - SSH" and install the extension.

   

4. Now, you'll want to open the command palette (CTRL+Shift+P on Windows and Linux, CMD+Shift+P on macOS) and search for "Remote-SSH: Connect to Host". A dialog will appear asking where you want to connect, and you'll want to enter kali@<IP_address_from_earlier> (hopefully you kept track of that address—it will probably be different from the screenshot).

   

5. The window should exit and re-open shortly, at which point you'll be prompted for a password. This is the password for the kali user, so it will still be kali unless you changed it. Once you enter it, your VSCode window will now be connected to the VM! You should see "SSH: " in the bottom left corner of the window. You might now want to install any extensions that you have in your local VSCode instance into the VM—open the command palette once again and search for "Remote: Install Local Extensions in…", select the box at the top to select all extensions, and install.

You should now essentially feel exactly like you're developing on your local machine with the same settings and extensions! For example, here is what you might see after opening a terminal and seeing what is in the Desktop folder:

With user kali and folders autopsy and eecs388p2, it's clear that our VSCode instance is connected to the VM.

Troubleshooting

If everything works well so far, you're all set - no need to scroll further down in this document. However, if that is not the case, you might find the following helpful.

VirtualBox Install Failed on macOS

This is an issue we have started to observe more frequently with the latest releases of macOS, i.e. Catalina and Big Sur. macOS may report "The installation failed." when installing VirtualBox, or a VM may not start with the error "Kernel driver not installed". To resolve this, open the System Preferences app, and click the Security & Privacy button. You will see a window similar to the following screenshot:

First, click the lock icon on the bottom left, and enter your password. This will make the Allow button opaque and clickable; click it, and restart your Mac.

VM Crashing on macOS

From the Piazza questions so far, this seems to be an issue affecting macOS, more specifically macOS Catalina (10.15). Unlike previous versions, Catalina by default restricts access by applications to certain system components for security. However, this has made it prone to compatibility issues - most commonly, crashing of the VM before completing to boot.

One such component appearing to be problematic is audio. To obviate this, open the VM's settings, move to Audio, and uncheck the Enable Audio box. That is, all audio should be disabled, like the screenshot below:

CPU Virtualization

VirtualBox requires an x86(-64) processor with hardware-assisted virtualization; such feature is called VT-x on Intel processors and AMD-V on AMD processors. If you have a Mac, virtualization should be enabled by default in firmware. If you have a PC, chances are the feature will be enabled from the factory, yet this is not always the case.

In order to enable virtualization, you will need to enter the setup menu of your BIOS or UEFI on your PC. The key combination to press immediately after startup differs by PC manufacturer, but oftentimes it is one of F2, Delete, F10, F12, or Esc. Consult your manufacturer's documentation if you are unsure. The location of the setting will also differ by manufacturer. However, the name will almost always include 'virtualization' or 'virtualization technology'.

If you are on Windows and are still encountering problems with running a virtual machine on VirtualBox, please check if you have Hyper-V enabled. Unfortunately, Hyper-V is known to cause problems with other virtualization software, including VirtualBox. To turn Hyper-V off, please consult the instructions here.

Video

This has been a known issue in the past with certain Macs, but may be applicable to other host machines. If you are having video issues such as no video / screen tearing / guest screen not resizing, navigate to the Settings of your VM, and then Display. The default display driver is VMSVGA; changing this to VBoxVGA may resolve the issue. If the issue persists nonetheless, please post on Piazza or visit office hours.

If you are on macOS and experiencing screen flickering, you may be able to resolve the issue by navigating to Settings, Display, then checking Enable 3D Acceleration.

Shrinking the VM

Note: this is not necessary directly after importing the VM, since the virtual hard disk is at its smallest size. You may want to visit this part closer to the end of the semester!

The VM uses a virtual hard disk (.vdi file) which is dynamically allocated. That is, the maximum size it will occupy is 80 GB, but its actual size on your host operating system will only be the portion of that 80 GB your VM actually occupies. This may sound promising, but it has one catch. When you delete a file with rm, the bytes on disk making up the file are still intact. The operating system just deletes a pointer to that file, and marks the region as free space (which can be overwritten by another file). However, VirtualBox (and your host operating system) cannot sense this; it will still perceive that region of your virtual hard disk as being used, and will not attempt to clean it up. A consequence of this phenomenon is that you may see your .vdi file growing to overwhelming sizes as you use the VM.

To resolve this, you must first overwrite the unused regions of the virtual hard disk with zeroes. Boot the VM, but when the bootloader (GRUB) appears with Kali Linux and advanced options, press E within 5 seconds to modify the boot options. Use the arrow keys to navigate downward in the boot configuration, to a line starting with linux - it will be similar to the following:

linux   /boot/vmlinuz-5.7.0-kali1-amd64 root=UUID=114c498f-de75-44bb-a5ec-6339282d4171 ro quiet splash

Remove the quiet splash, and replace with init=/bin/bash. Press F10 to boot with the new configuration. You should boot to a root shell (and no graphics). Enter df to list all virtual disks - there should be only one, /dev/sda1. The VM ships with the zerofree utility; run it with zerofree -v /dev/sda1 (this may take a while). When it finishes, power off the VM.

Then, in the VirtualBox Manager window, right-click on the VM and select Show in File Manager. The opened directory is the path where the VM's virtual disk (.vdi file) lives. Note this down, since you will have to provide it subsequently.

Finally, you will have to open VirtualBox's command-line utility, VBoxManage. For *nix hosts (macOS, Linux, etc.) the executable should already be in your PATH environment variable. For Windows hosts, the program is VBoxManage.exe, located in the same directory as your VirtualBox installation. In a terminal (command prompt or PowerShell for Windows), run:

VBoxManage modifymedium disk <PATH TO VDI> --compact

Windows Hosts - VM Boots to Black Screen

Credits to an anonymous student on Piazza - thanks for finding this out!

There is a chance that Hyper-V, covered earlier in this troubleshooting section, is implicitly enabled in your Windows host. Run the following command in command prompt as an administrator, and then reboot:

bcdedit /set hypervisorlaunchtype off

bcdedit /set hypervisorlaunchtype auto