Velociraptor Cheatsheet

Velociraptor is an advanced digital forensics and incident response tool that provides endpoint visibility at scale. It uses a powerful query language (VQL) to collect, query, and monitor endpoint data, making it ideal for threat hunting, incident response, and continuous monitoring across large enterprise environments.

Installation and Setup

Server Installation

Ubuntu/Debian Installation:

# Download latest release
wget https://github.com/Velocidex/velociraptor/releases/download/v0.7.0/velociraptor-v0.7.0-linux-amd64

# Make executable
chmod +x velociraptor-v0.7.0-linux-amd64
sudo mv velociraptor-v0.7.0-linux-amd64 /usr/local/bin/velociraptor

# Generate server configuration
sudo velociraptor config generate > /etc/velociraptor/server.config.yaml

# Create systemd service
sudo tee /etc/systemd/system/velociraptor.service << EOF
[Unit]
Description=Velociraptor Server
After=network.target

[Service]
Type=simple
User=velociraptor
Group=velociraptor
ExecStart=/usr/local/bin/velociraptor --config /etc/velociraptor/server.config.yaml frontend -v
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Create user and start service
sudo useradd -r -s /bin/false velociraptor
sudo systemctl enable velociraptor
sudo systemctl start velociraptor

Docker Installation:

# Create configuration directory
mkdir -p velociraptor-config

# Generate configuration
docker run --rm -v $(pwd)/velociraptor-config:/config \
  velocidex/velociraptor:latest \
  config generate --config /config/server.config.yaml

# Run server
docker run -d --name velociraptor-server \
  -p 8000:8000 -p 8080:8080 \
  -v $(pwd)/velociraptor-config:/config \
  velocidex/velociraptor:latest \
  --config /config/server.config.yaml frontend -v

Client Installation

Windows Client:

# Download client
Invoke-WebRequest -Uri "https://github.com/Velocidex/velociraptor/releases/download/v0.7.0/velociraptor-v0.7.0-windows-amd64.exe" -OutFile "velociraptor.exe"

# Install as service
.\velociraptor.exe --config client.config.yaml service install

# Start service
Start-Service Velociraptor

Linux Client:

# Download client
wget https://github.com/Velocidex/velociraptor/releases/download/v0.7.0/velociraptor-v0.7.0-linux-amd64

# Install as service
sudo ./velociraptor-v0.7.0-linux-amd64 --config client.config.yaml service install

# Start service
sudo systemctl start velociraptor_client

macOS Client:

# Download client
curl -L -o velociraptor https://github.com/Velocidex/velociraptor/releases/download/v0.7.0/velociraptor-v0.7.0-darwin-amd64

# Install as service
sudo ./velociraptor --config client.config.yaml service install

# Start service
sudo launchctl load /Library/LaunchDaemons/com.velocidx.velociraptor.plist

Configuration

Server Configuration

Basic Server Config:

# server.config.yaml
version:
  name: velociraptor
  version: 0.7.0

Client:
  server_urls:
    - https://velociraptor.company.com:8000/
  ca_certificate: |
    -----BEGIN CERTIFICATE-----
    [CA Certificate]
    -----END CERTIFICATE-----
  nonce: [Random nonce]

API:
  bind_address: 0.0.0.0
  bind_port: 8001
  bind_scheme: https

GUI:
  bind_address: 0.0.0.0
  bind_port: 8889
  bind_scheme: https
  public_url: https://velociraptor.company.com:8889/

Frontend:
  bind_address: 0.0.0.0
  bind_port: 8000
  certificate: |
    -----BEGIN CERTIFICATE-----
    [Server Certificate]
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN PRIVATE KEY-----
    [Server Private Key]
    -----END PRIVATE KEY-----

Datastore:
  implementation: FileBaseDataStore
  location: /var/lib/velociraptor
  filestore_directory: /var/lib/velociraptor

Client Configuration

Client Config Generation:

# Generate client configuration
velociraptor --config server.config.yaml config client > client.config.yaml

# Generate MSI installer for Windows
velociraptor --config server.config.yaml config client --deployment windows_msi > client.msi

# Generate DEB package for Linux
velociraptor --config server.config.yaml config client --deployment linux_deb > client.deb

VQL (Velociraptor Query Language)

Basic VQL Syntax

Simple Queries:

-- List running processes
SELECT Name, Pid, Ppid, CommandLine
FROM pslist()

