How to Use Velociraptor for Endpoint Forensic Investigation

Velociraptor uses a client-server model: a central server handles the web UI, query dispatch, and result storage, while lightweight agents run on every endpoint and execute VQL queries when instructed.

Server installation (Linux recommended):

# Download the latest release binary
wget https://github.com/Velocidex/velociraptor/releases/latest/download/velociraptor-v0.72-linux-amd64
chmod +x velociraptor-v0.72-linux-amd64
mv velociraptor-v0.72-linux-amd64 /usr/local/bin/velociraptor

# Generate server configuration
velociraptor config generate --interactive
# Follow prompts: set server URL, TLS cert path, datastore path
# Config saved to server.config.yaml and client.config.yaml

# Install as service and start
velociraptor --config server.config.yaml debian server
dpkg -i velociraptor_server.deb
systemctl enable velociraptor_server && systemctl start velociraptor_server

# Access the web UI:
# https://your-server:8889 (admin credentials set during config generation)

Deploy agents to Windows endpoints:

# Generate the Windows MSI installer from server
velociraptor --config client.config.yaml config repack --exe velociraptor-v0.72-windows.exe output_installer.exe

# Deploy via Group Policy, SCCM, or Intune:
# Create a Software Distribution package or Win32 app
# Command: output_installer.exe service install
# The agent registers with the server and appears in the Web UI

# Verify agent is online in UI: Clients > Connected Clients
# Or from command line:
velociraptor --config server.config.yaml query "SELECT * FROM clients()" --format json

Collect Prefetch files from all endpoints (prove execution history):

// In the Velociraptor UI: Hunting > New Hunt > "Artifact Collection"
// Or use the built-in artifact: Windows.Forensics.Prefetch

-- VQL query equivalent:
SELECT Executable, LastRunTime, RunCount, PrefetchSize, Binary
FROM Artifact.Windows.Forensics.Prefetch()
WHERE Executable =~ '(?i)(mimikatz|psexec|cobalt|cobaltstrike|meterpreter|ncat|netcat)'
LIMIT 1000

// This returns Prefetch entries matching attacker tools from EVERY enrolled endpoint
// Results show: which machines have evidence, when the tool ran, how many times

Collect Windows Event Log entries (specific event IDs):

-- Hunt for failed logon attempts (Event 4625) across all machines
SELECT System.Computer, System.TimeCreated.SystemTime,
    EventData.TargetUserName, EventData.IpAddress, EventData.FailureReason
FROM Artifact.Windows.EventLogs.EvtxHunter(
    EvtxGlob="%SystemRoot%/system32/winevt/logs/Security.evtx",
    IdRegex="4625",
    SearchVSS=TRUE
)
WHERE System.TimeCreated.SystemTime > "2026-05-01T00:00:00Z"
LIMIT 10000

-- Hunt for lateral movement via remote service creation (Event 7045)
SELECT System.Computer, System.TimeCreated.SystemTime,
    EventData.ServiceName, EventData.ImagePath, EventData.AccountName
FROM Artifact.Windows.EventLogs.EvtxHunter(
    EvtxGlob="%SystemRoot%/system32/winevt/logs/System.evtx",
    IdRegex="7045"
)
LIMIT 5000

Collect running processes and network connections:

-- Snapshot of all running processes with network connections
SELECT Pid, Ppid, Name, Exe, CommandLine,
    Username, CreateTime, Laddr, Raddr, Status
FROM Artifact.Windows.Network.Netstat()
WHERE Raddr.IP !~ "^(127\.|::1|0\.0\.0\.0)"
  AND Status = "ESTABLISHED"

-- Same from process list:
SELECT Pid, Ppid, Name, Exe, CommandLine,
    Username, CreateTime, Hash.SHA256
FROM Artifact.Windows.System.Pslist()
WHERE Name =~ '(?i)(cmd|powershell|wscript|cscript|rundll32)'
  AND Username !~ 'SYSTEM|LOCAL SERVICE|NETWORK SERVICE'

The NTFS Master File Table ($MFT) records creation, modification, and access timestamps for every file on the volume. Velociraptor can parse the $MFT directly from a live system: giving you a complete file activity timeline without imaging the disk.

-- Collect $MFT entries for files created during a specific timeframe
SELECT FullPath, FileSize, Created0x10, Modified0x10, MFTId
FROM Artifact.Windows.NTFS.MFT(
    MFTFilename="%SystemDrive%",
    AllDrives=FALSE
)
WHERE Created0x10 > "2026-05-13T00:00:00Z"
  AND Created0x10 < "2026-05-15T00:00:00Z"
  AND FullPath =~ '(?i)(\\temp\\|\\appdata\\|\\downloads\\|\\public\\)'
ORDER BY Created0x10
LIMIT 10000

-- Find executable files created in unusual locations
SELECT FullPath, FileSize, Created0x10, Modified0x10
FROM Artifact.Windows.NTFS.MFT()
WHERE FullPath =~ '(?i)\.exe$'
  AND FullPath !~ '(?i)(\\Windows\\|\\Program Files)'
  AND Created0x10 > "2026-05-01T00:00:00Z"
ORDER BY Created0x10 DESC
LIMIT 5000

Collect registry run key persistence:

-- Check common persistence locations across all machines
SELECT Key.FullPath, Name, Data.value AS RegistryValue
FROM Artifact.Windows.Registry.RunKeys()
-- Built-in artifact checks all standard Run/RunOnce locations
-- Returns any entries that don't match a whitelist of known-good software

-- Also collect scheduled tasks:
SELECT Name, Path, Status, LastRunTime, NextRunTime, Actions
FROM Artifact.Windows.System.ScheduledTasks()
WHERE Path !~ '(?i)(\\microsoft\\|\\windows\\)'

A Hunt in Velociraptor runs a query across all enrolled clients simultaneously: each agent executes the VQL locally and streams results back. This is the primary mechanism for answering scope questions during IR.

Create a Hunt via the UI:

1. Velociraptor UI > Hunts > New Hunt
2. Select artifacts: Windows.Forensics.Prefetch, Windows.Network.Netstat,
   Windows.EventLogs.EvtxHunter
3. Set parameters: date range, specific process names, IoC patterns
4. Set conditions: All clients, or specific client labels/OS
5. Click "Start Hunt"
6. Monitor progress: Hunts > [hunt ID] > Status
7. Download results: Hunts > [hunt ID] > Results > Download CSV

Or via the Velociraptor CLI (for scripting):

# Start a hunt from the command line
velociraptor --config server.config.yaml hunt start \
  --artifact "Windows.Forensics.Prefetch" \
  --args '{"NameRegex": "MIMIKATZ|PSEXEC"}' \
  --description "IR Hunt - Credential Tool Execution Evidence" \
  --output hunt_id.txt

# Wait for hunt to complete and export results
HUNT_ID=$(cat hunt_id.txt)
velociraptor --config server.config.yaml hunt export \
  --hunt_id $HUNT_ID \
  --output /tmp/hunt_results/

Custom artifact for a specific IoC sweep:

# Create a custom artifact to check for a specific file hash or IP
name: Custom.IR.IOCSweep
description: Check endpoints for specific IoC artifacts from incident
parameters:
  - name: SuspiciousIPs
    default: "1.2.3.4,5.6.7.8"
  - name: SuspiciousHashes
    default: "abc123...,def456..."
sources:
  - query: |
      -- Check for suspicious network connections to IoC IPs
      LET ips <= split(string=SuspiciousIPs, sep=',')
      SELECT Pid, Name, Exe, Raddr.IP
      FROM Artifact.Windows.Network.Netstat()
      WHERE Raddr.IP IN ips