Ossec MCP

OSSEC MCP服务器

功能齐全 模型上下文协议（MCP） 服务器 OSSEC HIDS （基于主机的入侵检测系统）。该服务器将OSSEC的安全监控功能作为MCP工具、资源和提示公开，使AI助手能够查询警报、管理代理、检查规则、运行完整性检查等。

特性

工具（26个工具）

资源（8个静态资源+3个资源模板）

静态资源：

资源模板（动态、参数化）：

提示（5个提示）

安全

此服务器包括几个加固措施：

• 安全XML解析 --用途 defusedxml 在解析OSSEC规则、解码器和配置文件时，防止XXE和十亿笑攻击。
• 输入验证 --所有用户提供的参数(agent_id，代理人 name, ip, command, filename)在传递给CLI工具或API之前，根据严格的regex模式进行验证，从而防止命令注入和路径遍历。
• 路径遍历预防 --文件系统中使用的文件名参数 glob() 调用拒绝路径分隔符和 .. 序列。
• 错误清理 --返回给客户端的错误消息已剥离文件系统路径，以避免泄漏内部目录结构。
• 有限的资源使用 --文件读取的上限为10MB，日志尾部操作使用有界内存，查询限制被限制在配置的最大值。
• 安全默认值 --SSE传输绑定到 127.0.0.1 默认情况下（不是 0.0.0.0).API通信始终使用HTTPS。
• 不执行shell --所有子流程调用都使用 create_subprocess_exec 对于参数列表，永远不要使用shell字符串。

安装

先决条件

• Python 3.10+
• 已安装OSSEC HIDS（本地模式）或Wazuh/OSSEC API访问（API模式）
• Linux主机（或带WSL的Windows）用于本地模式

安装OSSEC HIDS

如果尚未安装OSSEC，您可以从源代码编译它。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 =1.0|MCP SDK与FastMCP服务器框架|
| `pydantic` >=2.0.0|数据验证|
| `pydantic-settings` >=2.0.0|基于环境/文件的配置|
| `httpx` >=0.25.0 | API模式的异步HTTP客户端|
| `python-dateutil` >=2.8.0|时间戳解析|
| `defusedxml` >=0.7.0|安全XML解析|

开发依赖关系： `pytest`, `pytest-asyncio`, `ruff`

### 从源代码安装

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]'

### 配置

Copy the example environment file

cp .env.example .env

Edit with your OSSEC settings

At minimum, verify OSSEC_PATH points to your installation

配置是从环境变量或 `.env` 文件。所有选项及其默认值：

|变量|默认值|描述|
|----------|---------|-------------|
| `OSSEC_PATH` | `/var/ossec` |OSSEC安装根目录|
| `OSSEC_MODE` | `local` | `local` （CLI工具+文件系统）或 `api` （REST API）|
| `OSSEC_API_HOST` | `localhost` |API主机名（仅限API模式）|
| `OSSEC_API_PORT` | `55000` |API端口（仅限API模式）|
| `OSSEC_API_USER` | `admin` |API用户名（仅限API模式）|
| `OSSEC_API_PASSWORD` | *（空）* |API密码（仅限API模式）|
| `OSSEC_API_SSL_VERIFY` | `true` |验证API连接的TLS证书|
| `MCP_TRANSPORT` | `stdio` |MCP传输： `stdio` 或 `sse` |
| `MCP_HOST` | `127.0.0.1` |SSE绑定地址（仅限SSE传输）|
| `MCP_PORT` | `8000` |SSE港口（仅限SSE运输）|
| `MAX_ALERTS` | `500` |每个查询返回的最大警报数|
| `MIN_ALERT_LEVEL` | `1` |默认最低警报级别筛选器|
| `LOG_LEVEL` | `INFO` |日志记录级别(`DEBUG`, `INFO`, `WARNING`, `ERROR`) |

## 用法

### 运行服务器

stdio transport (default -- for AI tool integration)

ossec-mcp-server

Or run as a Python module

python -m ossec_mcp

