velociraptor

Launch Velociraptor forensic collections and work with collection results in LimaCharlie.

---

LimaCharlie Integration

Prerequisites: Run /init-lc to initialize LimaCharlie context.

LimaCharlie CLI Access

All LimaCharlie operations use the limacharlie CLI directly:

limacharlie <noun> <verb> --oid <oid> --output yaml [flags]

For command help and discovery: limacharlie <command> --ai-help

Critical Rules

| Rule | Wrong | Right | |------|-------|-------| | CLI Access | Call MCP tools or spawn api-executor | Use Bash("limacharlie ...") directly | | Output Format | --output json | --output yaml (more token-efficient) | | Filter Output | Pipe to jq/yq | Use --filter JMESPATH to select fields | | LCQL Queries | Write query syntax manually | Use limacharlie ai generate-query first | | Timestamps | Calculate epoch values | Use date +%s or date -d '7 days ago' +%s | | OID | Use org name | Use UUID (call limacharlie org list if needed) |

---

Background

Velociraptor is an open source endpoint visibility tool for digital forensics, incident response, and triage. LimaCharlie integrates with Velociraptor via the ext-velociraptor extension.

How Velociraptor Data Flows in LimaCharlie

When a Velociraptor collection runs:

1. Raw Artifacts: The collected data is stored as a ZIP file in LimaCharlie's Artifact system

   • Filter by: artifact_type: velociraptor
   • The source field contains the Sensor ID (SID) where it was collected

2. Processed Events: For small collections, data is also processed to JSON and ingested as sensor events

   • Events appear on a sensor with hostname: velociraptor
   • Tagged with: ext:ext-velociraptor
   • Event types: velociraptor_collection, artifact_event

3. D&R Automation: You can trigger on these events for automated workflows

When to Use

Use this skill when the user wants to:

• List available Velociraptor artifacts for collection
• View the YAML definition of a specific artifact
• Launch Velociraptor collections on endpoints
• Find and download raw Velociraptor collection data
• Query processed Velociraptor events
• Build D&R rules for Velociraptor automation

Prerequisites

The organization must have the ext-velociraptor extension subscribed.

The limacharlie CLI must be available.

How to Use

Step 1: Get the Organization ID

If not already known, get the OID:

limacharlie org list --output yaml

Step 2: List Available Velociraptor Artifacts

List all VQL artifacts available for collection (built-in and external from triage.velocidex.com):

limacharlie extension request --name ext-velociraptor --action list_artifacts --oid <oid> --output yaml

Step 3: View Artifact Definition

Before collecting, view an artifact's YAML to understand its parameters:

limacharlie extension request --name ext-velociraptor --action show_artifact \
  --data '{"artifact_name": "Windows.System.Drivers"}' --oid <oid> --output yaml

Step 4: Launch a Collection

Collect from a single sensor:

limacharlie extension request --name ext-velociraptor --action collect \
  --data '{"artifact_list": ["Windows.System.Drivers"], "sid": "<sensor-id>"}' \
  --oid <oid> --output yaml

Collect from multiple sensors using a selector:

limacharlie extension request --name ext-velociraptor --action collect \
  --data '{"artifact_list": ["Windows.KapeFiles.Targets"], "sensor_selector": "plat == windows", "args": "KapeTriage=Y", "collection_ttl": 3600, "retention_ttl": 7}' \
  --oid <oid> --output yaml

Step 5: Find Collection Results (Raw Artifacts)

List raw Velociraptor artifacts stored in the Artifact system:

limacharlie artifact list --type velociraptor --sid <sensor-id> --oid <oid> --output yaml

Download an artifact:

limacharlie artifact download --id <artifact-id> --oid <oid> --output yaml

Step 6: Query Processed Events

For small collections, data is also available as events. Use LCQL to query them.

CRITICAL: Always use limacharlie ai generate-query first - never write LCQL manually.

limacharlie ai generate-query --prompt "velociraptor_collection events from the last 7 days" --oid <oid> --output yaml

Then execute:

limacharlie search run --query "<generated-query>" --start <ts> --end <ts> --oid <oid> --output yaml

