socfortress/wazuh-mcp-server
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).
Wazuh MCP Server
A production-ready Model Context Protocol (MCP) server for seamless integration between Wazuh SIEM and Large Language Models (LLMs).
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
- Installation
- Configuration
- Usage
- Available Tools
- Development
- CI/CD
- Deployment
- Security
- Contributing
- License
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
- Go to the Releases page
- Download the latest
.whl
file - Install with:
pip install wazuh_mcp_server-*.whl
From Build Artifacts (Latest Build)
- Go to the Actions tab
- Click on the latest successful workflow run
- Download the
python-package-distributions
artifact - 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
Variable | Description | Default | Required |
---|---|---|---|
WAZUH_PROD_URL | Wazuh Manager API URL | None | β |
WAZUH_PROD_USERNAME | Wazuh username | None | β |
WAZUH_PROD_PASSWORD | Wazuh password | None | β |
WAZUH_PROD_SSL_VERIFY | SSL verification | true | β |
WAZUH_PROD_TIMEOUT | Request timeout (seconds) | 30 | β |
MCP_SERVER_HOST | Server host | 127.0.0.1 | β |
MCP_SERVER_PORT | Server port | 8000 | β |
LOG_LEVEL | Logging level | INFO | β |
WAZUH_DISABLED_TOOLS | Comma-separated list of disabled tools | None | β |
WAZUH_DISABLED_CATEGORIES | Comma-separated list of disabled categories | None | β |
WAZUH_READ_ONLY | Enable read-only mode | false | β |
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 fromlimit
(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 addresslocal_port
(optional): Filter by local portremote_ip
(optional): Filter by remote IP addressstate
(optional): Filter by state (listening, established, etc.)process
(optional): Filter by process namepid
(optional): Filter by process IDtx_queue
(optional): Filter by tx_queuesort
(optional): Sort results by field(s)search
(optional): Search for elements containing the specified stringselect
(optional): Select which fields to returnq
(optional): Query to filter results bydistinct
(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 fromlimit
(optional): Maximum number of packages to return (default: 500)offset
(optional): Offset for pagination (default: 0)vendor
(optional): Filter by package vendorname
(optional): Filter by package namearchitecture
(optional): Filter by package architectureformat
(optional): Filter by package format (e.g., 'deb', 'rpm')version
(optional): Filter by package versionsort
(optional): Sort results by field(s)search
(optional): Search for elements containing the specified stringselect
(optional): Select which fields to returnq
(optional): Query to filter results bydistinct
(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 fromlimit
(optional): Maximum number of processes to return (default: 500)offset
(optional): Offset for pagination (default: 0)pid
(optional): Filter by process PIDstate
(optional): Filter by process stateppid
(optional): Filter by process parent PIDegroup
(optional): Filter by process egroupeuser
(optional): Filter by process euserfgroup
(optional): Filter by process fgroupname
(optional): Filter by process namenlwp
(optional): Filter by process nlwppgrp
(optional): Filter by process pgrppriority
(optional): Filter by process priorityrgroup
(optional): Filter by process rgroupruser
(optional): Filter by process rusersgroup
(optional): Filter by process sgroupsuser
(optional): Filter by process susersort
(optional): Sort results by field(s)search
(optional): Search for elements containing the specified stringselect
(optional): Select which fields to returnq
(optional): Query to filter results bydistinct
(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 bylimit
(optional): Maximum number of rules to return (default: 500)offset
(optional): Offset for pagination (default: 0)select
(optional): Select which fields to returnsort
(optional): Sort results by field(s)search
(optional): Search for elements containing the specified stringq
(optional): Query to filter results bystatus
(optional): Filter by status (enabled, disabled, all)group
(optional): Filter by rule grouplevel
(optional): Filter by rule level (e.g., '4' or '2-4')filename
(optional): Filter by filenamerelative_dirname
(optional): Filter by relative directory namepci_dss
(optional): Filter by PCI_DSS requirementgdpr
(optional): Filter by GDPR requirementgpg13
(optional): Filter by GPG13 requirementhipaa
(optional): Filter by HIPAA requirementnist_800_53
(optional): Filter by NIST-800-53 requirementtsc
(optional): Filter by TSC requirementmitre
(optional): Filter by MITRE technique IDdistinct
(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 fromraw
(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 formatwait_for_complete
(optional): Disable timeout responseoffset
(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 fieldssearch
(optional): Look for elements containing the specified stringrelative_dirname
(optional): Filter by relative directory namefilename
(optional): Filter by filename of one or more rule or decoder filesstatus
(optional): Filter by list status (enabled, disabled, all)q
(optional): Query to filter results byselect
(optional): Select which fields to returndistinct
(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 fromname
(optional): Filter by policy namedescription
(optional): Filter by policy descriptionreferences
(optional): Filter by referenceslimit
(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 stringselect
(optional): Select which fields to returnq
(optional): Query to filter results bydistinct
(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
anddevelop
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
-
Create and push a git tag:
git tag v1.0.0 git push origin v1.0.0
-
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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Make your changes and add tests
- Ensure tests pass:
pytest
- Check code quality:
black .
,isort .
,flake8 .
- Commit your changes (
git commit -m 'Add amazing feature'
) - Push to your branch (
git push origin feature/amazing-feature
) - 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
- π Documentation
- π Issues
- π’ SOCFortress
Made with β€οΈ by SOCFortress