wazuh-mcp-server

socfortress/wazuh-mcp-server

3.5

If you are the rightful owner of wazuh-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Wazuh MCP Server is a production-ready Model Context Protocol server designed for seamless integration between Wazuh SIEM and Large Language Models (LLMs).

Tools
9
Resources
0
Prompts
0

Wazuh MCP Server

A production-ready Model Context Protocol (MCP) server for seamless integration between Wazuh SIEM and Large Language Models (LLMs).

Build Status Python 3.11+ YouTube Channel Subscribers Get in Touch

Why? Combine the power of Wazuh's comprehensive security monitoring with the reasoning capabilities of large language modelsβ€”enabling natural language queries and intelligent analysis of your security data.


✨ Key Features

  • πŸš€ Production-ready: Proper package structure, logging, error handling, and configuration management
  • πŸ” Secure: JWT token management with automatic refresh
  • 🌐 HTTP/2 Support: Built on modern async HTTP client with connection pooling
  • πŸ“Š Comprehensive API: Access Wazuh agents, authentication, and more
  • πŸŽ›οΈ Configurable: Environment variables, CLI arguments, and fine-grained tool filtering
  • πŸ“¦ Pip installable: Install directly from GitHub releases or source

Table of Contents


Quick Start

1. Install

From GitHub (Recommended)
python -m venv .venv && source .venv/bin/activate
pip install git+https://github.com/socfortress/wazuh-mcp-server.git
From Release Artifacts
  1. Go to the Releases page
  2. Download the latest .whl file
  3. Install with:
pip install wazuh_mcp_server-*.whl
From Build Artifacts (Latest Build)
  1. Go to the Actions tab
  2. Click on the latest successful workflow run
  3. Download the python-package-distributions artifact
  4. Extract and install:
pip install wazuh_mcp_server-*.whl

2. Configure Environment

Create a .env file in your project directory:

# Wazuh Manager Configuration
WAZUH_PROD_URL=https://your-wazuh-manager:55000
WAZUH_PROD_USERNAME=your-username
WAZUH_PROD_PASSWORD=your-password
WAZUH_PROD_SSL_VERIFY=false
WAZUH_PROD_TIMEOUT=30

# MCP Server Configuration
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000

# Logging Configuration
LOG_LEVEL=INFO

# Tool Filtering (optional)
# WAZUH_DISABLED_TOOLS=DeleteAgentTool,RestartManagerTool
# WAZUH_DISABLED_CATEGORIES=dangerous,write
# WAZUH_READ_ONLY=false

3. Run the Server

# Using the CLI command
wazuh-mcp-server

# Or using the Python module
python -m wazuh_mcp_server

# With custom configuration
wazuh-mcp-server --host 0.0.0.0 --port 8080 --log-level DEBUG

The server will start and be available at http://127.0.0.1:8000 (or your configured host/port).


Installation

Requirements

  • Python 3.11 or higher
  • Access to a Wazuh Manager instance
  • Network connectivity to your Wazuh Manager

Development Installation

git clone https://github.com/socfortress/wazuh-mcp-server.git
cd wazuh-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks (optional)
pre-commit install

Configuration

Environment Variables

VariableDescriptionDefaultRequired
WAZUH_PROD_URLWazuh Manager API URLNoneβœ…
WAZUH_PROD_USERNAMEWazuh usernameNoneβœ…
WAZUH_PROD_PASSWORDWazuh passwordNoneβœ…
WAZUH_PROD_SSL_VERIFYSSL verificationtrue❌
WAZUH_PROD_TIMEOUTRequest timeout (seconds)30❌
MCP_SERVER_HOSTServer host127.0.0.1❌
MCP_SERVER_PORTServer port8000❌
LOG_LEVELLogging levelINFO❌
WAZUH_DISABLED_TOOLSComma-separated list of disabled toolsNone❌
WAZUH_DISABLED_CATEGORIESComma-separated list of disabled categoriesNone❌
WAZUH_READ_ONLYEnable read-only modefalse❌

CLI Options

