jelmervdm/sophos-firewall-mcp

# Sophos Firewall MCP Server (`sophos-firewall-mcp`) [](https://github.com/jelmervdm/sophos-firewall-mcp) [](LICENSE) [](pyproject.toml) [-success.svg)](https://github.com/glama-ai/tool-definition-quality-score) 一款用于 Sophos Firewall (SFOS) 的异步 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server，使 AI 助手（如 Antigravity IDE、Claude Desktop、VS Code 和 Cursor）能够管理、审计和排查 Sophos Firewall 网络安全基础设施。 ## 🌟 核心功能 * **异步 XML API 集成：** 基于 `httpx.AsyncClient` 构建，通过 Sophos SFOS XML API endpoint (`/webconsole/APIController`) 实现高吞吐量、非阻塞 IO。 * **7 大综合工具领域（28 个工具）：** * **系统与状态：** 系统版本、序列号、运行时间、服务运行状态以及网络接口配置。 * **防火墙规则：** 安全策略列表、创建、状态切换以及规则删除。 * **主机与网络对象：** IP 主机定义、网络子网、IP 主机组和 FQDN 对象。 * **服务：** 自定义 TCP/UDP 服务对象、端口范围和服务组。 * **NAT 规则：** SNAT 和 DNAT 端口转发规则检查。 * **用户管理：** 本地用户账户配置和实时用户会话监控。 * **VPN 管理：** IPsec 站点到站点隧道和 SSL VPN 远程访问策略。 * **FastMCP 资源：** 通过 URI (`sophos://system/info`, `sophos://interfaces`, `sophos://services/status`) 提供只读系统状态。 * **引导式提示词：** 上下文安全审计 (`audit_firewall_rules`) 和流量故障排查 (`troubleshoot_connectivity`)。 * **语义工具路由：** 采用 FastEmbed 文本嵌入路由实现智能工具选择 (`USE_ROUTER=true`)。 * **Tier A+ 质量评分：** 100% 的参数描述，完整的 `ToolAnnotations` 安全元数据，以及 100% 的测试覆盖率。 ## 🏆 工具定义质量评分 (TDQS) 此 server 已通过 **[Tool Definition Quality Score (TDQS)](https://github.com/glama-ai/tool-definition-quality-score)** 框架的审核，以保证 LLM 的最佳函数调用、类型安全和运行时安全。 ``` ---------------- SCORECARD METRICS ---------------- Tools Evaluated : 39 Behavioral Annotations : 39 / 39 (100.0%) 100% Parameter Descriptions : 39 / 39 (100.0%) Usage Guidelines (Docstrings): 39 / 39 (100.0%) Overall TDQS Score : 5.00 / 5.00 TDQS Quality Tier : Tier A+ ======================================================== ``` - **行为注解 (`ToolAnnotations`)：** 100% 的工具指定了 `readOnlyHint`、`destructiveHint` 和 `idempotentHint` 元数据。 - **参数描述 (`Annotated[..., Field(...)]`)：** 每个参数都包含明确的类型和人类可读的描述。 - **使用指南：** 标准化的 docstring 详细说明了确切的触发条件（“Use when...”）。 ## ⚙️ Sophos Firewall API 前置条件 在将 `sophos-firewall-mcp` 连接到您的 Sophos Firewall (SFOS) 设备之前，请确保已启用 XML API，并且您的客户端 IP 已被列入白名单： 1. **登录 Web 管理控制台**：在浏览器中打开 `https://:4444`。 2. **启用 API 访问**： - 导航至 **System** > **Administration** > **API Access**（或 **API Configuration**）。 - 勾选 **API Configuration** 切换开关/复选框以启用 API 服务。 3. **将客户端 IP 地址列入白名单**： - 在 **Allowed IP Addresses** 下，点击 **Add** 并指定运行 `sophos-firewall-mcp` 的机器或容器主机的 IP 地址。 - *注意*：Sophos Firewall 会拒绝任何未明确添加到此白名单的 IP 地址发出的 API 请求。 4. **管理员账户**： - 确保配置的用户账户 (`SOPHOS_USERNAME`) 具有有效的管理员权限。 ## 🔧 环境变量 | 变量 | 描述 | 默认值 | | :--- | :--- | :--- | | `SOPHOS_HOST` | Sophos Firewall IP 地址或 FQDN | `172.16.16.16` | | `SOPHOS_PORT` | Web Console API 端口 | `4444` | | `SOPHOS_USERNAME` | API 管理员用户名 | `admin` | | `SOPHOS_PASSWORD` | API 管理员密码 | *(必填)* | | `SOPHOS_API_VERSION` | Sophos XML API 版本（例如，`2200.1` 对应 SFOS v22） | `2200.1` | | `SOPHOS_VERIFY_SSL` | 验证 SSL/TLS 证书（自签名证书请设置为 `false`） | `false` | | `SOPHOS_TIMEOUT` | API 请求超时时间（秒） | `30.0` | | `USE_ROUTER` | 设置为 `true` 以启用 FastEmbed 语义工具路由 | `false` | ## 🛠 客户端集成 将与您的环境匹配的配置代码片段添加到您的 MCP 设置文件中（例如 Antigravity IDE、Claude Desktop 或 VS Code 中的 `.vscode/mcp.json` 或 `mcp_config.json`）。 ### 选项 1：Docker / Podman 插入式容器部署 Podman 作为 Docker 在 Fedora/RHEL/Linux 上的无 root 插入式替代方案受到完全支持： ``` { "mcpServers": { "sophos-firewall": { "command": "podman", "args": [ "run", "-i", "--rm", "-e", "SOPHOS_HOST", "-e", "SOPHOS_PORT", "-e", "SOPHOS_USERNAME", "-e", "SOPHOS_PASSWORD", "-e", "SOPHOS_API_VERSION", "-e", "SOPHOS_VERIFY_SSL", "-e", "USE_ROUTER", "ghcr.io/jelmervdm/sophos-firewall-mcp:latest" ], "env": { "SOPHOS_HOST": "172.16.16.16", "SOPHOS_PORT": "4444", "SOPHOS_USERNAME": "admin", "SOPHOS_PASSWORD": "your_secure_password_here", "SOPHOS_API_VERSION": "2200.1", "SOPHOS_VERIFY_SSL": "false", "USE_ROUTER": "false" } } } } ``` ### 选项 2：本地 Python 执行（不使用 PyPI） #### 通过 `uv`（本地工作区目录）： ``` { "mcpServers": { "sophos-firewall": { "command": "uv", "args": [ "--directory", "/path/to/sophos-firewall-mcp", "run", "sophos-firewall-mcp-server" ], "env": { "SOPHOS_HOST": "172.16.16.16", "SOPHOS_PORT": "4444", "SOPHOS_USERNAME": "admin", "SOPHOS_PASSWORD": "your_secure_password_here", "SOPHOS_VERIFY_SSL": "false" } } } } ``` #### 通过 `python`（可编辑安装 `pip install -e .`）： ``` { "mcpServers": { "sophos-firewall": { "command": "python", "args": ["-m", "sophos_firewall_mcp.server"], "env": { "SOPHOS_HOST": "172.16.16.16", "SOPHOS_PORT": "4444", "SOPHOS_USERNAME": "admin", "SOPHOS_PASSWORD": "your_secure_password_here", "SOPHOS_VERIFY_SSL": "false" } } } } ``` #### 直接从 GitHub 代码库通过 `uvx`： ``` { "mcpServers": { "sophos-firewall": { "command": "uvx", "args": [ "--from", "git+https://github.com/jelmervdm/sophos-firewall-mcp.git", "sophos-firewall-mcp-server" ], "env": { "SOPHOS_HOST": "172.16.16.16", "SOPHOS_PORT": "4444", "SOPHOS_USERNAME": "admin", "SOPHOS_PASSWORD": "your_secure_password_here", "SOPHOS_VERIFY_SSL": "false" } } } } ``` ## 🧠 语义工具路由 当将 `sophos-firewall-mcp` 连接到具有受限上下文窗口的 AI 模型时，请设置 `USE_ROUTER=true`（或 `TOOL_ROUTING=true`）。 启用后： 1. server 仅公开 2 个元工具：`route_tools` 和 `call_routed_tool`。 2. `route_tools` 使用本地 CPU 嵌入（带有 `BAAI/bge-small-en-v1.5` 的 `fastembed`）在 5-10ms 内搜索匹配的防火墙工具。 3. `call_routed_tool` 使用参数动态调用匹配的工具。 ## 🧪 测试与质量保证 运行综合测试套件、代码检查、mypy 类型检查和 TDQS 审计： ``` # 评估 Tool Definition Quality Score (TDQS) uv run python scripts/check_tdqs.py # 运行 pytest 单元测试套件（39 个测试） uv run pytest -v # 代码风格和语法 linting uv run flake8 src tests scripts # 静态类型验证 uv run mypy src ``` ## 📄 许可证 在 Apache 2.0 许可证下分发。详情请参阅 [LICENSE](LICENSE)。

标签：MCP服务器, Sophos, 人工智能, 用户模式Hook绕过, 系统集成, 请求拦截, 运行时操纵, 逆向工具, 防火墙