ir-velociraptor

name	ir-velociraptor
description	Endpoint visibility, digital forensics, and incident response using Velociraptor Query Language (VQL) for evidence collection and threat hunting at scale. Use when: (1) Conducting forensic investigations across multiple endpoints, (2) Hunting for indicators of compromise or suspicious activities, (3) Collecting endpoint telemetry and artifacts for incident analysis, (4) Performing live response and evidence preservation, (5) Monitoring endpoints for security events, (6) Creating custom forensic artifacts for specific threat scenarios.
version	0.1.0
maintainer	SirAppSec
category	incident-response
tags	["forensics","incident-response","endpoint-detection","threat-hunting","vql","dfir","live-response","evidence-collection"]
frameworks	["MITRE-ATT&CK","NIST"]
dependencies	{"tools":["velociraptor"]}
references	["https://docs.velociraptor.app/","https://github.com/Velocidex/velociraptor","https://docs.velociraptor.app/artifact_references/"]

Velociraptor Incident Response

Overview

Velociraptor is an endpoint visibility and forensics platform for collecting host-based state information using Velociraptor Query Language (VQL). It operates in three core modes: Collect (targeted evidence gathering), Monitor (continuous event capture), and Hunt (proactive threat hunting).

When to use this skill:

• Active incident response requiring endpoint evidence collection
• Threat hunting across enterprise infrastructure
• Digital forensics investigations and timeline analysis
• Endpoint monitoring and anomaly detection
• Custom forensic artifact development for specific threats

Quick Start

Local Forensic Triage (Standalone Mode)

# Download Velociraptor binary for your platform
# https://github.com/Velocidex/velociraptor/releases

# Run GUI mode for interactive investigation
velociraptor gui

# Access web interface at https://127.0.0.1:8889/
# Default admin credentials shown in console output

Enterprise Server Deployment

# Generate server configuration
velociraptor config generate > server.config.yaml

# Start server
velociraptor --config server.config.yaml frontend

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

# Deploy clients across endpoints
velociraptor --config client.config.yaml client

Core Incident Response Workflows

Workflow 1: Initial Compromise Investigation

Progress: [ ] 1. Identify affected endpoints and timeframe [ ] 2. Collect authentication logs and suspicious logins [ ] 3. Gather process execution history and command lines [ ] 4. Extract network connection artifacts [ ] 5. Collect persistence mechanisms (scheduled tasks, autoruns, services) [ ] 6. Analyze file system modifications and suspicious files [ ] 7. Extract memory artifacts if needed [ ] 8. Build timeline and document IOCs

Work through each step systematically. Check off completed items.

Key VQL Artifacts:

• Windows.EventLogs.RDP - Remote desktop authentication events
• Windows.System.Pslist - Running processes with details
• Windows.Network.NetstatEnriched - Network connections with process context
• Windows.Persistence.PermanentWMIEvents - WMI-based persistence
• Windows.Timeline.Prefetch - Program execution timeline
• Windows.Forensics.Timeline - Comprehensive filesystem timeline

Workflow 2: Threat Hunting Campaign

Progress: [ ] 1. Define threat hypothesis and IOCs [ ] 2. Select or create custom VQL artifacts for detection [ ] 3. Create hunt targeting relevant endpoint groups [ ] 4. Execute hunt across infrastructure [ ] 5. Monitor collection progress and errors [ ] 6. Analyze results and identify positive matches [ ] 7. Triage findings and escalate confirmed threats [ ] 8. Document TTPs and update detections

Work through each step systematically. Check off completed items.

Common Hunt Scenarios:

• Lateral movement detection (PsExec, WMI, remote services)
• Webshell identification on web servers
• Suspicious scheduled task discovery
• Credential dumping tool artifacts
• Malicious PowerShell execution patterns

Workflow 3: Evidence Collection for Forensics

Progress: [ ] 1. Document collection requirements and scope [ ] 2. Create offline collector with required artifacts [ ] 3. Deploy collector to target endpoint(s) [ ] 4. Execute collection and verify completion [ ] 5. Retrieve collection archive [ ] 6. Validate evidence integrity (hashes) [ ] 7. Import into forensic platform for analysis [ ] 8. Document chain of custody

Work through each step systematically. Check off completed items.

# Create offline collector (no server required)
velociraptor --config server.config.yaml artifacts collect \
  Windows.KapeFiles.Targets \
  Windows.EventLogs.Evtx \
  Windows.Registry.Sysinternals.Eulacheck \
  --output /path/to/collection.zip

# For custom artifact collection
velociraptor artifacts collect Custom.Artifact.Name --args param=value

VQL Query Patterns

Pattern 1: Process Investigation

Search for suspicious process execution patterns:

-- Find processes with unusual parent-child relationships
SELECT Pid, Ppid, Name, CommandLine, Username, Exe
FROM pslist()
WHERE Name =~ "(?i)(powershell|cmd|wscript|cscript)"
  AND CommandLine =~ "(?i)(invoke|download|iex|bypass|hidden)"

Pattern 2: Network Connection Analysis

Identify suspicious network connections:

-- Active connections with process context
SELECT Laddr.IP AS LocalIP,
       Laddr.Port AS LocalPort,
       Raddr.IP AS RemoteIP,
       Raddr.Port AS RemotePort,
       Status, Pid,
       process_tracker_get(id=Pid).Name AS ProcessName,
       process_tracker_get(id=Pid).CommandLine AS CommandLine
FROM netstat()
WHERE Status = "ESTABLISHED"
  AND Raddr.IP =~ "^(?!10\\.)" -- External IPs only