Step 7: Find the Velociraptor Sensor

To find the virtual sensor that receives processed Velociraptor data:

limacharlie sensor list --selector "\`ext:ext-velociraptor\` in tags" --oid <oid> --output yaml

Collection Parameters

| Parameter | Type | Description | |-----------|------|-------------| | artifact_list | string[] | List of artifacts to collect (use one of artifact_list OR custom_artifact) | | custom_artifact | string | Custom artifact YAML definition | | sid | string | Single sensor ID (use one of sid OR sensor_selector) | | sensor_selector | string | bexpr selector for multiple sensors (e.g., plat == windows) | | args | string | Comma-separated artifact arguments (e.g., KapeTriage=Y,EventLogs=Y) | | collection_ttl | int | Seconds to keep attempting collection (default: 604800 = 7 days) | | retention_ttl | int | Days to retain collected artifacts (default: 7) | | ignore_cert | bool | Ignore SSL certificate errors during collection |

Common Velociraptor Artifacts

| Artifact | Platform | Description | |----------|----------|-------------| | Windows.KapeFiles.Targets | Windows | KAPE-style triage collection | | Windows.System.Pslist | Windows | Running processes | | Windows.System.Drivers | Windows | Loaded kernel drivers | | Windows.Network.Netstat | Windows | Network connections | | Windows.EventLogs.Evtx | Windows | Windows event logs | | Windows.Registry.UserAssist | Windows | User activity tracking | | Generic.System.Pstree | All | Process tree | | Linux.Sys.Users | Linux | User accounts | | Linux.Sys.Syslog | Linux | System logs | | MacOS.Applications.List | macOS | Installed applications |

Example D&R Rules

Trigger on Artifact Upload

Detect when a Velociraptor collection completes:

# Detection
op: is
path: routing/log_type
value: velociraptor
target: artifact_event

# Response
- action: report
  name: Velociraptor Collection Complete
- action: output
  name: my-siem-output

Trigger on Collection Data

Process the actual collection data:

# Detection
event: velociraptor_collection
op: exists
path: event/collection

# Response
- action: report
  name: Velociraptor Data Available
- action: output
  name: bigquery-tailored

Trigger Collection from Detection

Start a Velociraptor collection as a response action:

# Response (add to any detection)
- action: extension request
  extension action: collect
  extension name: ext-velociraptor
  extension request:
    artifact_list: ['Windows.KapeFiles.Targets']
    sid: '{{ .routing.sid }}'
    args: 'KapeTriage=Y'
    collection_ttl: 3600
    retention_ttl: 7

Timestamps

When working with artifacts:

• API parameters (start, end in list_artifacts): Unix seconds (10 digits)
• Never calculate timestamps manually - use bash:

date +%s                        # Now
date -d '24 hours ago' +%s      # 24 hours ago
date -d '7 days ago' +%s        # 7 days ago

Important Notes

• Async operation: collect_velociraptor_artifact returns immediately with a job_id; results are ingested asynchronously
• Offline sensors: Uses reliable-tasking for persistent delivery; collection attempts continue until collection_ttl expires
• EDR sensors only: Velociraptor collections can only run on EDR agents:
  • Platform: Windows (x86/x64), Linux (386/amd64/arm64), macOS (amd64/arm64)
  • Architecture: Must NOT be usp_adapter (code 9) - adapters cannot run collections
  • Use combined selector: (plat==windows or plat==linux or plat==macos) and arch!=usp_adapter
• External artifacts: Automatically downloaded from triage.velocidex.com if needed
• Batch limit: Up to 100 sensors can be tasked in parallel
• Max artifact size: Results larger than 100 MB (configurable) are skipped
• Large collections: Raw artifacts may be large (hundreds of MB). Use get_url_only: true and download externally

Related Skills

• list-artifacts / get-artifact - Work with raw artifact files
• detection-engineering - Build D&R rules for Velociraptor events
• sensor-tasking - Execute live commands (alternative to Velociraptor for some use cases)

Reference

• Velociraptor Extension Documentation
• Velociraptor to BigQuery Tutorial
• Use limacharlie extension request --ai-help for CLI help