Runbook: Velociraptor Operations

Purpose

Day-to-day operator runbook for Velociraptor at Cirius: how to start a collection, common artifacts to use, how to author a VQL hunt for threat hunting, how to push artifacts across the fleet, how to export results, and how to feed findings back to SecOps.

This document assumes Velociraptor is deployed per velociraptor-architecture-eval.md (single Ubuntu 24.04 server VELOCIRAPTOR-VM in PROD, clients across PROD/DDE/AWS). If Velociraptor has not been deployed yet, the architecture evaluation doc controls; this runbook becomes live on go-live.

Scope of this runbook: operator-level tasks Rory or Kobe will perform during an investigation or a threat hunt. It is not a server administration runbook — server install, cert rotation, and patching are in the architecture doc's deployment section.

Access

Logging in

URL: https://velociraptor.ciriusgroup.com
Auth: Entra PROD OIDC (group SecOps DFIR → Velociraptor role investigator; Rory holds the administrator role)
MFA required (Entra conditional access)
No local accounts permitted except the one break-glass administrator account stored in Key Vault — that account is tracked as break-glass, activity generates a CRITICAL SecOps incident

API access

Machine-to-machine (agents, SecOps integrations) uses the Velociraptor API with an api.config.yaml credential stored in Key Vault (cirius-openai-kv-prod, secret name velociraptor-api-config). Never embed API credentials in scripts — always fetch at runtime.

Core Concepts (Quick Reference)

Client — an enrolled endpoint running the Velociraptor agent
Flow — a single collection against a single client (e.g., "pull KAPE Targets from PROD-DC-01")
Hunt — a collection run across multiple clients in parallel (e.g., "run Windows.System.Pslist against every Windows VM in PROD")
Artifact — a YAML-defined collection or detection; hundreds built-in, custom ones authored in the GUI or added via the server artifact directory
VQL — Velociraptor Query Language, SQL-ish, how artifacts are written and how ad-hoc queries are run
Notebook — scratchpad for post-collection analysis, supports VQL queries against flow results

Starting a Collection — Single Host

Use when: you have one suspect host and need to collect evidence from it.

Steps

Identify the client
- Web UI → top-left Search → type hostname (e.g., BIZWRKAZP11)
- Confirm the client ID and Last Seen time (should be < 5 minutes)
- If the client has not checked in recently, see Client not responding below
Open the client's page
- Click the client ID
- Tabs: Overview, VFS, Collected, Flows, Notebooks
Start the collection
- Click Collected tab → Collect From Host
- Search for the artifact (e.g., Windows.KapeFiles.Targets)
- Set parameters (see artifact reference below for parameter guidance)
- Click Launch at the bottom
Monitor the flow
- Flow appears under Collected tab with state RUNNING
- Progress bar indicates bytes collected
- Typical KAPE Triage collection: 2-5 minutes on a standard VM
Review results
- When state = FINISHED, click the flow ID
- Results tab shows structured output; Uploaded Files tab shows raw collected files (MFT, Event Logs, etc.)
- Download options: zipped uploads, CSV exports, JSON

Authorization gate

Every on-demand collection is logged to the Velociraptor audit log and forwarded to LAW. Rory reviews the audit log during monthly health check. For PHI-adjacent hosts (system_type = SERVER, phi_adjacent=true in CMDB), open a CM ticket in SecOps before the collection:

POST /api/changes
{
  "type": "dfir_collection",
  "source_system": "PROD",
  "description": "Velociraptor Windows.KapeFiles.Targets on BIZWRKAZP11 — <reason>",
  "window_start": "<ISO>",
  "window_end": "<ISO+2h>",
  "approver": "rory"
}

This aligns with the Cirius policy that any admin action touching PHI-adjacent systems has a CM paper trail.

Common Artifacts — Reference

The artifacts listed below are the ones most commonly used in a Cirius context. Full library at https://docs.velociraptor.app/artifact_references/.

Windows.KapeFiles.Targets

Use for: full triage acquisition of a suspected-compromise Windows host. Collects the KAPE Targets set — MFT, USN journal, registry hives, Event Logs, scheduled tasks, prefetch, browser history, common persistence locations.

Parameters to set:

Targets — default KapeTriage (a curated set). Use BasicCollection for a faster/smaller grab.
UseAutoAccessor — leave default Y (bypasses file locks on Event Logs)

Runtime: 3-8 minutes on a standard VM, output 200 MB-2 GB depending on how much Event Log history is resident.

When to use: suspected compromise, ransomware staging, credential theft investigation. This is the canonical "triage the host" artifact.

Windows.System.Pslist

Use for: current process list with parent-child relationships, command line, executable hash.

Parameters:

ProcessRegex — optional, limit output (e.g., .*powershell.* to grep)
CommandLineRegex — optional filter on command line

