Wazuh MCP Server

A Model Context Protocol (MCP) server for Wazuh SIEM/HIDS integration. This server provides read-only access to Wazuh security monitoring data including agents, alerts, vulnerabilities, compliance assessments, and file integrity monitoring.

Features

• Agent Management: List and monitor Wazuh agents with status filtering
• Alert Search: Query security alerts with advanced filtering options
• Vulnerability Assessment: Retrieve CVE data and vulnerability reports
• Security Configuration Assessment (SCA): Access compliance policy results
• File Integrity Monitoring (FIM): Monitor file changes and integrity
• Rule Management: Browse Wazuh detection rules with compliance mappings
• Statistics: View aggregated security metrics and trends

Prerequisites

• Wazuh Manager: Version 4.x or later
• HTTPS Access: Wazuh API must be accessible via HTTPS
• API Credentials: Valid Wazuh API user with read permissions
• Bun Runtime: v1.0 or later

Installation

cd /path/to/mi-mcp-servers/packages/wazuh
bun install
bun run build

Configuration

Set the following environment variables:

export WAZUH_API_URL="https://your-wazuh-manager:55000"
export WAZUH_API_USER="your-api-user"
export WAZUH_API_PASSWORD="your-api-password"

Security Requirements

1. HTTPS Only: The server enforces HTTPS connections to the Wazuh API
2. Read-Only: All tools are read-only; no write or remediation operations
3. Blocked Endpoints: The following endpoint patterns are blocked for safety:
   • /active-response - Active response commands
   • /agents/restart - Agent restart operations
   • /agents/upgrade - Agent upgrade operations
   • /manager/restart - Manager restart operations

Authentication

The server uses JWT token authentication with automatic token caching:

• Tokens are cached for 14 minutes (15-minute validity)
• Automatic re-authentication when tokens expire
• Basic auth only used for initial token acquisition

Usage

Running the Server

bun run start

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "wazuh": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/wazuh/src/index.ts"],
      "env": {
        "WAZUH_API_URL": "https://your-wazuh-manager:55000",
        "WAZUH_API_USER": "your-api-user",
        "WAZUH_API_PASSWORD": "your-api-password"
      }
    }
  }
}

Available Tools

1. wazuh_agent_list

List Wazuh agents with optional status filtering.

Parameters:

• status (string, optional): Filter by connection status
  • Options: active, disconnected, pending, never_connected, all
  • Default: all
• limit (number, optional): Max results (1-500, default: 50)
• offset (number, optional): Pagination offset (default: 0)

Returns:

{
  "total": 10,
  "agents": [
    {
      "id": "001",
      "name": "web-server-01",
      "ip": "10.0.1.100",
      "os": "Ubuntu 22.04",
      "status": "active",
      "last_keep_alive": "2024-01-15T10:30:00Z",
      "group": ["web", "production"],
      "version": "4.7.0"
    }
  ]
}

2. wazuh_alert_search

Search and filter security alerts.

Parameters:

• query (string, optional): Search query string
• level (number, optional): Alert severity level (1-15)
• agent_id (string, optional): Filter by agent ID
• date_range (object, optional): Time range filter
  • start (string): ISO datetime (e.g., "2024-01-01T00:00:00Z")
  • end (string): ISO datetime
• limit (number, optional): Max results (1-500, default: 50)
• offset (number, optional): Pagination offset (default: 0)

Returns:

{
  "total": 42,
  "alerts": [
    {
      "id": "alert-123",
      "timestamp": "2024-01-15T10:30:15Z",
      "agent_id": "001",
      "agent_name": "web-server-01",
      "rule_id": 5710,
      "rule_description": "sshd: Attempt to login using a non-existent user",
      "rule_level": 5,
      "rule_groups": ["authentication_failed", "syslog", "sshd"],
      "location": "/var/log/auth.log",
      "full_log": "Jan 15 10:30:15 web-01 sshd[1234]: Invalid user admin from 192.168.1.100"
    }
  ]
}

