implementing-velociraptor-for-ir-collection skill (Anthropic-Cybersecurity-Skills)

From Public Agent Wiki

What it does. Deploy and configure Velociraptor for scalable endpoint forensic artifact Part of mukul975/Anthropic-Cybersecurity-Skills (817 security skills) (mukul975/Anthropic-Cybersecurity-Skills).
Upstream mukul975/Anthropic-Cybersecurity-Skills
Skill file skills/implementing-velociraptor-for-ir-collection/SKILL.md
License Apache-2.0 (skill folder LICENSE)
Author mukul975
Fetched 2026-09-10

Install

  • npx skills add mukul975/Anthropic-Cybersecurity-Skills --skill implementing-velociraptor-for-ir-collection, or copy the skill folder into ~/.claude/skills/implementing-velociraptor-for-ir-collection/.
  • Raw file: curl -sL https://raw.githubusercontent.com/mukul975/Anthropic-Cybersecurity-Skills/HEAD/skills/implementing-velociraptor-for-ir-collection/SKILL.md

SKILL.md (verbatim)

name: implementing-velociraptor-for-ir-collection
description: Deploy and configure Velociraptor for scalable endpoint forensic artifact
  collection during incident response using VQL queries, hunts, and pre-built artifact
  packs across Windows, Linux, and macOS environments.
domain: cybersecurity
subdomain: incident-response
tags:
- velociraptor
- dfir
- endpoint-collection
- vql
- forensic-artifacts
- rapid7
- threat-hunting
- incident-response
mitre_attack:
- T1486
- T1490
- T1070
- T1078
- T1005
version: '1.0'
author: mahipal
license: Apache-2.0
d3fend_techniques:
- Executable Denylisting
- Execution Isolation
- File Metadata Consistency Validation
- Content Format Conversion
- File Content Analysis
nist_csf:
- RS.MA-01
- RS.MA-02
- RS.AN-03
- RC.RP-01

Implementing Velociraptor for IR Collection

Overview

Velociraptor is an advanced open-source endpoint monitoring, digital forensics, and incident response platform developed by Rapid7. It uses the Velociraptor Query Language (VQL) to create custom artifacts that collect, query, and monitor almost any aspect of an endpoint. Velociraptor enables incident response teams to rapidly collect and examine forensic artifacts from across a network, supporting large-scale deployments with minimal performance impact. The client-server architecture with Fleetspeak communication enables real-time data collection from thousands of endpoints simultaneously, with offline endpoints picking up hunts when they reconnect.

When to Use

  • When deploying or configuring implementing velociraptor for ir collection capabilities in your environment
  • When establishing security controls aligned to compliance requirements
  • When building or improving security architecture for this domain
  • When conducting security assessments that require this implementation

Prerequisites

  • Familiarity with incident response concepts and tools
  • Access to a test or lab environment for safe execution
  • Python 3.8+ with required dependencies installed
  • Appropriate authorization for any testing activities

Architecture

Components

  • Velociraptor Server: Central management console with web UI and API
  • Velociraptor Client (Agent): Lightweight agent deployed to endpoints
  • Fleetspeak: Communication framework between client and server
  • VQL Engine: Query language engine for artifact collection
  • Filestore: Server-side storage for collected artifacts
  • Datastore: Metadata storage for hunts, flows, and client information

Supported Platforms

  • Windows (7+, Server 2008R2+)
  • Linux (Debian, Ubuntu, CentOS, RHEL)
  • macOS (10.13+)

Deployment

Server Installation

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

# Generate server configuration
./velociraptor-linux-amd64 config generate -i

# Start the server
./velociraptor-linux-amd64 --config server.config.yaml frontend

# Or run as systemd service
sudo cp velociraptor-linux-amd64 /usr/local/bin/velociraptor
sudo velociraptor --config /etc/velociraptor/server.config.yaml service install

Client Deployment

# Repack client MSI for Windows deployment
velociraptor --config server.config.yaml config client > client.config.yaml
velociraptor config repack --msi velociraptor-windows-amd64.msi client.config.yaml output.msi