Runtime: seconds.

When to use: spot-check a host during incident triage; baseline a healthy host for comparison; use in hunts to find processes matching a pattern across the fleet.

Windows.Persistence.PermanentWMIEvents

Use for: enumerate permanent WMI event subscriptions (a common persistence technique — APT29, APT33, etc.).

Runtime: seconds.

When to use: anytime the persistence-stage kill chain agent fires. Any WMI event subscription that isn't from Defender/Cortex is worth a second look.

Windows.Persistence.Startup

Use for: Registry Run keys, Startup folders, Winlogon shell/userinit modifications.

Runtime: seconds.

When to use: persistence-stage investigation; baseline audit of clean hosts.

Windows.Persistence.ScheduledTasks

Use for: scheduled tasks, includes principal, trigger, action, last-run/next-run.

Runtime: seconds.

When to use: 4698 event seen in LAW and we want to correlate to the task definition and its continued presence.

Windows.Sys.Users

Use for: local user accounts including last-logon, password flags, groups.

When to use: check for suspicious local accounts on a domain-joined machine.

Windows.EventLogs.Evtx

Use for: pull selected Event Log channels (Security, System, PowerShell Operational, Microsoft-Windows-Sysmon/Operational).

Parameters:

EventLog — channel name
TimeAfter / TimeBefore — window filter
EventIDs — comma-separated

When to use: targeted pull for a specific event ID and window; more surgical than KAPE Targets.

Windows.Memory.Acquisition

Use for: full live memory capture via winpmem. Output ~RAM-size bytes, archive in S3 evidence bucket with hash sealing.

Runtime: 5-15 minutes. Host CPU impact noticeable during collection.

When to use: major incident with suspected in-memory malware (Cobalt Strike, Mimikatz resident). Open a CM ticket first, coordinate with the host's owner, and only collect when there is real suspicion.

Linux.Sys.Pslist / Linux.Sys.Packages / Linux.Forensics.Journal

Use for: Linux equivalents for process listing, installed packages, and systemd-journal export.

When to use: Linux investigations. Same patterns as Windows artifacts above.

Threat Hunting — Fleet-Wide via Hunts

Use when: you have a hypothesis and want to test it across every host.

Example 1 — Hunt for PowerShell spawning from unusual parents

Hypothesis: PowerShell executing with parent != explorer.exe, powershell.exe, cmd.exe, or one of the known Intune / MECM process names is suspicious.

Steps

Hunts → New Hunt
Description: hunt-20260416-ps-unusual-parent
Expires: 24 hours
Target: All Clients (or scope to a label like env:prod)
Add artifact: Windows.System.Pslist
Set ProcessRegex = powershell\.exe|pwsh\.exe
Start the hunt
Monitor under Hunt Manager → when results land, open the hunt's notebook
In the notebook, VQL-filter to unusual parents:

sql

SELECT Fqdn, Name, Pid, Ppid, CommandLine, ParentName
FROM hunt_results(hunt_id=$hunt_id, artifact='Windows.System.Pslist')
WHERE Name =~ 'powershell' AND NOT ParentName =~ 'explorer|powershell|cmd|wmiprvse|svchost|mmc|SenseIR'

Any matches get a SecOps finding (see Posting to SecOps below) and further per-host investigation

Example 2 — Hunt for a specific DLL across the estate

Hypothesis: A known-malicious DLL hash from a threat intel report may be resident on one or more Cirius hosts.

Hunts → New Hunt → artifact Windows.Search.FileFinder
SearchFilesGlob = C:\Windows\**, C:\Users\**\AppData\**
Name_regex = .*\.dll$
Hash parameter: set the known hash
Start. Let it run. It is I/O-heavy — schedule for off-hours if the fleet is large.
Any hits = CRITICAL SecOps incident, the host gets Velociraptor Windows.KapeFiles.Targets in follow-up, and Arctic Wolf is notified.

Hunt hygiene

Never leave a hunt running indefinitely. Always set an expiry (1-7 days).
Hunts consume disk on the server — review Hunt Manager monthly, archive completed hunts, delete expired flow data after it has been exported to S3 evidence.
A hunt is an authorized admin action — log a CM ticket alongside the hunt with type=dfir_hunt.

Writing Custom VQL Artifacts

Built-in artifacts cover most cases. Custom artifacts are authored when the built-in library doesn't match or when we want a Cirius-specific hunt parameterized.

Pattern — author in GUI, commit to Git

Velociraptor GUI → View Artifacts → + Add an Artifact
Prototype the VQL; save
Test against a single client first, then one-off against a small hunt
Once validated, export the YAML:
- GUI → Artifact → Export YAML
Save to the Cirius velociraptor-artifacts subfolder in ops-automation:

