[SECURITY FEATURE]: Gateway-Level Rate Limiting, DDoS Protection & Abuse Detection

[crivetimihai]

🧭 Epic

Title: Gateway-Level Rate Limiting, DDoS Protection & Abuse Detection
Goal: Implement a comprehensive protection framework in our MCP Gateway to defend against resource exhaustion, distributed attacks, and abusive usage patterns through intelligent rate limiting, adaptive DDoS mitigation, and behavioral abuse detection.
Why now: Mitigate potential vulnerabilities to burst traffic and malicious actors. We need battle-tested protection mechanisms that can scale with legitimate usage while blocking bad actors. This builds a reference implementation for upstream MCP security standards and recommendations.

---

🧭 Type of Feature

• Security hardening
• Performance optimization
• New functionality (experimental)
• Reliability improvement

---

🙋‍♂️ User Story 1 — Adaptive Rate Limiting

As a: Platform reliability engineer
I want: the gateway to enforce per-client rate limits with burst allowances and adaptive thresholds
So that: legitimate users get fair resource access while preventing any single client from overwhelming the system.

✅ Acceptance Criteria

Scenario: Enforce per-client rate limits
Given client "app_123" has limit 100 req/min with burst 20
When client makes 25 requests in 10 seconds
Then first 20 succeed immediately
And remaining 5 are rate-limited with 429 "rate_limit_exceeded"
And include "Retry-After" header with backoff time

Scenario: Adaptive threshold adjustment
Given baseline traffic shows 95th percentile at 50 req/min
When system detects consistent 200 req/min from legitimate sources
Then automatically adjust thresholds upward
And log threshold changes for audit

---

🙋‍♂️ User Story 2 — DDoS Attack Mitigation

As a: Security operations engineer
I want: automatic detection and mitigation of distributed denial-of-service attacks
So that: the gateway remains responsive to legitimate traffic during attack conditions.

✅ Acceptance Criteria

Scenario: Detect volumetric DDoS attack
Given normal traffic baseline of 1000 req/min
When traffic spikes to 10000 req/min from 100+ unique IPs
Then activate DDoS protection mode
And apply progressive backpressure (429 → 503 → connection drops)
And alert security team with attack metrics

Scenario: Geographic anomaly detection
Given 90% of traffic normally from US/EU
When 70% of traffic suddenly originates from single /16 subnet
Then flag as potential botnet activity
And apply enhanced verification (CAPTCHA/proof-of-work)

---

🙋‍♂️ User Story 3 — Behavioral Abuse Detection

As a: API product manager
I want: detection of suspicious usage patterns and automated abuse prevention
So that: resource-intensive or malicious behavior is identified and contained before impacting service quality.

✅ Acceptance Criteria

Scenario: Detect resource exhaustion abuse
Given tool "expensive_analysis" has 30-second average execution
When client makes 50 concurrent calls to same tool
Then flag as potential abuse pattern
And queue subsequent requests with exponential backoff
And notify client of usage optimization recommendations

Scenario: Credential stuffing detection
Given multiple failed auth attempts from single IP
When 100+ auth failures in 5 minutes with different usernames
Then temporarily block IP for 15 minutes
And require additional verification for subsequent attempts

---

📐 Design Sketch

flowchart TD
    subgraph ProtectionLayer
        A[Incoming Request] --> RL{Rate Limiter<br/>Token Bucket}
        RL --✔--> DD{DDoS Detector<br/>Anomaly Analysis}
        RL --✖--> R1[HTTP 429]
        DD --✔--> AB{Abuse Detector<br/>Pattern Analysis}
        DD --✖--> R2[HTTP 503]
        AB --✔--> H[Handler]
        AB --✖--> R3[HTTP 422]
    end
    H --> M[Metrics Collection]
    M --> A1[Alert System]
    M --> A2[Auto-Scaling Triggers]
    
    subgraph Storage
        Redis[(Redis<br/>Rate Counters)]
        Metrics[(InfluxDB<br/>Time Series)]
        Patterns[(PostgreSQL<br/>Abuse Patterns)]
    end
    
    RL -.-> Redis
    DD -.-> Metrics
    AB -.-> Patterns

Loading

