Glama
Illumio MCP Server

# Illumio MCP Server

A Model Context Protocol (MCP) server that provides an interface to interact with Illumio PCE (Policy Compute Engine). This server enables programmatic access to Illumio workload management, label operations, and traffic flow analysis.

## What can it do?

Use conversational AI to talk to your PCE:

- Create, update and delete workloads
- Create, update and delete labels
- Get traffic summaries and do security analysis on them
- Get PCE health

## Prerequisites

- Python 3.8+
- Access to an Illumio PCE instance
- Valid API credentials for the PCE

## Installation

1. Clone the repository:

```bash
git clone [repository-url]
cd illumio-mcp
```

2. Install dependencies:

```bash
pip install -r requirements.txt
```

## Configuration

You should run this using the `uv` command, which makes it easier to pass in environment variables and run it in the background.

## Using uv and Claude Desktop

On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

Add the following to the `custom_settings` section:

```json
"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", # your org id
        "API_KEY": "api_key",
        "API_SECRET": "api_secret"
      }
    }
  }
}
```

## Features

### Resources

Resources are not finished yet and i will look into that later.

- `illumio://workloads` - Get workloads from the PCE
- `illumio://labels` - Get all labels from PCE

### Tools

#### Workload Management
- `get-workloads` - Retrieve all workloads from PCE
- `create-workload` - Create an unmanaged workload with specified name, IP addresses, and labels
- `update-workload` - Update an existing workload's properties
- `delete-workload` - Remove a workload from PCE by name

#### Label Operations
- `create-label` - Create a new label with key-value pair
- `delete-label` - Remove an existing label by key-value pair
- `get-labels` - Retrieve all labels from PCE

#### Traffic Analysis
- `get-traffic-flows` - Get detailed traffic flow data with comprehensive filtering options:
  - Date range filtering
  - Source/destination filtering
  - Service (port/protocol) filtering
  - Policy decision filtering
  - Workload and IP list query options
  - Results limiting
  
- `get-traffic-flows-summary` - Get summarized traffic flow information with the same filtering capabilities as get-traffic-flows

#### Policy Management
- `get-rulesets` - Get rulesets from the PCE with optional filtering:
  - Filter by name
  - Filter by enabled status

#### IP Lists Management
- `get-iplists` - Get IP lists from the PCE with optional filtering:
  - Filter by name
  - Filter by description
  - Filter by IP ranges

#### Connection Testing
- `check-pce-connection` - Verify PCE connectivity and credentials

#### Event Management
- `get-events` - Get events from the PCE with optional filtering:
  - Filter by event type (e.g., 'system_task.expire_service_account_api_keys')
  - Filter by severity (emerg, alert, crit, err, warning, notice, info, debug)
  - Filter by status (success, failure)
  - Limit number of results returned

## Error Handling

The server implements comprehensive error handling and logging:
- PCE connection issues
- API authentication failures
- Resource creation/update failures
- Invalid input validation

All errors are logged with full stack traces and returned as formatted error messages to the client.

## Development

### Running Tests

Testing is not implemented yet.

```bash
python -m pytest tests/
```

### Debug Mode
Set logging level to DEBUG in the code or environment for detailed operation logs.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

This project is licensed under the GPL-3.0 License. See the [LICENSE](LICENSE) file for details.

## Support