ops-automation/
  velociraptor/
    artifacts/
      Cirius.Windows.Persistence.CiriusScheduledTasks.yaml

PR in ops-automation — Rory reviews the VQL
On merge, CI deploys the artifact to the server via the Velociraptor api.NewServerNotebookCell API

Custom artifact example — CMDB-aware inventory

yaml

name: Cirius.Inventory.CmdbReconcile
description: |
  Collect host-reported identity fields and reconcile with CMDB expectations.
parameters:
  - name: ExpectedOwner
    default: infrastructure
sources:
  - query: |
      SELECT Fqdn, Hostname,
             agent.VersionInfo() AS agent_version,
             config.Labels AS labels,
             now() AS collected_at
      FROM info()

This artifact would run as part of the quarterly CMDB accuracy check, posting to SecOps for cross-reference with the CMDB.

Pushing Artifacts to Clients

Use when: you want every client to periodically run a detection (persistent monitoring) rather than on-demand.

Client monitoring

Server Admin → Server Artifacts → Client Monitoring
Add artifact to the monitored set (e.g., Windows.Detection.PsExec for continuous PsExec detection)
Save → clients pick up the new monitoring set at their next config check (~10 minute cycle)

Guidance on what to monitor:

Use sparingly. Each monitoring artifact runs continuously on every client.
Best candidates: low-noise, high-signal detections — named-pipe creation for known malware families, specific registry changes, persistence mechanism additions.
Do not add general-purpose process listing to client monitoring. Use hunts for that.

Events pushed back

Client monitoring events stream back to the server and land in the client_monitoring index. A SecOps job (velociraptor_monitoring_agent, 4-hour cycle) polls the last-24h events and pattern-matches to detection rules. Matches become SecOps findings.

Exporting Results

To local machine (operator review)

Flow → Downloaded Files → Download zip
Hash zip on download and cross-check against Velociraptor's reported hash (integrity check)
For KAPE-style collections, open in local tool of choice (KAPE, Timeline Explorer, EZtools) — the file layout is KAPE-compatible

To HIPAA evidence archive (long-term)

Any collection that has evidentiary value is exported to the 6-year HIPAA evidence archive:

# From the server, or via Velociraptor CLI:
velociraptor flows export --flow-id F.CEZGI9B -o /tmp/F.CEZGI9B.zip
sha256sum /tmp/F.CEZGI9B.zip > /tmp/F.CEZGI9B.zip.sha256

# Upload to the evidence S3 bucket (Logging account):
aws s3 cp /tmp/F.CEZGI9B.zip s3://cirius-evidence-logging/velociraptor/2026/incident-XYZ/
aws s3 cp /tmp/F.CEZGI9B.zip.sha256 s3://cirius-evidence-logging/velociraptor/2026/incident-XYZ/

# Register evidence in SecOps:
curl -X POST https://soc.bedrockcybersecurity.org/api/evidence \
  -H "X-API-Key: $SECOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "velociraptor",
    "flow_id": "F.CEZGI9B",
    "incident_id": "INC-XYZ",
    "archive_uri": "s3://cirius-evidence-logging/velociraptor/2026/incident-XYZ/F.CEZGI9B.zip",
    "hash_sha256": "<sha256>",
    "retention_years": 6
  }'

The S3 bucket has Object Lock with 6-year retention, same boundary as other Cirius HIPAA evidence.

To SecOps as a finding

For detections (hunt matches, monitoring events) that warrant incident handling:

curl -X POST https://soc.bedrockcybersecurity.org/api/ingest/findings \
  -H "X-API-Key: $SECOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_system": "PROD",
    "source": "velociraptor_hunt",
    "ioc_key": "velociraptor:HUNT_ID:HOST:ARTIFACT",
    "severity": "HIGH",
    "finding_type": "dfir_hunt_match",
    "host": "BIZWRKAZP11",
    "title": "Velociraptor hunt matched suspicious PowerShell parent on BIZWRKAZP11",
    "description": "...",
    "evidence_uri": "https://velociraptor.ciriusgroup.com/app/index.html#/hunt/HUNT_ID",
    "raw": { ... minimal structured evidence ... }
  }'

ioc_key includes source_system to prevent cross-tenant dedup per the Cirius standard.

Integrating with SecOps — Summary

Velociraptor event	SecOps action	Channel
Hunt match (HIGH/CRITICAL)	Finding → incident	`/api/ingest/findings`
Hunt match (benign classified)	Finding → closed with known-good	`/api/ingest/findings`
Client monitoring detection	Finding via `velociraptor_monitoring_agent`	agent-polled
Collection initiated	CM ticket	`/api/changes` (type=`dfir_collection`)
Hunt initiated	CM ticket	`/api/changes` (type=`dfir_hunt`)
Evidence preserved	Evidence record	`/api/evidence`
Server audit log	LAW table `VelociraptorAudit_CL`	syslog-ng on server