-- Get file information
SELECT FullPath, Size, Mtime, Atime, Ctime
FROM glob(globs="/etc/passwd")

-- Search for files
SELECT FullPath, Size, Mtime
FROM glob(globs="C:/Users/*/Desktop/*.exe")
WHERE Size > 1000000

Advanced Queries:

-- Process tree with parent information
SELECT Name, Pid, Ppid, CommandLine,
       get(item=pslist(pid=Ppid), member="0.Name") AS ParentName
FROM pslist()
WHERE Name =~ "powershell"

-- Network connections with process info
SELECT Laddr, Raddr, Status, Pid,
       get(item=pslist(pid=Pid), member="0.Name") AS ProcessName,
       get(item=pslist(pid=Pid), member="0.CommandLine") AS CommandLine
FROM netstat()
WHERE Status = "ESTABLISHED"

File System Operations

File Discovery:

-- Find executable files
SELECT FullPath, Size, Mtime, hash(path=FullPath) AS Hash
FROM glob(globs="C:/Windows/System32/*.exe")

-- Search for suspicious files
SELECT FullPath, Size, Mtime, Atime, Ctime
FROM glob(globs=["C:/Temp/**", "C:/Users/*/AppData/Local/Temp/**"])
WHERE FullPath =~ "\\.(exe|bat|cmd|ps1|vbs)$"
  AND Size > 0

-- Find recently modified files
SELECT FullPath, Size, Mtime
FROM glob(globs="C:/Users/**")
WHERE Mtime > now() - 86400  -- Last 24 hours
  AND FullPath =~ "\\.(doc|docx|pdf|txt)$"

File Content Analysis:

-- Search file contents
SELECT FullPath, Line, HitContext
FROM grep(globs="C:/Users/*/Documents/*.txt",
          keywords=["password", "secret", "confidential"])

-- Extract strings from binaries
SELECT FullPath, String
FROM strings(globs="C:/Temp/*.exe", length=8)
WHERE String =~ "(http|ftp)://"

-- YARA scanning
SELECT FullPath, Rule, Meta, Strings
FROM yara(files="C:/Temp/*.exe",
          rules='''
          rule SuspiciousStrings {
              strings:
                  $s1 = "cmd.exe" ascii
                  $s2 = "powershell" ascii
                  $s3 = "CreateProcess" ascii
              condition:
                  2 of them
          }''')

Process Analysis

Process Monitoring:

-- Current processes with details
SELECT Name, Pid, Ppid, CommandLine, Username, Exe,
       CreateTime, hash(path=Exe) AS ExeHash
FROM pslist()
ORDER BY CreateTime DESC

-- Process tree visualization
SELECT Name, Pid, Ppid, CommandLine,
       get(item=pslist(pid=Ppid), member="0.Name") AS ParentName,
       CreateTime
FROM pslist()
WHERE Ppid != 0
ORDER BY Ppid, CreateTime

-- Suspicious process detection
SELECT Name, Pid, CommandLine, Exe
FROM pslist()
WHERE (CommandLine =~ "powershell.*-enc" OR
       CommandLine =~ "cmd.*echo.*>" OR
       Exe =~ "C:\\\\Temp\\\\.*\\.exe" OR
       Name =~ "^[a-f0-9]{8,}\\.(exe|tmp)$")

Process Memory Analysis:

-- Dump process memory
SELECT Pid, Name, dump(pid=Pid, length=1000000) AS MemoryDump
FROM pslist()
WHERE Name = "suspicious.exe"

-- Search process memory
SELECT Pid, Name, Address, HitContext
FROM proc_memory_grep(pid=1234, keywords=["password", "secret"])

-- Extract loaded modules
SELECT Pid, Name, ModuleName, ModuleBase, ModuleSize
FROM modules(pid=1234)

Network Analysis

Network Connections:

-- Active network connections
SELECT Laddr, Raddr, Status, Pid,
       get(item=pslist(pid=Pid), member="0.Name") AS ProcessName,
       get(item=pslist(pid=Pid), member="0.CommandLine") AS CommandLine
FROM netstat()
WHERE Status = "ESTABLISHED"

-- Listening services
SELECT Laddr, Status, Pid,
       get(item=pslist(pid=Pid), member="0.Name") AS ProcessName
FROM netstat()
WHERE Status = "LISTEN"
ORDER BY Laddr

-- DNS cache analysis
SELECT Name, Type, Data, TTL
FROM dns_cache()
WHERE Name =~ "suspicious-domain\\.com"

