Tufin MCP Server - Open Source Community Project

<!-- Optional: Add license badge -->

<!-- Optional: Add build status, code coverage badges etc. -->

Introduction

Welcome to the Tufin MCP (Multi-Controller Protocol) Server project! This open-source initiative aims to provide Tufin users with a powerful tool to bridge the gap between Tufin's robust APIs (SecureTrack and SecureChange) and modern AI development workflows.

By exposing Tufin functionalities through a secure, standardized REST API with Role-Based Access Control (RBAC), this server allows you to easily integrate Tufin data and actions into your custom scripts, applications, and AI agents (like those running in Cursor, ChatGPT Actions, Ollama, etc.).

This is a community-driven project. We encourage contributions! Whether it's adding new endpoint coverage, improving security, enhancing the client libraries, or fixing bugs, your input is valuable. Please check the Contributing section for more details.

Find the project repository on GitHub: https://github.com/stonecircle82/tufin-mcp <!-- ** ACTION REQUIRED: Replace with your actual repo URL ** -->

Why Use This?

• Simplify AI Integration: Provides a modern REST API layer over Tufin's existing APIs, making it easier to integrate with AI tools, chatbots, and automation scripts.
• Centralized Control: Manage Tufin access and authentication from one place.
• Enhanced Security: Adds API Key and Role-Based Access Control on top of Tufin's authentication.
• Extensibility: Designed to be extended to cover more Tufin APIs and potentially other security platforms.
• Future Potential: Aims to support newer Tufin APIs (like GraphQL) and features like bulk operations (e.g., adding devices from a file) which can be complex via direct API calls.

Overview

This server acts as a secure proxy and abstraction layer for Tufin APIs (v25.1 targeted).

Key Features:

• Standard REST/JSON API interface (documented via OpenAPI).
• Centralized Tufin Authentication (using Basic Auth configured via environment variables).
• API Key Authentication for MCP clients (keys are hashed using bcrypt).
• Configurable Role-Based Access Control (Admin, Ticket Manager, User).
• Endpoints for key SecureChange and SecureTrack operations (Ticketing, Devices, Topology).
• Structured JSON Logging with Request IDs.
• IP-based Rate Limiting.
• Basic Python Client Library.
• Docker support.

Getting Started

Prerequisites

• Python 3.8+
• Access to running Tufin SecureTrack and SecureChange instances (v25.1 compatible).
• Docker (if running via container).
• Git.

Installation

1. Clone the repository:

   git clone https://github.com/<your-username>/tufin-mcp.git # ** Replace URL **
   cd tufin-mcp
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate # On Windows use `venv\Scripts\activate`
   

3. Install dependencies:

   pip install -r requirements.txt
   

Configuration

Configuration is managed via environment variables or a .env file in the project root.

1. Create .env file: Copy .env.example (if provided) or create .env manually.

2. Set required variables:

   # Server Settings
   MCP_PORT=8000
   LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR
   
   # Tufin Connection (REPLACE with your details)
   TUFIN_SECURETRACK_URL="https://your-securetrack-host"
   TUFIN_SECURECHANGE_URL="https://your-securechange-host"
   TUFIN_USERNAME="your_tufin_username"
   TUFIN_PASSWORD="your_tufin_password"
   TUFIN_SSL_VERIFY="True" # Set to False only if absolutely necessary (insecure!)
   TUFIN_API_TIMEOUT="30.0" # Timeout for Tufin API calls in seconds
   
   # --- Development API Keys (Insecure - For Dev/Test Only!) ---
   # For the default In-Memory secure store, provide initial RAW keys and roles via this JSON string.
   # The server will HASH the keys on startup and store them in memory.
   # DO NOT USE PRODUCTION KEYS HERE.
   DEV_API_KEYS='[{"key":"admin_key_abc", "role":"admin"}, {"key":"manager_key_xyz", "role":"ticket_manager"}, {"key":"user_key_123", "role":"user"}]'
   

   SSL Verification Note (TUFIN_SSL_VERIFY): By default, the server attempts to verify the SSL certificates of your Tufin instances (TUFIN_SSL_VERIFY="True"). Setting this to "False" disables verification, which can be necessary for environments using self-signed certificates, but it is highly insecure for production as it exposes the connection to man-in-the-middle attacks. If using internal CAs, consider configuring the underlying system or providing a custom CA bundle path (requires code modification).

   Production Security Note: API Keys are hashed using bcrypt. The default InMemorySecureStore loads raw keys from DEV_API_KEYS only for development. For production, you MUST:

   1. Replace InMemorySecureStore in src/app/core/secure_store.py with an implementation using a secure database or secrets manager (e.g., HashiCorp Vault).
   2. Implement a secure process/endpoint for managing API keys (generating, storing hash+role, revoking).
   3. Do not use DEV_API_KEYS in production.