Client Not Responding — Troubleshooting

If Last Seen is > 30 minutes:

Confirm the VM is running (Azure / AWS console)
RDP/SSH to the host. On Windows: Get-Service velociraptor. Service should be Running.
vcmdline.exe --config C:\ProgramData\Velociraptor\client.config.yaml client --verbose — review output. Check for TLS handshake errors, network errors.
Check Palo Alto logs for the VM's source IP toward velociraptor.ciriusgroup.com (443). If blocked, verify rule VELOCIRAPTOR-AGENT-EGRESS is enabled.
Check server — systemctl status velociraptor on VELOCIRAPTOR-VM. Review /var/log/velociraptor/ for errors.
If server is healthy, cert mismatch suspected: reinstall the client MSI from current Intune package (embeds current cert fingerprint).

Any prolonged client-not-responding (>4 hours) with no clear cause = open a SecOps finding velociraptor_agent_offline, priority HIGH. We don't leave investigation coverage gaps.

Quarterly Review Checklist

Fold into monthly security review (Velociraptor section).

[ ] Server patched within last 30 days (apt-get upgrade + velociraptor binary current)
[ ] All agents at current version (check Clients → sort Version)
[ ] Enrollment tokens rotated (quarterly)
[ ] Server backup successful in last 7 days (RSV)
[ ] Disk utilization on /var/lib/velociraptor < 70%
[ ] Expired flow data purged (>90 days, not under legal hold)
[ ] Audit log ingestion into LAW healthy (rows in VelociraptorAudit_CL in last 24 hours)
[ ] At least one test collection run this quarter (canary — confirms operator readiness)

velociraptor-architecture-eval.md — architecture, deployment, sizing
incident-response.md — IR procedure, Velociraptor collection is step in triage
arctic-wolf-mdr-scope-gap.md — MDR scope context
kill-chain-audit-policy.md — Event log coverage, complements Velociraptor
monthly-security-review.md — broader monthly review

Change History

Date	Change	Author
April 2026	Initial operations runbook — collections, hunts, VQL, SecOps integration	Kobe

Runbook: Velociraptor Operations ​

Purpose ​

Access ​

Logging in ​

API access ​

Core Concepts (Quick Reference) ​

Starting a Collection — Single Host ​

Steps ​

Authorization gate ​

Common Artifacts — Reference ​

Windows.KapeFiles.Targets ​

Windows.System.Pslist ​

Windows.Persistence.PermanentWMIEvents ​

Windows.Persistence.Startup ​

Windows.Persistence.ScheduledTasks ​

Windows.Sys.Users ​

Windows.EventLogs.Evtx ​

Windows.Memory.Acquisition ​

Linux.Sys.Pslist / Linux.Sys.Packages / Linux.Forensics.Journal ​

Threat Hunting — Fleet-Wide via Hunts ​

Example 1 — Hunt for PowerShell spawning from unusual parents ​

Steps ​

Example 2 — Hunt for a specific DLL across the estate ​

Hunt hygiene ​

Writing Custom VQL Artifacts ​

Pattern — author in GUI, commit to Git ​

Custom artifact example — CMDB-aware inventory ​

Pushing Artifacts to Clients ​

Client monitoring ​

Events pushed back ​

Exporting Results ​

To local machine (operator review) ​

To HIPAA evidence archive (long-term) ​

To SecOps as a finding ​

Integrating with SecOps — Summary ​

Client Not Responding — Troubleshooting ​

Quarterly Review Checklist ​

Related Documents ​

Change History ​

Runbook: Velociraptor Operations

Purpose

Access

Logging in

API access

Core Concepts (Quick Reference)

Starting a Collection — Single Host

Steps

Authorization gate

Common Artifacts — Reference

Windows.KapeFiles.Targets

Windows.System.Pslist

Windows.Persistence.PermanentWMIEvents

Windows.Persistence.Startup

Windows.Persistence.ScheduledTasks

Windows.Sys.Users

Windows.EventLogs.Evtx

Windows.Memory.Acquisition

Linux.Sys.Pslist / Linux.Sys.Packages / Linux.Forensics.Journal

Threat Hunting — Fleet-Wide via Hunts

Example 1 — Hunt for PowerShell spawning from unusual parents

Steps

Example 2 — Hunt for a specific DLL across the estate

Hunt hygiene

Writing Custom VQL Artifacts

Pattern — author in GUI, commit to Git

Custom artifact example — CMDB-aware inventory

Pushing Artifacts to Clients

Client monitoring

Events pushed back

Exporting Results

To local machine (operator review)

To HIPAA evidence archive (long-term)

To SecOps as a finding

Integrating with SecOps — Summary

Client Not Responding — Troubleshooting

Quarterly Review Checklist

Related Documents

Change History