Velociraptor DFIR: Endpoint Forensics and Incident Response

Introduction

When a security incident breaks, time is everything. Chasing logs across individual machines, manually running PowerShell on dozens of endpoints, and waiting for EDR telemetry to trickle in burns precious hours. Velociraptor is an open-source Digital Forensics and Incident Response (DFIR) platform that changes that equation dramatically.

Velociraptor lets you deploy a lightweight agent to every endpoint in your environment and then query those endpoints in real time using its own query language — VQL (Velociraptor Query Language). You can run a "hunt" that simultaneously interrogates hundreds of machines for persistence mechanisms, lateral movement indicators, or specific file hashes in a matter of minutes. It also collects full forensic artifact packages (memory, registry hives, event logs, prefetch, MFT) for offline analysis.

This guide walks you through deploying a Velociraptor server on Ubuntu, enrolling Windows and Linux clients, running your first threat hunt, and collecting forensic artifacts — everything a SOC analyst or incident responder needs to get operational quickly.

Prerequisites

Before you begin, ensure you have:

• A dedicated Ubuntu 22.04 LTS server with a public or internal static IP address. Clients must be able to reach this server on the ports you configure.
• Sudo access on the server.
• At least one test endpoint (Windows 10/11 VM or Linux host) to enroll.
• Firewall rules allowing inbound TCP 8000 (client comms) and TCP 8889 (web UI) on the server.
• A domain name or IP address you will use for the server — you will bake this into the client config at build time.

Step 1 — Download Velociraptor

Velociraptor ships as a single static binary. Grab the latest release from GitHub:

# Set the version (check https://github.com/Velocidex/velociraptor/releases for latest)
VR_VERSION="0.73.3"
 
# Download the Linux amd64 binary
wget -O /usr/local/bin/velociraptor \
  "https://github.com/Velocidex/velociraptor/releases/download/v${VR_VERSION}/velociraptor-v${VR_VERSION}-linux-amd64"
 
# Make it executable
chmod +x /usr/local/bin/velociraptor
 
# Verify
velociraptor version

You should see version information confirming the binary works.

Step 2 — Generate the Server Configuration

Velociraptor uses a YAML configuration file that embeds the server's TLS certificate and defines communication settings. The interactive generator handles this:

velociraptor config generate -i

The wizard asks a series of questions. Key answers:

Once complete, two files are written:

• server.config.yaml — the server configuration (keep this private)
• client.config.yaml — the client configuration embedded in agents

Move them to a permanent location:

sudo mkdir -p /etc/velociraptor
sudo mv server.config.yaml /etc/velociraptor/server.config.yaml
sudo mv client.config.yaml /etc/velociraptor/client.config.yaml
sudo chmod 600 /etc/velociraptor/server.config.yaml

Step 3 — Create an Admin User

Before starting the server, create your first GUI admin account:

sudo velociraptor --config /etc/velociraptor/server.config.yaml \
  user add admin --role administrator

Enter a strong password when prompted.

Step 4 — Install Velociraptor as a systemd Service

sudo velociraptor --config /etc/velociraptor/server.config.yaml \
  service install

This writes a systemd unit file and starts the server. Verify it is running:

sudo systemctl status velociraptor_server
sudo journalctl -u velociraptor_server -f

Confirm the server is listening:

ss -tlnp | grep -E '8000|8889'

Step 5 — Access the Web GUI

Open a browser and navigate to https://<your-server-ip>:8889. Accept the self-signed certificate warning (or configure a trusted cert later). Log in with the admin credentials you created in Step 3.

The dashboard shows:

• Clients — enrolled endpoints
• Hunts — active and completed fleet-wide queries
• Artifacts — the library of built-in and custom collectors
• Notebooks — ad-hoc VQL workspace

Step 6 — Build and Deploy the Windows Agent

Velociraptor produces a self-contained Windows MSI or executable that embeds the client configuration. Build the Windows installer from the server:

sudo velociraptor --config /etc/velociraptor/server.config.yaml \
  config repack --exe /usr/local/bin/velociraptor \
  /etc/velociraptor/client.config.yaml \
  /tmp/velociraptor-agent-windows-amd64.exe

Note: To produce an actual MSI, replace --exe with --msi. You need the msitools package installed: sudo apt install msitools.

Copy the resulting executable to your Windows endpoint (via a file share, SCCM, or GPO software deployment) and run it as administrator:

# On the Windows endpoint — run as Administrator
.\velociraptor-agent-windows-amd64.exe service install

Within 30 seconds the client should appear in the GUI under Clients.

Step 7 — Deploy the Linux Agent

For Linux endpoints, copy the client config and the binary:

# On each Linux endpoint
sudo mkdir -p /etc/velociraptor
sudo scp user@dfir-server:/etc/velociraptor/client.config.yaml \
  /etc/velociraptor/client.config.yaml
 
sudo scp user@dfir-server:/usr/local/bin/velociraptor \
  /usr/local/bin/velociraptor
sudo chmod +x /usr/local/bin/velociraptor
 
# Install as a service
sudo velociraptor --config /etc/velociraptor/client.config.yaml \
  service install
sudo systemctl enable --now velociraptor_client

Step 8 — Run Your First Hunt

A hunt dispatches a query to every enrolled client simultaneously. Let's hunt for scheduled tasks — a common persistence mechanism:

1. In the GUI, click Hunts → New Hunt.
2. Set a Description: Persistence - Scheduled Tasks.
3. Click Select Artifacts and search for Windows.System.ScheduledTasks. Add it.
4. Leave default parameters and click Create Hunt.
5. Click Start on the hunt row.

