Illumio MCP 服务器

一个模型上下文协议（MCP）服务器，提供与 Illumio PCE（策略计算引擎）交互的接口。该服务器支持以编程方式访问 Illumio 工作负载管理、标签操作和流量分析。

它能做什么？

使用对话式 AI 与您的 PCE 进行交互：

• 创建、更新和删除工作负载
• 创建、更新和删除标签
• 获取流量摘要并对其进行安全分析
• 获取 PCE 健康状况

先决条件

• Python 3.8+
• 访问 Illumio PCE 实例
• 有效的 PCE API 凭证

安装

1. 克隆仓库：

git clone [仓库地址]
cd illumio-mcp

2. 安装依赖：

pip install -r requirements.txt

配置

您应该使用 uv 命令运行此程序，这样可以更轻松地传递环境变量并在后台运行。

使用 uv 和 Claude Desktop

在 MacOS 上：~/Library/Application\ Support/Claude/claude_desktop_config.json
在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

在 custom_settings 部分添加以下内容：

"mcpServers": {
    "illumio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/alex.goller/git/illumio-mcp",
        "run",
        "illumio-mcp"
      ],
      "env": {
        "PCE_HOST": "您的 PCE 主机",
        "PCE_PORT": "您的 PCE 端口",
        "PCE_ORG_ID": "1", # 您的组织 ID
        "API_KEY": "api_key",
        "API_SECRET": "api_secret"
      }
    }
  }
}

功能

资源

资源尚未完成，我稍后会处理。

• illumio://workloads - 从 PCE 获取工作负载
• illumio://labels - 从 PCE 获取所有标签

工具

工作负载管理

• get-workloads - 从 PCE 检索所有工作负载
• create-workload - 创建具有指定名称、IP 地址和标签的未管理的工作负载
• update-workload - 更新现有工作负载的属性
• delete-workload - 按名称从 PCE 中删除工作负载

标签操作

• create-label - 创建具有键值对的新标签
• delete-label - 按键值对删除现有标签
• get-labels - 从 PCE 检索所有标签

流量分析

• get-traffic-flows - 获取详细的流量数据，并提供全面的过滤选项：

  • 日期范围过滤
  • 源/目标过滤
  • 服务（端口/协议）过滤
  • 策略决策过滤
  • 工作负载和 IP 列表查询选项
  • 结果限制

• get-traffic-flows-summary - 获取汇总的流量信息，过滤功能与 get-traffic-flows 相同

策略管理

• get-rulesets - 从 PCE 获取规则集，并提供可选过滤：
  • 按名称过滤
  • 按启用状态过滤

IP 列表管理

• get-iplists - 从 PCE 获取 IP 列表，并提供可选过滤：
  • 按名称过滤
  • 按描述过滤
  • 按 IP 范围过滤

连接测试

• check-pce-connection - 验证 PCE 连接性和凭证

事件管理

• get-events - 从 PCE 获取事件，并提供可选过滤：
  • 按事件类型过滤（例如，'system_task.expire_service_account_api_keys'）
  • 按严重性过滤（紧急、警报、严重、错误、警告、通知、信息、调试）
  • 按状态过滤（成功、失败）
  • 限制返回的结果数量

错误处理

服务器实现了全面的错误处理和日志记录：

• PCE 连接问题
• API 认证失败
• 资源创建/更新失败
• 无效的输入验证

所有错误都会记录完整的堆栈跟踪，并以格式化的错误消息返回给客户端。

开发

运行测试

尚未实现测试。

python -m pytest tests/

调试模式

在代码或环境中将日志级别设置为 DEBUG，以获取详细的操作日志。

贡献

1. Fork 仓库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建 Pull Request

许可证

本项目采用 GPL-3.0 许可证。详情请参阅 LICENSE 文件。

示例

可视化示例

以下所有示例均由 Claude Desktop 3.5 Sonnet 生成，并通过此 MCP 服务器获取数据。我发现将数据渲染为 React 组件可以生成美丽的可视化和结果。

应用程序分析

应用程序通信模式和依赖关系的详细视图

不同应用程序层级之间的流量模式分析

基础设施洞察

显示关键基础设施指标和状态的概览仪表板

基础设施服务通信的详细分析

安全评估

全面的安全分析报告

高风险漏洞的安全评估发现

PCI 合规性评估发现

SWIFT 合规性评估发现

修复计划

安全修复计划的概览

安全修复实施的详细步骤

策略管理

IP 列表的管理界面

规则集类别和组织的概览

应用程序规则集排序的配置

工作负载管理

详细的工作负载分析和指标

工作负载流量模式的识别和分析

标签管理

按类型和类别组织的 PCE 标签

服务分析

基于流量模式自动推断服务角色

前五大流量来源和目的地的分析

项目规划

项目实施时间表和里程碑

可用提示

隔离应用程序

ringfence-application 提示帮助创建安全策略，通过控制入站和出站流量来隔离和保护应用程序。

所需参数：

• application_name：要隔离的应用程序名称
• application_environment：要隔离的应用程序环境

功能：

• 为应用程序内的层级间通信创建规则
• 使用流量流识别所需的外部连接
• 基于来源应用程序实施入站流量限制
• 为必要的外部通信创建出站流量规则
• 处理范围内部（同一应用程序/环境）和范围外部（外部）连接
• 为远程应用程序连接创建单独的规则集

