ir-velociraptor
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.
What this skill does
# 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)
```bash
# 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
```bash
# 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.
```bash
# 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:
```sql
-- 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:
```sql
-- 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:
```sql
-- 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:
```sql
-- 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](references/vql-patterns.md)
## Custom Artifact Development
Create custom VQL artifacts for specific investigation needs:
```yaml
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](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 Related in incident-response
detection-sigma
IncludedGeneric detection rule creation and management using Sigma, the universal SIEM rule format. Sigma provides vendor-agnostic detection logic for log analysis across multiple SIEM platforms. Use when: (1) Creating detection rules for security monitoring, (2) Converting rules between SIEM platforms (Splunk, Elastic, QRadar, Sentinel), (3) Threat hunting with standardized detection patterns, (4) Building detection-as-code pipelines, (5) Mapping detections to MITRE ATT&CK tactics, (6) Implementing compliance-based monitoring rules.
detection-sigma
IncludedGeneric detection rule creation and management using Sigma, the universal SIEM rule format. Sigma provides vendor-agnostic detection logic for log analysis across multiple SIEM platforms. Use when: (1) Creating detection rules for security monitoring, (2) Converting rules between SIEM platforms (Splunk, Elastic, QRadar, Sentinel), (3) Threat hunting with standardized detection patterns, (4) Building detection-as-code pipelines, (5) Mapping detections to MITRE ATT&CK tactics, (6) Implementing compliance-based monitoring rules.
forensics-osquery
IncludedSQL-powered forensic investigation and system interrogation using osquery to query operating systems as relational databases. Enables rapid evidence collection, threat hunting, and incident response across Linux, macOS, and Windows endpoints. Use when: (1) Investigating security incidents and collecting forensic artifacts, (2) Threat hunting across endpoints for suspicious activity, (3) Analyzing running processes, network connections, and persistence mechanisms, (4) Collecting system state during incident response, (5) Querying file hashes, user activity, and system configuration for compromise indicators, (6) Building detection queries for continuous monitoring with osqueryd.
forensics-osquery
IncludedSQL-powered forensic investigation and system interrogation using osquery to query operating systems as relational databases. Enables rapid evidence collection, threat hunting, and incident response across Linux, macOS, and Windows endpoints. Use when: (1) Investigating security incidents and collecting forensic artifacts, (2) Threat hunting across endpoints for suspicious activity, (3) Analyzing running processes, network connections, and persistence mechanisms, (4) Collecting system state during incident response, (5) Querying file hashes, user activity, and system configuration for compromise indicators, (6) Building detection queries for continuous monitoring with osqueryd.
ir-velociraptor
IncludedEndpoint 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.