Imagine that you work on different engagements or projects in which Kali Linux is one of your primary tools. Furthermore, maybe you also have the need to keep the data for each of those projects isolated from the others – in other words, you need to avoid cross-contamination between your projects. In this article I will show you how to use my Vagrant Kali Project Setup tool to quickly and easily accomplish the following on your Windows host:
- Create a project folder that will provide the workspace for a new project
- Create a BitLocker-protected virtual drive to provide “encryption at rest” data protection for your project files and data portability for archival purposes
- Provision a clean Kali Linux virtual machine, configured with an encrypted virtual storage device that provides “encryption at rest” for the virtual machine itself. We’ll use Virtualbox as our Vagrant VM provisioner.
The requirement for project-based data isolation is fairly common in the consulting industry and other business contexts where you find yourself working with data from multiple clients. In these cases, you need to make sure that sensitive data is protected by encryption at rest, and you also want to make sure that any tools or data artifacts you create for one client (or department or business unit) does not leak into other machines or project data sets.
Consider the case where you have four different “projects” that you need to individually manage and protect. It would be useful to have a tool that can spin up a complete and isolated environment for each project on demand. The following diagram illustrates such a scenario in which we’ve established four project-specific folders, each containing a mountable virtual disk synced to an encrypted and Vagrant-managed Kali virtual machine:
The Vagrant Kali Project Setup Tool
The Vagrant Kali Project Setup tool automates the process of setting up a new project environment like those depicted in the diagram. The tool is a Windows Powershell script that builds the following:
- A new project folder containing a new project-specific Vagrantfile and virtual disk (vhdx) file. For example, this could be the “MyProj1” folder seen in the diagram.
- A project-specific virtual drive file, mounted to a Windows drive letter (e.g., “G:”), and BitLocker-protected. This is the “MyProj1.vhdx” file seen in the diagram along with the associated mounted G:\ drive.
- An initialized project-specific Vagrantfile that defines the Vagrant configuration for the Kali Linux box. The Vagrantfile is dynamically generated by the tool in order to facilitate definition of the project-specific synced folder name (e.g., “/MyProj1”).
- A configured and Vagrant-managed Kali virtual machine where the associated virtual storage device has been encrypted by Virtualbox.
The Vagrant Kali Project Setup tool also performs a small but critical patch to Vagrant. Vagrant, at least as of version 2.2.5, needs patching to support the survival of the “vagrant up” operation through the point in time when the Virtualbox boot process pauses to allow you to type in an encryption password. The tool checks to see if the patch needs to be applied, then patches it if needed (the Powershell script contains a deeper discussion of the mechanism in play). If you don’t patch, then the “vagrant up” operation aborts during the boot process, and certain startup steps like folder syncing will fail. This is all handled by the script.
Running the tool
The tool consists of a Powershell script and a Vagrant “Vagrantfile.erb” template file. You’ll need to download these two files from the GitHub repository:
- vagrant-kali-project-setup-tool.ps1 – the Powershell script that performs all of the tool actions
- Vagrantfile.erb – the Vagrant template file that defines most of the initial settings we need to specify and launch our Kali box.
The tool assumes that you are on a Windows host, of course, and also assumes that you have Vagrant and Virtualbox installed.
Start by opening a command prompt as the administrator. The Powershell script performs a few operations that require elevated privileges, including creating and encrypting the virtual drive and patching Vagrant, so it needs to be run as the administrator as seen here:
The tool will create a project folder to contain the artifacts related to your new Kali box. For purposes of illustration, I’ve created a folder called “My Kali Projects” to represent the parent “Projects Folder” seen in the diagram above. Here, I’m starting with a clean folder with no projects yet. After we run the tool, we’ll see our new project folder in there.
Now let’s run the Powershell script. At the administrator command prompt, type the following command line to start the script:
powershell -executionpolicy bypass -file vagrant-kali-project-setup-tool.ps1
The script performs some initial checks to ensure that the required prerequisites are set up:
- The script checks to make sure Vagrant is installed. Normally Vagrant will add its directory to your PATH environment variable. If the Vagrant executable is not resolved in that PATH, then the script will notify you and exit.
- The script checks to make sure that Virtualbox is installed. In my own Windows 10 installation, the path to the Virtualbox binaries (specifically VBoxManage.exe) was not in my PATH, so the script searches the 64-bit Program Files directory. If VBoxManage.exe is not found, the script will notify you and exit.
- The script checks to make sure that BitLocker is installed. The BitLocker executable should also be in the PATH. Again, if BitLocker is not found, then the script will notify you and exit.
- Finally, the script checks to see if Vagrant needs our small patch, which consists of a single line of code to one of Vagrant’s ruby scripts. If needed, the script saves a copy of the original file and then updates that line of code to make it compatible with the Virtualbox boot process that pauses for encryption password entry.
After successful completion of the environment checks, the script prompts you to designate the “parent” folder in which your project folder will be created. In my case, I want any new project folder to be created in the “My Kali Projects” folder. As seen here, the script pops a Windows “Browse for Folder” window to help you find and designate your parent project folder.
After you select your parent folder, the script will ask you for the name of your project. Your project name will become embedded in a variety of places, including the project folder name, the name of the virtual disk file, and the volume label of the virtual disk. Mostly to accommodate virtual disk volume label format constraints, the script enforces an allowable character set and maximum string length for the project name you choose. In the following example, I’ve chosen “MyProj1” to match the diagram at the top of this post.
After checking to make sure your selected project name hasn’t already been used as a project name in your parent folder location, the script asks you for a Windows “drive letter”. When the script creates a new virtual disk file, it is automatically mounted and assigned to a drive letter (e.g, the “G:\ drive”). To help you select a suitable drive letter and avoid collisions, the script presents a list of currently mounted drives. After you provide your desired drive letter, the script will check to make sure the drive letter isn’t already in use. In this example, I’m choosing “G” as my Windows drive letter.
After accepting the drive letter, the script presents a summary of the proposed project configuration, and asks for a final approval before the build process starts:
After we type “Y” to continue, the script creates the new project folder, then creates the project virtual disk file in that folder. The script then mounts the virtual disk with the designated drive letter. Once the disk is mounted, the script invokes the BitLocker utility to encrypt the drive. In the following screenshot, BitLocker asks for the password that will be used to unlock the drive the next time it is mounted.
During the process of creating and BitLocker-protecting the drive, Windows pops a new explorer window for the new drive. In the screenshot below you can see our new “G:” drive, and as we expect, the drive doesn’t contain any files yet. Later, when the script has finished running and our new Kali VM has been created, this mapped drive will be synced to a corresponding folder inside the VM.
Once the virtual drive has been setup, the script proceeds with the Vagrant construction of the Kali VM. Here we see that the script has performed a “vagrant init” operation (which creates a project-specific Vagrantfile), and it is now running the initial “vagrant up” operation.
The very first “vagrant up” operation for a new box can take a long time, because Vagrant will need to download the Vagrant box template from the Vagrant repository. This can take many minutes. Subsequent “vagrant up” operations don’t take as along because Vagrant already has the box template.
During the “vagrant up” operation, you will see the Virtualbox Kali VM window appear in which you can see the project name embedded in the machine-generated Virtualbox name.
After the Kali VM boots and becomes accessible, the initial “vagrant up” operation continues with the provisioning of the box. “Provisioning” is a series of post-boot steps that include associating our mounted virtual drive to the VM to serve as a “synced folder”. The provisioning process also runs a shell script on the VM to install additional software packages that we may have specified in the Vagrantfile file.
After the final provisioning steps have been completed and we have a usable Kali VM, there is still one unmet requirement – the Kali VM is not yet running on an encrypted storage device. To meet our requirement of “encryption at rest”, we’ll need to apply storage encryption.
The script applies Virtualbox encryption in a sequence of several steps. First, the script performs a graceful shutdown of the VM with a “vagrant halt” operation. Then, the script performs some data mining to determine the ID of the virtual storage image associated with our Kali VM. Once we’ve found the correct storage image, then it can be encrypted using the Virtualbox management utility.
In the screenshot below, the Virtualbox management utility collects the password that we’ll use to encrypt, then unlock the VM during the boot process.
Note that this password is independent of the password we provided during construction of the encrypted virtual disk. In other words, you have two passwords now – one required to mount/unlock our project virtual disk, and a second password to unlock the Kali VM as it boots up.
After we provide our second password, the script encrypts the storage image and performs a second “vagrant up” operation to reboot the now-encrypted Kali VM:
During the boot process of our now-encrypted VM, Virtualbox pauses to ask us for the encryption password we just provided:
From the perspective of the running script (below), we can see the interaction between Virtualbox and Vagrant as the “vagrant up” completes.
In section A of the screenshot, Vagrant gives us an early heads-up that we need to look for the Virtualbox encryption password entry form as it pops up.
In section B, Vagrant is polling the state of the VM, waiting for the boot-up to complete. It is during this time that the encryption password entry form appears and waits for our input.
In section C, Virtualbox has successfully collected our password and booted the Kali VM. The normal post-boot provisioning processes continue until all of the “vagrant up” steps have completed.
Test-driving the new Kali project
After the Powershell script completes, our Kali VM is now running and we can login with the default Kali username “root” and default password “toor”:
If we look at the contents of our new project folder, we can see the virtual disk “vhdx” file created by the tool, the Vagrantfile created by Vagrant, and the “.vagrant” folder that contains various Virtualbox files related to our Kali VM. In the left-side pane of the window, we can also still see the mounted virtual disk (our new “G:\” drive).
Let’s demonstrate that our virtual drive works correctly as a Kali synced folder.
During the Vagrant provisioning process, Vagrant created a top-level folder in the Kali VM with the name of our project. In Kali, let’s open a terminal, change our working directory to the top-level folder with the name “MyProj1”, then write “Hello World” into a test file named “testfile.txt”.
After the “echo” command creates the test file, we can immediately see the test file appear in our G: drive. This demonstrates that the file sync process between the Kali VM and our mounted virtual disk (“G:\ drive”) is working (note that the “.encryptionsemaphore” file you see in the screenshot is an expected artifact of the provisioning process).
We can use Windows Notepad to open the test file seen in our G: drive to confirm that the data arrived intact:
At this point you can confidently use the Kali VM and know that anything you sync to the G: drive will be complete and protected. When you are finishing using Kali, you can perform a “vagrant halt” through your command line to execute an orderly shutdown of the box, and then you can “eject” the mounted virtual disk. Both the VM storage and the virtual disk are safely “encrypted at rest”.
When you want to resume work later, just “mount” the virtual disk by double-clicking on the virtual disk file, then run a “vagrant up” to start up the Kali VM. If you later wish to completely destroy the VM in order to recover the disk space, run a “vagrant destroy”.
Here’s an important note about re-mounting the BitLocker-protected virtual disk later after you’ve ejected it. When you double-click on the file, you will probably (and immediately) see the “access is denied” message seen in Section A of the screenshot below. This is normal. However, if you peek at the left-hand pane of the explorer window (seen in Section B of the screenshot), you will see your drive letter is in use, as if the drive is mounted, or in the process of being mounted. This is good and what you want to see.
To complete the mount operation, you simply need to provide the password. The form seen in the following screenshot is somewhat small, and probably hiding in plain view in your primary monitor. Find it, supply the virtual disk password, then click the “unlock” button.
To Learn More
Vagrant support for Kali Linux: https://www.kali.org/news/announcing-kali-for-vagrant/
The Vagrant Kali Project Setup tool: https://github.com/tonykarre/Vagrant-Kali-Project-Setup-Tool
For more information, or for help assessing the security of your web applications, just contact us at Perficient.