分析应用程序流量

analyze-application-traffic 提示提供应用程序流量模式和连接性的详细分析。

所需参数：

• application_name：要分析的应用程序名称
• application_environment：要分析的应用程序环境

分析功能：

• 按入站和出站流量排序
• 按应用程序/环境/角色组合分组
• 识别相关标签类型和模式
• 以 React 组件格式显示结果
• 显示协议和端口信息
• 尝试识别已知服务模式（例如，Nagios 在端口 5666 上）
• 将流量分类为基础设施和应用程序类型
• 确定互联网暴露情况
• 显示 Illumio 角色、应用程序和环境标签

如何使用 MCP 提示

步骤 1：在界面中点击“从 MCP 附加”按钮

步骤 2：从已安装的 MCP 服务器中选择

步骤 3：填写所需的提示参数：

步骤 4：点击提交以发送配置好的提示

提示的工作原理

• MCP 服务器将配置好的提示发送给 Claude
• Claude 通过模型上下文协议接收上下文
• 允许对 Illumio 特定任务进行专门处理

此工作流程支持 Illumio 系统和 Claude 之间的自动上下文共享，用于应用程序流量分析和隔离任务。

Docker

该应用程序可从 GitHub 容器仓库获取为 Docker 容器。

拉取容器

docker pull ghcr.io/alexgoller/illumio-mcp-server:latest

您也可以通过将 latest 替换为版本号来使用特定版本：

docker pull ghcr.io/alexgoller/illumio-mcp-server:1.0.0

与 Claude Desktop 一起运行

要与 Claude Desktop 一起使用容器，您需要：

1. 创建一个环境文件（例如 ~/.illumio-mcp.env），其中包含您的 PCE 凭证：

PCE_HOST=您的 PCE 主机
PCE_PORT=您的 PCE 端口
PCE_ORG_ID=1
API_KEY=您的 API 密钥
API_SECRET=您的 API 密钥

2. 将以下配置添加到您的 Claude Desktop 配置文件中：

在 MacOS 上（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
    "mcpServers": {
        "illumio-mcp-docker": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--init",
                "--rm",
                "-v",
                "/Users/YOUR_USERNAME/tmp:/var/log/illumio-mcp",
                "-e",
                "DOCKER_CONTAINER=true",
                "-e",
                "PYTHONWARNINGS=ignore",
                "--env-file",
                "/Users/YOUR_USERNAME/.illumio-mcp.env",
                "illumio-mcp:latest"
            ]
        }
    }
}

请确保：

• 将 YOUR_USERNAME 替换为您的实际用户名
• 创建日志目录（例如 ~/tmp）
• 根据您的系统调整路径

独立运行

您也可以直接运行容器：

docker run -i --init --rm \
  -v /path/to/logs:/var/log/illumio-mcp \
  -e DOCKER_CONTAINER=true \
  -e PYTHONWARNINGS=ignore \
  --env-file ~/.illumio-mcp.env \
  ghcr.io/alexgoller/illumio-mcp-server:latest

Docker Compose

对于开发或测试，您可以使用 Docker Compose。创建一个 docker-compose.yml 文件：

version: '3'
services:
  illumio-mcp:
    image: ghcr.io/alexgoller/illumio-mcp-server:latest
    init: true
    volumes:
      - ./logs:/var/log/illumio-mcp
    environment:
      - DOCKER_CONTAINER=true
      - PYTHONWARNINGS=ignore
    env_file:
      - ~/.illumio-mcp.env

然后运行：

docker-compose up

已知问题

运行容器时，您可能会看到来自 Illumio SDK 的正则表达式语法警告。这些警告不会影响功能，并且在容器中会自动抑制。

如果您在运行容器时看到这些警告，可以通过以下方式手动抑制：

docker run \
  -e PYTHONWARNINGS=ignore \
  ... 其他环境变量 ...
  ghcr.io/alexgoller/illumio-mcp-server:latest

或者在 docker-compose.yml 中：

services:
  illumio-mcp:
    environment:
      - PYTHONWARNINGS=ignore
      # ... 其他环境变量 ...

Claude Desktop 配置

对于 Claude Desktop 用户，将此配置添加到您的 Claude Desktop 配置文件中：

{
    "mcpServers": {
        "illumio-mcp-docker": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--init",
                "--rm",
                "-v",
                "/Users/YOUR_USERNAME/tmp:/var/log/illumio-mcp",
                "-e",
                "DOCKER_CONTAINER=true",
                "-e",
                "PYTHONWARNINGS=ignore",
                "--env-file",
                "/Users/YOUR_USERNAME/.illumio-mcp.env",
                "illumio-mcp:latest"
            ]
        }
    }
}

请确保：

1. 将 YOUR_USERNAME 替换为您的实际用户名
2. 在 ~/tmp 创建日志目录（或根据需要调整路径）
3. 在 ~/.illumio-mcp.env 创建一个包含 PCE 凭证的环境文件：

PCE_HOST=您的 PCE 主机
PCE_PORT=您的 PCE 端口
PCE_ORG_ID=1
API_KEY=您的 API 密钥
API_SECRET=您的 API 密钥

配置：

• 使用 Docker 运行容器
• 挂载本地目录用于日志
• 抑制 Python 警告
• 从环境文件加载 PCE 凭证
• 使用 --init 和 --rm 启用适当的容器清理