如果venv未激活，请使用完整路径：

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

### Sudo/权限

OSSEC文件位于 `/var/ossec/` 归...所有 `root` 和那个 `ossec` 用户。MCP服务器必须以提升的权限运行，才能读取警报、日志、规则和配置。没有 `sudo`，大多数工具将返回 `Permission denied`.

有两种方法可以处理这个问题：

**选项A——内联密码（简单，将密码存储在配置中）：**

使用 `sudo -S` 通过stdin输入密码，然后 `exec sudo` 要使用缓存的凭据运行服务器，请执行以下操作：

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

第一个命令对凭据进行身份验证和缓存。这 `exec sudo` 然后使用缓存的会话运行服务器，使MCP stdio协议的stdin保持空闲。

**选项B——无密码sudo（更安全，一次性设置）：**

添加一个sudoers规则，允许在没有密码的情况下只运行这个二进制文件：

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

那么配置只需要 `sudo` 无需任何密码处理：

sudo /path/to/ossec-mcp-server

以下所有示例均使用 **选项A** （内联密码）。替换 `
` 使用您的Linux sudo密码。如果您更喜欢选项B，请删除 `echo ... | sudo -S true 2>/dev/null;` 前缀和用法 `sudo` 直接。

______________________________________________________________________

### 与AI工具集成

OSSEC是一个Linux HIDS。MCP服务器需要访问OSSEC安装——可以在同一Linux主机上本地访问，也可以通过Wazuh/OSSEC REST API远程访问。

**如果您的编辑器与OSSEC在同一台Linux机器上运行**，下面的命令直接工作。 **如果你的编辑器在Windows/macOS上，而OSSEC在WSL或远程服务器上**，请参阅下面的“带WSL的Windows”和“远程/API模式”部分。

______________________________________________________________________

### VS代码（GitHub副本）

现成的配置文件包含在 `.vscode/mcp.json`。将包安装到venv中后，当您打开项目文件夹时，VS Code会自动拾取它。

要手动或在其他项目中配置它，请创建 `.vscode/mcp.json`:

**原生Linux：**

{ "servers": { "ossec": { "type": "stdio", "command": "bash", "args": [ "-c", "echo ' ' | 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" } } } }

**带WSL的Windows：**

{ "servers": { "ossec": { "type": "stdio", "command": "wsl.exe", "args": [ "-d", "kali-linux", "-e", "bash", "-c", "echo ' ' | 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" } } } }

然后在VS Code中：打开Copilot Chat，切换到 **代理** 模式，OSSEC工具将可用。

______________________________________________________________________

### 克劳德代码（CLI）

现成的配置文件包含在 `.mcp.json` 在项目根中。Claude Code在您运行时会自动读取此内容 `claude` 从这个目录。

要手动添加它，请执行以下操作：

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

或创建/编辑 `.mcp.json` 在项目根目录中：

{ "mcpServers": { "ossec": { "command": "bash", "args": [ "-c", "echo ' ' | 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" } } } }

对于所有项目的全球可用性，请添加 `~/.claude.json` 相反。

______________________________________________________________________

### 克劳德桌面版

在以下位置编辑配置文件：

- macOS： `~/Library/Application Support/Claude/claude_desktop_config.json`
- 窗户： `%APPDATA%\Claude\claude_desktop_config.json`
- Linux： `~/.config/Claude/claude_desktop_config.json`

**原生Linux/macOS：**

{ "mcpServers": { "ossec": { "command": "bash", "args": [ "-c", "echo ' ' | 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" } } } }

**带WSL的Windows：**

