Security docs

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

docs/docs/architecture/.pages

@@ -1,4 +1,5 @@
 nav:
   - Overview: index.md
   - Roadmap: roadmap.md
+  - Security Features: security-features.md
   - Decision Records: adr

docs/docs/architecture/security-features.md

@@ -0,0 +1,288 @@
+# MCP Gateway Security Features
+
+**⚠️ Important**: MCP Gateway is an **OPEN SOURCE PROJECT** provided "as-is" with **NO OFFICIAL SUPPORT** from IBM or its affiliates. Community contributions and best-effort maintenance are provided by project maintainers and contributors.
+
+**Current Version: 0.5.0 (Beta)** - MCP Gateway is currently in early beta. Security features are continuously evolving toward the 1.0 release.
+
+## Comprehensive Security Capabilities
+
+### 🔐 Authentication & Identity Management
+
+• **JWT Token Management** - Configurable JWT tokens with expiration, per-user token catalogs, and revocation support ([#87](https://github.com/IBM/mcp-context-forge/issues/87), [#425](https://github.com/IBM/mcp-context-forge/issues/425))
+
+• **Database-Backed User Authentication** - Argon2id password hashing replacing basic auth ([#544](https://github.com/IBM/mcp-context-forge/issues/544))
+
+• **Enterprise SSO Integration** - Support for GitHub, Google, LDAP/Active Directory identity providers ([#220](https://github.com/IBM/mcp-context-forge/issues/220), [#277](https://github.com/IBM/mcp-context-forge/issues/277), [#278](https://github.com/IBM/mcp-context-forge/issues/278), [#284](https://github.com/IBM/mcp-context-forge/issues/284))
+
+• **Per-Virtual-Server API Keys** - Scoped access control for individual virtual servers ([#282](https://github.com/IBM/mcp-context-forge/issues/282))
+
+• **Enhanced Session Management** - Secure session handling for Admin UI ([#541](https://github.com/IBM/mcp-context-forge/issues/541))
+
+• **CSRF Token Protection** - Cross-site request forgery prevention ([#543](https://github.com/IBM/mcp-context-forge/issues/543))
+
+### 🛡️ Authorization & Access Control
+
+• **Role-Based Access Control (RBAC)** - User/Team/Global scopes with private, team, and global catalog separation ([#283](https://github.com/IBM/mcp-context-forge/issues/283))
+
+• **Policy-as-Code Engine** - Rego-based policy enforcement for fine-grained authorization ([#271](https://github.com/IBM/mcp-context-forge/issues/271))
+
+• **IP-Based Access Control** - Configurable IP allowlisting for network-level security ([#536](https://github.com/IBM/mcp-context-forge/issues/536))
+
+• **Endpoint Feature Flags** - Selectively enable/disable tools, resources, prompts, servers, gateways ([#537](https://github.com/IBM/mcp-context-forge/issues/537))
+
+• **Resource-Level Access Control** - Virtual server composition with granular tool/resource visibility control
+
+### 🔒 Data Protection & Encryption
+
+• **Cryptographic Request Signing** - End-to-end request/response signing and verification ([#230](https://github.com/IBM/mcp-context-forge/issues/230))
+
+• **TLS/mTLS Support** - Certificate-based authentication with private CA support ([#568](https://github.com/IBM/mcp-context-forge/issues/568))
+
+• **Enterprise Secrets Management** - HashiCorp Vault integration for secure credential storage ([#542](https://github.com/IBM/mcp-context-forge/issues/542))
+
+• **Transport Layer Security** - Multiple secure protocols (SSE, WebSocket, HTTPS) with configurable TLS termination
+
+### 🚦 Input Validation & Sanitization
+
+• **Gateway-Level Input Validation** - Prevent path traversal and injection attacks ([#221](https://github.com/IBM/mcp-context-forge/issues/221))
+
+• **AI Guardrails & PII Masking** - Input/output sanitization with sensitive data detection ([#229](https://github.com/IBM/mcp-context-forge/issues/229))
+
+• **Content Size & Type Limits** - Security limits for resources and prompts ([#538](https://github.com/IBM/mcp-context-forge/issues/538))
+
+• **XSS Prevention** - DOMPurify integration and content sanitization ([#336](https://github.com/IBM/mcp-context-forge/issues/336), [#341](https://github.com/IBM/mcp-context-forge/issues/341), [#361](https://github.com/IBM/mcp-context-forge/issues/361))
+
+• **SQL Injection Prevention** - Database-level security constraints ([#342](https://github.com/IBM/mcp-context-forge/issues/342))
+
+### 🛠️ Plugin & Middleware Framework
+
+• **Pre/Post Request Hooks** - Extensible plugin system for custom security policies ([#319](https://github.com/IBM/mcp-context-forge/issues/319))
+
+• **AI Middleware Integration** - Framework for adding LLM-based security capabilities ([#313](https://github.com/IBM/mcp-context-forge/issues/313))
+
+• **Semantic Tool Filtering** - Intelligent auto-filtering of tools based on context ([#182](https://github.com/IBM/mcp-context-forge/issues/182))
+
+• **Dynamic Tool Generation** - LLM-powered tool creation with security controls ([#130](https://github.com/IBM/mcp-context-forge/issues/130))
+
+### 📊 Monitoring & Audit
+
+• **Comprehensive Audit Logging** - Database-backed audit trail for all operations ([#535](https://github.com/IBM/mcp-context-forge/issues/535))
+
+• **Structured JSON Logging** - Correlation IDs for request tracing ([#300](https://github.com/IBM/mcp-context-forge/issues/300))
+
+• **Dual Logging Support** - Console and file outputs with rotation policies ([#364](https://github.com/IBM/mcp-context-forge/issues/364))
+
+• **OpenTelemetry Integration** - OpenLLMetry for comprehensive observability ([#175](https://github.com/IBM/mcp-context-forge/issues/175))
+
+• **Prometheus Metrics** - Performance and security metrics instrumentation ([#218](https://github.com/IBM/mcp-context-forge/issues/218))
+
+### 🚨 Rate Limiting & DDoS Protection
+
+• **Gateway-Level Rate Limiting** - Configurable request throttling per client/endpoint ([#257](https://github.com/IBM/mcp-context-forge/issues/257))
+
+• **Tool Execution Limits** - Resource controls and execution boundaries ([#539](https://github.com/IBM/mcp-context-forge/issues/539))
+
+• **Circuit Breakers** - Automatic failover for unstable backends ([#301](https://github.com/IBM/mcp-context-forge/issues/301))
+
+• **Smart Retry Mechanisms** - Exponential backoff with jitter ([#258](https://github.com/IBM/mcp-context-forge/issues/258), [#456](https://github.com/IBM/mcp-context-forge/issues/456))
+
+### 🔍 Security Testing & Validation
+
+• **SAST/DAST Integration** - Semgrep and OWASP ZAP automated testing ([#259](https://github.com/IBM/mcp-context-forge/issues/259))
+
+• **Input Validation Test Suite** - Comprehensive security validation tests ([#552](https://github.com/IBM/mcp-context-forge/issues/552))
+
+• **Fuzz Testing** - Hypothesis, atheris, schemathesis, RESTler ([#256](https://github.com/IBM/mcp-context-forge/issues/256))
+
+• **Mutation Testing** - Test quality validation with mutmut ([#280](https://github.com/IBM/mcp-context-forge/issues/280))
+
+• **Security Scanners** - Bandit, grype, nodejsscan integration ([#279](https://github.com/IBM/mcp-context-forge/issues/279), [#415](https://github.com/IBM/mcp-context-forge/issues/415), [#499](https://github.com/IBM/mcp-context-forge/issues/499))
+
+### 🏗️ Infrastructure Security
+
+• **Zero-Trust Architecture** - Peer gateway health checks with automatic failover ([#424](https://github.com/IBM/mcp-context-forge/issues/424))
+
+• **Configuration Validation** - Schema enforcement with startup security checks ([#285](https://github.com/IBM/mcp-context-forge/issues/285), [#534](https://github.com/IBM/mcp-context-forge/issues/534))
+
+• **Security Headers** - Configurable headers and CORS policies ([#344](https://github.com/IBM/mcp-context-forge/issues/344), [#533](https://github.com/IBM/mcp-context-forge/issues/533))
+
+• **Well-Known URI Handler** - security.txt and robots.txt support ([#540](https://github.com/IBM/mcp-context-forge/issues/540))
+
+• **Password Policy Engine** - Configurable password and secret policies ([#426](https://github.com/IBM/mcp-context-forge/issues/426))
+
+• **Graceful Shutdown** - SIGTERM-safe rollouts with connection draining ([#217](https://github.com/IBM/mcp-context-forge/issues/217))
+
+## Multi-Layered Defense Strategy
+
+MCP Gateway implements a comprehensive, multi-layered security approach with "defense in depth" and "secure by design" principles:
+
+### Security Philosophy
+
+- **Proactive Security**: Security measures are built-in from design phase, not added retroactively
+- **Human + Automated**: Combines 30+ automated security tools with manual code reviews and threat modeling
+- **Continuous Improvement**: Regular updates to security toolchain and practices based on community feedback
+- **Shared Responsibility**: Security across all system components - gateway is one layer in your defense strategy
+
+### Comprehensive Security Pipeline
+
+**Pre-commit Security Gates**: 
+- Bandit, Semgrep, Dodgy for security scanning
+- Type checking and code quality enforcement
+- Run `make security-all` locally before pushing
+
+**Continuous Integration Security**: 
+- 30+ security scans on every PR
+- CodeQL semantic analysis
+- Gitleaks secret detection
+- Dependency vulnerability scanning
+- Container security assessment
+
+**Runtime Security**:
+- Monitoring and security policies
+- Anomaly detection
+- Incident response procedures
+
+## Security Compliance & Standards
+
+### 🏆 Currently Implemented (v0.4.0)
+
+• **Authentication**: JWT tokens with configurable secrets, Basic Auth support
+• **Input Validation**: Comprehensive validation across all API endpoints using Pydantic
+• **XSS Prevention**: Character restrictions, URL scheme validation, JSON depth limits
+• **Security Scanning**: 30+ security tools integrated, 100% Bandit pass rate
+• **Container Hardening**: Non-root execution, read-only filesystems, minimal base images
+• **Secure Defaults**: Admin UI disabled by default, localhost-only binding
+• **Secret Detection**: Gitleaks, Dodgy integration preventing credential leaks
+
+### 🚀 Upcoming Security Enhancements
+
+**Release 0.5.0 (August 2025)**
+- Enhanced authentication mechanisms
+- Configuration validation framework
+- Comprehensive audit logging
+- Security headers implementation
+
+**Release 0.6.0 (August 2025)**
+- Database-backed authentication
+- Multi-layer caching security
+- Circuit breakers implementation
+
+**Release 0.7.0 (September 2025)**
+- Full RBAC implementation
+- Multi-tenancy support
+- Correlation ID tracking
+
+**Release 0.8.0 (September 2025)**
+- Policy-as-Code engine
+- Advanced guardrails
+- DDoS protection
+
+**Release 0.9.0 (September 2025)**
+- Marketplace security
+- Protocol negotiation
+- Advanced connectivity
+
+**Release 1.0.0 (October 2025)**
+- Security audit completion
+- Production hardening
+- GA security certification
+
+## Production Deployment Security
+
+### ⚠️ Critical Production Requirements
+
+**The Admin UI is development-only and must NEVER be exposed in production**:
+- Designed for localhost-only access with trusted MCP servers
+- Single-user administration without access controls
+- Must be disabled in production: `MCPGATEWAY_UI_ENABLED=false`
+
+### 📋 Production Security Checklist
+
+- [ ] **Disable unused features** (`FEATURES_ROOTS_ENABLED=false`, `FEATURES_PROMPTS_ENABLED=false`, etc.)
+- [ ] **Disable Admin UI and API** (`MCPGATEWAY_UI_ENABLED=false`, `MCPGATEWAY_ADMIN_API_ENABLED=false`)
+- [ ] **Enable authentication** with strong passwords/keys and custom usernames
+- [ ] **Configure TLS/HTTPS** with valid certificates (never HTTP in production)
+- [ ] **Validate all MCP servers** before connecting
+- [ ] **Implement network controls** (firewalls, ingress policies)
+- [ ] **Set rate limits** per endpoint and client
+- [ ] **Configure monitoring** and anomaly detection
+- [ ] **Secure databases** (TLS, strong passwords, restricted access)
+- [ ] **Set resource limits** (CPU, memory) to prevent DoS
+- [ ] **Implement secrets management** (never hardcode credentials)
+- [ ] **Configure CORS policies** appropriately
+- [ ] **Disable debug mode** in production
+- [ ] **Keep gateway updated** to latest version
+- [ ] **Regular security audits** of connected servers
+
+## Security Best Practices
+
+### Gateway as One Layer in Defense-in-Depth
+
+MCP Gateway should be integrated as **one component** in a comprehensive security architecture:
+
+1. **Upstream validation**: Validate and trust all MCP servers before connection
+2. **Gateway validation**: Input/output validation at gateway level
+3. **Downstream validation**: Applications must implement their own security controls
+4. **Network isolation**: Use network policies to restrict access
+5. **Comprehensive monitoring**: Log and alert on suspicious activities
+
+### Integration Requirements
+
+MCP Gateway is **not a standalone product**. Integrate with:
+- API gateways/reverse proxies (auth, rate-limiting, routing)
+- Secrets management systems (Vault, SOPS)
+- Identity and access management (IAM) platforms
+- Logging, monitoring, and SIEM platforms
+- Runtime security and anomaly detection
+- Custom UI/orchestration layers for multi-tenancy
+
+### Developer Security Tools
+
+**Core Security Commands**:
+- `make security-all` - Run all security tools
+- `make security-report` - Generate security report
+- `make security-fix` - Auto-fix issues where possible
+- `make pre-commit` - Run pre-commit hooks locally
+- `make lint` - 30+ linting and security tools
+
+**Individual Security Scanners**:
+- `make bandit` - Python security vulnerabilities
+- `make semgrep` - Semantic code analysis
+- `make dodgy` - Hardcoded secrets detection
+- `make gitleaks` - Git history secrets scan
+- `make pip-audit` - Dependency vulnerabilities
+- `make trivy` - Container security scan
+- `make grype-scan` - Container vulnerability audit
+- `make osv-scan` - Open source vulnerability scan
+
+## Multi-Tenancy Considerations
+
+**MCP Gateway is not yet multi-tenant ready**. For multi-user platforms, implement:
+- User isolation and data segregation
+- Role-Based Access Control (RBAC)
+- Resource cleanup and lifecycle management
+- Tenant-specific validation and limits
+- Per-user audit logging
+- Team/organization management
+
+Deploy as a **single-tenant component** within your larger multi-tenant architecture.
+
+## Security Patching Policy
+
+**⚠️ Disclaimer**: All patching is **best-effort** with no SLAs or commercial support.
+
+- **Critical/High**: Best-effort patches within 1 week (minor version bump)
+- **Medium**: Addressed in next release (~2 weeks)
+- **Low**: Regular maintenance updates (~2-4 weeks)
+- **No backports**: Fixes only applied to latest main branch
+- **No zero-day guarantees**: Users must evaluate and mitigate risks
+
+## Security Contact
+
+For security vulnerabilities, report privately via [GitHub's security reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability):
+
+1. Navigate to Security tab
+2. Click "Report a vulnerability"
+3. Fill out the vulnerability details
+
+For more information, see our [Security Policy](https://github.com/IBM/mcp-context-forge/security/policy).