# Firewall Governance MCP Server 🛡️
这是一个标准的 MCP (Model Context Protocol) 服务端，专为防火墙策略治理设计。
它集成了 CMDB 资产查询和 Panorama/Firewall 策略审计能力，支持通过任何 MCP 客户端（Claude Desktop, Cursor, Dify, etc.）直接调用。
---
## 🛠️ 工具能力 (Tools)
本服务提供以下标准的 MCP 工具：
| 工具名称 | 功能描述 | 核心输入 | 预期输出 |
| :--- | :--- | :--- | :--- |
| **`search_cmdb_asset`** | 资产查询 | `keyword`: 系统名/IP/缩写 | 包含 IP、Owner、DC、描述的资产列表 |
| **`get_firewall_object`** | 对象透视 | `ip_address`: 目标 IP | 防火墙对象详情 (Name, Zone, Tags) |
| **`search_firewall_policy`** | 策略审计 | `source_ip`: 源 IP<br>`destination_ip`: 目的 IP (可选) | 匹配的安全策略列表 (含 Action, Service, Shadow 状态) |
---
## 📋 配置说明 (Configuration)
本项目遵循标准 [12-Factor App](https://12factor.net/) 配置原则，使用环境变量管理所有敏感信息。
**注意：未配置必选变量时，工具调用将直接返回错误信息，以便 Agent 进行自我诊断。**
### 必选配置 (Firewall)
用于连接 Panorama 或 NGFW 进行策略和对象查询。
| 变量名 | 示例值 | 描述 |
| :--- | :--- | :--- |
| `FW_HOSTNAME` | `10.1.2.150` | 防火墙/Panorama 管理 IP 或域名 |
| `FW_USERNAME` | `admin` | 管理账号 |
| `FW_PASSWORD` | `Secret123!` | 管理员密码 |
### 必选配置 (CMDB)
用于查询业务系统资产信息。
| 变量名 | 示例值 | 描述 |
| :--- | :--- | :--- |
| `CMDB_SERVER` | `http://10.1.4.100` | CMDB API 地址 |
| `CMDB_APP_ID` | `c9a37...` | CMDB App ID |
| `CMDB_APP_SECRET` | `3d22e...` | CMDB App Secret |
| `CMDB_VIEW_ID` | `f0410...` | CMDB View ID (视图模型ID) |
---
## 🚀 部署指南 (Deployment)
本项目使用 [uv](https://github.com/astral-sh/uv) 进行全生命周期管理，支持多种运行模式。
### 方式一：开发调试 (Local Dev)
适用于本地开发调试或 Claude Desktop 直连。
```bash
# 进入目录
cd ai_agents/firewall_governance/firewall-mcp
# 1. 配置环境变量
export FW_HOSTNAME="10.1.2.150"
export FW_USERNAME="admin"
export FW_PASSWORD="your_password"
# ... 配置其他 CMDB 变量
# 2. 启动服务 (Stdio 模式)
uv run mcp_server.py
```
### 调试指南 (Debugging) 🐞
开发人员可以通过以下三种方式调试工具逻辑：
#### 1. 脚本直测 (最快)
底层工具脚本 (`fw_tool.py`, `cmdb_tool.py`) 都包含 `__main__` 测试入口。可以直接运行它们来验证 API 连通性。
```bash
# 需先设置环境变量
export FW_HOSTNAME=10.1.2.150 FW_PASSWORD=xxx
# 运行防火墙工具测试
uv run fw_tool.py
# 运行 CMDB 工具测试
uv run cmdb_tool.py
```
#### 2. MCP Inspector (交互式调试)
使用官方 Inspector UI 在浏览器中测试所有 MCP Tools。
```bash
# 启动 Inspector
npx @modelcontextprotocol/inspector uv run mcp_server.py
```
> 这将打开一个 Web 界面，您可以像在 Claude 中一样点击并从网页调用工具，查看完整的输入/输出/日志。
#### 3. IDE 断点调试 (VS Code / Cursor)
在项目根目录创建 `.vscode/launch.json`：
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug FW Tool",
"type": "python",
"request": "launch",
"program": "${workspaceFolder}/firewall-mcp/fw_tool.py",
"console": "integratedTerminal",
"env": {
"FW_HOSTNAME": "10.1.2.150",
"FW_USERNAME": "admin",
"FW_PASSWORD": "your_password"
}
},
{
"name": "Debug MCP Server",
"type": "python",
"request": "launch",
"program": "${workspaceFolder}/firewall-mcp/mcp_server.py",
"console": "integratedTerminal",
"env": { ... }
}
]
}
```
### 方式二：内网无源码分发 (uvx style) - 推荐 🌟
这是公司内网最推荐的分发方式，支持离线或无源码环境。
**1. 构建阶段 (Builder Machine)**
```bash
# 生成 .whl 包
uv pip install build
uv run -m build
# 产物在 dist/firewall_governance_mcp-0.1.0-py3-none-any.whl
```
**2. 运行阶段 (User Machine)**
用户只需拿到 `.whl` 文件，无需安装依赖，单行命令即用：
```bash
# 在运行机器上配置环境变量
export FW_HOSTNAME=10.1.2.150
export FW_PASSWORD=xxx
# ...
# 一键运行 (uv 会自动全托管环境)
uvx --from ./dist/firewall_governance_mcp-0.1.0-py3-none-any.whl firewall-mcp
```
### 方式三: Claude Desktop 集成 (Remote Git) 🌟 [推荐]
这是最推荐的集成方式。利用 `uvx` 直接从 Git 仓库拉取安装，支持自动环境隔离与依赖管理。
**前提**: 您的机器需要拥有该 Git 仓库的访问权限 (SSH Key)。
编辑配置文件 (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"firewall-governance": {
"command": "uvx",
"args": [
"--from",
"git+ssh://git@10.1.2.68/script/ae/mcp-server.git#subdirectory=firewall-mcp",
"firewall-mcp"
],
"env": {
"FW_HOSTNAME": "10.1.2.150",
"FW_USERNAME": "admin",
"FW_PASSWORD": "your_password",
"CMDB_SERVER": "http://10.1.4.100",
"CMDB_APP_ID": "...",
"CMDB_APP_SECRET": "..."
}
}
}
}
```
### 方式四: Claude Desktop 集成 (Local Source) [不推荐]
仅建议在开发调试时使用。需要手动 clone 代码并维护本地路径。
```json
{
"mcpServers": {
"firewall-governance-local": {
"command": "uv",
"args": [
"run",
"/absolute/path/to/ai_agents/firewall_governance/firewall-mcp/mcp_server.py"
],
"env": {
"FW_HOSTNAME": "10.1.2.150",
"FW_USERNAME": "admin",
"FW_PASSWORD": "..."
}
}
}
}
```
---
## 📦 依赖列表 (Dependencies)
核心依赖如下 (详见 `pyproject.toml`):
* **`mcp`**: 官方 Model Context Protocol SDK (实现 FastMCP 服务端)。
* **`requests`**: 处理所有 HTTP REST API 调用 (PAN-OS, CMDB)。
* **`python-dotenv`**: 支持从 `.env` 文件加载配置。
* **`minzhi-sdk`**: (可选) 内部系统集成 SDK。
---
## �️ 项目结构
```text
.
├── pyproject.toml # 项目元数据与依赖定义
├── mcp_server.py # MCP Server 入口
├── fw_tool.py # 防火墙交互逻辑
├── cmdb_tool.py # CMDB 交互逻辑
└── data/ # 辅助数据
```