Within a few minutes, results from all enrolled Windows clients populate the hunt. Use the Results tab to pivot on suspicious task names, command lines, or unusual authors.

Hunting from the command line (VQL)

You can also run ad-hoc VQL directly against a single client. In the GUI, select a client, click Shell, and run:

-- List all running processes with their hashes
SELECT Pid, Ppid, Name, Exe,
       hash(path=Exe).MD5 AS MD5
FROM pslist()
ORDER BY Name

Or check for recently modified files in suspicious paths:

-- Files modified in the last 24 hours under Windows temp directories
SELECT FullPath, Mtime, Size
FROM glob(globs=[
  "C:/Windows/Temp/**",
  "C:/Users/*/AppData/Local/Temp/**"
])
WHERE Mtime > now() - 86400
ORDER BY Mtime DESC
LIMIT 100

Step 9 — Collect a Full Forensic Artifact Package

When you need to collect evidence from an endpoint for offline analysis, use the Windows.KapeFiles.Targets artifact (based on KAPE's target definitions):

1. Select the target client in Clients.
2. Click Collect Artifact.
3. Search for Windows.KapeFiles.Targets.
4. Under parameters, enable:
   • _SANS_Triage — a curated set of triage artifacts (event logs, prefetch, registry, MFT, LNK files, browser history)
5. Click Launch.

The collection runs on the client, compresses the results, and uploads them to the server filestore. Download the ZIP from the Results tab for analysis in tools like Eric Zimmerman's suite, Autopsy, or Timeline Explorer.

Step 10 — Create a Reusable Artifact

Custom VQL artifacts let you encode institutional knowledge that any analyst can re-run. Create a YAML artifact file:

# /etc/velociraptor/artifacts/Custom.Detect.LsassAccess.yaml
name: Custom.Detect.LsassAccess
description: |
  Detect processes that have recently opened a handle to lsass.exe,
  which may indicate credential dumping activity.
type: CLIENT
sources:
  - query: |
      LET lsass_pid = SELECT Pid FROM pslist() WHERE Name =~ "lsass.exe"
      SELECT
        p.Pid AS AccessorPID,
        p.Name AS AccessorName,
        p.Exe AS AccessorExe,
        h.AccessRights AS AccessRights
      FROM handles() AS h
      JOIN pslist() AS p ON h.Pid = p.Pid
      WHERE h.TargetPid IN (SELECT Pid FROM lsass_pid)
        AND h.AccessRights > 0

Import it into the server:

sudo velociraptor --config /etc/velociraptor/server.config.yaml \
  artifacts load /etc/velociraptor/artifacts/Custom.Detect.LsassAccess.yaml

The artifact now appears in the GUI's artifact library and can be used in hunts.

Verification

After deployment, run these checks to confirm everything is working correctly.

Verify server health:

sudo systemctl is-active velociraptor_server
# Expected: active
 
curl -sk https://localhost:8889/app/index.html | grep -o 'Velociraptor'
# Expected: Velociraptor

Verify client connectivity from the GUI:

Navigate to Clients and confirm each enrolled endpoint shows a Last Seen time within the last few minutes and a green connectivity indicator.

Verify hunt execution:

Run the built-in Generic.Client.Info artifact as a hunt against all clients. All clients should return hostname, OS version, and agent version data — confirming end-to-end communication is functional.

Verify artifact collection:

Collect Windows.System.Pslist from a single client. Confirm the process list returns within 30 seconds and is downloadable as a CSV from the Results tab.

Troubleshooting

Clients not connecting to the server

• Confirm TCP 8000 is open on the server firewall (ufw allow 8000/tcp).
• Verify the server DNS name or IP in client.config.yaml resolves correctly from the client host.
• Check client logs on Windows: %ProgramData%\Velociraptor\velociraptor.log
• Check client service status on Linux: sudo journalctl -u velociraptor_client -n 50

GUI returns a TLS certificate error

Self-signed certificates trigger browser warnings by default. Either accept the exception, or place Velociraptor behind an nginx reverse proxy with a Let's Encrypt certificate. Set GUI.bind_address: 127.0.0.1 in server.config.yaml and proxy via nginx on port 443.

Hunt returns no results from enrolled clients

Clients only respond to hunts when they check in. By default the polling interval is around 60 seconds. Wait 2 minutes after launching a hunt before assuming no results. You can lower Client.max_poll in the server config to reduce this delay in lab environments.

VQL query errors: Unknown function

Velociraptor's built-in functions vary slightly between versions. Run SELECT * FROM info() on a client shell to confirm the agent version, then check the VQL reference for that version.

High memory usage on server

Large hunts collecting many artifacts can spike RAM. Set limits in server.config.yaml:

Frontend:
  resources:
    max_upload_size: 10737418240   # 10 GB max per collection
  concurrency: 20                  # Limit concurrent client connections

Restart the service after changes: sudo systemctl restart velociraptor_server.

Summary

You now have a fully operational Velociraptor DFIR platform capable of:

• Real-time endpoint queries — ask any question across your entire fleet in seconds using VQL
• Fleet-wide threat hunts — simultaneously interrogate all endpoints for persistence, lateral movement, or IOC matches
• Forensic artifact collection — gather triage packages (event logs, registry, prefetch, MFT) for offline analysis
• Custom detections — encode your threat intelligence as reusable VQL artifacts that any analyst can execute

Velociraptor pairs excellently with the rest of your detection stack. Feed hunt results into Wazuh or Sentinel for correlation, use it alongside Sysmon for deep Windows event telemetry, and trigger collections automatically from SIEM alerts via the Velociraptor API. With VQL, there is virtually no forensic question you cannot answer across a live fleet — making it one of the most powerful additions to any SOC or IR team's toolkit.