OSSEC MCP Server

A fully functional Model Context Protocol (MCP) server for OSSEC HIDS (Host-based Intrusion Detection System). This server exposes OSSEC's security monitoring capabilities as MCP tools, resources, and prompts -- enabling AI assistants to query alerts, manage agents, inspect rules, run integrity checks, and more.

Features

Tools (26 tools)

Category	Tool	Description
Alerts	get_alerts	Retrieve alerts with filtering by level, group, time range, and search
	get_alert_summary	Aggregated alert statistics by severity, group, and top rules
	search_alerts	Free-text search across all alert data
Agents	list_agents	List all managed agents with status
	get_agent_info	Detailed info for a specific agent
	add_agent	Register a new agent
	remove_agent	Remove an agent registration
	restart_agent	Restart an agent remotely
Rules	get_rules	Search rules by ID, level, group, or keyword
	get_rule_details	Full rule definition with match criteria
	list_rule_files	List all rule XML files
	get_decoders	Search and list log decoders
Syscheck	get_syscheck_results	File Integrity Monitoring results
	run_syscheck_scan	Trigger a FIM scan
	clear_syscheck_database	Reset FIM baseline
Rootcheck	get_rootcheck_results	Rootkit/anomaly detection results
	run_rootcheck_scan	Trigger rootcheck scan
Status	get_ossec_status	Service health for all daemons
	restart_ossec	Restart all OSSEC services
	get_ossec_logs	Internal OSSEC logs with filtering
	get_ossec_stats	Processing statistics
	get_ossec_configuration	Parsed configuration (full or by section)
	get_ossec_configuration_raw	Raw ossec.conf XML
Log Test	run_logtest	Test log lines against rules/decoders
Response	get_active_responses	List configured active responses
	run_active_response	Execute active response on an agent

Resources (8 static resources + 3 resource templates)

Static resources:

URI	Description
ossec://status	Current service status
ossec://alerts/recent	Last 50 alerts
ossec://alerts/critical	Critical alerts (level 12+, last 24h)
ossec://agents/list	All agents
ossec://config/main	Parsed configuration
ossec://config/raw	Raw XML configuration
ossec://rules/summary	Rule files summary
ossec://logs/recent	Recent internal logs

Resource templates (dynamic, parameterized):

URI Template	Description
ossec://agents/{agent_id}	Specific agent detail
ossec://agents/{agent_id}/syscheck	Agent FIM results
ossec://agents/{agent_id}/rootcheck	Agent rootcheck results

Prompts (5 prompts)

Prompt	Description
analyze_alerts	Structured security alert analysis with recommendations
investigate_agent	Deep-dive investigation of a specific agent
security_audit	Comprehensive OSSEC deployment audit
incident_response	Guided IR workflow for security events
tune_rules	Rule tuning to reduce false positives

Security

This server includes several hardening measures:

• Secure XML parsing -- Uses defusedxml to prevent XXE and billion laughs attacks when parsing OSSEC rules, decoders, and configuration files.
• Input validation -- All user-supplied parameters (agent_id, agent name, ip, command, filename) are validated against strict regex patterns before being passed to CLI tools or the API, preventing command injection and path traversal.
• Path traversal prevention -- Filename parameters used in filesystem glob() calls reject path separators and .. sequences.
• Error sanitization -- Error messages returned to clients have filesystem paths stripped to avoid leaking internal directory structure.
• Bounded resource usage -- File reads are capped at 10 MB, log tail operations use bounded memory, and query limits are clamped to configured maximums.
• Secure defaults -- SSE transport binds to 127.0.0.1 by default (not 0.0.0.0). API communication always uses HTTPS.
• No shell execution -- All subprocess calls use create_subprocess_exec with argument lists, never shell strings.

Installation

Prerequisites

• Python 3.10+
• OSSEC HIDS installed (local mode) or Wazuh/OSSEC API access (API mode)
• Linux host (or Windows with WSL) for local mode

Installing OSSEC HIDS

If OSSEC is not already installed, you can compile it from source. Example for Debian/Ubuntu/Kali:

# Install build dependencies
sudo apt update && sudo apt install -y \
  build-essential make gcc libssl-dev libpcre2-dev \
  zlib1g-dev wget libsystemd-dev

# Download OSSEC 3.7.0
cd /tmp
wget https://github.com/ossec/ossec-hids/archive/refs/tags/3.7.0.tar.gz
tar -zxf 3.7.0.tar.gz
cd ossec-hids-3.7.0

