Wazuh OpenSearch Analytics

🚀 OpenSearch MCP Server

A Model Context Protocol (MCP) server for querying and analyzing Wazuh security logs stored in OpenSearch.

🚀 Quick Start

The OpenSearch MCP Server is a powerful tool for querying and analyzing Wazuh security logs. Here's how to get started:

Prerequisites

• Node.js v16 or higher.
• Access to an OpenSearch instance containing Wazuh security logs.

Installation

Option 1: Directly use npx from GitHub (Recommended)

You can run this tool directly using npx without cloning the repository:

# Run the latest version from GitHub
npx github:jetbalsa/mcp-opensearch-js

# Enable debug mode
npx github:jetbalsa/mcp-opensearch-js --debug

# You can also specify a specific branch or commit
npx github:jetbalsa/mcp-opensearch-js#main

Option 2: Local Installation

1. Clone this repository:

git clone https://github.com/jetbalsa/mcp-opensearch-js.git
cd mcp-opensearch-js

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

4. Edit the .env file with your OpenSearch connection details:

OPENSEARCH_URL=https://your-opensearch-endpoint:9200
OPENSEARCH_USERNAME=your-username
OPENSEARCH_PASSWORD=your-password
DEBUG=false

Starting the Server

Start the server:

npm start

This will start the server in stdio mode.

Enable debug logging:

npm run stdio:debug

Test with MCP CLI:

npm run dev

This will start the server and perform an interactive test using the MCP CLI tool.

Test with MCP Inspector:

npm run inspect

This will start the server and connect to the MCP Inspector for visual debugging.

✨ Features

• Search for security alerts with advanced filtering capabilities.
• Retrieve detailed information about specific alerts.
• Generate statistics on security events.
• Visualize the time trends of alerts.
• Provide long - term operation progress reports.
• Implement structured error handling.

📦 Installation

The installation process has been detailed in the Quick Start section above.

💻 Usage Examples

Using the MCP CLI Tool

# Search for alerts
mcp-cli search --keyword "error" --output json

# Get alert details
mcp-cli get --id 12345 --verbose

# Generate statistics
mcp-cli stats --time-range "2023-10-01 00:00:00" "2023-10-07 23:59:59" --summary

# Visualize trends
mcp-cli trends --start-time "2023-10-01" --end-time "2023-10-07" --format chart

Using the Client

const { MCPClient } = require('mcp-opensearch');
const client = new MCPClient({
  host: 'localhost',
  port: 9200,
  username: 'your-username',
  password: 'your-password'
});

// Search for alerts
client.search({ keyword: 'error' }, (err, result) => {
  if (err) return console.error(err);
  console.log(result);
});

// Get alert details
client.get({ id: '12345' }, (err, result) => {
  if (err) return console.error(err);
  console.log(result);
});

📚 Documentation

Server Tools

The server provides the following tools:

1. Search Alerts

Search for security alerts in Wazuh data.

Parameters:

• --search: Specify the keyword or condition to search for.
• --filter: Apply advanced filters (e.g., time range, log level, etc.).
• -o, --output: Specify the output format (supports JSON, CSV, text, etc.).

2. Get Alert Details

Retrieve detailed information about a specific alert.

Parameters:

• --id: Specify the ID of the alert to query.
• --fields: Specify the fields to display (comma - separated).
• -v, --verbose: Enable verbose mode to display more relevant information.

3. Statistics

Generate statistics on security events.

Parameters:

• --time-range: Specify the time range (format: YYYY-MM-DD HH:MM:SS).
• --aggregation: Specify the aggregation method (e.g., by hour, day, week, etc.).
• -s, --summary: Display the summary result.

4. Visualize Trends

Visualize the time trends of alerts.

Parameters:

• --start-time: Specify the start time.
• --end-time: Specify the end time.
• -f, --format: Specify the output format (e.g., chart, table, etc.).

Using the Client

To use this server as a client, follow these steps:

Install dependencies:

npm install mcp-opensearch

Connect to the MCP server:

const { MCPClient } = require('mcp-opensearch');
const client = new MCPClient({
  host: 'localhost',
  port: 9200,
  username: 'your-username', // Optional
  password: 'your-password'  // Optional
});

Example usage:

// Search for alerts
client.search({ keyword: 'error' }, (err, result) => {
  if (err) return console.error(err);
  console.log('Search Result:', result);
});

// Get alert details
client.get({ id: '12345' }, (err, result) => {
  if (err) return console.error(err);
  console.log('Alert Details:', result);
});