Illumio PCE Interfacing Utility

This component functions as a Model Context Protocol (MCP) server proxy, establishing a communication bridge to the Illumio PCE (Policy Compute Engine). It grants scripted control over Illumio workload configuration, label administration, and in-depth visibility into network communication patterns.

Core Capabilities

Leverage natural language processing to query and manipulate your PCE state:

• Provision, modify, and retire workload definitions
• Create, update, and remove security labeling constructs
• Retrieve network flow summaries and conduct security assessments on communication data
• Obtain reports on PCE system wellness

Prerequisites for Deployment

• Python runtime environment, version 3.8 or newer
• Network accessibility to a designated Illumio PCE instance
• Valid API authentication credentials authorized for the PCE

Setup Instructions

1. Obtain the source code repository:

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

1. Install required software packages:

bash pip install -r requirements.txt

Configuration Procedure

It is recommended to utilize the uv utility for execution, as it simplifies environment variable injection and background process management.

Integration with Claude Desktop

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

Inject the subsequent JSON snippet into the custom_settings block:

"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", # Organization identifier "API_KEY": "api_key", "API_SECRET": "api_secret" } } } }

Functionality Breakdown

Resource Accessors

Work in progress; future enhancements planned.

• illumio://workloads - Fetch current workload inventory from the PCE
• illumio://labels - Retrieve all defined labels from the PCE registry

Operational Tools

Workload Administration

• get-workloads - Query and return the complete set of workloads managed by the PCE
• create-workload - Provision a new, unmanaged workload specifying its identifier, network addresses, and associated labels
• update-workload - Modify attributes of an existing workload entity
• delete-workload - Erase a workload entry from the PCE based on its name

Label Administration

• create-label - Register a novel label defined by its key-value pair
• delete-label - Remove a previously established label using its key-value specification
• get-labels - Fetch the entire collection of security labels within the PCE

Traffic Telemetry Analysis

• get-traffic-flows - Obtain granular network flow records with extensive filtering parameters:
• Temporal window specification
• Originator/Target filtering
• Protocol and port specification
• Enforcement decision inclusion/exclusion
• Queries based on workload or IP address sets

• Result set size limitation

• get-traffic-flows-summary - Acquire aggregated traffic statistics utilizing the identical filtering mechanisms as detailed above

Policy Governance

• get-rulesets - Retrieve PCE rule sets, supporting optional refinement filters:
• Filtering by descriptive name
• Filtering based on active/inactive status

IP List Control

• get-iplists - Fetch defined IP address lists, supporting optional search criteria:
• Filtering by list name
• Filtering by descriptive text
• Filtering based on contained IP address blocks

Connectivity Diagnostics

• check-pce-connection - Validate established network linkage and API credential validity with the PCE

Event Monitoring

• get-events - Retrieve system events from the PCE with optional filtering criteria:
• Filtering by event category (e.g., 'system_task.expire_service_account_api_keys')
• Filtering by severity levels (emerg, alert, crit, err, warning, notice, info, debug)
• Filtering by operational status (success, failure)
• Limiting the quantity of output records

Exception Management

The service incorporates robust mechanisms for error detection and reporting: - Failures in establishing PCE connectivity - Problems with API authorization procedures - Failures during resource creation or modification attempts - Validation errors concerning input parameters

All detected exceptions are comprehensively logged, including full stack traces, and returned to the client as structured error responses.

Development Lifecycle

Executing Verification Suites

Testing modules are not yet finalized.

bash python -m pytest tests/

Operational Verbosity (Debug Mode)

Enable the DEBUG logging level either within the source code or via environment variables to obtain extensive operational tracing.

Contributions Guidelines

1. Duplicate the project repository (Fork)
2. Establish a dedicated feature branch
3. Commit all modifications
4. Push the branch to the remote repository
5. Submit a Pull Request

Licensing

This software is distributed under the GPL-3.0 License. Refer to the [LICENSE] document for specifics.

Assistance

For support inquiries, please initiate a report via create an issue.

Usage Illustrations

Graphical Examples

All visualizations below were produced utilizing Claude Desktop 3.5 Sonnet, based on data retrieved via this MCP adapter. Integrating this data into React components yields superior visual outcomes.

Application Communication Mapping

In-depth visualization of application connectivity relationships and dependencies

Analysis charting traffic flows across various application strata

Infrastructure Status Insights

Executive dashboard summarizing essential infrastructure metrics and current state

Detailed examination of service interactions within the infrastructure

Security Posture Review

Comprehensive report detailing security audit findings

Security assessment outcomes targeting high-severity vulnerabilities