# Create non-interactive install config
cat > etc/preloaded-vars.conf << 'EOF'
USER_LANGUAGE="en"
USER_NO_STOP="y"
USER_INSTALL_TYPE="local"
USER_DIR="/var/ossec"
USER_DELETE_DIR="y"
USER_ENABLE_ACTIVE_RESPONSE="y"
USER_ENABLE_SYSCHECK="y"
USER_ENABLE_ROOTCHECK="y"
USER_ENABLE_EMAIL="n"
USER_ENABLE_SYSLOG="y"
USER_ENABLE_FIREWALL_RESPONSE="n"
USER_WHITE_LIST="127.0.0.1"
EOF

# Compile and install
sudo ./install.sh

# Start OSSEC
sudo /var/ossec/bin/ossec-control start

# Verify
sudo /var/ossec/bin/ossec-control status

After installation, the following daemons should be running: ossec-analysisd, ossec-logcollector, ossec-syscheckd, ossec-monitord, ossec-execd.

Dependencies

Package	Purpose
mcp >= 1.0.0	MCP SDK with FastMCP server framework
pydantic >= 2.0.0	Data validation
pydantic-settings >= 2.0.0	Environment/file-based configuration
httpx >= 0.25.0	Async HTTP client for API mode
python-dateutil >= 2.8.0	Timestamp parsing
defusedxml >= 0.7.0	Secure XML parsing

Dev dependencies: pytest, pytest-asyncio, ruff

Install from source

# Clone or download the project
cd OSSEC_MCP_SERVER

# Create a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# Install the package
pip install -e .

# Or install with dev dependencies
pip install -e '.[dev]'

Configure

# Copy the example environment file
cp .env.example .env

# Edit with your OSSEC settings
# At minimum, verify OSSEC_PATH points to your installation

Configuration is loaded from environment variables or a .env file. All options and their defaults:

Variable	Default	Description
OSSEC_PATH	/var/ossec	OSSEC installation root directory
OSSEC_MODE	local	local (CLI tools + filesystem) or api (REST API)
OSSEC_API_HOST	localhost	API hostname (API mode only)
OSSEC_API_PORT	55000	API port (API mode only)
OSSEC_API_USER	admin	API username (API mode only)
OSSEC_API_PASSWORD	(empty)	API password (API mode only)
OSSEC_API_SSL_VERIFY	true	Verify TLS certificates for API connections
MCP_TRANSPORT	stdio	MCP transport: stdio or sse
MCP_HOST	127.0.0.1	SSE bind address (SSE transport only)
MCP_PORT	8000	SSE port (SSE transport only)
MAX_ALERTS	500	Maximum alerts returned per query
MIN_ALERT_LEVEL	1	Default minimum alert level filter
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)

Usage

Run the server

# stdio transport (default -- for AI tool integration)
ossec-mcp-server

# Or run as a Python module
python -m ossec_mcp

If the venv is not activated, use the full path:

/path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server

Sudo / permissions

OSSEC files under /var/ossec/ are owned by root and the ossec user. The MCP server must run with elevated privileges to read alerts, logs, rules, and configuration. Without sudo, most tools will return Permission denied.

There are two ways to handle this:

Option A -- Inline password (simple, stores password in config):

Use sudo -S to feed the password via stdin, then exec sudo to run the server with cached credentials:

echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /path/to/ossec-mcp-server

The first command authenticates and caches the credential. The exec sudo then runs the server using the cached session -- keeping stdin free for the MCP stdio protocol.

Option B -- Passwordless sudo (more secure, one-time setup):

Add a sudoers rule that allows running only this one binary without a password:

echo 'YOUR_USER ALL=(ALL) NOPASSWD: /path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server' \
  | sudo tee /etc/sudoers.d/ossec-mcp
sudo chmod 440 /etc/sudoers.d/ossec-mcp

Then the config only needs sudo without any password handling:

sudo /path/to/ossec-mcp-server

All examples below use Option A (inline password). Replace <PASSWORD> with your Linux sudo password. If you prefer Option B, remove the echo ... | sudo -S true 2>/dev/null; prefix and use sudo directly.

---

Integration with AI tools

OSSEC is a Linux HIDS. The MCP server needs access to the OSSEC installation -- either locally on the same Linux host, or remotely via the Wazuh/OSSEC REST API.

