sica-fondt/knowledge/cyber-skills/skills/implementing-velociraptor-for-ir-collection/references/api-reference.md

API Reference: Velociraptor Incident Response Collection

Libraries Used

Library	Purpose
pyvelociraptor	Official Python bindings for Velociraptor gRPC API
grpc	gRPC transport for API communication
json	Parse VQL query results
yaml	Read Velociraptor API config files

Installation

pip install pyvelociraptor grpcio pyyaml

Authentication

Velociraptor uses mTLS with an API config file generated by the server:

import pyvelociraptor
import json
import os

# Generate API config on the Velociraptor server:
# velociraptor config api_client --name analyst > api_client.yaml

config_path = os.environ.get("VELOCIRAPTOR_API_CONFIG", "api_client.yaml")

gRPC API — Query Method

The primary API method is Query(), which executes VQL (Velociraptor Query Language) statements:

import pyvelociraptor
import json

def run_vql(config_path, query):
    config = pyvelociraptor.LoadConfigFile(config_path)
    grpc_channel = pyvelociraptor.grpc_channel(config)
    stub = pyvelociraptor.api_pb2_grpc.APIStub(grpc_channel)

    request = pyvelociraptor.api_pb2.VQLCollectorArgs(
        max_wait=10,
        max_row=1000,
        Query=[pyvelociraptor.api_pb2.VQLRequest(
            VQL=query,
        )],
    )

    results = []
    for response in stub.Query(request):
        if response.Response:
            rows = json.loads(response.Response)
            results.extend(rows)
    return results

Common VQL Queries

List Connected Clients

clients = run_vql(config_path, """
    SELECT client_id, os_info.hostname as hostname,
           os_info.system as os, last_seen_at
    FROM clients()
    WHERE last_seen_at > now() - 3600
""")

Collect Artifacts from an Endpoint

# Start a collection (hunt) on a specific client
collection = run_vql(config_path, """
    SELECT collect_client(
        client_id='C.abc123def456',
        artifacts=['Windows.KapeFiles.Targets'],
        parameters=dict(Device='C:', VSSAnalysis='Y')
    ) FROM scope()
""")
flow_id = collection[0]["collect_client"]["flow_id"]

Monitor Collection Status

status = run_vql(config_path, f"""
    SELECT * FROM flows(client_id='C.abc123def456')
    WHERE session_id = '{flow_id}'
""")
# Fields: state, create_time, total_collected_rows, total_uploaded_bytes

Retrieve Flow Results

results = run_vql(config_path, f"""
    SELECT * FROM flow_results(
        client_id='C.abc123def456',
        flow_id='{flow_id}',
        artifact='Windows.KapeFiles.Targets'
    )
""")

Hunt Across All Clients

hunt = run_vql(config_path, """
    SELECT hunt(
        description='Search for suspicious scheduled tasks',
        artifacts=['Windows.System.TaskScheduler'],
        parameters=dict()
    ) FROM scope()
""")
hunt_id = hunt[0]["hunt"]["hunt_id"]

Search for IOCs Across Fleet

ioc_results = run_vql(config_path, """
    SELECT * FROM hunt_results(hunt_id='H.abc123')
    WHERE OSPath =~ 'mimikatz|lazagne|rubeus'
""")

Key VQL Functions

Function	Purpose
clients()	List all enrolled clients
collect_client()	Start artifact collection on endpoint
flows()	List collection flows for a client
flow_results()	Get results from a completed flow
hunt()	Create a new hunt across clients
hunt_results()	Get results from a hunt
artifact_definitions()	List available artifacts
source()	Read server-side event log data
upload()	Upload files from endpoint to server

Built-in Artifact Categories

Category	Examples
Windows Triage	Windows.KapeFiles.Targets, Windows.EventLogs.Evtx
Process Forensics	Windows.System.Pslist, Generic.System.Pstree
Persistence	Windows.Persistence.PermanentWMIEvents, Windows.System.TaskScheduler
Network	Windows.Network.Netstat, Windows.Network.ArpCache
Memory	Windows.Detection.Yara.Process, Windows.System.VAD
Linux	Linux.Sys.Users, Linux.Search.FileFinder
macOS	MacOS.System.Users, MacOS.Applications.Chrome.History

Output Format

{
  "client_id": "C.abc123def456",
  "hostname": "WORKSTATION-01",
  "os": "windows",
  "flow_id": "F.xyz789",
  "state": "FINISHED",
  "artifacts_collected": ["Windows.KapeFiles.Targets"],
  "total_collected_rows": 1542,
  "total_uploaded_bytes": 52428800,
  "create_time": "2025-01-15T10:30:00Z"
}