Registry Analysis (Windows)

Registry Queries:

-- Startup programs
SELECT Key, ValueName, ValueData
FROM registry(globs="HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*")

-- Recently accessed files
SELECT Key, ValueName, ValueData
FROM registry(globs="HKEY_CURRENT_USER/SOFTWARE/Microsoft/Windows/CurrentVersion/Explorer/RecentDocs/*")

-- Installed software
SELECT Key, ValueName, ValueData
FROM registry(globs="HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Uninstall/*/DisplayName")
WHERE ValueData

Registry Monitoring:

-- Monitor registry changes
SELECT timestamp(epoch=Timestamp) AS Time,
       Key, ValueName, ValueData, EventType
FROM watch_registry(globs="HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*")

Artifacts and Hunts

Built-in Artifacts

System Information:

-- Windows.System.Info
SELECT Hostname, OS, Architecture, Platform, PlatformVersion,
       KernelVersion, Uptime, BootTime
FROM info()

-- Windows.System.Users
SELECT Name, Description, Disabled, PasswordLastSet, LastLogon
FROM users()

-- Windows.System.Services
SELECT Name, DisplayName, Status, StartType, ServiceType, BinaryPath
FROM services()

Security Artifacts:

-- Windows.EventLogs.Security
SELECT EventTime, EventID, Computer, UserName, LogonType, IpAddress
FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx")
WHERE EventID IN (4624, 4625, 4648, 4672)

-- Windows.Forensics.Prefetch
SELECT FullPath, LastRunTime, RunCount, Hash
FROM prefetch()

-- Windows.Registry.Sysinternals.Eulaaccepted
SELECT Key, ValueName, ValueData, Mtime
FROM registry(globs="HKEY_CURRENT_USER/SOFTWARE/Sysinternals/*/EulaAccepted")

Custom Artifacts

Create Custom Artifact:

name: Custom.Windows.SuspiciousProcesses
description: Hunt for suspicious process execution patterns
type: CLIENT

sources:
  - precondition:
      SELECT OS From info() where OS = 'windows'
    
    query: |
      SELECT Name, Pid, Ppid, CommandLine, Exe, CreateTime,
             hash(path=Exe) AS ExeHash,
             get(item=pslist(pid=Ppid), member="0.Name") AS ParentName
      FROM pslist()
      WHERE (
        -- Processes running from temp directories
        Exe =~ "(?i)C:\\\\(Temp|Users\\\\[^\\\\]+\\\\AppData\\\\Local\\\\Temp)\\\\" OR
        
        -- Suspicious command line patterns
        CommandLine =~ "(?i)(powershell.*-enc|cmd.*echo.*>|certutil.*-decode)" OR
        
        -- Processes with random names
        Name =~ "^[a-f0-9]{8,}\\.(exe|tmp)$" OR
        
        -- Common malware process names
        Name =~ "(?i)(svchost|winlogon|csrss|lsass)\\.(tmp|exe)$" AND 
        NOT Exe =~ "(?i)C:\\\\Windows\\\\System32\\\\"
      )
      ORDER BY CreateTime DESC

Deploy Custom Artifact:

# Upload artifact to server
velociraptor --config server.config.yaml artifacts upload custom_artifact.yaml

# Run artifact on specific client
velociraptor --config server.config.yaml query "SELECT * FROM Artifact.Custom.Windows.SuspiciousProcesses()" --client_id C.1234567890abcdef

Hunt Management

Create Hunt:

-- Create hunt for suspicious processes
SELECT hunt_id FROM hunt(
    description="Hunt for suspicious processes",
    artifacts=["Custom.Windows.SuspiciousProcesses"],
    spec=dict(
        artifacts=["Custom.Windows.SuspiciousProcesses"],
        parameters=dict()
    )
)

Monitor Hunt Progress:

-- Check hunt status
SELECT hunt_id, state, create_time, creator,
       total_clients_scheduled, completed_clients
FROM hunts()
WHERE state = "RUNNING"

-- Get hunt results
SELECT ClientId, Timestamp, Name, Pid, CommandLine, ExeHash
FROM hunt_results(hunt_id="H.1234567890abcdef",
                  artifact="Custom.Windows.SuspiciousProcesses")

Incident Response

Live Response

Remote Shell:

-- Execute commands remotely
SELECT Stdout, Stderr, ReturnCode
FROM execve(argv=["cmd", "/c", "whoami"])

