npm package: @modular-intelligence/wazuh
Description: MCP server for Wazuh SIEM/HIDS API — agent management, alerts, and security monitoring
Latest version: 1.0.2

# 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

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

## Configuration

Set the following environment variables:

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

```bash
bun run start
```

### MCP Client Configuration

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

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

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

```bash
bun run build
```

### Testing

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