Velociraptor MCP Server

MCP server providing tools for Velociraptor endpoint visibility and digital forensics API integration. Query clients, collect artifacts, retrieve hunt results, and execute VQL queries with built-in security controls.

Features

• Client Management: Search and inspect endpoint clients
• Artifact Collection: Deploy artifacts to endpoints for data collection
• Hunt Results: Retrieve results from hunting campaigns
• VQL Queries: Execute Velociraptor Query Language queries (SELECT-only)
• Flow Tracking: Monitor and retrieve collection flow results
• Security Controls: Built-in validation to prevent dangerous operations

Prerequisites

1. Velociraptor Server: Running instance with API access enabled
2. API Credentials: API key with appropriate permissions
3. Network Access: HTTPS connection to Velociraptor server (or localhost for testing)

Installation

cd velociraptor
bun install

Configuration

Set the following environment variables:

export VELOCIRAPTOR_API_URL="https://your-velociraptor-server:8889"
export VELOCIRAPTOR_API_KEY="your-api-key-here"

Security Requirements

• HTTPS Required: API URL must use HTTPS (exception: localhost for development)
• VQL Restrictions: Only SELECT queries allowed; INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, EXEC are blocked
• Artifact Blocking: Artifacts containing Exec, Shell, Kill, Delete, Remove, Write, Upload, Destroy, or Wipe are blocked
• Client ID Validation: Must match pattern C.{alphanumeric}
• Hunt ID Validation: Must match pattern H.{alphanumeric}
• Query Length: VQL queries limited to 4096 characters

Usage

Start the Server

bun run start

Build

bun run build

Available Tools

1. velociraptor_hunt_results

Retrieve results from a completed or running hunt.

Parameters:

• hunt_id (string, required): Hunt ID (e.g., "H.abc123")
• limit (number, optional): Max results to return (1-1000, default: 100)

Returns:

• hunt_id: The hunt identifier
• rows: Array of result rows
• total_rows: Total number of results
• columns: Column definitions

Example:

{
  "hunt_id": "H.C8D9E2F1",
  "limit": 50
}

2. velociraptor_client_search

Search for clients by hostname, IP, label, or OS.

Parameters:

• query (string, required): Search query
• limit (number, optional): Max results (1-1000, default: 100)

Returns:

• clients: Array of matching clients with details
• total: Number of clients found

Example:

{
  "query": "windows server",
  "limit": 25
}

3. velociraptor_artifact_list

List available artifacts with optional filtering.

Parameters:

• search (string, optional): Filter by artifact name
• type (enum, optional): "client", "server", or "all" (default: "all")

Returns:

• artifacts: Array of artifact definitions
• total: Number of artifacts

Example:

{
  "search": "Windows.System",
  "type": "client"
}

4. velociraptor_artifact_collect

Initiate artifact collection on a client endpoint.

Parameters:

• client_id (string, required): Client ID (e.g., "C.abc123")
• artifact_name (string, required): Artifact name (e.g., "Windows.System.Services")
• parameters (object, optional): Artifact-specific parameters
• timeout (number, optional): Collection timeout in seconds (30-600, default: 120)

Returns:

• flow_id: Collection flow identifier
• client_id: Target client
• artifact: Collected artifact name
• state: Flow state
• start_time: Collection start timestamp

Security: Blocks dangerous artifacts containing Exec, Shell, Kill, Delete, Remove, Write, Upload, Destroy, or Wipe.

Example:

{
  "client_id": "C.1a2b3c4d",
  "artifact_name": "Windows.System.Services",
  "timeout": 180
}

5. velociraptor_flow_results

Get results from a specific collection flow.

Parameters:

• client_id (string, required): Client ID
• flow_id (string, required): Flow/collection ID
• artifact_name (string, optional): Filter by specific artifact
• limit (number, optional): Max results (1-1000, default: 100)

Returns:

• flow_id: Flow identifier
• client_id: Client identifier
• state: Current flow state
• artifacts_collected: List of collected artifacts
• rows: Result data rows
• total: Total row count

Example:

{
  "client_id": "C.1a2b3c4d",
  "flow_id": "F.5e6f7g8h",
  "limit": 100
}

6. velociraptor_vql_query

