mcp-security-framework 1.5.1

Universal security framework for microservices with SSL/TLS, authentication, authorization, and rate limiting. Added UnknownRoleError exception for certificate role validation. Added to_string() method for CertificateRole serialization. Enhanced error handling with detailed exception information. Comprehensive test coverage with 1052+ tests including UnknownRoleError tests. All tests use real certificates. Requires cryptography>=42.0.0 for certificate operations.

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, Django, 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]
pip install mcp-security-framework[django]

# 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_file="roles.json")
)

# 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 fastapi import FastAPI
from mcp_security_framework import create_fastapi_security_middleware, SecurityConfig

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

# Create FastAPI app
app = FastAPI()

# Add security middleware
security_middleware = create_fastapi_security_middleware(config)
app.add_middleware(security_middleware)

@app.get("/secure")
async def secure_endpoint():
    return {"message": "Access granted"}

@app.get("/public")
async def public_endpoint():
    return {"message": "Public access"}

Flask Integration

from flask import Flask
from mcp_security_framework import create_flask_security_middleware, SecurityConfig

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

# Create Flask app
app = Flask(__name__)

# Add security middleware
security_middleware = create_flask_security_middleware(config)
app.wsgi_app = security_middleware(app.wsgi_app)

@app.route("/secure")
def secure_endpoint():
    return {"message": "Access granted"}

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

• Installation Guide
• Configuration Reference
• API Reference
• Examples
  • FastAPI Integration
  • Flask Integration
  • Standalone Usage
• Security Guide
  • SSL/TLS Setup
  • Authentication Methods
  • Authorization and Roles
  • Certificate Management
• Troubleshooting

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

# Format code
black src tests
isort src tests

# Lint code
flake8 src tests
mypy src

# Run all quality checks
tox

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 [e-mail].

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.