-- PowerShell execution
SELECT Stdout, Stderr, ReturnCode
FROM execve(argv=["powershell", "-Command", "Get-Process | Where-Object {$_.CPU -gt 100}"])

-- Collect system information
SELECT Stdout FROM execve(argv=["systeminfo"])

File Collection:

-- Collect specific files
SELECT upload(file=FullPath) AS Upload
FROM glob(globs="C:/Users/*/Desktop/suspicious.exe")

-- Collect log files
SELECT FullPath, upload(file=FullPath) AS Upload
FROM glob(globs="C:/Windows/System32/winevt/Logs/*.evtx")
WHERE Name =~ "(Security|System|Application)\\.evtx"

-- Memory dump collection
SELECT upload(file=dump_process(pid=1234)) AS MemoryDump
FROM scope()

Timeline Analysis

File System Timeline:

-- Create filesystem timeline
SELECT FullPath, Size, Mtime, Atime, Ctime, Btime,
       "M" AS MtimeType, "A" AS AtimeType, "C" AS CtimeType, "B" AS BtimeType
FROM glob(globs="C:/Users/*/Documents/**")
WHERE Mtime > timestamp(string="2023-01-01T00:00:00Z")
ORDER BY Mtime

-- Process creation timeline
SELECT Name, Pid, CommandLine, CreateTime, Exe
FROM pslist()
WHERE CreateTime > now() - 86400  -- Last 24 hours
ORDER BY CreateTime

Event Log Timeline:

-- Security event timeline
SELECT EventTime, EventID, Computer, UserName, LogonType,
       IpAddress, WorkstationName
FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx")
WHERE EventTime > timestamp(string="2023-01-01T00:00:00Z")
  AND EventID IN (4624, 4625, 4648, 4672, 4720, 4726)
ORDER BY EventTime

Threat Hunting

Lateral Movement Detection:

-- Detect lateral movement via RDP
SELECT EventTime, Computer, UserName, IpAddress, LogonType
FROM parse_evtx(filename="C:/Windows/System32/winevt/Logs/Security.evtx")
WHERE EventID = 4624 AND LogonType = 10  -- RDP logons
  AND IpAddress != "127.0.0.1"
  AND IpAddress != "-"

-- Detect PSExec usage
SELECT Name, Pid, CommandLine, CreateTime
FROM pslist()
WHERE (CommandLine =~ "psexec" OR
       Name =~ "PSEXESVC\\.exe" OR
       CommandLine =~ "\\\\\\\\.*\\\\admin\\$")

-- Detect suspicious PowerShell
SELECT Name, Pid, CommandLine, CreateTime
FROM pslist()
WHERE Name =~ "powershell\\.exe" AND
      (CommandLine =~ "-enc" OR
       CommandLine =~ "-nop" OR
       CommandLine =~ "-w hidden" OR
       CommandLine =~ "DownloadString" OR
       CommandLine =~ "IEX")

Persistence Detection:

-- Startup folder persistence
SELECT FullPath, Size, Mtime, hash(path=FullPath) AS Hash
FROM glob(globs=[
    "C:/Users/*/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/*",
    "C:/ProgramData/Microsoft/Windows/Start Menu/Programs/Startup/*"
])

-- Scheduled task persistence
SELECT Name, State, LastRunTime, NextRunTime, TaskPath, Actions
FROM scheduled_tasks()
WHERE State = "Ready" AND
      (Actions =~ "powershell" OR
       Actions =~ "cmd" OR
       Actions =~ "C:\\\\Temp\\\\" OR
       Actions =~ "C:\\\\Users\\\\.*\\\\AppData\\\\")

-- Service persistence
SELECT Name, DisplayName, BinaryPath, StartType, Status
FROM services()
WHERE BinaryPath =~ "(?i)(temp|appdata)" OR
      BinaryPath =~ "(?i)\\.(bat|cmd|ps1|vbs)$" OR
      (Name =~ "^[a-f0-9]{8,}$" AND StartType = "Auto")

Monitoring and Alerting

Real-time Monitoring

Process Monitoring:

-- Monitor new process creation
SELECT timestamp(epoch=Timestamp) AS Time,
       Name, Pid, Ppid, CommandLine, Exe
FROM watch_process()
WHERE CommandLine =~ "(powershell.*-enc|cmd.*echo|certutil.*-decode)"

File System Monitoring:

