Wednesday, June 3, 2020

Installing a Velociraptor Server on Ubuntu 18.04

Update on 2023/10/12.  The Velociraptor project is still going stronger than ever, but this post is now old and outdated.  


     What if I were to tell you that there is a free way to query one hundred hosts or more in a matter of 20 seconds, and get visibility into the possibility of them being compromised.  Would you believe me?  But most importantly, would you take advantage of it?  Would you like to know how to do it with Velociraptor?  If the answer to any of these questions was a “yes”, then you are reading the right blog post. 

     Velociraptor from Velocidex is a free open source utility created by Mike Cohen, who is one of the lead developers for Rekall and GRR.  “With a solid architecture, a library of customisable forensic artifacts and its own unique and flexible query language, Velociraptor provides the next generation in endpoint monitoring, digital forensic investigations and cyber incident response.” (Source: Velocidex). 

     Mike has many years of experience making forensic utilities and we think that Velociraptor has been created with the incident responder in mind.  Velociraptor allows you to query just about anything on the system and also collect just about anything that you want.  It can scale to over 100 thousand hosts and the coolest thing is that you can extend its usability by creating your own collection artifacts using the “The Velociraptor Query Language” (VQL).  VQL is an expressive query language similar to SQL that allows you to quickly and easily adapt Velociraptor to do what you want it to do without needing to modify any of the source code or deploy additional software. 

     Writing VQL queries is beyond the scope of this post, but we can consider creating an article to help you get started with VQL.  The purpose of this post is to talk about the process of standing up a Velociraptor server on Linux machine, so that you can connect a single Windows machine to it.  We hope that once you feel comfortable with the steps described in this post you will be ready to graduate into using these procedures to connect more clients to the server and even graduate into putting your velociraptor server in the cloud.  Let’s get started. 


What you need:

     In order to get started with Velociraptor and to follow along with this post, you are going to need two computers that can reach each other.  In other words, two systems that can ping each other or be on the same subnet. 

     One system will be a Linux machine and the other will be a Windows machine.  The Velociraptor server will be installed on Ubuntu 18.04 and the Windows machine that we will connect to it, will be a Windows 10 machine.  For the purposes of this article we will install each of these machines using the free Virtualization software called VMWare Player.  


Installing the Velociraptor Sever:

     The first step in the process is undoubtedly getting the Velociraptor server up and running and getting the web GUI working.  To accomplish that we went ahead and started by creating a new virtual machine of Ubuntu 18.04 with the default hardware configurations provided by VMWare Player.  Two GB of memory is more than enough for this test server, but feel free to increase it to improve performance. 

     We created one user “ubuntu” with a password of 1234 and gave the machine hostname "velo01".  Yes, the password is short and weak, great for a demo, but not secure as this is just a test.  Do not make this a publicly routable machine. 

     Once the installation completes.  Log in to the Ubuntu machine and open a terminal window.  We will be working from the terminal window during the installation of the Velociraptor utility. 

     Once the terminal window is open, you should be in the home directory of the user of your machine, mine is user “ubuntu”.  Next, elevate privileges to root with “sudo su”.  This is what my machine looks like at this moment.

     The next step is to download the Velociraptor Linux binary to the Ubuntu machine.  The easiest way to accomplish this is via the "wget" utility.  Navigate to this link which should contain the latest release.  As of this writing the latest release was version 0.4.4.   

     Copy the link address to the Linux binary and paste it to the Ubuntu Terminal window.

     Once the binary is on our machine.  The next step in the process would be to add executable permissions to our binary file to that we can well… execute it.  You can accomplish this via the chmod +x command, like so.

# chmod +x velociraptor-v0.4.4-linux-amd64

     Now that the Velociraptor binary has executable permissions, we can now move into the process of installing Velociraptor.  Velociraptor uses two separate locations to store data.  One location is used by the “Data Store” and the other is for its logs.  In order to store both of these locations under one directory, we like to create these two directories using these two commands below.  Mkdir is the command to make a directory and the -p is to create the parent directory in the event that it doesn’t already exists.  

# mkdir -p /velo/velo

