内容
# ESA（CES）策略命中次数 MCP 服务器（第 2 阶段）
## 开始前： 第 1 阶段 vs 第 2 阶段
此仓库是 ESA 策略健康分析的两阶段工作流的一部分。
- 第 1 阶段（仅脚本基准线）：
- 引用：https://github.com/CiscoDevNet/ESA-Policy-Hitcount
- 目的：运行直接脚本以获取策略命中次数并与策略库存进行比较。
- 最适合：希望使用最小化编排的直接 CLI/脚本工作流的操作员。
- 第 2 阶段（此仓库）：
- 目的：通过 MCP 工具公开相同的核心分析，以便 AI 助手和 MCP 客户端可以运行交互式、对话式调查。
- 最适合：引导式调查、上下文感知后续问题和更轻松的工作流自动化。
如果您是此解决方案的新用户，请先查看第 1 阶段以获取基准逻辑，然后继续此处获取启用 MCP 的第 2 阶段工作流。
### 快速决策指南
| 如果您的目标是... | 使用 | 为什么 |
|---|---|---|
| 从 CLI 脚本运行简单的单次命中次数检查 | 第 1 阶段 | 设置最小且直接的脚本执行 |
| 在没有 MCP 客户端的情况下比较配置库存与命中次数 | 第 1 阶段 | 直接的脚本驱动工作流 |
| 询问有关策略活动的对话式后续问题 | 第 2 阶段 | MCP 工具实现 AI 引导的调查 |
| 构建可重复的 AI 辅助操作工作流 | 第 2 阶段 | 工具编排和跨步骤的上下文保留 |
| 生成更丰富的摘要和引导式操作建议 | 第 2 阶段 | 在相同核心数据上实现更好的交互式分析 |
第 2 阶段为 ESA 策略分析提供基于 MCP 的工作流，支持 AI/NLP 对话式调查。
此第 2 阶段工作流支持 ESA 和 CES 部署。
## ESA 和 CES 支持说明
- ESA：与标准 API 访问和配置工作流本地配合使用。
- CES（云邮件安全）：受支持，但 CES 基础设施由 Cisco CES Operations 管理。
- 对于 CES，客户应打开 TAC 请求以获取 API 用户访问和 CES 配置导出支持。
- 对于 CES 策略库存，基于 SSH 的策略收集（`fetch_via_ssh=true`）通常是最容易且最实用的选项。
- API 用户权限（ESA 和 CES）：仅使用只读访问权限。不建议使用完全管理员权限，因为存在敏感凭证。
第 1 阶段参考（仅脚本基准线）：
- https://github.com/CiscoDevNet/ESA-Policy-Hitcount
- 第 1 阶段运行直接脚本以获取和比较策略命中数据，而无需 MCP 工具编排。
## 第 2 阶段新增功能
通过第 2 阶段，MCP 客户端可以调用工具：
- 查询选定时间窗口的传入和传出策略命中次数。
- 使用第 1 阶段等效的分析逻辑比较策略库存（ESA XML 配置导出或 SSH `policyconfig`）与 API 命中结果。
- 更可靠地识别零命中和低流量策略。
- 提出后续调查问题并获取上下文感知摘要。
- 可选地，将比较输出导出为 JSON 并生成 DOCX 健康报告。
主要服务器和客户端：
- `mcp-esa-ces.py`
- `mcp-client.py`
## 第 2 阶段工具表面
服务器公开这些 MCP 工具：
- `get_policy_hit_count_tool`
- 输入：`days_to_query`，`top_n_policies`
- 返回：传入/传出策略命中列表，包含命中次数
- `compare_config_to_hit_counts_tool`
- 输入：`config_text` 或 `config_file_path`（预期为 ESA XML 配置导出文件输入）
- 可选的 SSH 库存模式：`fetch_via_ssh`，`ssh_host`，`ssh_user`，`ssh_pass`，`ssh_port`
- 返回：`policies_with_hits`，`policies_without_hits`，摘要计数
- `explain_top_policy_hits_tool`
- 输入：`days_to_query`，`top_n_policies`，`compare_with_previous_period`
- 返回：具有证据的周期间解释候选项
- `fetch_esa_config_text_tool`
- 输入：`config_api_path`/`config_url`，可选 `save_to_file_path`
- 返回：配置文本预览和保存状态
## 先决条件
- Python 3.11+
- Node.js（用于 DOCX 生成脚本）
- 从此主机到 ESA API/管理接口的网络可达性
- 具有报告访问权限的 ESA API 凭证
- ESA 策略库存来源：
- 首选：ESA XML 配置导出
- 替代：来自 `policyconfig` 的 SSH 库存收集
服务器使用的 Python 包：
- `fastmcp`
- `paramiko`
- `requests`
- `urllib3`
## 快速入门（第 2 阶段）
1. 创建并激活虚拟环境
```bash
python3 -m venv env
source env/bin/activate
```
2. 安装依赖项
```bash
pip install fastmcp paramiko requests urllib3
npm install
```
3. 配置环境变量
```bash
# 包含一个虚拟的.env文件。
# 编辑.env文件并在首次运行前设置实际值。
set -a && source .env && set +a
```
重要：
- 提交的 `.env` 文件仅包含虚拟值。
- 在运行服务器之前更新 `ESA_IP`、`ESA_API_USER` 和 `ESA_API_PASS`。
- 不要将实际凭证提交回源代码控制。
4. 启动 MCP 服务器
```bash
python3 mcp-esa-ces.py
```
5. 保持服务器运行，然后选择以下使用路径之一
默认端点：
- `http://127.0.0.1:8080/mcp`
## 第 2 阶段使用路径
### A) 后端烟雾测试（CLI）
使用此路径仅验证服务器健康状况和 ESA 连接性。
在另一个终端：
```bash
python3 mcp-client.py --mode list-tools
python3 mcp-client.py --mode run --days 1 --top 5
python3 mcp-client.py --mode compare-config --days 30 --top 1000 --config-file /path/to/esa-config.xml
python3 mcp-client.py --mode compare-config --days 30 --top 1000 --config-file /path/to/esa-config.xml --output-json compare-config-output.json
```
### B) AI 对话工作流（主要）
这是第 2 阶段的主要价值。
1. 将您的 MCP 启用 AI 客户端连接到 `http://127.0.0.1:8080/mcp`。
2. 提供 ESA XML 配置导出作为策略库存（或使用 SSH 库存模式）。
3. 提出自然语言问题；AI 将调用工具并指导调查。
典型的第 2 阶段 AI 使用（最低要求）：
- 保持第 2 阶段 MCP 服务器运行。
- 将您的 AI 客户端连接到 `http://127.0.0.1:8080/mcp`。
- 为比较工作流提供策略库存源：
- 直接在 AI 聊天中上传 ESA XML 配置导出，或
- SSH 库存模式（`fetch_via_ssh=true`）。
首选/常见方式提供配置给 AI 聊天：
- 首选：直接在 AI 聊天中上传 ESA XML 配置导出，然后要求 AI 为目标窗口运行比较。
- 替代：提供本地 XML 文件路径（如果您的 AI 客户端可以访问本地文件）。
- 备用：当 XML 导出不可用时，使用 SSH 库存模式（`fetch_via_ssh=true`）。
如果您跳过策略库存输入，命中次数工具仍然有效，但配置与命中次数比较将不完整。
建议的提示：
- 根据此 ESA XML 导出，在过去 30 天内哪些策略的命中次数为零？
- 将策略分为活跃、低流量和不活跃组。
- 哪些零命中策略更安全地禁用，首先是哪些，为什么？
- 在禁用不活跃策略之前起草客户沟通。
## 演练运行手册
使用此运行手册在不到 10 分钟内验证第 2 阶段端到端。
1. 启动服务器
```bash
python3 mcp-esa-ces.py
```
2. 验证 MCP 工具注册
```bash
python3 mcp-client.py --url http://127.0.0.1:8080/mcp --mode list-tools
```
预期结果：
- 4 个工具可见：`get_policy_hit_count_tool`，`compare_config_to_hit_counts_tool`，`explain_top_policy_hits_tool`，`fetch_esa_config_text_tool`
3. 验证实时命中次数检索
```bash
python3 mcp-client.py --url http://127.0.0.1:8080/mcp --mode run --days 1 --top 5
```
预期结果：
- 具有 `incoming_policy_hits` 和/或 `outgoing_policy_hits` 的非空 JSON 样式响应
4. 验证具有 ESA XML 库存的比较流程
```bash
python3 mcp-client.py --url http://127.0.0.1:8080/mcp --mode compare-config --days 30 --top 1000 --config-file /path/to/esa-config.xml --output-json compare-config-output.json
```
预期结果：
- `compare-config-output.json` 已创建
- 包括活动/不活动证据字段和摘要总数
5. 可选的报告生成
```bash
node generate-health-report.js --input compare-config-output.json --output ESA-Policy-Health-Check.docx
```
预期结果：
- 成功生成 DOCX 报告工件
## 操作员问答（罐装提示）
在您的 MCP 启用 AI 聊天中使用这些确切的提示。
1. 库存和基准线
- 我的策略来自此 ESA XML 导出是什么？
- 将它们分为传入和传出库存。
2. 活动分析
- 在过去 30 天内，哪些是活跃的而哪些是不活跃的？
- 使用实际阈值显示低流量策略并解释该阈值。
3. 可行性
- 显示具有推荐清理优先级的仅不活动策略。
- 哪些策略更安全地禁用，首先是什么备份计划？
4. 房屋管理治理
- 为这些不活动策略建立每月房屋管理计划。
- 在停用前起草变更控制说明和客户沟通。
## 快速命令（默认本地端点）
以下所有命令都假定本地第 2 阶段服务器端点：
- `http://127.0.0.1:8080/mcp`
```bash
# 列出 MCP 工具
python3 mcp-client.py --url http://127.0.0.1:8080/mcp --mode list-tools
# 获取最新的命中次数快照
python3 mcp-client.py --url http://127.0.0.1:8080/mcp --mode run --days 1 --top 5
# 30 天视图，策略覆盖范围更广
python3 mcp-client.py --url http://127.0.0.1:8080/mcp --mode run --days 30 --top 500 --output-json last30-hits.json
# 比较 ESA XML 库存与 30 天命中次数
python3 mcp-client.py --url http://127.0.0.1:8080/mcp --mode compare-config --days 30 --top 1000 --config-file /path/to/esa-config.xml --output-json compare-config-output.json
```
## 第 2 阶段工作流详细信息（两种路径）
本节支持上述两种使用路径。
如果您使用路径 B（AI 对话工作流），除非您想要进行手动调试检查，否则无需运行 `mcp-client.py`。
1. 收集策略库存
- 使用 ESA XML 配置导出文件，或
- 通过 MCP 工具参数使用 SSH `policyconfig` 收集
2. 为目标窗口运行策略比较（例如 30 天）
- AI 路径（主要）：要求您的 AI 客户端为目标时间窗口比较 ESA XML 库存。
- CLI 路径（可选/手动）：
```bash
python3 mcp-client.py --mode compare-config --days 30 --top 1000 --config-file /path/to/esa-config.xml --output-json compare-config-output.json
```
输入指南：
- 对于 `--config-file`，使用 ESA XML 配置导出。
- 不要使用 CLI 表格文本转储（例如 `policyconfig` 终端输出）作为文件输入。
- 如果您只有 CLI 访问权限，请改用 SSH 库存模式（`fetch_via_ssh=true`）。
3. 使用 MCP/AI 问答来调查可行性（第 2 阶段的主要价值）
- 零命中策略
- 活动 vs 低流量 vs 不活动分组
- 更安全的删除候选项
- 停用前客户消息传递
4. 可选：生成 DOCX 报告工件
```bash
node generate-health-report.js --input compare-config-output.json --output ESA-Policy-Health-Check.docx
```
## 屏幕截图演练（第 2 阶段问答）
以下屏幕截图显示了一个实用的第 2 阶段调查序列。
### Q1：过去 30 天内哪些策略的命中次数为零？
使用此方法识别初始清理候选项并确认库存/命中次数覆盖范围。
### Q2：按活动、低流量和不活动组总结策略
这提供了操作决策的快速分类视图。
### Q3：哪些零命中策略更安全地删除，首先是哪些，为什么？
这有助于优先考虑风险较低的候选项（例如，测试/实验室类策略名称），然后再进行业务关键流程。
### Q4：停用零命中策略前应传达什么？
使用此方法构建客户验证检查和分阶段推广指南。
## 可选报告工件
DOCX 输出预览：
## 注意和注意事项
- API 命中次数端点报告观察到的流量；它们不能独立证明策略意图。
- 某个时间段内命中次数为零是一个强烈的信号，但单独而言并不足以删除。
- 在停用前验证异常、季节性、备用和合规相关策略。
- SSH `policyconfig` 输出可能包含截断的名称；在审查时请仔细处理名称匹配。
## 安全性和发布卫生
在发布之前，请删除任何硬编码的凭证，并将机密存储在环境变量中。
推荐的 `.gitignore` 条目：
- `env/`
- `node_modules/`
- `__pycache__/`
- `.DS_Store`
- `*.pyc`
- `*.log`
- 仅在源代码管理中保留虚拟 `.env` 值；请勿提交实际凭证。
---
## 许可
版权 (c) 2020-2026 思科及其/或其附属公司。
根据 Apache License, Version 2.0（“许可”）授权；
除非符合许可要求，否则不得使用此文件。
您可以在以下网址找到许可的副本：
http://www.apache.org/licenses/LICENSE-2.0
除非法律要求或书面协议另有规定，否则根据许可分发的软件以“原样”基础分发，
不附带任何形式的保证或条件，无论是明示还是暗示。
请参阅许可以了解管理许可和
在许可下的限制。
