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
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
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
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.
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
# 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!
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
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
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
> 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 “velo01.com”
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
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
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
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
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
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 CovertBitForensics.com
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.