Skip to content

Commit 7c3e08d

Browse files
skyopsaiskyopsai
committed
add skill ir/velociraptor
1 parent c53bdda commit 7c3e08d

13 files changed

Lines changed: 4886 additions & 0 deletions

‎skills/incident-response/ir-velociraptor/SKILL.md‎

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
---
2+
name: ir-velociraptor
3+
description: >
4+
Endpoint visibility, digital forensics, and incident response using Velociraptor
5+
Query Language (VQL) for evidence collection and threat hunting at scale. Use when:
6+
(1) Conducting forensic investigations across multiple endpoints, (2) Hunting for
7+
indicators of compromise or suspicious activities, (3) Collecting endpoint telemetry
8+
and artifacts for incident analysis, (4) Performing live response and evidence
9+
preservation, (5) Monitoring endpoints for security events, (6) Creating custom
10+
forensic artifacts for specific threat scenarios.
11+
version: 0.1.0
12+
maintainer: asrour
13+
category: incident-response
14+
tags: [forensics, incident-response, endpoint-detection, threat-hunting, vql, dfir, live-response, evidence-collection]
15+
frameworks: [MITRE-ATT&CK, NIST]
16+
dependencies:
17+
tools: [velociraptor]
18+
references:
19+
- https://docs.velociraptor.app/
20+
- https://github.com/Velocidex/velociraptor
21+
- https://docs.velociraptor.app/artifact_references/
22+
---
23+
24+
# Velociraptor Incident Response
25+
26+
## Overview
27+
28+
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).
29+
30+
**When to use this skill**:
31+
- Active incident response requiring endpoint evidence collection
32+
- Threat hunting across enterprise infrastructure
33+
- Digital forensics investigations and timeline analysis
34+
- Endpoint monitoring and anomaly detection
35+
- Custom forensic artifact development for specific threats
36+
37+
## Quick Start
38+
39+
### Local Forensic Triage (Standalone Mode)
40+
41+
```bash
42+
# Download Velociraptor binary for your platform
43+
# https://github.com/Velocidex/velociraptor/releases
44+
45+
# Run GUI mode for interactive investigation
46+
velociraptor gui
47+
48+
# Access web interface at https://127.0.0.1:8889/
49+
# Default admin credentials shown in console output
50+
```
51+
52+
### Enterprise Server Deployment
53+
54+
```bash
55+
# Generate server configuration
56+
velociraptor config generate > server.config.yaml
57+
58+
# Start server
59+
velociraptor --config server.config.yaml frontend
60+
61+
# Generate client configuration
62+
velociraptor --config server.config.yaml config client > client.config.yaml
63+
64+
# Deploy clients across endpoints
65+
velociraptor --config client.config.yaml client
66+
```
67+
68+
## Core Incident Response Workflows
69+
70+
### Workflow 1: Initial Compromise Investigation
71+
72+
Progress:
73+
[ ] 1. Identify affected endpoints and timeframe
74+
[ ] 2. Collect authentication logs and suspicious logins
75+
[ ] 3. Gather process execution history and command lines
76+
[ ] 4. Extract network connection artifacts
77+
[ ] 5. Collect persistence mechanisms (scheduled tasks, autoruns, services)
78+
[ ] 6. Analyze file system modifications and suspicious files
79+
[ ] 7. Extract memory artifacts if needed
80+
[ ] 8. Build timeline and document IOCs
81+
82+
Work through each step systematically. Check off completed items.
83+
84+
**Key VQL Artifacts**:
85+
- `Windows.EventLogs.RDP` - Remote desktop authentication events
86+
- `Windows.System.Pslist` - Running processes with details
87+
- `Windows.Network.NetstatEnriched` - Network connections with process context
88+
- `Windows.Persistence.PermanentWMIEvents` - WMI-based persistence
89+
- `Windows.Timeline.Prefetch` - Program execution timeline
90+
- `Windows.Forensics.Timeline` - Comprehensive filesystem timeline
91+
92+
### Workflow 2: Threat Hunting Campaign
93+
94+
Progress:
95+
[ ] 1. Define threat hypothesis and IOCs
96+
[ ] 2. Select or create custom VQL artifacts for detection
97+
[ ] 3. Create hunt targeting relevant endpoint groups
98+
[ ] 4. Execute hunt across infrastructure
99+
[ ] 5. Monitor collection progress and errors
100+
[ ] 6. Analyze results and identify positive matches
101+
[ ] 7. Triage findings and escalate confirmed threats
102+
[ ] 8. Document TTPs and update detections
103+
104+
Work through each step systematically. Check off completed items.
105+
106+
**Common Hunt Scenarios**:
107+
- Lateral movement detection (PsExec, WMI, remote services)
108+
- Webshell identification on web servers
109+
- Suspicious scheduled task discovery
110+
- Credential dumping tool artifacts
111+
- Malicious PowerShell execution patterns
112+
113+
### Workflow 3: Evidence Collection for Forensics
114+
115+
Progress:
116+
[ ] 1. Document collection requirements and scope
117+
[ ] 2. Create offline collector with required artifacts
118+
[ ] 3. Deploy collector to target endpoint(s)
119+
[ ] 4. Execute collection and verify completion
120+
[ ] 5. Retrieve collection archive
121+
[ ] 6. Validate evidence integrity (hashes)
122+
[ ] 7. Import into forensic platform for analysis
123+
[ ] 8. Document chain of custody
124+
125+
Work through each step systematically. Check off completed items.
126+
127+
```bash
128+
# Create offline collector (no server required)
129+
velociraptor --config server.config.yaml artifacts collect \
130+
Windows.KapeFiles.Targets \
131+
Windows.EventLogs.Evtx \
132+
Windows.Registry.Sysinternals.Eulacheck \
133+
--output /path/to/collection.zip
134+
135+
# For custom artifact collection
136+
velociraptor artifacts collect Custom.Artifact.Name --args param=value
137+
```
138+
139+
## VQL Query Patterns
140+
141+
### Pattern 1: Process Investigation
142+
143+
Search for suspicious process execution patterns:
144+
145+
```sql
146+
-- Find processes with unusual parent-child relationships
147+
SELECT Pid, Ppid, Name, CommandLine, Username, Exe
148+
FROM pslist()
149+
WHERE Name =~ "(?i)(powershell|cmd|wscript|cscript)"
150+
AND CommandLine =~ "(?i)(invoke|download|iex|bypass|hidden)"
151+
```
152+
153+
### Pattern 2: Network Connection Analysis
154+
155+
Identify suspicious network connections:
156+
157+
```sql
158+
-- Active connections with process context
159+
SELECT Laddr.IP AS LocalIP,
160+
Laddr.Port AS LocalPort,
161+
Raddr.IP AS RemoteIP,
162+
Raddr.Port AS RemotePort,
163+
Status, Pid,
164+
process_tracker_get(id=Pid).Name AS ProcessName,
165+
process_tracker_get(id=Pid).CommandLine AS CommandLine
166+
FROM netstat()
167+
WHERE Status = "ESTABLISHED"
168+
AND Raddr.IP =~ "^(?!10\\.)" -- External IPs only
169+
```
170+
171+
### Pattern 3: File System Forensics
172+
173+
Timeline suspicious file modifications:
174+
175+
```sql
176+
-- Recent file modifications in suspicious locations
177+
SELECT FullPath, Size, Mtime, Atime, Ctime, Btime
178+
FROM glob(globs="C:/Users/*/AppData/**/*.exe")
179+
WHERE Mtime > timestamp(epoch=now() - 86400) -- Last 24 hours
180+
ORDER BY Mtime DESC
181+
```
182+
183+
### Pattern 4: Registry Persistence
184+
185+
Hunt for registry-based persistence:
186+
187+
```sql
188+
-- Common autorun registry keys
189+
SELECT Key.Name AS RegistryKey,
190+
ValueName,
191+
ValueData
192+
FROM read_reg_key(globs="HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run/*")
193+
WHERE ValueData =~ "(?i)(powershell|cmd|wscript|rundll32)"
194+
```
195+
196+
For comprehensive VQL patterns and advanced queries, see [references/vql-patterns.md](references/vql-patterns.md)
197+
198+
## Custom Artifact Development
199+
200+
Create custom VQL artifacts for specific investigation needs:
201+
202+
```yaml
203+
name: Custom.Windows.SuspiciousProcess
204+
description: |
205+
Detect processes with suspicious characteristics for incident response.
206+
207+
parameters:
208+
- name: ProcessNameRegex
209+
default: "(?i)(powershell|cmd|wscript)"
210+
type: regex
211+
- name: CommandLineRegex
212+
default: "(?i)(invoke|download|bypass)"
213+
type: regex
214+
215+
sources:
216+
- query: |
217+
SELECT Pid, Ppid, Name, CommandLine, Username, Exe, CreateTime
218+
FROM pslist()
219+
WHERE Name =~ ProcessNameRegex
220+
AND CommandLine =~ CommandLineRegex
221+
```
222+
223+
Save artifacts in YAML format and import via Velociraptor UI or command line.
224+
225+
**For artifact development guidance**, see [references/artifact-development.md](references/artifact-development.md)
226+
227+
## Security Considerations
228+
229+
- **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.
230+
231+
- **Access Control**: Velociraptor server access provides significant endpoint control. Implement RBAC, audit all queries, and restrict administrative access. Use client certificates for authentication.
232+
233+
- **Audit Logging**: All VQL queries, hunts, and collections are logged. Enable audit trail for compliance. Document investigation scope and approvals.
234+
235+
- **Compliance**: Ensure evidence collection follows organizational policies and legal requirements. Document chain of custody for forensic investigations. Consider data sovereignty for multi-region deployments.
236+
237+
- **Operational Security**: Velociraptor generates significant endpoint activity. Plan for network bandwidth, endpoint performance impact, and detection by adversaries during covert investigations.
238+
239+
## Common Investigation Patterns
240+
241+
### Pattern: Ransomware Investigation
242+
243+
1. Identify patient zero endpoint
244+
2. Collect: `Windows.Forensics.Timeline` for file modification patterns
245+
3. Collect: `Windows.EventLogs.Evtx` for authentication events
246+
4. Hunt for: Lateral movement artifacts across network
247+
5. Hunt for: Scheduled tasks or services for persistence
248+
6. Extract: Ransomware binary samples for malware analysis
249+
7. Build: Timeline of infection spread and data encryption
250+
251+
### Pattern: Data Exfiltration Detection
252+
253+
1. Collect network connection history: `Windows.Network.NetstatEnriched`
254+
2. Identify large outbound transfers to unusual destinations
255+
3. Correlate with process execution and file access
256+
4. Hunt for: Compression tools or staging directories
257+
5. Examine: Browser downloads and cloud sync activities
258+
6. Review: DNS queries for tunneling or C2 domains
259+
7. Document: Data classification and breach scope
260+
261+
### Pattern: Insider Threat Investigation
262+
263+
1. Collect: User authentication and logon events
264+
2. Track: USB device connections and file transfers
265+
3. Monitor: Sensitive file access patterns
266+
4. Review: Email and browser history (with authorization)
267+
5. Analyze: Print spooler activity for document printing
268+
6. Examine: Cloud storage access and uploads
269+
7. Build: User activity timeline with behavioral anomalies
270+
271+
## Integration Points
272+
273+
- **SIEM Integration**: Export VQL results to Splunk, Elastic, or other SIEM platforms for correlation
274+
- **Threat Intel Platforms**: Enrich IOCs with TIP integrations via VQL plugins
275+
- **SOAR Platforms**: Trigger automated Velociraptor hunts from SOAR playbooks
276+
- **Forensic Suites**: Import Velociraptor collections into X-Ways, Autopsy, or EnCase
277+
- **EDR Interoperability**: Complement EDR with custom VQL detections and forensic depth
278+
279+
## Troubleshooting
280+
281+
### Issue: High CPU Usage During Collection
282+
283+
**Solution**:
284+
- Limit concurrent VQL queries using `rate()` function
285+
- Reduce glob scope to specific directories
286+
- Use `--ops_per_second` limit when creating offline collectors
287+
- Schedule resource-intensive hunts during maintenance windows
288+
289+
### Issue: Client Not Reporting to Server
290+
291+
**Solution**:
292+
- Verify network connectivity and firewall rules (default: TCP 8000)
293+
- Check client logs: `velociraptor --config client.config.yaml logs`
294+
- Validate client certificate and enrollment status
295+
- Ensure server frontend is running and accessible
296+
297+
### Issue: VQL Query Returns No Results
298+
299+
**Solution**:
300+
- Test query in local notebook mode first
301+
- Verify filesystem paths use correct syntax (forward slashes)
302+
- Check plugin availability on target OS
303+
- Use `log()` function to debug query execution
304+
- Review client event logs for permission errors
305+
306+
## Bundled Resources
307+
308+
### Scripts (`scripts/`)
309+
310+
- `vql_query_builder.py` - Generate common VQL queries from templates
311+
- `artifact_validator.py` - Validate custom artifact YAML syntax
312+
- `evidence_collector.sh` - Automate offline collector deployment
313+
314+
### References (`references/`)
315+
316+
- `vql-patterns.md` - Comprehensive VQL query patterns for common IR scenarios
317+
- `artifact-development.md` - Guide to creating custom forensic artifacts
318+
- `mitre-attack-mapping.md` - MITRE ATT&CK technique detection artifacts
319+
- `deployment-guide.md` - Enterprise server deployment and architecture
320+
321+
### Assets (`assets/`)
322+
323+
- `artifact-template.yaml` - Template for custom artifact development
324+
- `hunt-template.yaml` - Hunt configuration template with best practices
325+
- `offline-collector-config.yaml` - Offline collector configuration example
326+
327+
## References
328+
329+
- [Velociraptor Documentation](https://docs.velociraptor.app/)
330+
- [VQL Reference](https://docs.velociraptor.app/vql_reference/)
331+
- [Artifact Exchange](https://docs.velociraptor.app/exchange/)
332+
- [GitHub Repository](https://github.com/Velocidex/velociraptor)
333+
- [MITRE ATT&CK Framework](https://attack.mitre.org/)

‎skills/incident-response/ir-velociraptor/assets/.gitkeep‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Assets Directory
2+
3+
Place files that will be used in the output Claude produces:
4+
- Templates
5+
- Configuration files
6+
- Images/logos
7+
- Boilerplate code
8+
9+
These files are NOT loaded into context but copied/modified in output.

0 commit comments

Comments
 (0)