# mkdir -p /velo/logs

     The “Data Store” will be stored in “/velo/velo” and the logs will be stored in “/velo/logs”.  The reason why we like to put these directories under the “/velo” directory is simply for organization purposes.  The location of the “Data Store” can be put anywhere that you like.  The “Data Store” of Velociraptor is extremely important to Velociraptor as this location collects information about its clients and whatever data Velociraptor monitors from your clients, so remember it!

     With the location of the “Data Store” now defined, let’s move on to the next step which is to create the pair of configuration files that Velociraptor needs.   Velociraptor uses a pair of configuration files that tell Velociraptor how to operate.  One configuration file is for the server and the other configuration file is for the clients.  The client configuration file let the clients know the location of the velociraptor server and also contains information on how to securely communicate with the Velociraptor server.  

     We can finally begin the process of creating these configuration files by executing the Velociraptor executable interactively like so.

# ./velociraptor-v0.4.4-linux-amd64 config generate -i

     Use arrows to move

     Press enter as we will in fact be using a Linux server

     The next question is: Will you be using the File Base “DataStore” or “MySQL”.  I have heard Mike mention that around after 10,000 clients you should consider using “MySQL”.  For now, we will just use FileBaseDataStore, press enter.

     The next question is:  What is the path to the DataStore.  I placed mine under “/velo/velo”.  So I added that location there and pressed enter.

     The next question is:  What kind of deployment will you need?  Let us talk about the different options...

> Self Signed SSL.   In a self-signed SSL deployment, communication between you, the user, and the Velocirpator web GUI is established using TLS with self-signed certificates.  When you use the browser to log into the Velociraptor GUI, the communications are authenticated with basic Auth and the GUI will bind to localhost only on port 8889 by default.  This means that when you fire up the browser to log into the GUI you must navigate to https://localhost:8889/.  For the purposes of this test this will work just fine and we will use this, but as you graduate from testing into other forms of deployment the other two forms of deployment offer better options. 

> Automatically provision certificates with Lets Encrypt.  In this type of deployment.  You can assign a domain during the Velociraptor installation and Velocirpator will automatically uses the Letsencrypt protocol to obtain and manage its own certificates.  This allows you to put a server in the cloud that you can access by going to a domain that you control, but the GUI authentications are still utilizing username and password authentications that you set up and MFA cannot be used. 

> Authenticate users with Google OAuth SSO.  In this type of Deployment, the verification of the user’s identity is done via Google’s oauth mechanism and you no longer need to assign a password to the users.  Additionally, during this kind of deployment, MFA can be used.  This is where you ultimately want to end up with, this type of deployment is sweet and the authentication is seamless.  As you can imagine, is does take a little bit of set up, time and practice to get good with it. 

     We will use Self Signed SSL because we are just testing, it is fast, and it works.  Press Enter

     The next question is:  What is the port of the front end, leave it default and press enter

     The next question is an Important one:  What is the DNS name of the front end?  In a self-signed deployment, you can leave this default and it will bind to localhost, but I want to edit this here and assign a DNS name so that our Windows client can resolve a DNS to an IP just like if this were a cloud deployment.  This helps in practicing using DNS without having to assign a DNS to a public IP address. 

     We gave it a DNS of “” and pressed enter.

     Default port for the GUI, and a “no” since we are not using google DNS.

     This is where you add your user’s usernames to the GUI as well as their password.  I kept it simple with a username of carlos and a password of 1234.  Again, not secure, this is just a demo…   Press enter when you are done adding your users.

     Location of the logs directory and press enter

     Finish by pressing enter to save the client and server configuration files to your current directory

     Our configuration is now finished.  We are now ready to install Velociraptor to this Ubuntu machine.  To do that we should create Linux packages for both server and clients.  To create Linux packages for the installation of the server and Linux clients execute this command for the server..

# ./velociraptor-v0.4.4-linux-amd64 -c server.config.yaml debian server

And this command for the client..

# ./velociraptor-v0.4.4-linux-amd64 -c server.config.yaml debian client

     This will grab the server configuration file and package it inside of the .deb file so that they can easily be handled by a package installer like “dpkg”.

     Since the server package is ready for installation, let’s go ahead and install it with “dpkg”.  Execute the below command to install the debian server package on this Ubuntu machine.  This will get the Velociraptor utility persistently installed on the machine and ready to allow us to log in using the previously created username and password. 

     When the package is installed on your Ubuntu machine, the installation process also creates a new user on your machine called “velociraptor” that should be the “owner” of the directories created during installation and used by the Velociraptor utility.  This doesn’t always occur since the creation of the directories and the installation of the package were done by user “root”.  My recommendation is to take a quick peak at the “velo” directory to see who currently owns that directory.  To check the “/velo” directory ownership run, ls -l on /velo and see…

