# Megaraptor MCP
A Model Context Protocol (MCP) server that provides AI assistants with access to [Velociraptor](https://docs.velociraptor.app/) - the powerful digital forensics and incident response (DFIR) platform.
## Overview
Megaraptor MCP enables AI assistants like Claude to interact with Velociraptor servers for:
- **Endpoint Management**: Search, interrogate, and manage Velociraptor clients
- **Artifact Collection**: Schedule forensic artifact collection on endpoints
- **Threat Hunting**: Create and manage hunts across multiple endpoints
- **VQL Queries**: Execute arbitrary Velociraptor Query Language queries
- **Incident Response**: Pre-built DFIR workflow prompts for common scenarios
- **Deployment Automation**: Deploy Velociraptor servers and agents across infrastructure (Docker, binary, cloud, GPO, SSH, WinRM, Ansible)
## Features
### MCP Tools (33 tools)
#### Core DFIR Tools (15 tools)
| Category | Tool | Description |
|----------|------|-------------|
| **Clients** | `list_clients` | Search and list Velociraptor endpoints |
| | `get_client_info` | Get detailed information about a client |
| | `label_client` | Add/remove labels from clients |
| | `quarantine_client` | Quarantine or release endpoints |
| **Artifacts** | `list_artifacts` | List available Velociraptor artifacts |
| | `get_artifact` | Get full artifact definition |
| | `collect_artifact` | Schedule artifact collection on a client |
| **Hunts** | `create_hunt` | Create a mass collection campaign |
| | `list_hunts` | List existing hunts |
| | `get_hunt_results` | Retrieve results from a hunt |
| | `modify_hunt` | Start, pause, stop, or archive hunts |
| **Flows** | `list_flows` | List collection flows for a client |
| | `get_flow_results` | Get results from a collection |
| | `get_flow_status` | Check collection status |
| | `cancel_flow` | Cancel a running collection |
| **VQL** | `run_vql` | Execute arbitrary VQL queries |
| | `vql_help` | Get help on VQL syntax and plugins |
#### Deployment Tools (18 tools)
| Category | Tool | Description |
|----------|------|-------------|
| **Server Deployment** | `deploy_server_binary` | Deploy Velociraptor server as standalone binary |
| | `deploy_server_docker` | Deploy Velociraptor server using Docker |
| | `deploy_server_cloud` | Deploy Velociraptor server to AWS/Azure cloud |
| | `generate_server_config` | Generate server configuration with certificates |
| **Agent Deployment** | `deploy_agent_gpo` | Generate GPO deployment package for Windows |
| | `deploy_agent_winrm` | Deploy agents via WinRM to Windows endpoints |
| | `deploy_agent_ssh` | Deploy agents via SSH to Linux/macOS endpoints |
| | `deploy_agent_ansible` | Generate Ansible playbook for agent deployment |
| | `build_offline_collector` | Build standalone offline collector |
| | `generate_client_config` | Generate client configuration file |
| **Deployment Management** | `list_deployments` | List tracked deployment operations |
| | `get_deployment_status` | Get detailed status of a deployment |
| | `verify_deployment` | Verify deployment health and connectivity |
| | `rollback_deployment` | Rollback a failed deployment |
| **Credentials** | `store_credential` | Securely store deployment credentials |
| | `list_credentials` | List stored credential aliases |
| | `delete_credential` | Remove stored credentials |
| **Utilities** | `download_velociraptor` | Download Velociraptor binary for platform |
### MCP Resources
Browse Velociraptor data through standardized URIs:
- `velociraptor://clients` - Browse connected endpoints
- `velociraptor://clients/{client_id}` - View specific client details
- `velociraptor://hunts` - Browse hunt campaigns
- `velociraptor://hunts/{hunt_id}` - View specific hunt details
- `velociraptor://artifacts` - Browse available artifacts
- `velociraptor://server-info` - View server information
- `velociraptor://deployments` - Browse deployment operations and status
### MCP Prompts (8 prompts)
Pre-built DFIR and deployment workflow prompts:
| Prompt | Category | Description |
|--------|----------|-------------|
| `investigate_endpoint` | DFIR | Comprehensive endpoint investigation workflow |
| `threat_hunt` | DFIR | Create and execute threat hunting campaigns |
| `triage_incident` | DFIR | Rapid incident triage and scoping |
| `malware_analysis` | DFIR | Analyze suspicious files or processes |
| `lateral_movement` | DFIR | Detect lateral movement indicators |
| `deploy_velociraptor` | Deployment | Interactive Velociraptor deployment wizard |
| `scale_deployment` | Deployment | Plan enterprise-scale agent rollout |
| `troubleshoot_deployment` | Deployment | Diagnose and fix deployment issues |
## Installation
### Prerequisites
- Python 3.10 or higher
- A running Velociraptor server with API access enabled
- API client credentials (see [Configuration](#configuration))
### Install from source
```bash
git clone https://github.com/yourusername/megaraptor-mcp.git
cd megaraptor-mcp
# Core DFIR functionality only
pip install -e .
# With deployment features
pip install -e ".[deployment]"
# With cloud deployment (AWS/Azure)
pip install -e ".[cloud]"
# All features
pip install -e ".[all]"
```
### Optional Dependencies
| Extra | Features | Packages |
|-------|----------|----------|
| `deployment` | Agent/server deployment | paramiko, pywinrm, cryptography, jinja2 |
| `cloud` | Cloud deployment | boto3, azure-mgmt-compute |
| `all` | All features | All of the above |
### Install dependencies manually
```bash
# Core only
pip install mcp pyvelociraptor pyyaml grpcio
# For deployment features
pip install paramiko pywinrm cryptography jinja2
# For cloud deployment
pip install boto3 azure-mgmt-compute azure-identity
```
## Configuration
Megaraptor MCP supports two authentication methods:
### Option 1: Config File (Recommended)
1. Generate an API client config on your Velociraptor server:
```bash
velociraptor --config server.config.yaml config api_client \
--name mcp-client \
--role reader,investigator \
api_client.yaml
```
2. Set the environment variable:
```bash
export VELOCIRAPTOR_CONFIG_PATH=/path/to/api_client.yaml
```
### Option 2: Environment Variables
Set individual configuration values:
```bash
export VELOCIRAPTOR_API_URL=https://velociraptor.example.com:8001
export VELOCIRAPTOR_CLIENT_CERT=/path/to/client.crt # or PEM content
export VELOCIRAPTOR_CLIENT_KEY=/path/to/client.key # or PEM content
export VELOCIRAPTOR_CA_CERT=/path/to/ca.crt # or PEM content
```
### API Roles
Assign appropriate roles to your API client based on required capabilities:
| Role | Capabilities |
|------|--------------|
| `reader` | Read clients, artifacts, hunts, flows |
| `investigator` | Above + collect artifacts, create hunts |
| `administrator` | Full access (use with caution) |
## Usage
### Running the Server
```bash
# Using the installed command
megaraptor-mcp
# Or as a Python module
python -m megaraptor_mcp
```
### Claude Desktop Integration
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"velociraptor": {
"command": "python",
"args": ["-m", "megaraptor_mcp"],
"env": {
"VELOCIRAPTOR_CONFIG_PATH": "/path/to/api_client.yaml"
}
}
}
}
```
### Example Interactions
**List connected endpoints:**
```
Use the list_clients tool to show all Windows endpoints
```
**Investigate an endpoint:**
```
Use the investigate_endpoint prompt for client C.1234567890abcdef
```
**Create a threat hunt:**
```
Create a hunt for the file hash a1b2c3d4e5f6... across all endpoints
```
**Run custom VQL:**
```
Run this VQL query: SELECT * FROM pslist() WHERE Name =~ 'suspicious'
```
## VQL Reference
VQL (Velociraptor Query Language) is the core query language. Common patterns:
```sql
-- List all clients
SELECT * FROM clients()
-- Search for clients by hostname
SELECT * FROM clients(search='host:workstation')
-- Get running processes from collected data
SELECT * FROM source(client_id='C.xxx', flow_id='F.xxx')
-- Create a hunt
SELECT hunt(artifacts='Windows.System.Pslist', description='Process audit')
FROM scope()
```
For complete VQL reference, see: https://docs.velociraptor.app/vql_reference/
## Deployment Features
Megaraptor MCP includes comprehensive deployment automation for Velociraptor infrastructure.
### Server Deployment
Deploy Velociraptor servers using multiple methods:
| Method | Use Case | Command |
|--------|----------|---------|
| **Binary** | On-premise, direct installation | `deploy_server_binary` |
| **Docker** | Container environments, quick testing | `deploy_server_docker` |
| **Cloud** | AWS/Azure managed deployments | `deploy_server_cloud` |
**Example: Deploy Docker server**
```
Deploy a Velociraptor server using Docker on server.example.com with SSH credentials "prod-server"
```
### Agent Deployment
Multiple agent deployment methods for different environments:
| Method | Target | Best For |
|--------|--------|----------|
| **GPO** | Windows (Active Directory) | Enterprise Windows environments |
| **WinRM** | Windows (remote) | Windows without AD, smaller deployments |
| **SSH** | Linux/macOS | Unix-like systems |
| **Ansible** | Multi-platform | Large-scale infrastructure automation |
| **Offline Collector** | Air-gapped | Isolated networks, forensic collection |
**Example: Deploy agents via GPO**
```
Generate a GPO deployment package for 500 Windows endpoints using the enterprise profile
```
**Example: Deploy via Ansible**
```
Create an Ansible playbook to deploy Velociraptor agents to all Linux servers in inventory.yml
```
### Deployment Profiles
Pre-configured deployment profiles for different scenarios:
| Profile | Use Case | Characteristics |
|---------|----------|-----------------|
| **rapid** | Quick testing, POC | Minimal config, self-signed certs |
| **standard** | Production single-site | Proper certificates, standard hardening |
| **enterprise** | Large-scale multi-site | HA config, advanced monitoring, compliance |
### Credential Management
Securely store deployment credentials:
```
Store SSH credentials for prod-servers with username admin and key file ~/.ssh/prod_key
```
Credentials are encrypted at rest using AES-256-GCM with a locally-generated key.
### Offline Collectors
Build standalone collectors for air-gapped environments:
```
Build an offline collector for Windows that collects browser history and network connections
```
Collectors include embedded configuration and can run without network connectivity.
## Project Structure
```
megaraptor-mcp/
├── pyproject.toml # Project configuration
├── README.md # This file
├── src/
│ └── megaraptor_mcp/
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Module entry point
│ ├── server.py # MCP server main entry
│ ├── client.py # Velociraptor API wrapper
│ ├── config.py # Configuration handling
│ ├── tools/ # MCP tool implementations
│ │ ├── clients.py # Client management tools
│ │ ├── artifacts.py # Artifact tools
│ │ ├── hunts.py # Hunt management tools
│ │ ├── flows.py # Flow/collection tools
│ │ └── vql.py # VQL query tools
│ ├── resources/ # MCP resource implementations
│ │ └── resources.py
│ ├── prompts/ # MCP prompt implementations
│ │ └── prompts.py
│ └── deployment/ # Deployment automation
│ ├── __init__.py # Deployment module init
│ ├── tools.py # Deployment tool implementations
│ ├── server/ # Server deployment
│ │ ├── __init__.py
│ │ ├── binary.py # Binary deployment
│ │ ├── docker.py # Docker deployment
│ │ └── cloud.py # Cloud deployment (AWS/Azure)
│ ├── agent/ # Agent deployment
│ │ ├── __init__.py
│ │ ├── gpo.py # GPO package generation
│ │ ├── winrm.py # WinRM deployment
│ │ ├── ssh.py # SSH deployment
│ │ ├── ansible.py # Ansible playbook generation
│ │ └── offline.py # Offline collector builder
│ ├── credentials.py # Secure credential storage
│ ├── config_generator.py # Config file generation
│ └── profiles.py # Deployment profiles (rapid/standard/enterprise)
└── tests/ # Test suite
├── test_config.py
└── test_deployment.py
```
## Security Considerations
### API Security
- **API Credentials**: Store API client credentials securely. The config file contains private keys.
- **Principle of Least Privilege**: Use the minimum required roles for API clients.
- **Network Security**: Ensure API connections are only accessible from trusted networks.
- **Audit Logging**: Velociraptor logs all API actions. Review logs regularly.
- **Quarantine Caution**: The quarantine tool can isolate endpoints from the network.
### Deployment Security
- **Credential Encryption**: Deployment credentials are encrypted at rest using AES-256-GCM. The `.keyfile` is generated locally and should be protected.
- **Generated Configs**: Server and client configurations contain CA certificates and private keys. These are excluded from git via `.gitignore`.
- **Ansible Playbooks**: Generated playbooks may contain CA certificates. Store securely and limit access.
- **Cloud Templates**: CloudFormation and ARM templates may contain sensitive parameters. Review before committing.
- **SSH/WinRM**: Use key-based authentication where possible. Avoid storing passwords in plain text.
- **Offline Collectors**: Built collectors contain embedded configuration. Protect as you would agent binaries.
- **GPO Packages**: MSI packages contain embedded configuration. Control access to distribution share.
## Development
### Running Tests
```bash
pip install -e ".[dev]"
pytest
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Resources
- [Velociraptor Documentation](https://docs.velociraptor.app/)
- [Velociraptor GitHub](https://github.com/Velocidex/velociraptor)
- [VQL Reference](https://docs.velociraptor.app/vql_reference/)
- [MCP Specification](https://modelcontextprotocol.io/)
- [pyvelociraptor](https://github.com/Velocidex/pyvelociraptor)
## Acknowledgments
- The Velociraptor team at Velocidex for creating an amazing DFIR platform
- Anthropic for the Model Context Protocol specification