Execute a VQL (Velociraptor Query Language) query.

Parameters:

• query (string, required): VQL query (SELECT-only, max 4096 chars)
• timeout (number, optional): Query timeout in seconds (10-300, default: 60)

Returns:

• query: The executed query
• rows: Result rows
• columns: Column definitions
• total_rows: Total row count

Security: Only SELECT queries allowed. Blocks SET, DELETE, INSERT, UPDATE, DROP, CREATE, ALTER, EXEC.

Example:

{
  "query": "SELECT * FROM clients() LIMIT 10",
  "timeout": 60
}

7. velociraptor_client_info

Get detailed information about a specific client.

Parameters:

• client_id (string, required): Client ID (e.g., "C.abc123")

Returns:

• client_id: Client identifier
• hostname: Client hostname
• os: Operating system
• fqdn: Fully qualified domain name
• ip: IP address
• mac_addresses: MAC addresses
• first_seen: First seen timestamp
• last_seen: Last seen timestamp
• labels: Client labels
• agent_version: Velociraptor agent version
• platform: Platform details

Example:

{
  "client_id": "C.1a2b3c4d"
}

Security Features

Input Validation

• Client IDs: Must match C.{alphanumeric} pattern
• Hunt IDs: Must match H.{alphanumeric} pattern
• Artifact Names: Alphanumeric, dots, and underscores only
• VQL Queries: Maximum 4096 characters, SELECT-only

Blocked Operations

VQL Keywords (case-insensitive):

• SET, DELETE, INSERT, UPDATE
• DROP, CREATE, ALTER
• EXEC

Artifact Patterns:

• Exec, Shell, Kill
• Delete, Remove, Write
• Upload, Destroy, Wipe

Connection Security

• HTTPS required for production deployments
• Localhost exception for development
• API key authentication via headers

Error Handling

All tools return structured error messages:

{
  "content": [
    {
      "type": "text",
      "text": "Error: VQL query contains blocked keyword: DELETE. Only SELECT queries are allowed."
    }
  ],
  "isError": true
}

API Endpoints Used

• GET /api/v1/GetHuntResults - Hunt results
• GET /api/v1/SearchClients - Client search
• GET /api/v1/GetArtifacts - Artifact listing
• POST /api/v1/CollectArtifact - Artifact collection
• GET /api/v1/GetFlowResults - Flow results
• POST /api/v1/Query - VQL query execution
• GET /api/v1/GetClient - Client details

Best Practices

1. Use Specific Searches: Filter artifact lists and client searches to reduce noise
2. Monitor Flows: Check flow results after collection to verify completion
3. Start Small: Test with single clients before deploying hunts
4. Review Artifacts: Use velociraptor_artifact_list to understand artifact capabilities
5. Timeout Tuning: Adjust timeouts based on artifact complexity and network latency

Troubleshooting

"Missing required environment variables"

• Ensure VELOCIRAPTOR_API_URL and VELOCIRAPTOR_API_KEY are set

"must use HTTPS or be localhost"

• Use HTTPS in production or localhost for testing

"VQL query contains blocked keyword"

• Only SELECT queries allowed; remove modification keywords

"Artifact name contains blocked pattern"

• Dangerous artifacts blocked for security; use read-only artifacts

"Invalid client ID format"

• Client IDs must match pattern: C.{alphanumeric}

Development

Project Structure

velociraptor/
├── package.json           # Package configuration
├── tsconfig.json          # TypeScript configuration
├── README.md              # This file
└── src/
    ├── index.ts           # MCP server entry point
    ├── schemas.ts         # Zod schema definitions
    ├── security.ts        # Security validation functions
    └── tools/             # Tool implementations
        ├── velociraptor-hunt-results.ts
        ├── velociraptor-client-search.ts
        ├── velociraptor-artifact-list.ts
        ├── velociraptor-artifact-collect.ts
        ├── velociraptor-flow-results.ts
        ├── velociraptor-vql-query.ts
        └── velociraptor-client-info.ts

Adding New Tools

1. Create tool file in src/tools/
2. Export schema (Zod schema with descriptions)
3. Export handler function
4. Import and register in src/index.ts

License

MIT

Resources

• Velociraptor Documentation
• VQL Reference
• MCP SDK Documentation