wazuh-mcp-server --help

Available options:

  • --host: Host to bind server to (default: 127.0.0.1)
  • --port: Port to bind server to (default: 8000)
  • --log-level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  • --wazuh-url: Wazuh Manager URL (overrides env var)
  • --wazuh-username: Wazuh username (overrides env var)
  • --wazuh-password: Wazuh password (overrides env var)
  • --no-ssl-verify: Disable SSL certificate verification

Usage

Basic Usage

from wazuh_mcp_server import Config, create_server

# Create server with environment configuration
config = Config.from_env()
server = create_server(config)

# Start the server
server.start()

Custom Configuration

from wazuh_mcp_server.config import WazuhConfig, ServerConfig, Config

# Create custom configuration
wazuh_config = WazuhConfig(
    url="https://your-wazuh-manager:55000",
    username="admin",
    password="password",
    ssl_verify=False
)

server_config = ServerConfig(
    host="0.0.0.0",
    port=8080,
    log_level="DEBUG"
)

config = Config(wazuh=wazuh_config, server=server_config)
server = create_server(config)

Integration with LangChain

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import AgentType, initialize_agent

# Initialize LLM
model = ChatOpenAI(model="gpt-4")

# Connect to Wazuh MCP server
client = MultiServerMCPClient({
    "wazuh-mcp-server": {
        "transport": "sse",
        "url": "http://127.0.0.1:8000/sse/",
    }
})

# Get tools and create agent
tools = await client.get_tools()
agent = initialize_agent(
    tools=tools,
    llm=model,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)

# Query your Wazuh data
response = await agent.ainvoke({
    "input": "Show me all active agents and their status"
})

# Get network ports information
ports_response = await agent.ainvoke({
    "input": "Show me all listening TCP ports on agent 000"
})

Available Tools

The server exposes the following MCP tools:

1. AuthenticateTool

  • Purpose: Force JWT token refresh from Wazuh Manager
  • Parameters: None
  • Usage: Ensures fresh authentication tokens

2. GetAgentsTool

  • Purpose: Retrieve agents from Wazuh Manager with filtering
  • Parameters:
    • status (optional): Filter by agent status (e.g., ["active"])
    • limit (optional): Maximum number of agents to return (default: 500)
    • offset (optional): Offset for pagination (default: 0)

3. GetAgentPortsTool

  • Purpose: Get network ports information from a specific agent using syscollector
  • Parameters:
    • agent_id (required): Agent ID to get ports from
    • limit (optional): Maximum number of ports to return (default: 500)
    • offset (optional): Offset for pagination (default: 0)
    • protocol (optional): Filter by protocol (tcp, udp)
    • local_ip (optional): Filter by local IP address
    • local_port (optional): Filter by local port
    • remote_ip (optional): Filter by remote IP address
    • state (optional): Filter by state (listening, established, etc.)
    • process (optional): Filter by process name
    • pid (optional): Filter by process ID
    • tx_queue (optional): Filter by tx_queue
    • sort (optional): Sort results by field(s)
    • search (optional): Search for elements containing the specified string
    • select (optional): Select which fields to return
    • q (optional): Query to filter results by
    • distinct (optional): Look for distinct values

4. GetAgentPackagesTool

  • Purpose: Get installed packages information from a specific agent using syscollector
  • Parameters:
    • agent_id (required): Agent ID to get packages from
    • limit (optional): Maximum number of packages to return (default: 500)
    • offset (optional): Offset for pagination (default: 0)
    • vendor (optional): Filter by package vendor
    • name (optional): Filter by package name
    • architecture (optional): Filter by package architecture
    • format (optional): Filter by package format (e.g., 'deb', 'rpm')
    • version (optional): Filter by package version
    • sort (optional): Sort results by field(s)
    • search (optional): Search for elements containing the specified string
    • select (optional): Select which fields to return
    • q (optional): Query to filter results by
    • distinct (optional): Look for distinct values