Component / Area	Change	Detail
rate_limiting_middleware.py	NEW	Token bucket algorithm; sliding window counters; per-client & per-endpoint
ddos_protection.py	NEW	Traffic anomaly detection; geolocation analysis; progressive response delays
abuse_detection.py	NEW	Pattern recognition ML; resource usage analytics; behavioral fingerprinting
Redis Integration	NEW	Distributed rate counters; shared state across gateway instances
Metrics Pipeline	UPDATE	Real-time traffic analysis; alerting thresholds; dashboard integration
Config Management	UPDATE	RATE_LIMITS, DDOS_THRESHOLDS, ABUSE_PATTERNS dynamic configuration
Client SDK Updates	UPDATE	Retry logic with exponential backoff; rate limit header parsing
Monitoring Dashboard	NEW	Real-time protection status; attack visualization; client usage analytics

---

🔄 Roll-out Plan

1. Phase 0: Feature-flag via EXPERIMENTAL_PROTECTION_SUITE (monitoring only, no blocking).
2. Phase 1: Enable rate limiting in log-only mode; collect baseline metrics for 2 weeks.
3. Phase 2: Enforce rate limits in staging; tune DDoS detection thresholds.
4. Phase 3: Deploy DDoS protection to prod with conservative thresholds; A/B test abuse detection.
5. Phase 4: Full enforcement with automated threshold adjustment; publish MCP security addendum.

---

📊 Key Metrics & Thresholds

Protection Type	Metric	Baseline	Alert Threshold	Action Threshold
Rate Limiting	Requests/min per client	100	150	200
DDoS Detection	Traffic spike factor	2x normal	5x normal	10x normal
Geographic Anomaly	Traffic concentration	<30% per /16	>50% per /16	>70% per /16
Resource Abuse	Concurrent expensive ops	<10 per client	>25 per client	>50 per client

---

📝 Spec-Draft Clauses (to upstream later)

1. Rate Limiting Clause – "Servers SHOULD implement fair-use rate limiting with configurable per-client quotas and burst allowances."
2. DDoS Resilience Clause – "Servers MUST detect traffic anomalies and apply progressive backpressure to maintain service availability."
3. Abuse Prevention Clause – "Servers SHOULD monitor usage patterns and temporarily restrict clients exhibiting resource-intensive or suspicious behavior."
4. Protection Transparency Clause – "Rate limiting and protection responses MUST include appropriate HTTP status codes and 'Retry-After' headers."
5. Metrics Standardization Clause – "Servers SHOULD expose protection metrics via standard endpoints for monitoring integration."

---

🔧 Implementation Priorities

High Priority:

• Token bucket rate limiting with Redis backend
• Basic DDoS detection (traffic volume + request rate)
• Rate limit headers and client-friendly error responses

Medium Priority:

• Geographic anomaly detection
• Resource usage pattern analysis
• Automated threshold adjustment

Low Priority:

• ML-based behavioral fingerprinting
• Advanced proof-of-work challenges
• Cross-gateway coordination for distributed attacks

---

📣 Next Steps

• Implement core rate limiting middleware with unit tests (tests/security/test_rate_limiting.py).
• Set up Redis cluster for distributed counter storage.
• Create monitoring dashboard with Grafana + InfluxDB integration.
• Draft client SDK examples showing proper retry logic and rate limit handling.
• Benchmark protection overhead impact on gateway performance.

Once battle-tested in production, we'll propose these patterns as MCP Security Recommendations to establish industry standards for MCP gateway protection.

---

[crivetimihai]

Alternative (TO DISCUSS)

🧭 Epic

Title: Gateway-Level Rate Limiting, DDoS Protection & Abuse Detection
Goal: Implement a comprehensive protection framework in our MCP Gateway to defend against resource exhaustion, distributed attacks, and abusive usage patterns through intelligent rate limiting, adaptive DDoS mitigation, and behavioral abuse detection.
Why now: Mitigate potential vulnerabilities to burst traffic and malicious actors. We need battle-tested protection mechanisms that can scale with legitimate usage while blocking bad actors. This builds a reference implementation for upstream MCP security standards and recommendations.

---

🧭 Type of Feature

• Security hardening
• Performance optimization
• New functionality (experimental)
• Reliability improvement

---

🙋‍♂️ User Story 1 — Adaptive Rate Limiting

As a: Platform reliability engineer
I want: the gateway to enforce per-client rate limits with burst allowances and adaptive thresholds
So that: legitimate users get fair resource access while preventing any single client from overwhelming the system.

