AI4IA-MCP-Server

A Model Context Protocol Server for Role-Based Learning in AI-Assisted Cybersecurity Incident Analysis with Wazuh SIEM and OpenSearch

🔍 Overview

AI4IA-MCP is an intelligent Model Context Protocol (MCP) server that bridges AI assistants with Wazuh SIEM infrastructure. It provides natural language access to security alerts, vulnerability analysis, CVE databases, and network documentation through a comprehensive set of tools designed for security operations teams.

This server enables LLM assistants like Claude to perform complex security operations tasks including alert correlation, statistical analysis, vulnerability assessment, and incident investigation through conversational interfaces.

🏗️ Architecture

┌─────────────────┐
│   AI Assistant  │
│    (Claude)     │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  Wazuh AI4IA    │
│   MCP Server    │
│   (FastMCP)     │
└────────┬────────┘
         │
         ├──────────────┐
         │              │
┌────────▼────────┐ ┌──▼─────────┐
│   OpenSearch    │ │  Local     │
│    Cluster      │ │  Files     │
│  (Wazuh Data)   │ │  (CVE/PDF) │
└─────────────────┘ └────────────┘

✨ Key Features

🎯 Core Capabilities

• Real-time Alert Management: Query and filter Wazuh security alerts with flexible time ranges
• Intelligent Alert Correlation: Automatically discover related security events based on temporal proximity, agents, MITRE techniques, and rule patterns
• Vulnerability Analysis: Deep-dive into CVE vulnerabilities with CVSS scoring, categorization, and mitigation recommendations
• Statistical Insights: Generate comprehensive reports on alert patterns, severity distributions, and system performance
• Agent Monitoring: Track status and health of all Wazuh agents in your infrastructure
• CVE Database: Search and filter from extensive CVE datasets by severity, year, and vulnerability type
• Network Documentation: Parse and analyze network diagrams and PDF documentation

🛡️ Security Operations Use Cases

• Incident Response: Quickly correlate alerts to identify attack campaigns
• Threat Hunting: Search for specific patterns across historical security data
• Vulnerability Management: Prioritize patching based on detected vulnerabilities
• Compliance Reporting: Generate statistics for audit and compliance requirements
• Performance Monitoring: Track Wazuh system health and event processing metrics

🚀 Installation

1. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the project root:

OPENSEARCH_HOST=localhost:9200
OPENSEARCH_USER=admin
OPENSEARCH_PASSWORD=your_secure_password_here

4. Prepare Data Files

Place the following files in the project directory:

• cve_data.csv - CVE vulnerability database
• GOAD.pdf - Network documentation (optional)
• NetDiagram.png - Network diagram (optional)

🔧 Configuration

OpenSearch Connection

The server connects to OpenSearch using the following indices:

• wazuh-alerts-* - Security alerts
• wazuh-monitoring-* - Agent monitoring data
• wazuh-statistics-* - System performance metrics
• wazuh-states-vulnerabilities-* - Vulnerability states

CVE Database Format

The cve_data.csv should contain the following columns:

• vulnerability.id - CVE identifier (e.g., CVE-2024-12345)
• vulnerability.severity - Severity level (low, medium, high, critical)
• vulnerability.description - Detailed vulnerability description

📖 Available Tools

1. get_alerts

Retrieve Wazuh security alerts with flexible filtering.

# Example usage
get_alerts(
    time_range="2h",      # Last 2 hours
    rule_level=10,        # Critical alerts only
    agent_name="server-01",
    size=100
)

Parameters:

• time_range: Time window (e.g., "2h", "90m", "30m") - max 6 hours
• rule_level: Filter by severity level (1-15)
• agent_name: Filter by specific agent
• size: Number of results to return (default: 100)

2. correlate_alerts

Find related alerts that may indicate a coordinated attack.

# Example usage
correlate_alerts(
    alert_id="ABC123...",
    time_window="1h",
    max_alerts=50
)

Features:

• Temporal correlation
• Same agent detection
• Related rule groups
• Common MITRE ATT&CK techniques
• Correlation factor scoring