Findings related to PCI compliance validation

Findings related to SWIFT compliance validation

Remediation Strategy Formulation

High-level overview for planning security corrective actions

Step-by-step blueprint for implementing security remediation tasks

Policy Configuration Management

Interface for administering network address lists

Organizational view of ruleset groupings and sequence

Configuration ordering of application-specific rulesets

Workload Administration

Detailed scrutiny of workload data and performance indicators

Identification and analysis of communication patterns impacting specific workloads

Label Organization

Structured organization of PCE labels categorized by type and context

Service Pattern Deduction

Automated deduction of service roles based on observed traffic characteristics

Presentation of the top five communication sources and destinations

Project Execution Planning

Timeline and critical milestones for project realization

Available Query Prompts

Application Isolation (Ringfencing)

The ringfence-application utility automates the creation of security policies to logically partition and secure specified applications by regulating ingress and egress traffic streams.

Mandatory Parameters: - application_name: The identifier of the application requiring isolation - application_environment: The operational sphere of the application to be secured

Capabilities: - Constructs rules governing internal communication paths within the application boundary - Leverages traffic flow data to determine necessary external connection permissions - Enforces ingress traffic limitations based on originating applications - Establishes necessary egress rules for required external communication channels - Manages both same-scope (internal app/env) and cross-scope (external) connections - Generates distinct rulesets for connections extending outside the primary application scope

Application Traffic Analysis

The analyze-application-traffic utility supplies in-depth diagnostics concerning application communication topology and connectivity.

Mandatory Parameters: - application_name: Name of the application under review - application_environment: Contextual environment of the application being analyzed

Diagnostic Features: - Sorts traffic data by incoming and outgoing volumes - Aggregates data based on application/environment/role combinations - Pinpoints relevant security labeling taxonomies and patterns - Formats output for display within a React component structure - Details observed protocols and associated ports - Attempts to recognize standard service signatures (e.g., Nagios port 5666) - Classifies traffic streams as infrastructure-related or purely application-related - Determines exposure level to the public internet - Reports associated Illumio role, application, and environment labels

Utilizing MCP Query Prompts

Step1: Activate the "Attach from MCP" control within the graphical interface

Step 2: Select the correctly installed MCP service adapter

Step 3: Populate all required prompt arguments in the form fields

Step 4: Execute 'Submit' to transmit the formulated query to the model

Prompt Execution Mechanics

• The MCP adapter transmits the specified prompt configuration to the Claude model
• Claude interprets the context delivered via the Model Context Protocol
• This facilitates specialized execution for tasks intrinsically linked to Illumio security operations (like traffic assessment or isolation enforcement)

This procedural flow enables seamless, automated context transfer between Illumio security infrastructure and the AI model for advanced traffic analysis and policy enforcement tasks.

Containerization

The software package is accessible via a container image hosted on the GitHub Container Registry.

Image Retrieval

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

You may specify a precise version tag instead of latest:

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

Execution with Claude Desktop (Containerized)

To integrate the container with Claude Desktop, follow these configuration steps:

1. Provision an environment configuration file (e.g., ~/.illumio-mcp.env) containing 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

1. Update your Claude Desktop configuration file (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" ] } } }

Ensure you perform these actions: - Substitute YOUR_USERNAME with your actual system user identifier - Establish the designated log output directory (e.g., ~/tmp) - Customize file paths according to your operating environment

Direct Container Invocation

Execute the container image without orchestration tools:

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 Configuration

For local development or iterative testing, utilize Docker Compose via a docker-compose.yml definition:

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

Initiate execution with:

bash docker-compose up

Noted Issues

During container runtime, warnings related to regular expression syntax within the Illumio SDK may appear. These warnings do not impede core function and are silenced automatically within the container context.

If these warnings persist when running the container, you can manually suppress them by incorporating:

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

Or within the docker-compose.yml service definition:

yaml services: illumio-mcp: environment: - PYTHONWARNINGS=ignore # ... other environmental parameters ...

Claude Desktop Integration (Docker Context)

For users leveraging Claude Desktop, incorporate this specific configuration into the client's settings file:

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

Critical setup requirements: 1. Replace /Users/YOUR_USERNAME/tmp with your actual user directory path for log volume mapping. 2. Guarantee the log directory (e.g., ~/tmp) exists. 3. Create the environment file ~/.illumio-mcp.env to securely hold PCE connection parameters:

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 leverages Docker to execute the service, maps a local volume for persistent logging, suppresses non-critical Python warnings, loads sensitive PCE details from a separate file, and ensures clean container termination via --init and --rm flags.