✅ Acceptance Criteria

Scenario: Enforce per-client rate limits
Given client "app_123" has limit 100 req/min with burst 20
When client makes 25 requests in 10 seconds
Then first 20 succeed immediately
And remaining 5 are rate-limited with 429 "rate_limit_exceeded"
And include "Retry-After" header with backoff time
And include rate limit headers showing remaining quota

Scenario: Adaptive threshold adjustment
Given baseline traffic shows 95th percentile at 50 req/min
When system detects consistent 200 req/min from legitimate sources
Then automatically adjust thresholds upward
And log threshold changes for audit

---

🙋‍♂️ User Story 2 — DDoS Attack Mitigation

As a: Security operations engineer
I want: automatic detection and mitigation of distributed denial-of-service attacks
So that: the gateway remains responsive to legitimate traffic during attack conditions.

✅ Acceptance Criteria

Scenario: Detect volumetric DDoS attack
Given normal traffic baseline of 1000 req/min
When traffic spikes to 10000 req/min from 100+ unique IPs
Then activate DDoS protection mode
And apply progressive backpressure (429 → 503 → connection drops)
And alert security team with attack metrics

Scenario: Geographic anomaly detection
Given 90% of traffic normally from US/EU
When 70% of traffic suddenly originates from single /16 subnet
Then flag as potential botnet activity
And apply enhanced verification (CAPTCHA/proof-of-work)

---

🙋‍♂️ User Story 3 — Behavioral Abuse Detection

As a: API product manager
I want: detection of suspicious usage patterns and automated abuse prevention
So that: resource-intensive or malicious behavior is identified and contained before impacting service quality.

✅ Acceptance Criteria

Scenario: Detect resource exhaustion abuse
Given tool "expensive_analysis" has 30-second average execution
When client makes 50 concurrent calls to same tool
Then flag as potential abuse pattern
And queue subsequent requests with exponential backoff
And notify client of usage optimization recommendations

Scenario: Credential stuffing detection
Given multiple failed auth attempts from single IP
When 100+ auth failures in 5 minutes with different usernames
Then temporarily block IP for 15 minutes
And require additional verification for subsequent attempts

---

📐 Design Sketch

flowchart TD
    subgraph ProtectionLayer
        A[Incoming Request] --> RL{Rate Limiter<br/>Token Bucket + Redis}
        RL --✔--> DD{DDoS Detector<br/>Anomaly Analysis}
        RL --✖--> R1[HTTP 429<br/>+Rate Limit Headers]
        DD --✔--> AB{Abuse Detector<br/>Pattern Analysis}
        DD --✖--> R2[HTTP 503]
        AB --✔--> H[Handler]
        AB --✖--> R3[HTTP 422]
    end
    H --> M[Metrics Collection]
    M --> A1[Alert System]
    M --> A2[Auto-Scaling Triggers]
    
    subgraph Storage
        Redis[(Redis<br/>Rate Counters + DDoS State)]
        Metrics[(InfluxDB<br/>Time Series)]
        Patterns[(PostgreSQL<br/>Abuse Patterns)]
    end
    
    RL -.-> Redis
    DD -.-> Metrics
    AB -.-> Patterns

Loading

---

🔧 Implementation Components

Component / Area	Change	Detail
mcpgateway/middleware/rate_limiting.py	NEW	Token bucket algorithm; per-client & per-endpoint limiting; Redis backend
mcpgateway/middleware/ddos_protection.py	NEW	Traffic anomaly detection; geolocation analysis; progressive response delays
mcpgateway/middleware/abuse_detection.py	NEW	Pattern recognition; resource usage analytics; behavioral fingerprinting
mcpgateway/protection/	NEW	Protection utilities, IP analysis, metrics collection
mcpgateway/config.py	UPDATE	Add rate limiting, DDoS, and abuse detection configuration
mcpgateway/main.py	UPDATE	Register protection middleware in correct order
Redis Integration	UPDATE	Extend existing Redis usage for distributed rate counters
Monitoring Dashboard	NEW	Real-time protection status; attack visualization; client usage analytics

---

⚙️ Configuration (.env.example)

#####################################
# Rate Limiting & Protection
#####################################

# Enable the protection suite (feature flag)
EXPERIMENTAL_PROTECTION_SUITE=false

