# Velociraptor MCP Server — Comprehensive Documentation

> **Built by**: [mgreen27/mcp-velociraptor](https://github.com/mgreen27/mcp-velociraptor)  
> **Added onto by**: snoe-findley

This document serves as the comprehensive manual for the Velociraptor Model Context Protocol (MCP) Server. It outlines architecture mechanics, forensic constraints, and the full inventory of all supported DFIR, Triage, and Remediation tools across Windows, macOS, and Linux.

---

## Architecture & Implementation Principles

The Velociraptor MCP connects autonomous LLM agents to your Velociraptor deployment via the native gRPC API. 

### 1. Forensic Safety & Sanitization
*   **VQL Injection Prevention**: All inputs passed by the underlying AI agent are strictly scrubbed via `sanitize_vql_string` to strip out bare strings, inline syntax injections, and unescaped quotes.
*   **Result Limits**: Tools enforce a hard row limit (e.g., `LIMIT 500`) to guarantee that unbounded artifacts (like massive Event Log collections or MFT walks) do not overwhelm the LLM context window.

### 2. Concurrency Mechanics
Because forensic collections can take minutes to complete, synchronous networking is mitigated. All blocking gRPC artifact collections are bridged through `asyncio.to_thread`. This ensures the MCP server remains highly responsive and does not deadlock when servicing multiple agents or long-running hunts.

---

## Available MCP Tools

Once the MCP is connected to your platform, the following tool clusters are made available to the LLM agent.

### 🌐 Fleet Visibility (Aggregated / Agentless)

| Tool | Description | Artifact |
|---|---|---|
| `list_clients` | List all endpoints checking in — hostname, OS, last seen, client_id | `(Native API)` |
| `hunt_across_fleet` | Run an artifact collection across ALL endpoints at once | `(Dynamic)` |
| `get_hunt_results_tool` | Retrieve results from a completed hunt | `(Native API)` |
| `run_vql` | **[DISABLED BY DEFAULT - DANGEROUS]** Run arbitrary VQL queries | `(Raw VQL)` |
| `client_info` | Look up a single client by hostname | `(Native API)` |
| `list_windows_artifacts` | Discover all available Windows artifacts on the connected Velociraptor server | `(Server VQL)` |
| `list_linux_artifacts` | Discover all available Linux artifacts on the connected Velociraptor server | `(Server VQL)` |
| `list_macos_artifacts` | Discover all available macOS artifacts on the connected Velociraptor server | `(Server VQL)` |

### 🐧 Linux

**System & Enumeration**
| Tool | Description | Artifact |
|---|---|---|
| `linux_pslist` | List running processes | `Linux.Sys.Pslist` |
| `linux_groups` | List all user groups | `Linux.Sys.Groups` |
| `linux_mounts` | List active filesystem mounts | `Linux.Mounts` |
| `linux_netstat_enriched` | Network connections mapping strictly to their processes | `Linux.Network.NetstatEnriched` |
| `linux_users` | Complete inventory of all Linux users | `Linux.Sys.Users` |
| `linux_arp_cache` | ARP cache mapping local network neighbors | `Linux.Network.ArpCache` |

**Auth, Logs, & IOC Sweeps**
| Tool | Description | Artifact |
|---|---|---|
| `linux_bash_history` | Extract `.bash_history` from all active/historical users | `Linux.Sys.BashHistory` |
| `linux_ssh_logins` | Parse SSH authentication events directly from `auth.log` or syslog | `Linux.Syslog.SSHLogin` |
| `linux_last_user_login` | Parse `utmp` / `wtmp` bounds | `Linux.Sys.LastUserLogin` |
| `linux_journal_logs` | Deep search through `systemd` journal logs | `Linux.Forensics.Journal` |
| `linux_file_finder` | Search the filesystem for paths, sizes, YARA matches, or specific Hashes | `Linux.Search.FileFinder` |

**Persistence**
| Tool | Description | Artifact |
|---|---|---|
| `linux_crontab` | Dump current crontabs to hunt for persistent tasks | `Linux.Sys.Crontab` |
| `linux_services` | Inspect `systemd` persistence and active daemon configurations | `Linux.Sys.Services` |
| `linux_ssh_authorized_keys`| Hunt for attacker backdoors in `authorized_keys` files | `Linux.Sys.SSHAuthorizedKeys` |

### 🍎 macOS

**System & Persistence**
| Tool | Description | Artifact |
|---|---|---|
| `macos_pslist` | Process list mapping | `MacOS.Sys.Pslist` |
| `macos_users` | Enumeration of Mac local user accounts | `MacOS.Sys.Users` |
| `macos_netstat` | MacOS-specific network connections | `MacOS.Network.Netstat` |
| `macos_launch_agents` | Dump `LaunchAgents` and `LaunchDaemons` (primary macOS persistence) | `MacOS.Sys.LaunchAgents` |
| `macos_login_items` | Enumerate global user login items | `MacOS.Sys.LoginItems` |

**Forensics & User Activity**
| Tool | Description | Artifact |
|---|---|---|
| `macos_bash_history` | Dump `bash_history` and `zsh_history` for Mac users | `MacOS.Sys.BashHistory` |
| `macos_browser_history` | Recover browsing history for Chrome, Edge, and Safari | `MacOS.Applications.Chrome.History` |
| `macos_quarantine_events` | Parse Mac Quarantine data to detect exactly where and when files were downloaded | `MacOS.Forensics.Quarantine` |
| `macos_tcc_database` | Hunt for malicious apps granted Full Disk Access via TCC | `MacOS.System.TCC` |
| `macos_file_finder` | Search files via Glob, YARA, or file Hash | `MacOS.Search.FileFinder` |

### 🪟 Windows

**Process & Memory**
| Tool | Description | Artifact |
|---|---|---|
| `windows_pslist` | Advanced process list including Authenticode verification | `Windows.System.Pslist` |
| `windows_netstat_enriched` | Advanced Netstat mapping connections to their orchestrating processes | `Windows.Network.NetstatEnriched` |
| `windows_process_memory_strings`| Fast YARA scanning over active process memory targeting ASCII/Wide strings | `Windows.Detection.Yara.Process` |
| `windows_malfind` | Specialized forensic artifact looking for unbacked memory segments (VAD anomalies indicating injected code) | `Windows.Detection.Malfind` |
| `windows_mutants` | Enumerate system mutants/mutexes (critical for hunting known malware families) | `Windows.Detection.Mutants` |

**Persistence**
| Tool | Description | Artifact |
|---|---|---|
| `windows_scheduled_tasks` | Enumerate scheduled tasks with metadata — a primary persistence mechanism for attackers | `Windows.System.TaskScheduler` |
| `windows_services` | List all Windows services with hash, cert, and DLL metadata for detecting rogue service persistence | `Windows.System.Services` |
| `windows_autoruns` | Collect Run/RunOnce registry keys, startup folders, and other auto-start extension points | `Windows.Sys.StartupItems` |
| `windows_wmi_persistence` | Detect WMI event subscription persistence — stealthy technique binding event consumers to triggers | `Windows.Persistence.PermanentWMIEvents` |

**Authentication & Network**
| Tool | Description | Artifact |
|---|---|---|
| `windows_dns_cache` | Dump local DNS cache to reveal queried C2 domains without needing passive tapping | `Windows.System.DnsCache` |
| `windows_logon_events` | Parse 4624 events mapping logon sessions, source IPs, and specific accounts | `Windows.EventLogs.LogonSessions` |
| `windows_rdp_sessions` | Filter specifically for inbound and outbound RDP terminal services | `Windows.EventLogs.RDPAuth` |

**User Activity & Lateral Movement**
| Tool | Description | Artifact |
|---|---|---|
| `windows_recentdocs` | Parse RecentDocs registry keys showing recently accessed files per user | `Windows.Registry.RecentDocs` |
| `windows_shellbags` | Extract Shellbag registry entries revealing folder browsing history, even for deleted folders | `Windows.Forensics.Shellbags` |
| `windows_browser_history` | Collect browsing history from Chromium-based browsers (Chrome, Edge, Brave) | `Windows.Applications.Chrome.History` |
| `windows_evidence_of_download` | Collect Zone.Identifier ADS data proving file download origin URLs and referrers | `Windows.Analysis.EvidenceOfDownload` |
| `windows_mountpoints2` | Parse MountPoints2 registry entries — reveals mapped drives and network shares for lateral movement tracking | `Windows.Registry.MountPoints2` |
| `windows_mounted_mass_storage_usb` | Detect USB mass storage device history from the registry | `Windows.Mounted.Mass.Storage` |

**Forensics, Filesystem, & Eviction**
| Tool | Description | Artifact |
|---|---|---|
| `windows_event_logs` | Rapid EVTX grep over channels to locate targeted Event IDs or string patterns | `Windows.EventLogs.EvtxHunter` |
| `windows_event_log_cleared` | Anti-forensics check — specifically hunts for EID 104 and 1102 triggers | `Windows.EventLogs.EvtxHunter` |
| `windows_shadow_copies` | WMI bridge to enumerate Volume Shadow Copies | `Windows.System.WMIQuery` |
| `windows_timestomp` | Master File Table analysis: Map $SIA timestamps against $FNA to prove deliberate timestomping | `Windows.NTFS.Timestomp` |
| `windows_ntfs_mft` | Query the MFT by path regex and date range for hyper-fast filesystem mapping | `Windows.NTFS.MFT` |
| `windows_ntfs_mft_search` | Search the MFT by filename regex — use when targeting specific file names rather than paths | `Windows.NTFS.MFT` |
| `windows_usn_journal` | Extract USN Change Journal records to reconstruct deleted/renamed file timelines | `Windows.Forensics.Usn` |
| `windows_recycle_bin` | Read the Recycle Bin internal `$I` data structures | `Windows.Forensics.RecycleBin` |
| `windows_srum` | Unearth historical data exfiltration via 30-60 day Application Resource consumption tracking | `Windows.Forensics.SRUM` |
| `windows_hash_search` | Execute filesystem hunting for exact MD5/SHA hashes, specific files, or inline YARA rules | `Windows.Search.FileFinder` |

**Windows Execution Traces**
| Tool | Description | Artifact |
|---|---|---|
| `windows_execution_amcache` | Deep inspection of Amcache data for Application Execution verification | `Windows.Detection.Amcache` |
| `windows_execution_bam` | Review BAM (Background Activity Moderator) | `Windows.Forensics.Bam` |
| `windows_execution_activitiesCache`| Windows Timeline database metrics | `Windows.Forensics.Timeline` |
| `windows_execution_userassist` | Parse UserAssist Registry hives | `Windows.Registry.UserAssist` |
| `windows_execution_shimcache` | Parse ShimCache/AppCompatCache for temporal execution logging | `Windows.Registry.AppCompatCache` |
| `windows_execution_prefetch` | Forensically extract `.pf` files | `Windows.Forensics.Prefetch` |

**PowerShell Analysis**
| Tool | Description | Artifact |
|---|---|---|
| `windows_powershell_scriptblock` | Pull decoded PowerShell script blocks (EID 4104) directly from the telemetry logs | `Windows.EventLogs.EvtxHunter` |
| `windows_powershell_history` | Dump the operator-entered `ConsoleHost_history.txt` log from PSReadLine | `Windows.System.Powershell.PSReadline` |

### 🔬 YARA & Threat Detection

These tools allow the LLM agent to dynamically generate and deploy YARA rules for file and memory scanning across all supported operating systems.

| Tool | Description | Artifact |
|---|---|---|
| `yara_scan_files` | Scan files on a Windows endpoint using inline YARA rules via raw NTFS access — bypasses OS file locks | `Windows.Detection.Yara.NTFS` |
| `yara_scan_process` | Scan running process memory on Windows using inline YARA rules — detects fileless malware and injected shellcode | `Windows.Detection.Yara.Process` |
| `linux_yara_scan` | Scan running process memory on Linux using inline YARA rules — detects in-memory threats on Linux hosts | `Linux.Detection.Yara.Process` |

### 🚨 Orchestration & Active Response

> **⚠️ SECURITY WARNING: DANGEROUS TOOLS DISABLED BY DEFAULT**  
> Several tools in this category (`run_vql`, `quarantine_host`, `kill_process`) are deactivated by default. They grant arbitrary code execution and destructive capabilities that could disrupt business infrastructure. You accept a significant risk by enabling these.
> To activate them, you must set the environment variable `ENABLE_DANGEROUS_TOOLS=true`.

| Tool | Description | Artifact |
|---|---|---|
| `collect_artifact` | (Generic) Launch any arbitrary artifact on an endpoint without parsing the JSON — returns the `flow_id` to download manually later. | `(Any)` |
| `get_collection_results` | (Generic) Retrieve data via a `flow_id` from a previous collection. | `(Native API)` |
| `collect_forensic_triage` | Starts `Windows.KapeFiles.Targets`, zipping up MFT, Registry Hives, and Event logs for large-scale external review. | `Windows.KapeFiles.Targets` |
| `quarantine_host` | **[DISABLED BY DEFAULT - DANGEROUS]** Completely strip an endpoint off the network (while keeping the Velociraptor connection alive) using native firewall controls. | `Windows.Remediation.Quarantine` |
| `unquarantine_host` | Lift the network separation order. | `Windows.Remediation.Quarantine` |
| `kill_process` | **[DISABLED BY DEFAULT - DANGEROUS]** Obliterate an ongoing process by providing the PID. | `Generic.Utils.KillProcess` |
| `collect_file` | Explicitly zip and upload a single file directly from the endpoint's disk for downloading later. | `Generic.Collectors.File` |

---

## Appendix: Client Integrations & Specialized Environments

Most major LLM frontends utilize simple stdio connections (which is the main method outlined in the repo's README). However, you may need to integrate over local networks with orchestration nodes. If deploying using the Docker/SSE model (`docker compose up -d`), keep these transport paradigms in mind:

### n8n (Server-Sent Events)
n8n natively supports SSE configurations perfectly.
1. Add an **AI Agent** node.
2. In Tools, select the **MCP Client Tool**.
3. Point your endpoint to `http://<deployment-ip>:8088/sse`.

### Open WebUI (Streamable HTTP / OpenAPI)
Open WebUI does **not** consume standard SSE effectively. It expects an OpenAPI wrapper. 
**Tip:** If you need to map this MCP server into Open WebUI, rely on proxy sidecars like the `mcpo` container (`ghcr.io/open-webui/mcpo:latest`). `mcpo` runs on a secondary port, binds to the `velociraptor-mcp:8088/sse` feed, and translates it instantly into OpenAPI schemas compatible with Open WebUI.

### Transport Hardening (Gzip Warning)
If you proxy your deployment behind Nginx, Traefik, or Cloudflare borders for security reasons, **disable gzip compression** specifically for the `/sse` route. Gzip buffers the HTTP stream endlessly, actively breaking Server-Sent Events, leading your tools to timeout mysteriously.