If your editor is running on the same Linux machine as OSSEC, the commands below work directly. If your editor is on Windows/macOS and OSSEC is in WSL or a remote server, see the "Windows with WSL" and "Remote / API mode" sections further down.

---

VS Code (GitHub Copilot)

A ready-to-use config file is included at .vscode/mcp.json. After installing the package into the venv, VS Code will pick it up automatically when you open the project folder.

To configure it manually or in another project, create .vscode/mcp.json:

Native Linux:

{
  "servers": {
    "ossec": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

Windows with WSL:

{
  "servers": {
    "ossec": {
      "type": "stdio",
      "command": "wsl.exe",
      "args": [
        "-d", "kali-linux",
        "-e", "bash", "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /mnt/d/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

Then in VS Code: open Copilot Chat, switch to Agent mode, and the OSSEC tools will be available.

---

Claude Code (CLI)

A ready-to-use config file is included at .mcp.json in the project root. Claude Code reads this automatically when you run claude from this directory.

To add it manually:

claude mcp add ossec \
  -e OSSEC_PATH=/var/ossec \
  -e OSSEC_MODE=local \
  -- bash -c "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"

Or create/edit .mcp.json in the project root:

{
  "mcpServers": {
    "ossec": {
      "command": "bash",
      "args": [
        "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

For global availability across all projects, add to ~/.claude.json instead.

---

Claude Desktop

Edit the config file at:

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

Native Linux / macOS:

{
  "mcpServers": {
    "ossec": {
      "command": "bash",
      "args": [
        "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

Windows with WSL:

{
  "mcpServers": {
    "ossec": {
      "command": "wsl.exe",
      "args": [
        "-d", "kali-linux",
        "-e", "bash", "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /mnt/d/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

---

Cursor

A ready-to-use config file is included at .cursor/mcp.json. Cursor reads this automatically when you open the project.

To configure manually, create .cursor/mcp.json in the project root:

Native Linux:

{
  "mcpServers": {
    "ossec": {
      "command": "bash",
      "args": [
        "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

Windows with WSL:

{
  "mcpServers": {
    "ossec": {
      "command": "wsl.exe",
      "args": [
        "-d", "kali-linux",
        "-e", "bash", "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /mnt/d/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

---

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

Native Linux:

{
  "mcpServers": {
    "ossec": {
      "command": "bash",
      "args": [
        "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

Windows with WSL:

{
  "mcpServers": {
    "ossec": {
      "command": "wsl.exe",
      "args": [
        "-d", "kali-linux",
        "-e", "bash", "-c",
        "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /mnt/d/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"
      ],
      "env": {
        "OSSEC_PATH": "/var/ossec",
        "OSSEC_MODE": "local"
      }
    }
  }
}

---

Windows with WSL (summary)

All the per-tool sections above already include Windows with WSL examples. The key pattern is:

wsl.exe -d <DISTRO> -e bash -c "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo <ABSOLUTE_PATH_TO_SERVER>"

Replace:

• <DISTRO> with your WSL distro name (run wsl -l to list, e.g., kali-linux)
• <PASSWORD> with your Linux sudo password
• <ABSOLUTE_PATH_TO_SERVER> with the full path, e.g., /mnt/d/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server

Claude Code (on Windows):

claude mcp add ossec \
  -e OSSEC_PATH=/var/ossec \
  -e OSSEC_MODE=local \
  -- wsl.exe -d kali-linux -e bash -c \
  "echo '<PASSWORD>' | sudo -S true 2>/dev/null; exec sudo /mnt/d/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server"

---

Remote / API mode

If OSSEC runs on a remote server and you cannot run the MCP server locally alongside it, use API mode. The MCP server connects to the Wazuh/OSSEC REST API over HTTPS:

{
  "mcpServers": {
    "ossec": {
      "command": "/path/to/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server",
      "env": {
        "OSSEC_MODE": "api",
        "OSSEC_API_HOST": "192.168.1.100",
        "OSSEC_API_PORT": "55000",
        "OSSEC_API_USER": "admin",
        "OSSEC_API_PASSWORD": "your-password",
        "OSSEC_API_SSL_VERIFY": "false"
      }
    }
  }
}

This works from any machine -- Windows, macOS, or Linux -- as long as it can reach the API endpoint over the network.

---

SSE transport

For network-accessible deployment (e.g., shared MCP server for multiple clients):

MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=8000 ossec-mcp-server

SSE binds to 127.0.0.1 by default. Set MCP_HOST=0.0.0.0 explicitly to expose it externally.

Connection Modes

Local mode (default)

Interacts directly with OSSEC on the same host via:

• CLI tools: ossec-control, manage_agents, agent_control, syscheck_control, rootcheck_control, ossec-logtest
• Filesystem: Reads alerts (JSON and plain-text formats), internal logs, rule XML files, decoder XML files, and ossec.conf directly

Requires the server to run on the same machine as the OSSEC manager, or to have filesystem access to the OSSEC installation directory (e.g., via WSL mounts).

API mode

Connects to the OSSEC/Wazuh REST API over HTTPS. Use this when the MCP server runs on a different machine than the OSSEC manager. Set OSSEC_MODE=api and configure the API connection variables. See the "Remote / API mode" example in the Usage section above.

OSSEC Alert Levels Reference

Level	Severity	Description
0	Ignored	Not classified
1--3	Low	System notifications, successful events
4--6	Medium	Errors, warnings, bad configurations
7--9	High	Bad words detected, first-time events
10--11	Very High	Multiple failures, integrity changes
12--14	Critical	Firewall drops, high-impact events
15--16	Severe	Attack success, critical integrity changes

Testing

The project includes four test suites (356 tests total):

# Activate the virtual environment
source .venv/bin/activate

# Unit and integration tests (167 tests)
python tests/test_comprehensive.py

# Security validation tests (72 tests)
python tests/test_security.py

# Live MCP protocol tests via official SDK client (105 tests)
python tests/test_mcp_sdk_protocol.py

# Live OSSEC integration tests (12 tests) -- requires a running OSSEC installation
sudo .venv/bin/python tests/test_live_ossec.py

The security tests validate input sanitization, path traversal prevention, XML safety (defusedxml), error message sanitization, timezone-aware datetime handling, boundary clamping, and exact group matching.

The MCP protocol tests spawn the server as a subprocess and connect a real MCP SDK client to verify initialization, tool listing, tool calls, resource reads, and prompt retrieval over the stdio transport.

The live OSSEC integration tests run the OssecClient directly against a real OSSEC installation, exercising service status, log retrieval, rule/decoder parsing, alert queries, syscheck, rootcheck, agent listing, stats, and configuration reads. These require sudo since OSSEC files are owned by the ossec user.

Project Structure

OSSEC_MCP_SERVER/
├── pyproject.toml                  # Build config, dependencies, entry point
├── .env.example                    # Configuration template
├── .mcp.json                       # Claude Code MCP config (auto-detected)
├── .vscode/mcp.json                # VS Code MCP config (auto-detected)
├── .cursor/mcp.json                # Cursor MCP config (auto-detected)
├── README.md
├── .gitignore
├── src/
│   └── ossec_mcp/
│       ├── __init__.py             # Package version (1.0.0)
│       ├── __main__.py             # python -m ossec_mcp support
│       ├── server.py               # FastMCP server creation and entry point
│       ├── config.py               # Settings via pydantic-settings
│       ├── ossec_client.py         # OSSEC interaction layer (CLI + API)
│       ├── tools/
│       │   ├── alerts.py           # get_alerts, get_alert_summary, search_alerts
│       │   ├── agents.py           # list_agents, get_agent_info, add/remove/restart_agent
│       │   ├── rules.py            # get_rules, get_rule_details, list_rule_files, get_decoders
│       │   ├── syscheck.py         # get_syscheck_results, run_syscheck_scan, clear_syscheck_database
│       │   ├── rootcheck.py        # get_rootcheck_results, run_rootcheck_scan
│       │   ├── status.py           # get_ossec_status, restart_ossec, logs, stats, config
│       │   ├── logtest.py          # run_logtest
│       │   └── active_response.py  # get_active_responses, run_active_response
│       ├── resources/
│       │   └── providers.py        # 8 static resources + 3 resource templates
│       └── prompts/
│           └── templates.py        # 5 prompt templates
└── tests/
    ├── test_comprehensive.py       # 167 unit/integration tests
    ├── test_security.py            # 72 security validation tests
    ├── test_mcp_sdk_protocol.py    # 105 live MCP protocol tests
    └── test_live_ossec.py          # 12 live OSSEC integration tests

License

MIT