5. GetAgentProcessesTool

  • Purpose: Get running processes information from a specific agent using syscollector
  • Parameters:
    • agent_id (required): Agent ID to get processes from
    • limit (optional): Maximum number of processes to return (default: 500)
    • offset (optional): Offset for pagination (default: 0)
    • pid (optional): Filter by process PID
    • state (optional): Filter by process state
    • ppid (optional): Filter by process parent PID
    • egroup (optional): Filter by process egroup
    • euser (optional): Filter by process euser
    • fgroup (optional): Filter by process fgroup
    • name (optional): Filter by process name
    • nlwp (optional): Filter by process nlwp
    • pgrp (optional): Filter by process pgrp
    • priority (optional): Filter by process priority
    • rgroup (optional): Filter by process rgroup
    • ruser (optional): Filter by process ruser
    • sgroup (optional): Filter by process sgroup
    • suser (optional): Filter by process suser
    • sort (optional): Sort results by field(s)
    • search (optional): Search for elements containing the specified string
    • select (optional): Select which fields to return
    • q (optional): Query to filter results by
    • distinct (optional): Look for distinct values

6. ListRulesTool

  • Purpose: List rules from Wazuh Manager with various filtering options
  • Parameters:
    • rule_ids (optional): List of rule IDs to filter by
    • limit (optional): Maximum number of rules to return (default: 500)
    • offset (optional): Offset for pagination (default: 0)
    • select (optional): Select which fields to return
    • sort (optional): Sort results by field(s)
    • search (optional): Search for elements containing the specified string
    • q (optional): Query to filter results by
    • status (optional): Filter by status (enabled, disabled, all)
    • group (optional): Filter by rule group
    • level (optional): Filter by rule level (e.g., '4' or '2-4')
    • filename (optional): Filter by filename
    • relative_dirname (optional): Filter by relative directory name
    • pci_dss (optional): Filter by PCI_DSS requirement
    • gdpr (optional): Filter by GDPR requirement
    • gpg13 (optional): Filter by GPG13 requirement
    • hipaa (optional): Filter by HIPAA requirement
    • nist_800_53 (optional): Filter by NIST-800-53 requirement
    • tsc (optional): Filter by TSC requirement
    • mitre (optional): Filter by MITRE technique ID
    • distinct (optional): Look for distinct values

7. GetRuleFileContentTool

  • Purpose: Get the content of a specific rule file from the ruleset
  • Parameters:
    • filename (required): Filename of the rule file to get content from
    • raw (optional): Format response in plain text (default: false)
    • relative_dirname (optional): Filter by relative directory name

8. GetRuleFilesTool

  • Purpose: Get a list of all rule files and their status from Wazuh Manager
  • Parameters:
    • pretty (optional): Show results in human-readable format
    • wait_for_complete (optional): Disable timeout response
    • offset (optional): First element to return in the collection (default: 0)
    • limit (optional): Maximum number of elements to return (default: 500)
    • sort (optional): Sort the collection by a field or fields
    • search (optional): Look for elements containing the specified string
    • relative_dirname (optional): Filter by relative directory name
    • filename (optional): Filter by filename of one or more rule or decoder files
    • status (optional): Filter by list status (enabled, disabled, all)
    • q (optional): Query to filter results by
    • select (optional): Select which fields to return
    • distinct (optional): Look for distinct values

Example usage:

{"args": {"limit": 10, "status": "enabled"}}
{"args": {"filename": ["0020-syslog_rules.xml"]}}
{"args": {"search": "ruleset"}}

Returns:

  • JSON list of rule files with their status and directory info

9. GetAgentSCATool

  • Purpose: Get Security Configuration Assessment (SCA) results for a specific agent
  • Parameters:
    • agent_id (required): Agent ID to get SCA results from
    • name (optional): Filter by policy name
    • description (optional): Filter by policy description
    • references (optional): Filter by references
    • limit (optional): Maximum number of SCA policies to return (default: 500)
    • offset (optional): Offset for pagination (default: 0)
    • sort (optional): Sort results by field(s)
    • search (optional): Search for elements containing the specified string
    • select (optional): Select which fields to return
    • q (optional): Query to filter results by
    • distinct (optional): Look for distinct values

