@modular-intelligence/wazuh 1.0.0

package/README.md

@@ -0,0 +1,462 @@
+# 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