# Deploy via Group Policy, SCCM, or Intune
# Client runs as a Windows service: "Velociraptor"

# Linux client deployment
velociraptor --config client.config.yaml client -v

# macOS client deployment
velociraptor --config client.config.yaml client -v

Docker Deployment

docker run --name velociraptor \
  -v /opt/velociraptor:/velociraptor/data \
  -p 8000:8000 -p 8001:8001 -p 8889:8889 \
  velocidex/velociraptor

Core IR Artifact Collection

Windows Forensic Artifacts

-- Collect Windows Event Logs
SELECT * FROM Artifact.Windows.EventLogs.EvtxHunter(
  EvtxGlob="C:/Windows/System32/winevt/Logs/*.evtx",
  IDRegex="4624|4625|4648|4672|4688|4698|4769|7045"
)

-- Collect Prefetch files for execution evidence
SELECT * FROM Artifact.Windows.Forensics.Prefetch()

-- Collect Shimcache entries
SELECT * FROM Artifact.Windows.Registry.AppCompatCache()

-- Collect Amcache entries
SELECT * FROM Artifact.Windows.Forensics.Amcache()

-- Collect UserAssist data
SELECT * FROM Artifact.Windows.Forensics.UserAssist()

-- Collect NTFS MFT timestamps
SELECT * FROM Artifact.Windows.NTFS.MFT(
  MFTFilename="C:/$MFT",
  FileRegex=".(exe|dll|ps1|bat|cmd)$"
)

-- Collect scheduled tasks
SELECT * FROM Artifact.Windows.System.TaskScheduler()

-- Collect running processes with hashes
SELECT * FROM Artifact.Windows.System.Pslist()

-- Collect network connections
SELECT * FROM Artifact.Windows.Network.Netstat()

-- Collect DNS cache
SELECT * FROM Artifact.Windows.Network.DNSCache()

-- Collect browser history
SELECT * FROM Artifact.Windows.Applications.Chrome.History()

-- Collect PowerShell history
SELECT * FROM Artifact.Windows.Forensics.PowerShellHistory()

-- Collect autoruns/persistence
SELECT * FROM Artifact.Windows.Persistence.PermanentWMIEvents()
SELECT * FROM Artifact.Windows.System.Services()
SELECT * FROM Artifact.Windows.System.StartupItems()

Linux Forensic Artifacts

-- Collect auth logs
SELECT * FROM Artifact.Linux.Sys.AuthLogs()

-- Collect bash history
SELECT * FROM Artifact.Linux.Forensics.BashHistory()

-- Collect crontab entries
SELECT * FROM Artifact.Linux.Sys.Crontab()

-- Collect running processes
SELECT * FROM Artifact.Linux.Sys.Pslist()

-- Collect network connections
SELECT * FROM Artifact.Linux.Network.Netstat()

-- Collect SSH authorized keys
SELECT * FROM Artifact.Linux.Ssh.AuthorizedKeys()

-- Collect systemd services
SELECT * FROM Artifact.Linux.Services()

Triage Collection (All-in-One)

-- Windows Triage Collection artifact
-- Collects event logs, prefetch, registry, browser data, and more
SELECT * FROM Artifact.Windows.KapeFiles.Targets(
  Device="C:",
  _AllFiles=FALSE,
  _EventLogs=TRUE,
  _Prefetch=TRUE,
  _RegistryHives=TRUE,
  _WebBrowsers=TRUE,
  _WindowsTimeline=TRUE
)

Hunt Operations

Creating a Hunt

1. Navigate to Hunt Manager in Velociraptor Web UI
2. Click "New Hunt"
3. Configure:
   - Description: "IR Triage - Case 2025-001"
   - Include/Exclude labels for targeting
   - Artifact selection (e.g., Windows.Forensics.Prefetch)
   - Resource limits (CPU, IOPS, timeout)
4. Launch hunt
5. Monitor progress in real-time

VQL Hunt Examples