3. get_alert_statistics

Generate comprehensive statistical reports on alert patterns.

# Example usage
get_alert_statistics(
    time_range="6h",
    agent_name="web-server",
    group="web"
)

Provides:

• Alert frequency over time
• Severity distribution
• Top alert types
• Most active agents
• MITRE technique frequency
• Rule group analysis

4. analyze_vulnerability

Deep analysis of detected vulnerabilities with CVE details.

# Example usage
analyze_vulnerability(
    vulnerability_id="CVE-2024-21417",
    start_time="now-12h",
    limit=50
)

Includes:

• CVE details and descriptions
• CVSS scores and severity
• Detection timestamps
• Affected agents
• Category classification
• Mitigation suggestions

5. filter_network_cves

Search the CVE database with multiple filter criteria.

# Example usage
filter_network_cves(
    severity="critical",
    year="2024",
    type="SQL Injection",
    limit=100
)

6. get_agent_status

Monitor the health and status of all Wazuh agents.

# Example usage
get_agent_status()

Returns:

• Agent name and ID
• IP address
• Connection status
• Last keep-alive timestamp
• Wazuh version

7. get_statistics

Retrieve Wazuh system performance metrics.

# Example usage
get_statistics(timeframe="3h")

Metrics:

• Events received/processed/dropped
• Events per second (EDPS)
• Queue usage percentages
• Processing efficiency
• System health indicators

8. read_network_documentation

Extract text from PDF network documentation.

# Example usage
read_network_documentation(pdf_filename="GOAD.pdf")

9. process_network_diagram

Analyze network topology diagrams.

# Example usage
process_network_diagram(
    png_filename="NetDiagram.png",
    analysis_type="detailed"
)

⚠️ Important Limitations

Time Range Restrictions

Different tools have specific time range limitations for optimal performance:

• `get_alerts`: Maximum 6 hours
• `correlate_alerts`: Maximum 6 hours
• `get_alert_statistics`: Maximum 6 hours
• `get_statistics`: Maximum 6 hours
• `analyze_vulnerability`: Maximum 12 hours

These limits prevent rate limiting and ensure responsive query performance.

💡 Usage Examples

Example 1: Investigating a Security Incident

User: "Show me all critical alerts from the last 2 hours"
AI: [Uses get_alerts with rule_level=12+, time_range="2h"]

User: "What vulnerabilities were detected on affected systems?"
AI: [Uses analyze_vulnerability with affected agents]

Example 2: Vulnerability Management

User: "Find all critical CVEs from 2024"
AI: [Uses filter_network_cves with severity="critical", year="2024"]

User: "Which systems are affected by CVE-2024-12345?"
AI: [Uses analyze_vulnerability with vulnerability_id]

Example 3: Performance Monitoring

User: "How is the Wazuh system performing?"
AI: [Uses get_statistics for system metrics]

User: "Show alert trends over the last 6 hours"
AI: [Uses get_alert_statistics for trend analysis]

Common Errors

"No alerts found": Check time range and filter criteria "CVE database not found": Ensure cve_data.csv is in the project directory "Time range exceeds limit": Reduce time range to specified maximum "Connection refused": Verify OpenSearch is running and accessible

🚀 Quick Start with Claude Desktop

Configuration

1. Locate your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

1. Add the server configuration:

{
    "mcpServers": {
        "AI4IA": {
            "command": "python",
            "args": ["/absolute/path/to/AI4IA-MCP/mcp_server.py"]
        }
    }
}

📄 License

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

Acknowledgments

• mcp-wazuh-py by @cyberbalsa - This project is based on and inspired by this work on Wazuh MCP integration
• GOAD (Game of Active Directory) by Orange Cyberdefense — a pentesting Active Directory lab project that provides vulnerable AD environments for practicing attack techniques.
• Wazuh - Open source security platform
• FastMCP - Model Context Protocol framework
• OpenSearch - Search and analytics engine
• Anthropic - Claude AI assistant