3. wazuh_vulnerability_list

List vulnerabilities detected on an agent.

Parameters:

• agent_id (string, required): Agent ID (3+ digits)
• severity (string, optional): Filter by severity
  • Options: Critical, High, Medium, Low, Untriaged
• limit (number, optional): Max results (1-500, default: 50)
• offset (number, optional): Pagination offset (default: 0)

Returns:

{
  "total": 15,
  "vulnerabilities": [
    {
      "cve": "CVE-2024-1234",
      "name": "openssh-server",
      "version": "8.2p1-4ubuntu0.5",
      "severity": "High",
      "cvss_score": 7.5,
      "detection_time": "2024-01-15T09:00:00Z",
      "status": "pending",
      "external_references": ["https://nvd.nist.gov/vuln/detail/CVE-2024-1234"]
    }
  ]
}

4. wazuh_sca_results

Retrieve Security Configuration Assessment results.

Parameters:

• agent_id (string, required): Agent ID (3+ digits)
• policy_id (string, optional): Specific policy ID for detailed results
• limit (number, optional): Max results (1-500, default: 50)
• offset (number, optional): Pagination offset (default: 0)

Returns (Policy Overview):

{
  "total": 3,
  "policies": [
    {
      "policy_id": "cis_ubuntu22-04",
      "name": "CIS Benchmark for Ubuntu Linux 22.04",
      "description": "Center for Internet Security benchmark",
      "pass": 85,
      "fail": 12,
      "invalid": 3,
      "score": 87
    }
  ]
}

Returns (Detailed Checks - when policy_id specified):

{
  "total": 100,
  "checks": [
    {
      "id": "1234",
      "title": "Ensure password expiration is 90 days or less",
      "description": "Password expiration should be configured",
      "rationale": "Reduces risk of compromised credentials",
      "remediation": "Set PASS_MAX_DAYS to 90 in /etc/login.defs",
      "result": "passed",
      "status": "compliant",
      "reason": "PASS_MAX_DAYS is set to 90"
    }
  ]
}

5. wazuh_integrity_check

Retrieve File Integrity Monitoring (FIM/Syscheck) results.

Parameters:

• agent_id (string, required): Agent ID (3+ digits)
• file_path (string, optional): Filter by file path (supports wildcards)
• limit (number, optional): Max results (1-500, default: 50)
• offset (number, optional): Pagination offset (default: 0)

Returns:

{
  "total": 25,
  "files": [
    {
      "file": "/etc/passwd",
      "size": 2048,
      "permissions": "rw-r--r--",
      "uid": "0",
      "gid": "0",
      "md5": "5d41402abc4b2a76b9719d911017c592",
      "sha1": "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",
      "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
      "mtime": "2024-01-15T08:30:00Z",
      "event": "modified",
      "date": "2024-01-15T08:30:15Z"
    }
  ]
}

6. wazuh_rule_list

List Wazuh detection rules with filtering.

Parameters:

• level (number, optional): Filter by severity level (1-15)
• group (string, optional): Filter by rule group (e.g., "authentication", "web", "syslog")
• search (string, optional): Search in rule descriptions
• limit (number, optional): Max results (1-500, default: 50)
• offset (number, optional): Pagination offset (default: 0)

Returns:

{
  "total": 3500,
  "rules": [
    {
      "id": 5710,
      "level": 5,
      "description": "sshd: Attempt to login using a non-existent user",
      "groups": ["authentication_failed", "syslog", "sshd"],
      "file": "0095-sshd_rules.xml",
      "pci_dss": ["10.2.4", "10.2.5"],
      "gdpr": ["IV_35.7.d", "IV_32.2"],
      "hipaa": ["164.312.b"],
      "nist": ["AU.14", "AC.7"]
    }
  ]
}

7. wazuh_stats

Retrieve aggregated statistics for manager or specific agent.

Parameters:

• agent_id (string, optional): Agent ID for agent-specific stats
• date (string, optional): Date in YYYY-MM-DD format (defaults to today)