# Rate Limiting Configuration
RATE_LIMITING_ENABLED=true
RATE_LIMITING_STRATEGY=moving-window  # Options: fixed-window, moving-window
RATE_LIMITING_HEADERS_ENABLED=true   # Include rate limit headers in responses

# Default rate limits (can be overridden per endpoint)
RATE_LIMIT_DEFAULT=100/minute        # Default limit for authenticated users
RATE_LIMIT_ANONYMOUS=10/minute       # Limit for unauthenticated requests
RATE_LIMIT_TOOL_EXECUTION=50/minute  # Limit for tool execution endpoints
RATE_LIMIT_ADMIN_API=200/minute      # Higher limit for admin operations

# Rate limiting storage (requires Redis for distributed setups)
RATE_LIMIT_STORAGE_TYPE=redis        # Options: redis, memory
RATE_LIMIT_REDIS_URL=${REDIS_URL}    # Use existing Redis URL

# DDoS Protection
DDOS_PROTECTION_ENABLED=true
DDOS_DETECTION_WINDOW=300            # Seconds to analyze for anomalies
DDOS_TRAFFIC_SPIKE_THRESHOLD=5       # Multiple of baseline traffic to trigger protection
DDOS_IP_CONCENTRATION_THRESHOLD=0.7  # % of traffic from single /16 subnet to trigger alert
DDOS_AUTO_BAN_ENABLED=false          # Automatically ban suspicious IPs (use with caution)
DDOS_BAN_DURATION=3600              # Seconds to ban suspicious IPs

# Geographic Protection
GEO_PROTECTION_ENABLED=false         # Enable geographic anomaly detection
GEO_PROTECTION_ALLOWED_COUNTRIES=""  # Comma-separated ISO country codes (empty = all allowed)
GEO_PROTECTION_BLOCKED_COUNTRIES=""  # Comma-separated ISO country codes to block
GEO_DATABASE_PATH=""                 # Path to GeoIP database (optional)

# Abuse Detection  
ABUSE_DETECTION_ENABLED=true
ABUSE_PATTERN_LEARNING=true          # Enable ML-based pattern learning
ABUSE_CONCURRENT_LIMIT=20            # Max concurrent requests per client
ABUSE_EXPENSIVE_TOOL_LIMIT=5         # Max concurrent calls to expensive tools
ABUSE_SUSPICIOUS_THRESHOLD=100       # Failed requests per hour to flag as suspicious

# Progressive Backpressure
BACKPRESSURE_ENABLED=true
BACKPRESSURE_QUEUE_SIZE=1000         # Max requests to queue during high load
BACKPRESSURE_TIMEOUT=30              # Seconds to wait in queue before rejecting

# Monitoring and Alerting
PROTECTION_METRICS_ENABLED=true
PROTECTION_ALERT_WEBHOOK=""          # Webhook URL for security alerts
PROTECTION_LOG_LEVEL=INFO            # Logging level for protection events
PROTECTION_DASHBOARD_ENABLED=true    # Enable real-time protection dashboard

# Client Identification
CLIENT_ID_HEADER=X-Client-ID         # Header to identify different client applications
CLIENT_ID_JWT_CLAIM=client_id        # JWT claim containing client identifier

# Whitelisting
RATE_LIMIT_WHITELIST_IPS=""          # Comma-separated IPs to exclude from rate limiting
RATE_LIMIT_WHITELIST_USER_AGENTS=""  # Comma-separated user agents to exclude
RATE_LIMIT_WHITELIST_API_KEYS=""     # Comma-separated API keys to exclude

# Rate Limit Bypass
RATE_LIMIT_BYPASS_HEADER=X-Rate-Limit-Bypass  # Header for emergency bypass (admin only)
RATE_LIMIT_BYPASS_SECRET=""          # Secret value for bypass header

---

🧪 Testing Requirements

Unit Tests

• Test rate limiting per IP and per authenticated user
• Test different limits for different endpoints (tools vs admin vs general)
• Test whitelist functionality for IPs and user agents
• Test client identification logic (API key, JWT, IP fallback)
• Test Redis integration and fallback to memory storage
• Test rate limit headers in responses

Integration Tests

• Test progressive rate limiting under load
• Test concurrent request handling
• Test protection specifically for tool execution endpoints
• Test DDoS detection and mitigation
• Test abuse pattern detection