{ "mcpServers": { "ossec": { "command": "wsl.exe", "args": [ "-d", "kali-linux", "-e", "bash", "-c", "echo ' ' | 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/mcp.json`。打开项目时，Cursor会自动读取此内容。

要手动配置，请创建 `.cursor/mcp.json` 在项目根目录中：

**原生Linux：**

{ "mcpServers": { "ossec": { "command": "bash", "args": [ "-c", "echo ' ' | 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" } } } }

**带WSL的Windows：**

{ "mcpServers": { "ossec": { "command": "wsl.exe", "args": [ "-d", "kali-linux", "-e", "bash", "-c", "echo ' ' | 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" } } } }

______________________________________________________________________

### 帆板运动

编辑 `~/.codeium/windsurf/mcp_config.json`:

**原生Linux：**

{ "mcpServers": { "ossec": { "command": "bash", "args": [ "-c", "echo ' ' | 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" } } } }

**带WSL的Windows：**

{ "mcpServers": { "ossec": { "command": "wsl.exe", "args": [ "-d", "kali-linux", "-e", "bash", "-c", "echo ' ' | 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" } } } }

______________________________________________________________________

### 带WSL的Windows（摘要）

上述所有工具部分均已包括 **带WSL的Windows** 示例。关键模式是：

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

替换：

- `` 使用您的WSL发行版名称（run `wsl -l` 例如。， `kali-linux`)
- `
` 使用您的Linux sudo密码
- `` 对于完整路径。， `/mnt/d/OSSEC_MCP_SERVER/.venv/bin/ossec-mcp-server`

**克劳德代码** （在Windows上）：

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

______________________________________________________________________

### 远程/API模式

如果OSSEC在远程服务器上运行，并且您无法在本地同时运行MCP服务器，请使用API模式。MCP服务器通过HTTPS连接到Wazuh/OSSEC REST API：

{ "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" } } } }

只要它能通过网络到达API端点，它就可以在任何机器上工作——Windows、macOS或Linux。

______________________________________________________________________

### SSE运输

对于网络可访问的部署（例如，多个客户端的共享MCP服务器）：

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

SSE绑定到 `127.0.0.1` 默认情况下。集 `MCP_HOST=0.0.0.0` 明确地将其暴露在外部。

## 连接模式

### 本地模式（默认）

通过以下方式直接与同一主机上的OSSEC交互：

- **CLI工具**: `ossec-control`, `manage_agents`, `agent_control`, `syscheck_control`, `rootcheck_control`, `ossec-logtest`
- **文件系统**：读取警报（JSON和纯文本格式）、内部日志、规则XML文件、解码器XML文件和 `ossec.conf` 直接

要求服务器与OSSEC管理器在同一台机器上运行，或者具有对OSSEC安装目录的文件系统访问权限（例如，通过WSL挂载）。

### API模式

通过HTTPS连接到OSSEC/Wazuh REST API。当MCP服务器在与OSSEC管理器不同的机器上运行时，请使用此选项。集 `OSSEC_MODE=api` 并配置API连接变量。请参阅上面使用部分中的“远程/API模式”示例。

## OSSEC警报级别参考

|级别|严重性|描述|
|-------|----------|-------------|
|0|忽略|未分类|
|1--3|低|系统通知，成功事件|
|4--6|中等|错误、警告、配置错误|
|7--9|高|检测到脏话，首次事件|
|10--11|非常高|多次失败，完整性发生变化|
|12--14 |严重|防火墙掉线，高影响事件|
|15--16|严重|攻击成功，关键完整性变化|

## 测试

该项目包括四个测试套件（共356个测试）：

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

安全测试验证了输入净化、路径遍历预防、XML安全（debpedxml）、错误消息净化、时区感知的日期时间处理、边界夹紧和精确的组匹配。

MCP协议测试将服务器作为子进程生成，并连接一个真正的MCP SDK客户端，以验证初始化、工具列表、工具调用、资源读取，并通过stdio传输进行提示检索。

实时OSSEC集成测试运行 `OssecClient` 直接针对真实的OSSEC安装，执行服务状态、日志检索、规则/解码器解析、警报查询、系统检查、根检查、代理列表、统计数据和配置读取。这些要求 `sudo` 因为OSSEC文件归 `ossec` 用户。

## 项目结构

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

## 许可证

[麻省理工学院](https://github.com/president-xd/ossec-mcp/blob/main/LICENSE)