Development

Setting up Development Environment

git clone https://github.com/socfortress/wazuh-mcp-server.git
cd wazuh-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=wazuh_mcp_server

# Run specific test file
pytest tests/test_client.py

# Run with verbose output
pytest -v

Building the Package

# Install build dependencies
pip install build twine

# Build the package
python -m build

# Check the package
twine check dist/*

# Test installation
pip install dist/*.whl

Continuous Integration

This project uses GitHub Actions for automated building and testing:

  • Automatic builds: Every push to main and develop branches triggers a build
  • Quality assurance: Comprehensive testing including linting, type checking, and unit tests
  • Artifact publishing: Built packages are available as GitHub releases and workflow artifacts

Creating a Release

  1. Create and push a git tag:

    git tag v1.0.0
    git push origin v1.0.0
    
  2. The GitHub Action will automatically:

    • Build the package
    • Run all tests
    • Create a GitHub release with downloadable artifacts

Installing from CI Artifacts

Visit the Actions page and download the python-package-distributions artifact from any successful build.


Security Considerations

Credentials Management

  • Never commit credentials: Use environment variables or secrets management
  • Use strong passwords: Ensure Wazuh credentials are secure
  • Rotate tokens: Regularly update API credentials

Network Security

  • TLS/SSL: Always use HTTPS in production (WAZUH_PROD_SSL_VERIFY=true)
  • Firewall rules: Restrict access to necessary ports only
  • VPN/Private networks: Deploy in secured network environments

Access Control

  • Least privilege: Create dedicated Wazuh users with minimal required permissions
  • Read-only mode: Use WAZUH_READ_ONLY=true when write operations aren't needed
  • Tool filtering: Disable unnecessary tools using WAZUH_DISABLED_TOOLS

Monitoring

  • Logging: Enable appropriate log levels for monitoring
  • Health checks: Implement monitoring of the MCP server endpoint
  • Rate limiting: Consider implementing rate limiting for production deployments

Project Structure

wazuh-mcp-server/
β”œβ”€β”€ wazuh_mcp_server/          # Main package
β”‚   β”œβ”€β”€ __init__.py           # Package initialization
β”‚   β”œβ”€β”€ __main__.py           # CLI entry point
β”‚   β”œβ”€β”€ client.py             # Wazuh API client
β”‚   β”œβ”€β”€ config.py             # Configuration management
β”‚   β”œβ”€β”€ server.py             # MCP server implementation
β”‚   └── exceptions.py         # Custom exceptions
β”œβ”€β”€ tests/                    # Test suite
β”‚   β”œβ”€β”€ conftest.py          # Test configuration
β”‚   β”œβ”€β”€ test_client.py       # Client tests
β”‚   β”œβ”€β”€ test_config.py       # Configuration tests
β”‚   └── test_server.py       # Server tests
β”œβ”€β”€ .github/workflows/        # GitHub Actions
β”‚   └── publish.yml          # CI/CD pipeline
β”œβ”€β”€ requirements.txt          # Dependencies
β”œβ”€β”€ pyproject.toml           # Package configuration
β”œβ”€β”€ .env.example             # Environment template
└── README.md                # This file

Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes and add tests
  4. Ensure tests pass: pytest
  5. Check code quality: black ., isort ., flake8 .
  6. Commit your changes (git commit -m 'Add amazing feature')
  7. Push to your branch (git push origin feature/amazing-feature)
  8. Open a Pull Request

Development Guidelines

  • Write tests for new functionality
  • Follow existing code style and patterns
  • Update documentation for new features
  • Ensure all CI checks pass

License

This project is licensed under the MIT License - see the file for details.


Changelog

v0.1.0 (Latest)

  • Initial release
  • Basic MCP server functionality
  • Wazuh API integration with JWT authentication
  • CLI interface with configuration options
  • Docker and Kubernetes deployment support
  • Comprehensive test suite
  • GitHub Actions CI/CD pipeline

Support


Made with ❀️ by SOCFortress