Performance Tests

• Measure rate limiting overhead (should be < 50ms per request)
• Test Redis performance under load
• Test concurrent request processing
• Benchmark different rate limiting strategies

Files to Create

tests/middleware/test_rate_limiting.py
tests/middleware/test_ddos_protection.py
tests/middleware/test_abuse_detection.py
tests/integration/test_protection_integration.py
tests/performance/test_protection_performance.py

---

📊 Key Metrics & Thresholds

Protection Type	Metric	Baseline	Alert Threshold	Action Threshold
Rate Limiting	Requests/min per client	100	150	200
DDoS Detection	Traffic spike factor	2x normal	5x normal	10x normal
Geographic Anomaly	Traffic concentration	<30% per /16	>50% per /16	>70% per /16
Resource Abuse	Concurrent expensive ops	<10 per client	>25 per client	>50 per client

---

📋 Documentation Requirements

API Documentation

• Rate limiting headers and error responses
• Client retry logic guidelines
• Protection bypass procedures for emergencies

Operational Documentation

• DDoS response runbook
• Protection threshold tuning guide
• Redis scaling considerations

Developer Documentation

• Custom rate limiting implementation guide
• Testing applications against rate limits
• Integration with existing auth systems

---

🔄 Roll-out Plan

1. Phase 0: Feature-flag via EXPERIMENTAL_PROTECTION_SUITE=false (monitoring only, no blocking).
2. Phase 1: Enable rate limiting in log-only mode; collect baseline metrics for 2 weeks.
3. Phase 2: Enforce rate limits in staging; tune DDoS detection thresholds.
4. Phase 3: Deploy DDoS protection to prod with conservative thresholds; A/B test abuse detection.
5. Phase 4: Full enforcement with automated threshold adjustment; publish MCP security addendum.

---

📝 Spec-Draft Clauses (to upstream later)

1. Rate Limiting Clause – "Servers SHOULD implement fair-use rate limiting with configurable per-client quotas and burst allowances using standard HTTP headers."
2. DDoS Resilience Clause – "Servers MUST detect traffic anomalies and apply progressive backpressure to maintain service availability during attack conditions."
3. Abuse Prevention Clause – "Servers SHOULD monitor usage patterns and temporarily restrict clients exhibiting resource-intensive or suspicious behavior."
4. Protection Transparency Clause – "Rate limiting and protection responses MUST include appropriate HTTP status codes, 'Retry-After' headers, and rate limit information."
5. Metrics Standardization Clause – "Servers SHOULD expose protection metrics via standard endpoints for monitoring integration and security analysis."

---

🔧 Implementation Priorities

High Priority:

• Rate limiting middleware with Redis backend
• Basic DDoS detection (traffic volume + request rate)
• Rate limit headers and client-friendly error responses

Medium Priority:

• Geographic anomaly detection
• Resource usage pattern analysis
• Automated threshold adjustment

Low Priority:

• ML-based behavioral fingerprinting
• Advanced proof-of-work challenges
• Cross-gateway coordination for distributed attacks

---

💡 Implementation Options

Rate Limiting Libraries

• SlowAPI: FastAPI-specific rate limiting with Redis support and built-in header management
• python-limits: Generic rate limiting library with multiple storage backends
• Custom implementation: Using Redis directly with token bucket algorithm

DDoS Protection

• Cloudflare integration: API-based DDoS protection and traffic analysis
• Custom middleware: Traffic pattern analysis with configurable thresholds
• NGINX rate limiting: Upstream rate limiting at reverse proxy layer

Abuse Detection

• Scikit-learn: ML-based pattern recognition for behavioral analysis
• Rule-based detection: Configurable thresholds for concurrent requests and failure rates
• External services: Integration with abuse detection APIs

---

📣 Next Steps

1. Choose implementation approach from options above
2. Create middleware structure: mkdir -p mcpgateway/middleware
3. Implement core rate limiting with chosen library
4. Add configuration to settings and environment files
5. Create comprehensive test suite covering all scenarios
6. Update main.py to register middleware in proper order
7. Set up monitoring and alerting for protection metrics
8. Deploy with feature flags for safe progressive rollout

Once battle-tested in production, we'll propose these patterns as MCP Security Recommendations to establish industry standards for MCP gateway protection.