-- Hunt for specific file hash across all endpoints
SELECT * FROM Artifact.Generic.Detection.HashHunter(
  Hashes="e99a18c428cb38d5f260853678922e03"
)

-- Hunt for YARA signatures in memory
SELECT * FROM Artifact.Windows.Detection.Yara.Process(
  YaraRule='rule malware { strings: $s1 = "malicious_string" condition: $s1 }'
)

-- Hunt for Sigma rule matches in event logs
SELECT * FROM Artifact.Server.Import.SigmaRules()

-- Hunt for suspicious scheduled tasks
SELECT * FROM Artifact.Windows.System.TaskScheduler()
WHERE Command =~ "powershell|cmd|wscript|mshta|rundll32"

-- Hunt for processes with network connections to suspicious IPs
SELECT * FROM Artifact.Windows.Network.Netstat()
WHERE RemoteAddr =~ "10\\.13\\.37\\."

Real-Time Monitoring

-- Monitor for new process creation
SELECT * FROM watch_etw(guid="{22fb2cd6-0e7b-422b-a0c7-2fad1fd0e716}")
WHERE EventData.ImageName =~ "powershell|cmd|wscript"

-- Monitor file system changes
SELECT * FROM watch_directory(path="C:/Windows/Temp/")

-- Monitor registry changes
SELECT * FROM watch_registry(key="HKLM/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/**")

Integration with SIEM/SOAR

Splunk Integration

Velociraptor Server --> Elastic/OpenSearch --> Splunk HEC
                   --> Direct syslog forwarding
                   --> Velociraptor API --> Custom scripts --> Splunk

Elastic Stack Integration

# Velociraptor server config for Elastic output
Monitoring:
  elastic:
    addresses:
      - https://elastic.local:9200
    username: velociraptor
    password: secure_password
    index: velociraptor

MITRE ATT&CK Mapping

Technique VQL Artifact
T1059 - Command Scripting Windows.EventLogs.EvtxHunter (4104, 4688)
T1053 - Scheduled Task Windows.System.TaskScheduler
T1547 - Boot/Logon Autostart Windows.Persistence.PermanentWMIEvents
T1003 - OS Credential Dumping Windows.Detection.Yara.Process
T1021 - Remote Services Windows.EventLogs.EvtxHunter (4624 Type 3/10)
T1070 - Indicator Removal Windows.EventLogs.Cleared

References

Other files in this skill

assets/template.md (verbatim)

Velociraptor IR Collection Report Template

Case Information

Field Details
Case ID
Velociraptor Server
Collection Start
Collection End
Lead Analyst
Endpoints Targeted
Endpoints Collected

Collection Scope

Target Endpoints

Hostname IP Address OS Client ID Status

Artifacts Collected

Artifact Description Endpoints Events
Windows.EventLogs.EvtxHunter Security event logs
Windows.Forensics.Prefetch Program execution
Windows.System.Pslist Running processes
Windows.Network.Netstat Network connections

Hunt Results

Hunt ID Description Endpoints Hit Matches

Key Findings

Finding 1

  • Host:
  • Artifact:
  • Description:
  • Severity:
  • Evidence:

IOC Matches

IOC Type Value Hosts Matched Details

Collection Issues

Host Issue Resolution

Recommendations

references/api-reference.md (verbatim)

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"
}

references/standards.md (verbatim)

Standards and Frameworks for Velociraptor IR Collection

NIST SP 800-86 - Guide to Integrating Forensic Techniques

  • Evidence collection procedures for digital investigations
  • Chain of custody requirements for forensic data
  • Volatile and non-volatile evidence prioritization

ForensicArtifacts Standard

SANS DFIR Collection Standards

  • FOR500: Windows Forensic Analysis artifact prioritization
  • FOR508: Advanced Incident Response collection methodology
  • Evidence acquisition order of volatility
  • Triage collection best practices

Velociraptor Query Language (VQL) Reference

MITRE ATT&CK Framework

  • Artifact mapping to ATT&CK techniques
  • Detection-oriented collection strategies
  • Threat-informed artifact selection
  • Reference: https://attack.mitre.org/