Running the Server

Local Development (Uvicorn)

# From the project root directory
uvicorn src.app.main:app --reload --port ${MCP_PORT:-8000}

• The --reload flag enables auto-reloading on code changes.
• Uses the port defined in .env or defaults to 8000.

Docker Container

1. Build the image:

   # From the project root directory
   docker build -t tufin-mcp-server:latest .
   

2. Run the container:

   docker run --rm -d \
     --name tufin-mcp \
     --env-file .env \
     -p ${MCP_PORT:-8000}:${MCP_PORT:-8000} \
     tufin-mcp-server:latest
   

   • Loads environment variables from your local .env file.
   • Maps the host port to the container port (defined by MCP_PORT or default 8000).

3. Accessing: http://localhost:${MCP_PORT:-8000}

4. Logs: docker logs tufin-mcp (-f to follow)

5. Stopping: docker stop tufin-mcp

Testing

This project uses pytest for testing.

1. Install test dependencies:

   pip install -r requirements-dev.txt
   

2. Run tests:

   # From the project root directory
   pytest
   

   • You can run specific files: pytest tests/api/v1/test_endpoints.py
   • Use -v for verbose output: pytest -v
   • Use -k to filter tests by name: pytest -k list_devices

3. Test Coverage (Optional): Install pytest-cov (pip install pytest-cov) and run:

   pytest --cov=src/app --cov-report=term-missing
   

API Usage

Authentication

Pass your generated API key in the X-API-Key HTTP header for all requests except /health.

Authorization (RBAC)

Access is controlled by roles assigned to API keys during key creation (using a secure production process or via DEV_API_KEYS for development). Allowed roles for each endpoint are configured in src/app/core/config.py under ENDPOINT_PERMISSIONS.

• Roles: admin, ticket_manager, user.
• Attempting an action without the required permission results in 403 Forbidden.

Configuring Endpoint Permissions:

The ENDPOINT_PERMISSIONS dictionary in src/app/core/config.py defines which roles can access which logical action (permission ID). Example:

# src/app/core/config.py
ENDPOINT_PERMISSIONS: Dict[str, List[UserRole]] = {
    "list_devices": [UserRole.ADMIN, UserRole.TICKET_MANAGER, UserRole.USER],
    "get_device": [UserRole.ADMIN, UserRole.TICKET_MANAGER, UserRole.USER],
    "create_ticket": [UserRole.ADMIN, UserRole.TICKET_MANAGER],
    # ... other permissions ...
}

• Why this approach? This centralizes access control policy in one place, making it easy to review and modify permissions without changing the endpoint code itself.
• How it works: Each API endpoint route uses the require_permission("permission_id") dependency. This dependency checks if the role associated with the user's validated API key is present in the list defined for that specific permission_id in the ENDPOINT_PERMISSIONS dictionary.
• Customization: You can easily customize access by modifying the list of UserRole enums for any given permission ID directly within config.py. Add new permission IDs as you add new endpoints.

Rate Limiting

IP-based rate limits apply (default: 60/minute). Exceeding limits results in 429 Too Many Requests.

Endpoints Overview

The API structure is defined in openapi.yaml. You can explore this file directly or use tools like Swagger UI if the spec is served by the application (requires adding static file serving to main.py).

Current Endpoint Summary:

• GET /health: Health check.
• POST /api/v1/tickets: Create SecureChange ticket.
• GET /api/v1/tickets: List SecureChange tickets (Supports filtering by status).
• GET /api/v1/tickets/{ticket_id}: Get a specific SecureChange ticket.
• PUT /api/v1/tickets/{ticket_id}: Update a SecureChange ticket.
• GET /api/v1/devices: List SecureTrack devices (Supports filtering by status, name, vendor).
• GET /api/v1/devices/{device_id}: Get SecureTrack device details.
• POST /api/v1/devices/bulk: Add one or more devices (requires vendor-specific device_data in request body).
• POST /api/v1/devices/bulk/import: Import managed devices (DGs, ADOMs, contexts, etc.) into existing management devices.
• GET /api/v1/topology/map: Get SecureTrack topology map.
• POST /api/v1/topology/query: Run a SecureTrack topology query.
• `GET /api/v1/