Illumio MCP 服务器

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

它能做什么？

使用对话式 AI 与您的 PCE 对话：

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

前提条件

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

安装

1. 克隆存储库：

git clone [repository-url]
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": "your-pce-host",
        "PCE_PORT": "your-pce-port",
        "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'）
  • 按严重性过滤（emerg、alert、crit、err、warning、notice、info、debug）
  • 按状态过滤（success、failure）
  • 限制返回的结果数

错误处理

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

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

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

开发

运行测试

测试尚未实现。

python -m pytest tests/

调试模式

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

贡献

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

许可证

该项目已获得 GPL-3.0 许可证的许可。 有关详细信息，请参见 LICENSE 文件。

支持

如需支持，请创建一个 issue。

示例

可视化示例

以下所有示例均由 Claude Desktop 3.5 Sonnet 生成，数据通过此 MCP 服务器获得。 我发现将数据渲染到 react 组件可以产生美观的可视化效果和结果。

应用程序分析

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

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

基础设施洞察

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

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

安全评估

全面的安全分析报告

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

PCI 合规性评估发现

SWIFT 合规性评估发现

补救计划

安全补救计划概述

安全补救实施的详细步骤

策略管理

IP 列表的管理界面

规则集类别和组织的概述

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

工作负载管理

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

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

标签管理

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

服务分析

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

前 5 个流量来源和目标的分析

项目规划

项目实施时间表和里程碑

可用提示

环绕应用程序

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

必需参数：

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

功能：

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

分析应用程序流量

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

必需参数：

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

分析功能：

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

如何使用 MCP 提示

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

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

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

步骤 4：单击“提交”以发送配置的提示

提示如何工作

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

此工作流程支持 Illumio 系统和 Claude 之间自动共享上下文，以进行应用程序流量分析和环绕任务。

Docker

该应用程序可以作为 Docker 容器从 GitHub 容器注册表中获得。

拉取容器

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. 创建一个包含您的 PCE 凭据的环境文件（例如 ~/.illumio-mcp.env）：

PCE_HOST=your-pce-host
PCE_PORT=your-pce-port
PCE_ORG_ID=1
API_KEY=your-api-key
API_SECRET=your-api-secret

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 \
  ... other environment variables ...
  ghcr.io/alexgoller/illumio-mcp-server:latest

或者在 docker-compose.yml 中：

services:
  illumio-mcp:
    environment:
      - PYTHONWARNINGS=ignore
      # ... other environment variables ...

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=your-pce-host
PCE_PORT=your-pce-port
PCE_ORG_ID=1
API_KEY=your-api-key
API_SECRET=your-api-secret

配置：

• 使用 Docker 运行容器
• 为日志挂载本地目录
• 抑制 Python 警告
• 从环境变量文件加载 PCE 凭据
• 使用 --init 和 --rm 启用正确的容器清理