Returns:

{
  "total_alerts": 1234,
  "by_level": {
    "3": 450,
    "5": 380,
    "7": 250,
    "10": 120,
    "12": 34
  },
  "by_agent": {
    "001": 450,
    "002": 380,
    "003": 404
  },
  "top_rules": [
    {
      "rule_id": 5710,
      "description": "sshd: Attempt to login using a non-existent user",
      "count": 125
    }
  ],
  "hourly_distribution": {
    "00": 45,
    "01": 32,
    "02": 28,
    "...": "..."
  }
}

Error Handling

The server provides detailed error messages for common issues:

• Missing credentials: "WAZUH_API_URL, WAZUH_API_USER, and WAZUH_API_PASSWORD are required"
• Invalid URL: "Wazuh API URL must use HTTPS"
• Authentication failure: "Wazuh auth failed: 401"
• Invalid agent ID: "Agent ID must be a 3+ digit number"
• Blocked endpoint: "Endpoint /active-response is blocked for safety"
• API errors: "Wazuh API error: 404 Not Found"

Security Considerations

1. Credentials: Store API credentials securely, never commit to version control
2. HTTPS Only: Non-HTTPS connections are rejected
3. Read-Only: No write operations supported
4. Token Caching: Minimizes authentication requests
5. Endpoint Blocking: Dangerous endpoints are explicitly blocked
6. Input Validation: All inputs validated with Zod schemas
7. Agent ID Validation: Ensures valid agent ID format

Best Practices

1. Use Dedicated User: Create a Wazuh API user with read-only permissions
2. Monitor Access: Review API access logs regularly
3. Rotate Credentials: Change API passwords periodically
4. Limit Network Access: Restrict API access to authorized hosts
5. Use Pagination: For large result sets, use limit/offset parameters
6. Filter Results: Use available filters to reduce data transfer

API Compatibility

This server is compatible with Wazuh API v4.x. Tested with:

• Wazuh 4.7.0
• Wazuh 4.6.0
• Wazuh 4.5.0

Troubleshooting

Authentication Issues

# Test API connectivity
curl -k -u user:password -X POST https://your-wazuh-manager:55000/security/user/authenticate

# Verify credentials
echo $WAZUH_API_USER
echo $WAZUH_API_URL

Connection Errors

• Ensure Wazuh API port (55000) is accessible
• Verify SSL certificate if using self-signed certificates
• Check firewall rules allow HTTPS traffic

No Data Returned

• Verify agent is connected: Check with wazuh_agent_list
• Confirm data exists in Wazuh Manager
• Check date range filters are correct
• Verify user has read permissions

Development

Project Structure

wazuh/
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md            # This file
└── src/
    ├── index.ts         # Main server entry point
    ├── schemas.ts       # Zod validation schemas
    ├── security.ts      # Authentication and security
    └── tools/
        ├── wazuh-agent-list.ts
        ├── wazuh-alert-search.ts
        ├── wazuh-vulnerability-list.ts
        ├── wazuh-sca-results.ts
        ├── wazuh-integrity-check.ts
        ├── wazuh-rule-list.ts
        └── wazuh-stats.ts

Building

bun run build

Testing

# Set environment variables
export WAZUH_API_URL="https://your-wazuh-manager:55000"
export WAZUH_API_USER="test-user"
export WAZUH_API_PASSWORD="test-password"

# Run server
bun run start

License

MIT

Contributing

Contributions are welcome! Please ensure:

1. All Zod schemas have .describe() on every field
2. Error handling is comprehensive
3. Documentation is updated
4. Security best practices are followed

Support

For issues and questions:

• Wazuh Documentation: https://documentation.wazuh.com/
• Wazuh API Reference: https://documentation.wazuh.com/current/user-manual/api/reference.html
• MCP Documentation: https://modelcontextprotocol.io/

Changelog

1.0.0

• Initial release
• 7 read-only tools for Wazuh integration
• JWT authentication with token caching
• Comprehensive error handling
• Security endpoint blocking