For support, please [create an issue](https://github.com/illumio/illumio-mcp/issues).

# Examples

## Visual Examples

All the examples below were generated by Claude Desktop 3.5 Sonnet and with data obtained through this MCP server. I found out that rendering the data to react components is resulting in beautiful visualizations and results.

### Application Analysis
![Application Analysis](images/application-analysis.png)
*Detailed view of application communication patterns and dependencies*

![Application Tier Analysis](images/application-tier-analysis.png)
*Analysis of traffic patterns between different application tiers*

### Infrastructure Insights
![Infrastructure Analysis Dashboard](images/infrastrcture-analysis-dashboard.png)
*Overview dashboard showing key infrastructure metrics and status*

![Infrastructure Services](images/infrastructure-services-analysis.png)
*Detailed analysis of infrastructure service communications*

### Security Assessment
![Security Analysis Report](images/security-analysis-report.png)
*Comprehensive security analysis report*

![High Risk Findings](images/security-assessment-findings-high-risk.png)
*Security assessment findings for high-risk vulnerabilities*

![PCI Compliance](images/security-assessment-findings-pci.png)
*PCI compliance assessment findings*

![SWIFT Compliance](images/security-assessment-findings-swift.png)
*SWIFT compliance assessment findings*

### Remediation Planning
![Remediation Plan Overview](images/security-remediation-plan.png)
*Overview of security remediation planning*

![Detailed Remediation Steps](images/security-remediation-plan-2.png)
*Detailed steps for security remediation implementation*

### Policy Management
![IP Lists Overview](images/iplists-overview.png)
*Management interface for IP lists*

![Ruleset Categories](images/ruleset-categories.png)
*Overview of ruleset categories and organization*

![Application Ruleset Ordering](images/ordering-application-ruleset-overview.png)
*Configuration of application ruleset ordering*

### Workload Management
![Workload Analysis](images/workload-analysis.png)
*Detailed workload analysis and metrics*

![Workload Traffic](images/workload-traffic-identification.png)
*Identification and analysis of workload traffic patterns*

### Label Management
![PCE Labels by Type](images/pce-labels-by-type.png)
*Organization of PCE labels by type and category*

### Service Analysis
![Service Role Inference](images/service-role-inference.png)
*Automatic inference of service roles based on traffic patterns*

![Top Sources and Destinations](images/top-5-sources-and-destinations.png)
*Analysis of top 5 traffic sources and destinations*

### Project Planning
![Project Plan](images/project-plan-mermaid.png)
*Project implementation timeline and milestones*

## Available Prompts

### Ringfence Application
The `ringfence-application` prompt helps create security policies to isolate and protect applications by controlling inbound and outbound traffic.

**Required Arguments:**
- `application_name`: Name of the application to ringfence
- `application_environment`: Environment of the application to ringfence

**Features:**
- Creates rules for inter-tier communication within the application
- Uses traffic flows to identify required external connections
- Implements inbound traffic restrictions based on source applications
- Creates outbound traffic rules for necessary external communications
- Handles both intra-scope (same app/env) and extra-scope (external) connections
- Creates separate rulesets for remote application connections

### Analyze Application Traffic
The `analyze-application-traffic` prompt provides detailed analysis of application traffic patterns and connectivity.

**Required Arguments:**
- `application_name`: Name of the application to analyze
- `application_environment`: Environment of the application to analyze

**Analysis Features:**
- Orders traffic by inbound and outbound flows
- Groups by application/environment/role combinations
- Identifies relevant label types and patterns
- Displays results in a React component format
- Shows protocol and port information
- Attempts to identify known service patterns (e.g., Nagios on port 5666)
- Categorizes traffic into infrastructure and application types
- Determines internet exposure
- Displays Illumio role, application, and environment labels

### How to use MCP prompts

Step1: Click "Attach from MCP" button in the interface

![MCP Prompt Workflow](images/prompts-finding-prompt-menu.png)

Step 2: Choose from installed MCP servers

![MCP Prompt Workflow](images/prompts-choose-integration.png)

Step 3: Fill in required prompt arguments:

![MCP Prompt Workflow](images/prompts-required-parameters.png)

Step 4: Click Submit to send the configured prompt

### How prompts work

- The MCP server sends the configured prompt to Claude
- Claude receives context through the Model Context Protocol
- Allows specialized handling of Illumio-specific tasks

This workflow enables automated context sharing between Illumio systems and Claude for application traffic analysis and ringfencing tasks.

## Docker

The application is available as a Docker container from the GitHub Container Registry.

### Pull the container

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

You can also use a specific version by replacing `latest` with a version number:

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

### Run with Claude Desktop

To use the container with Claude Desktop, you'll need to:

1. Create an environment file (e.g. `~/.illumio-mcp.env`) with your PCE credentials:

```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. Add the following configuration to your Claude Desktop config file:

On MacOS (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```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"
            ]
        }
    }
}
```

Make sure to:
- Replace `YOUR_USERNAME` with your actual username
- Create the log directory (e.g. `~/tmp`)
- Adjust the paths according to your system

### Run Standalone

You can also run the container directly:

```bash
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

For development or testing, you can use Docker Compose. Create a `docker-compose.yml` file:

```yaml
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
```

Then run:

```bash
docker-compose up
```

### Known Issues

When running the container, you may see syntax warnings from the Illumio SDK's regular expressions. These warnings don't affect functionality and are automatically suppressed in the container.

If you're seeing the warnings when running the container, you can manually suppress them by adding:

```bash
docker run \
  -e PYTHONWARNINGS=ignore \
  ... other environment variables ...
  ghcr.io/alexgoller/illumio-mcp-server:latest
```

Or in docker-compose.yml:

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

### Claude Desktop Configuration

For Claude Desktop users, add this configuration to your Claude Desktop config file:

```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"
            ]
        }
    }
}
```

Make sure to:
1. Replace `YOUR_USERNAME` with your actual username
2. Create a log directory at `~/tmp` (or adjust the path as needed)
3. Create an environment file at `~/.illumio-mcp.env` with your PCE credentials:

```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
```

The configuration:
- Uses Docker to run the container
- Mounts a local directory for logs
- Suppresses Python warnings
- Loads PCE credentials from an environment file
- Enables proper container cleanup with `--init` and `--rm`