# ls -l /velo/

     Notice that the “logs” directory is still owned by “root”.  We can fix this with the “chown” command.  Do you remember how we earlier recommended the “DataStore” and the “logs” directory under one?  It was also for this reason.  Run the “chown” command in recursive mode on the “velo” directory to fix ownership like so!

# chown -R velociraptor:velociraptor /velo

   All fixed now. 

     We are now ready to log into the GUI.  We need to test the GUI and make sure that it works, before we can deploy the configuration file to client machines.  You can log into the GUI of a self-signed SSL deployment by navigating to https://localhost:8889/.  Open your browser on the Ubuntu server and navigate to that URL. 

     If you get the security warning, you have done everything right so far.  This happens because the GUI is served over TLS with a self-signed certificate and the browser is letting you know.  This is normal.  Accept the and continue to the Velociraptor GUI.  You should see a prompt asking you for the username and password created during the velociraptor configuration process.

     Enter the username and password created earlier and log in.  Congratulations.  Marvel at the beauty of Velociraptor!

     Awesome! You now have a Velociraptor server that is waiting for clients to connect to it.  If you click on the “magnifying glass” you can see the clients that are currently talking to your server.

     Unfortunately, there are no clients talking to it.  Lets us change that.  In order to get a client communicating to your Velociraptor server you are going to have to extract the “client.config.yaml” file from your Velociraptor server and get it over to the Windows machine, which is our client in this demo.  The client machine needs to know how to communicate to the server and all the information that it needs is stored there. 

     We have tested Velociraptor so far on Windows 7, Windows 10, Server 2012 and Server 2016 and the Velociraptor client has worked perfectly on all versions.    

     The easiest method of installation that I have found so far has been installing the Velociraptor client on a windows machine via the Windows MSI installation package.  The MSI can be downloaded from here.  As of this writing Mike has not made the MSI for 0.4.4 accessible, but the MSI for version 0.4.2 should work for 0.4.4 as well, as you will see below.  The Velociraptor MSI is signed, which means that it should get treated as a trusted executable and Windows Defender should allow the installation and should not quarantine it.  The MSI will install Velociraptor as a service that starts at boot.  When the service starts, it attempts to load the configuration file from the C:\Program Files\Velocirapror directory called velociraptor.config.yaml.

     This means that if the C:\Program Files\Velocirapror directory doesn’t exist, you will need to create it.  It also means that the client.config.yaml configuration file needs to renamed to velociraptor.config.yaml after it has been added the to the C:\Program Files\Velocirapror directory along with the MSI.  

     It should look like this…

     OK.  We are just one step away from getting this Windows machine talking with the Velociraptor server, but in order to do that we need to tell the Windows machine how to resolve the DNS name that we assigned to Velociraptor.  One easy way to accomplish this is by editing the hosts file on the Windows machine located on C:\Windows\System32\drivers\etc\hosts. 

     Finally, right click on the MSI and select install. 

     If everything worked your directory should look like this.

     Even if your directory on the windows machine looks like ours, nothing beats checking the Velociraptor server to see if it worked.  Go back to the Velociraptor GUI and refresh the screen and boom!  Success!

     You are now ready to query the client machine or machines (plural!!!), using Velociraptor.  This was just the first step needed to connect a client to the Velociraptor server so that you can get visibility into the hosts that are talking to the Velociraptor server.  Continue to practice with the utility and you will see that out of the box, it can do a lot.  Use it to query the running processes, established network connections, and even installed services (like Velociraptor) on your client machines.  The possibilities are endless. 


     Velociraptor is a very powerful free utility that can give you visibility into the hosts or hosts withing your organization.  If the article and its procedures helped you at all, we would like to hear from you.  You can leave a comment and reach me on twitter: @carlos_cajigas or email carlos at 

About the Author: Carlos brings his deep forensic experience from the West Palm Beach Florida Police Department where he served as a digital forensics detective, examiner, and instructor specializing in computer crime investigations. Carlos shares his expertise in his classes on how to directly target specific files and folders that can yield the biggest amount of answers in the least amount of time - "That way you can have answers within minutes rather than within hours," he says, when he teaches the FOR500 and FOR508 courses for the SANS Institute.  Carlos is currently the Managing Partner and Chief Technical Officer of Covert Bit Forensics, a firm specializing in Digital Forensic Investigations.