MCP Security Framework

Universal security framework for microservices with SSL/TLS, authentication, authorization, and rate limiting.

Features

• 🔐 Multi-method Authentication: API keys, JWT tokens, X.509 certificates
• 🛡️ SSL/TLS Management: Server and client certificate handling
• 🔑 Role-based Authorization: Flexible permission system with role hierarchy
• ⚡ Rate Limiting: Configurable request rate limiting
• 🚀 Framework Agnostic: Works with FastAPI, Flask, and standalone
• 🛠️ CLI Tools: Certificate management and security testing
• 📊 Comprehensive Logging: Security event logging and monitoring

Quick Start

Installation

# Basic installation
pip install mcp-security-framework

# With framework support
pip install mcp-security-framework[fastapi]
pip install mcp-security-framework[flask]

# Development installation
pip install mcp-security-framework[dev]

Basic Usage

from mcp_security_framework import SecurityManager, SecurityConfig
from mcp_security_framework.schemas.config import AuthConfig, PermissionConfig

# Create configuration
config = SecurityConfig(
    auth=AuthConfig(
        enabled=True,
        methods=["api_key"],
        api_keys={"admin": "admin_key_123"}
    ),
    permissions=PermissionConfig(
        roles={"admin": ["read", "write"]}
    )
)

# Create security manager
security_manager = SecurityManager(config)

# Validate request
result = security_manager.validate_request({
    "api_key": "admin_key_123",
    "required_permissions": ["read", "write"]
})

if result.is_valid:
    print("Access granted!")
else:
    print(f"Access denied: {result.error_message}")

FastAPI Integration

from mcp_security_framework import SecurityManager, SecurityConfig
from mcp_security_framework.schemas.config import AuthConfig, PermissionConfig

# Configuration
config = SecurityConfig(
    auth=AuthConfig(
        enabled=True,
        methods=["api_key", "jwt"],
        api_keys={"user": "user_key_456"},
        jwt_secret="your_jwt_secret_key"
    ),
    permissions=PermissionConfig()
)

# Create security manager
security_manager = SecurityManager(config)

# Create FastAPI middleware
security_middleware = security_manager.create_fastapi_middleware()

# The middleware is now ready to be integrated with your FastAPI application
# via the standard FastAPI middleware integration pattern

Flask Integration

from mcp_security_framework import SecurityManager, SecurityConfig
from mcp_security_framework.schemas.config import AuthConfig, PermissionConfig

# Configuration
config = SecurityConfig(
    auth=AuthConfig(
        enabled=True,
        methods=["api_key"]
    ),
    permissions=PermissionConfig()
)

# Create security manager
security_manager = SecurityManager(config)

# Create Flask middleware
security_middleware = security_manager.create_flask_middleware()

# The middleware can be integrated with your Flask application
# via: app.wsgi_app = security_middleware(app.wsgi_app)

CLI Tools

Certificate Management

# Create root CA
mcp-cert create-ca --ca-name "My Root CA" --output-dir ./certs

# Create client certificate
mcp-cert create-client-cert --name "client1" --roles "user,admin" --permissions "read,write"

# Create server certificate
mcp-cert create-server-cert --name "api-server" --domains "api.example.com"

Security Testing

# Validate configuration
mcp-security validate-config --config-file security_config.json

# Test authentication
mcp-security test-auth --config-file security_config.json --api-key "test_key"

Configuration

Basic Configuration File

{
  "ssl": {
    "enabled": true,
    "cert_file": "server.crt",
    "key_file": "server.key",
    "ca_cert_file": "ca.crt",
    "verify_mode": "CERT_REQUIRED",
    "min_version": "TLSv1.2"
  },
  "auth": {
    "enabled": true,
    "methods": ["api_key", "jwt", "certificate"],
    "api_keys": {
      "admin": "admin_key_123",
      "user": "user_key_456"
    },
    "jwt_secret": "your_jwt_secret_key",
    "jwt_expiry_hours": 24,
    "public_paths": ["/docs", "/health"]
  },
  "certificates": {
    "ca_dir": "./certs",
    "roles_oid": "1.3.6.1.4.1.99999.1.1",
    "permissions_oid": "1.3.6.1.4.1.99999.1.2",
    "verify_certificates": true,
    "check_revocation": true
  },
  "permissions": {
    "roles_file": "roles.json",
    "deny_by_default": true,
    "case_sensitive": false,
    "allow_wildcard": true
  },
  "rate_limit": {
    "enabled": true,
    "rate_limit": 100,
    "time_window": 60,
    "by_ip": true,
    "by_user": true
  }
}

Roles and Permissions

{
  "roles": {
    "admin": {
      "name": "admin",
      "description": "Administrator role",
      "permissions": ["read", "write", "delete", "admin"],
      "priority": 100
    },
    "user": {
      "name": "user",
      "description": "Regular user role",
      "permissions": ["read", "write"],
      "priority": 50
    },
    "guest": {
      "name": "guest",
      "description": "Guest role",
      "permissions": ["read"],
      "priority": 10
    }
  },
  "role_hierarchy": {
    "roles": {
      "admin": ["user"],
      "user": ["guest"]
    }
  },
  "default_policy": {
    "deny_by_default": true,
    "require_role_match": true,
    "case_sensitive": false,
    "allow_wildcard": true
  }
}

Wildcard Roles

Some deployments need to assign every available role to a token or certificate. The framework now supports the wildcard role marker * (aliases: all, any) in every configuration point that accepts role lists (API tokens, user role mappings, certificate roles, and validator inputs). When present, the wildcard:

• Grants access to every role defined in the Permission Manager
• Satisfies any allow_roles constraint in certificate validation
• Automatically inherits all permissions associated with every configured role

Security note: wildcard roles implicitly include denied roles. If you add a wildcard token or certificate, ensure that deny_roles lists or permission policies explicitly guard sensitive actions. To block wildcard usage entirely, add "*" to the relevant deny list.

Documentation

• X.509 Attribute Certificates and Role Model
• Certificate Validation Methods Reference

Development

Setup Development Environment

# Clone repository
git clone https://github.com/mcp-security/mcp-security-framework.git
cd mcp-security-framework

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_security_framework --cov-report=html

# Run specific test categories
pytest -m unit
pytest -m integration
pytest -m "not slow"

Code Quality

# Run all tests and quality checks
python -m pipeline

# List all available checks
python -m pipeline --list

# Format code
black mcp_security_framework tests
isort mcp_security_framework tests

# Lint code
flake8 mcp_security_framework tests
mypy mcp_security_framework

Building Documentation

# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation
sphinx-build -b html docs docs/_build/html

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (pytest)
6. Format and lint your code (black, isort, flake8, mypy)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Security

If you discover a security vulnerability, please report it to us at security@mcp.example.com.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Changelog

See CHANGELOG.md for a list of changes and version history.