Pattern 3: File System Forensics

Timeline suspicious file modifications:

-- Recent file modifications in suspicious locations
SELECT FullPath, Size, Mtime, Atime, Ctime, Btime
FROM glob(globs="C:/Users/*/AppData/**/*.exe")
WHERE Mtime > timestamp(epoch=now() - 86400) -- Last 24 hours
ORDER BY Mtime DESC

Pattern 4: Registry Persistence

Hunt for registry-based persistence:

-- Common autorun registry keys
SELECT Key.Name AS RegistryKey,
       ValueName,
       ValueData
FROM read_reg_key(globs="HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*")
WHERE ValueData =~ "(?i)(powershell|cmd|wscript|rundll32)"

For comprehensive VQL patterns and advanced queries, see references/vql-patterns.md

Custom Artifact Development

Create custom VQL artifacts for specific investigation needs:

name: Custom.Windows.SuspiciousProcess
description: |
  Detect processes with suspicious characteristics for incident response.

parameters:
  - name: ProcessNameRegex
    default: "(?i)(powershell|cmd|wscript)"
    type: regex
  - name: CommandLineRegex
    default: "(?i)(invoke|download|bypass)"
    type: regex

sources:
  - query: |
      SELECT Pid, Ppid, Name, CommandLine, Username, Exe, CreateTime
      FROM pslist()
      WHERE Name =~ ProcessNameRegex
        AND CommandLine =~ CommandLineRegex

Save artifacts in YAML format and import via Velociraptor UI or command line.

For artifact development guidance, see references/artifact-development.md

Security Considerations

• Sensitive Data Handling: VQL queries can collect credentials, PII, and sensitive files. Implement data minimization - only collect necessary evidence. Use encryption for evidence transport and storage.

• Access Control: Velociraptor server access provides significant endpoint control. Implement RBAC, audit all queries, and restrict administrative access. Use client certificates for authentication.

• Audit Logging: All VQL queries, hunts, and collections are logged. Enable audit trail for compliance. Document investigation scope and approvals.

• Compliance: Ensure evidence collection follows organizational policies and legal requirements. Document chain of custody for forensic investigations. Consider data sovereignty for multi-region deployments.

• Operational Security: Velociraptor generates significant endpoint activity. Plan for network bandwidth, endpoint performance impact, and detection by adversaries during covert investigations.

Common Investigation Patterns

Pattern: Ransomware Investigation

1. Identify patient zero endpoint
2. Collect: Windows.Forensics.Timeline for file modification patterns
3. Collect: Windows.EventLogs.Evtx for authentication events
4. Hunt for: Lateral movement artifacts across network
5. Hunt for: Scheduled tasks or services for persistence
6. Extract: Ransomware binary samples for malware analysis
7. Build: Timeline of infection spread and data encryption

Pattern: Data Exfiltration Detection

1. Collect network connection history: Windows.Network.NetstatEnriched
2. Identify large outbound transfers to unusual destinations
3. Correlate with process execution and file access
4. Hunt for: Compression tools or staging directories
5. Examine: Browser downloads and cloud sync activities
6. Review: DNS queries for tunneling or C2 domains
7. Document: Data classification and breach scope

Pattern: Insider Threat Investigation

1. Collect: User authentication and logon events
2. Track: USB device connections and file transfers
3. Monitor: Sensitive file access patterns
4. Review: Email and browser history (with authorization)
5. Analyze: Print spooler activity for document printing
6. Examine: Cloud storage access and uploads
7. Build: User activity timeline with behavioral anomalies

Integration Points

• SIEM Integration: Export VQL results to Splunk, Elastic, or other SIEM platforms for correlation
• Threat Intel Platforms: Enrich IOCs with TIP integrations via VQL plugins
• SOAR Platforms: Trigger automated Velociraptor hunts from SOAR playbooks
• Forensic Suites: Import Velociraptor collections into X-Ways, Autopsy, or EnCase
• EDR Interoperability: Complement EDR with custom VQL detections and forensic depth

Troubleshooting

Issue: High CPU Usage During Collection

Solution:

• Limit concurrent VQL queries using rate() function
• Reduce glob scope to specific directories
• Use --ops_per_second limit when creating offline collectors
• Schedule resource-intensive hunts during maintenance windows

Issue: Client Not Reporting to Server

Solution:

• Verify network connectivity and firewall rules (default: TCP 8000)
• Check client logs: velociraptor --config client.config.yaml logs
• Validate client certificate and enrollment status
• Ensure server frontend is running and accessible

Issue: VQL Query Returns No Results

Solution:

• Test query in local notebook mode first
• Verify filesystem paths use correct syntax (forward slashes)
• Check plugin availability on target OS
• Use log() function to debug query execution
• Review client event logs for permission errors

Bundled Resources

Scripts (scripts/)

• vql_query_builder.py - Generate common VQL queries from templates
• artifact_validator.py - Validate custom artifact YAML syntax
• evidence_collector.sh - Automate offline collector deployment

References (references/)

• vql-patterns.md - Comprehensive VQL query patterns for common IR scenarios
• artifact-development.md - Guide to creating custom forensic artifacts
• mitre-attack-mapping.md - MITRE ATT&CK technique detection artifacts
• deployment-guide.md - Enterprise server deployment and architecture

Assets (assets/)

• artifact-template.yaml - Template for custom artifact development
• hunt-template.yaml - Hunt configuration template with best practices
• offline-collector-config.yaml - Offline collector configuration example

References

• Velociraptor Documentation
• VQL Reference
• Artifact Exchange
• GitHub Repository
• MITRE ATT&CK Framework