npm package: @modular-intelligence/velociraptor
Description: MCP server for Velociraptor endpoint visibility and collection API
Latest version: 1.0.2

# 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

```bash
cd velociraptor
bun install
```

## Configuration

Set the following environment variables:

```bash
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

```bash
bun run start
```

### Build

```bash
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```json
{
  "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](https://docs.velociraptor.app/)
- [VQL Reference](https://docs.velociraptor.app/vql_reference/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)