-- Monitor file creation in suspicious locations
SELECT timestamp(epoch=Timestamp) AS Time,
       FullPath, Action
FROM watch_file(globs=[
    "C:/Temp/**",
    "C:/Users/*/AppData/Local/Temp/**",
    "C:/Windows/Temp/**"
])
WHERE Action = "CREATED" AND
      FullPath =~ "\\.(exe|bat|cmd|ps1|vbs)$"

Registry Monitoring:

-- Monitor registry changes for persistence
SELECT timestamp(epoch=Timestamp) AS Time,
       Key, ValueName, ValueData, EventType
FROM watch_registry(globs=[
    "HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*",
    "HKEY_CURRENT_USER/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*"
])

Alerting Integration

SIEM Integration:

-- Export alerts to SIEM
SELECT timestamp(epoch=now()) AS AlertTime,
       "Velociraptor" AS Source,
       "Suspicious Process" AS AlertType,
       Name, Pid, CommandLine, Exe
FROM pslist()
WHERE CommandLine =~ "powershell.*-enc"

Webhook Alerts:

-- Send webhook alerts
SELECT http_client(
    url="https://webhook.site/your-webhook-url",
    method="POST",
    data=serialize(item=dict(
        alert_type="Suspicious Process",
        hostname=info().Hostname,
        process_name=Name,
        command_line=CommandLine,
        timestamp=now()
    ), format="json")
) AS Response
FROM pslist()
WHERE CommandLine =~ "powershell.*-enc"

Performance and Scaling

Query Optimization

Efficient Queries:

-- Use specific globs instead of wildcards
-- Good
SELECT * FROM glob(globs="C:/Users/*/Desktop/*.exe")

-- Avoid
SELECT * FROM glob(globs="C:/**")
WHERE FullPath =~ "\\.exe$"

-- Use LIMIT for large datasets
SELECT * FROM pslist() LIMIT 100

-- Use WHERE clauses early
SELECT Name, Pid FROM pslist()
WHERE Name = "powershell.exe"

Resource Management:

-- Control memory usage
SELECT * FROM pslist()
WHERE Pid < 10000  -- Limit scope

-- Use streaming for large results
SELECT * FROM foreach(
    row={SELECT Pid FROM pslist() WHERE Name = "chrome.exe"},
    query={SELECT * FROM modules(pid=Pid)}
)

Distributed Deployment

Multi-Server Setup:

# Load balancer configuration
Frontend:
  bind_address: 0.0.0.0
  bind_port: 8000
  expected_clients: 10000
  
# Database clustering
Datastore:
  implementation: MySQL
  mysql_connection_string: "user:pass@tcp(mysql-cluster:3306)/velociraptor"
  
# File storage
Filestore:
  implementation: S3
  s3_bucket: "velociraptor-files"
  s3_region: "us-east-1"

Troubleshooting

Common Issues

Client Connection Problems:

# Check client status
velociraptor --config client.config.yaml status

# Test server connectivity
velociraptor --config client.config.yaml query "SELECT * FROM info()"

# Debug client logs
tail -f /var/log/velociraptor_client.log

# Force client enrollment
velociraptor --config client.config.yaml enroll

Performance Issues:

-- Check server performance
SELECT * FROM server_metadata()

-- Monitor query performance
SELECT query, duration, rows_returned
FROM query_log()
WHERE duration > 10000  -- Queries taking > 10 seconds

-- Check client resource usage
SELECT Pid, Name, CPU, Memory
FROM pslist()
WHERE Name =~ "velociraptor"

Query Debugging:

-- Debug VQL queries
SELECT log(message="Debug: Processing " + str(str=Pid))
FROM pslist()

-- Check query syntax
EXPLAIN SELECT * FROM pslist()

-- Validate artifact syntax
SELECT validate_artifact(definition=read_file(filename="artifact.yaml"))

Log Analysis

Server Logs:

# Monitor server logs
tail -f /var/log/velociraptor.log

# Search for errors
grep -i error /var/log/velociraptor.log

# Check client connections
grep "client connected" /var/log/velociraptor.log

Client Logs:

# Monitor client logs
tail -f /var/log/velociraptor_client.log

# Check enrollment status
grep "enrollment" /var/log/velociraptor_client.log

# Monitor query execution
grep "query" /var/log/velociraptor_client.log

This comprehensive Velociraptor cheatsheet covers installation, VQL queries, artifact development, incident response, and advanced features for effective endpoint monitoring and threat hunting.