A Practical Guide to Installing the Velociraptor Client on Windows and Linux
Velociraptor is an advanced, open-source tool for digital forensics and incident response (DFIR). Its power lies in its ability to rapidly collect and analyze data from thousands of endpoints in real-time. The core of this system is the client-server architecture, where a lightweight client installed on each machine maintains a connection with a central server.
Deploying this client, or “agent,” is the first crucial step toward gaining deep visibility into your network. This guide will walk you through the essential steps to install the Velociraptor client on both Windows and Linux endpoints, transforming them into fully monitored assets for your security operations.
Before You Begin: Key Prerequisites
Before deploying the client, ensure you have the following in place:
- A Running Velociraptor Server: The client needs a server to connect to. You must have your central Velociraptor server installed, configured, and accessible over the network.
- Network Connectivity: The endpoint must be able to reach the Velociraptor server on the configured port.
- Administrative Privileges: You will need administrator or root permissions on the target Windows or Linux machine to install the service.
The Foundation: Creating Your Client Configuration File
The client’s behavior is dictated by a single configuration file. This file tells the client where the server is, how to authenticate, and how to behave. Fortunately, the server can generate this configuration for you.
On your Velociraptor server, run the command to generate a client configuration. This will produce a file, typically named client.config.yaml, containing the necessary connection details and security keys. This file is critical and must be securely copied to the endpoint you are targeting.
Deploying the Velociraptor Client on Windows
Installing the client as a persistent service on Windows ensures it runs automatically and survives reboots.
Step 1: Download and Prepare the Executable
First, download the appropriate Velociraptor Windows executable (e.g., velociraptor-v0.7.1-windows-amd64.exe). For organizational purposes, it’s a best practice to create a dedicated directory for the tool, such as C:\Program Files\Velociraptor.
Place both the Velociraptor executable and your client.config.yaml file into this directory. You may want to rename the executable to something simpler, like velociraptor.exe.
Step 2: Install the Service
Open a Command Prompt (CMD) or PowerShell with Administrator privileges. Navigate to the directory where you placed the files. To install the client as a Windows service, run the following command:
.\velociraptor.exe --config client.config.yaml service install
This command registers Velociraptor with the Windows Service Manager. It will now be configured to start automatically when the system boots.
Step 3: Start and Verify
You can manually start the service immediately to test the connection:
sc start velociraptor
After starting the service, log in to your Velociraptor server’s web interface. Within a minute or two, the new Windows client should appear in the main dashboard, ready for investigation.
Installing the Velociraptor Client on Linux
The process for Linux is similar, typically relying on systemd to manage the service for modern distributions like Ubuntu, CentOS, and Debian.
Step 1: Download and Set Permissions
Download the correct Velociraptor binary for your Linux distribution (e.g., velociraptor-v0.7.1-linux-amd64). Place it in a standard location for system binaries, such as /usr/local/bin/.
Next, copy your client.config.yaml file to a configuration directory like /etc/velociraptor/.
Most importantly, make the binary executable. If you placed it in /usr/local/bin/velociraptor, run:
sudo chmod +x /usr/local/bin/velociraptor
Step 2: Install the systemd Service
With the binary and configuration file in place, you can now instruct Velociraptor to install its own systemd service file. Run the following command from the directory containing the binary, or by providing the full path:
sudo /usr/local/bin/velociraptor --config /etc/velociraptor/client.config.yaml service install
This command creates a velociraptor_client.service file in the appropriate systemd directory.
Step 3: Enable and Start the Service
Finally, enable the service to ensure it starts on boot, and then start it for the current session:
# Enable the service to start automatically on boot
sudo systemctl enable velociraptor_client.service
# Start the service immediately
sudo systemctl start velociraptor_client.service
To check its status, you can run sudo systemctl status velociraptor_client.service. As with Windows, the new Linux client should now appear in your server’s GUI.
Actionable Security Tips for Your Deployment
- Secure the Configuration File: On both Windows and Linux, ensure the
client.config.yamlfile has restricted permissions. It contains sensitive connection information and should only be readable by the root or SYSTEM account. - Automate Deployment: For large-scale environments, consider using tools like Group Policy (GPO) for Windows or Ansible/Puppet for Linux to automate the distribution and installation of the client.
- Regularly Update Clients: As new versions of Velociraptor are released with security patches and new features, plan to update your clients across the fleet to maintain a strong security posture.
By following these steps, you have successfully deployed a powerful endpoint agent that provides unprecedented visibility. You are now equipped to perform threat hunting, collect forensic artifacts, and respond to security incidents with speed and precision.
Source: https://kifarunix.com/install-velociraptor-client-on-linux-and-windows-systems/