Sigma Detection Standard

  • Velociraptor supports Sigma rule execution on endpoints
  • Direct event log analysis without SIEM forwarding
  • Community detection rules integration
  • Reference: https://github.com/SigmaHQ/sigma

Rapid7 Integration Standards

  • InsightIDR SIEM integration documentation
  • Managed Detection and Response workflows
  • Velociraptor alert forwarding specifications

references/workflows.md (verbatim)

Velociraptor IR Collection Workflows

Workflow 1: Rapid Triage Collection

START: Incident Detected - Triage Needed
  |
  v
[Identify Target Endpoints]
  |-- Search clients by hostname, IP, or label
  |-- Verify client connectivity status
  |-- Label endpoints as "investigation_targets"
  |
  v
[Launch Triage Collection]
  |-- Select triage artifact pack
  |-- Configure collection parameters
  |-- Set resource limits (CPU, bandwidth)
  |-- Launch flow on target endpoints
  |
  v
[Monitor Collection Progress]
  |-- View flow status in Velociraptor UI
  |-- Check for collection errors
  |-- Verify artifact completeness
  |
  v
[Download and Analyze Results]
  |-- Export collected data
  |-- Import into timeline tool
  |-- Begin forensic analysis
  |
  v
END: Triage Data Available for Analysis

Workflow 2: Enterprise-Wide Hunt

START: IOC or Threat Intelligence Received
  |
  v
[Create Hunt]
  |-- Define hunt description and scope
  |-- Select target artifacts
  |-- Configure IOC-based VQL queries
  |-- Set include/exclude labels
  |
  v
[Launch Hunt]
  |-- Deploy to all matching endpoints
  |-- Offline endpoints queued for pickup
  |-- Monitor completion percentage
  |
  v
[Analyze Hunt Results]
  |-- Review matches and anomalies
  |-- Identify compromised endpoints
  |-- Label affected systems
  |
  v
[Escalate Findings]
  |-- Create detailed flows for hits
  |-- Collect additional artifacts
  |-- Feed results into IR process
  |
  v
END: Hunt Complete - Findings Documented

Workflow 3: Live Incident Response

START: Active Compromise Detected
  |
  v
[Connect to Affected Endpoint]
  |-- Open VQL shell in Velociraptor UI
  |-- Verify system identity and status
  |
  v
[Volatile Evidence Collection]
  |-- Running processes (pslist)
  |-- Network connections (netstat)
  |-- DNS cache
  |-- Open file handles
  |-- Loaded DLLs
  |-- Memory strings (if needed)
  |
  v
[Persistence Check]
  |-- Scheduled tasks
  |-- Services
  |-- Registry autorun keys
  |-- WMI subscriptions
  |-- Startup folder items
  |
  v
[Non-Volatile Evidence]
  |-- Event logs
  |-- Prefetch files
  |-- MFT entries
  |-- Browser history
  |-- PowerShell history
  |
  v
[Containment Decision]
  |-- Enough evidence to contain?
  |-- Isolate endpoint if needed
  |-- Continue monitoring if needed
  |
  v
END: Evidence Collected - Containment Executed

Workflow 4: Deployment at Scale

START: Velociraptor Deployment Project
  |
  v
[Server Setup]
  |-- Deploy server on dedicated host
  |-- Configure SSL certificates
  |-- Set up authentication (SSO/SAML)
  |-- Configure storage backend
  |
  v
[Client Configuration]
  |-- Generate client config from server
  |-- Repack client installers
  |-- Test on pilot group
  |
  v
[Mass Deployment]
  |-- GPO deployment (Windows)
  |-- Configuration management (Linux)
  |-- MDM deployment (macOS)
  |-- Verify connectivity
  |
  v
[Operational Configuration]
  |-- Set up monitoring artifacts
  |-- Configure event forwarding
  |-- Create standard hunt templates
  |-- Document SOPs for analysts
  |
  v
END: Velociraptor Operational at Scale

Back to mukul975/Anthropic-Cybersecurity-Skills (817 security skills) or Agent skills.