mcp-wordpress 1.5.2 → 2.0.0

package/docs/SECURITY.md

@@ -0,0 +1,621 @@
+# 🔒 Security Guide
+
+**Comprehensive security guide for MCP WordPress Server deployment and operation.**
+
+## Table of Contents
+
+- [Security Overview](#security-overview)
+- [Authentication Security](#authentication-security)
+- [Input Validation & Sanitization](#input-validation--sanitization)
+- [Network Security](#network-security)
+- [Data Protection](#data-protection)
+- [Security Testing](#security-testing)
+- [Production Deployment](#secure-deployment)
+- [Incident Response](#incident-response)
+
+## Security Overview
+
+The MCP WordPress Server is designed with security as a core principle. This guide covers security best practices,
+threat mitigation, and compliance requirements.
+
+### Security Posture
+
+- **✅ 40/40 Security Tests Passing** - Comprehensive security validation
+- **✅ Input Validation** - All inputs validated and sanitized with edge case handling
+- **✅ XSS Protection** - Cross-site scripting prevention with content sanitization
+- **✅ SQL Injection Prevention** - Database attack protection with parameterized queries
+- **✅ Path Traversal Protection** - File system security with directory restrictions
+- **✅ Rate Limiting** - DoS protection with configurable thresholds
+- **✅ Credential Security** - Secure authentication handling with encryption
+
+### Security Architecture
+
+```text
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   AI Client     │    │   MCP Server    │    │   WordPress     │
+│   (Claude)      │◄──►│   (This App)    │◄──►│   REST API      │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │ Security Layer  │
+                    │ - Validation    │
+                    │ - Sanitization  │
+                    │ - Rate Limiting │
+                    │ - Audit Log     │
+                    └─────────────────┘
+```
+
+### Threat Model
+
+**Protected Against:**
+
+- ✅ **Injection Attacks** - SQL, NoSQL, Command injection
+- ✅ **Cross-Site Scripting (XSS)** - Reflected, stored, DOM-based
+- ✅ **Path Traversal** - Directory traversal, file inclusion
+- ✅ **Authentication Bypass** - Session hijacking, credential stuffing
+- ✅ **Denial of Service** - Request flooding, resource exhaustion
+- ✅ **Data Exposure** - Sensitive information leakage
+- ✅ **Authorization Flaws** - Privilege escalation, access control bypass
+
+## Authentication Security
+
+### WordPress Application Passwords (Recommended)
+
+**Benefits:**
+
+- ✅ Revocable without changing main password
+- ✅ Scoped to specific applications
+- ✅ Audit trail and access logging
+- ✅ WordPress native security features
+
+**Security Implementation:**
+
+```bash
+# Create dedicated MCP user with minimal permissions
+# Use unique application password name
+# Regenerate passwords regularly
+```
+
+**Best Practices:**
+
+1. **Dedicated User Account**: Create specific user for MCP access
+2. **Minimal Permissions**: Grant only required WordPress capabilities
+3. **Regular Rotation**: Change passwords every 90 days
+4. **Unique Names**: Use descriptive application password names
+5. **Monitor Access**: Review authentication logs regularly
+
+### Authentication Methods Comparison
+
+| Method | Security Level | Production Ready | Use Case |
+|--------|----------------|------------------|----------|
+| **Application Password** | 🟢 High | ✅ Yes | Recommended for all environments |
+| **JWT** | 🟡 Medium | ⚠️ With proper setup | API-heavy applications |
+| **Basic Auth** | 🔴 Low | ❌ No | Development only |
+| **API Key** | 🟡 Medium | ⚠️ Plugin dependent | Plugin-based authentication |
+
+## Input Validation & Sanitization
+
+### Enhanced Validation System
+
+The MCP WordPress Server implements **multi-layer validation** with comprehensive edge case handling:
+
+#### 1. Type & Format Validation
+
+```typescript
+// Enhanced ID validation with edge cases
+validateId(id, "post ID");
+// Handles: null, undefined, strings, decimals, negatives, overflow
+
+// URL validation with security checks
+validateUrl(url, "site URL");
+// Validates: protocol, hostname, port, localhost restrictions
+
+// Username validation with security filtering
+validateUsername(username);
+// Checks: length, characters, reserved names, consecutive spaces
+```
+
+#### 2. Content Sanitization
+
+```typescript
+// HTML content sanitization
+sanitizeHtml(content);
+// Removes: <script>, event handlers, javascript:, dangerous patterns
+
+// Search query sanitization
+validateSearchQuery(query);
+// Filters: SQL patterns, XSS attempts, control characters
+```
+
+#### 3. Complex Parameter Validation
+
+```typescript
+// Post creation with contextual validation
+validatePostParams({
+  title: "My Post",           // Required, sanitized
+  content: "<p>Safe HTML</p>", // XSS protection
+  status: "future",           // Valid status
+  date: "2024-01-01T10:00:00", // Required for future posts
+  categories: [1, 2, 3]       // Valid category IDs
+});
+
+// Pagination with conflict detection
+validatePaginationParams({
+  page: 1,
+  per_page: 10,
+  offset: 20  // ERROR: Cannot use page and offset together
+});
+```
+
+#### 4. Security Patterns Protection
+
+**XSS Prevention:**
+
+```typescript
+// Content filtering
+const dangerousPatterns = [
+  /<script[^>]*>[\s\S]*?<\/script>/gi,
+  /<iframe[^>]*>/gi,
+  /javascript:/gi,
+  /on\w+\s*=/gi  // Event handlers
+];
+```
+
+**SQL Injection Prevention:**
+
+```typescript
+// Query sanitization
+sanitized = sanitized.replace(
+  /(\b(union|select|insert|update|delete|drop|create)\b)/gi,
+  ""
+);
+```
+
+**Path Traversal Prevention:**
+
+```typescript
+// File path validation
+if (path.includes("..") || path.includes("~")) {
+  throw new Error("Directory traversal not allowed");
+}
+```
+
+### Content Security Policies
+
+#### WordPress Content Validation
+
+- HTML content sanitization
+- Media file type validation
+- URL format verification
+- Email address validation
+- WordPress ID validation
+
+#### File Upload Security
+
+- Extension whitelist enforcement
+- MIME type validation
+- File size limitations
+- Virus scanning integration points
+
+## Network Security
+
+### HTTPS Requirements
+
+**Production Deployment:**
+
+```bash
+# Always use HTTPS in production
+WORDPRESS_SITE_URL=https://your-site.com  # ✅ Secure
+WORDPRESS_SITE_URL=http://your-site.com   # ❌ Insecure
+```
+
+**Development Exceptions:**
+
+```bash
+# HTTP acceptable for localhost only
+WORDPRESS_SITE_URL=http://localhost:8080  # ✅ OK for development
+```
+
+### Rate Limiting
+
+**Default Protection:**
+
+```bash
+# Built-in rate limiting
+RATE_LIMIT_REQUESTS=1000    # 1000 requests
+RATE_LIMIT_WINDOW=60000     # per minute (60 seconds)
+```
+
+**Aggressive Protection:**
+
+```bash
+# High-security environments
+RATE_LIMIT_REQUESTS=100     # 100 requests
+RATE_LIMIT_WINDOW=60000     # per minute
+```
+
+### Network Access Control
+
+#### Docker Deployment
+
+```yaml
+# Restrict network access
+services:
+  mcp-wordpress:
+    networks:
+      - internal-network
+    # Don't expose ports directly to host
+```
+
+#### Firewall Configuration
+
+```bash
+# Allow only necessary ports
+# Port 80/443 for WordPress API access
+# Internal ports for MCP communication only
+```
+
+## Credential Management
+
+### Environment Variables Security
+
+**✅ Secure Practices:**
+
+```bash
+# Use environment variables for credentials
+WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
+
+# Never hardcode credentials in code
+# Use .env files for development
+# Use secrets management for production
+```
+
+**❌ Insecure Practices:**
+
+```javascript
+// Never do this
+const password = "my-password";
+const config = { password: "hardcoded-password" };
+```
+
+### File Permissions
+
+**Configuration Files:**
+
+```bash
+# Secure file permissions
+chmod 600 .env
+chmod 600 mcp-wordpress.config.json
+chown app:app .env
+
+# Verify permissions
+ls -la .env
+# Should show: -rw------- 1 app app
+```
+
+### Git Security
+
+**Exclude Sensitive Files:**
+
+```gitignore
+# .gitignore - Always exclude
+.env
+.env.*
+mcp-wordpress.config.json
+claude_desktop_config.json
+```
+
+**Credential Scanning:**
+
+```bash
+# Use tools to scan for committed secrets
+git-secrets --scan
+truffleHog --regex --entropy=False .
+```
+
+## Docker Security
+
+### Container Security
+
+**Base Image Security:**
+
+```dockerfile
+# Use official, minimal base images
+FROM node:18-alpine
+
+# Run as non-root user
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nextjs -u 1001
+USER nextjs
+```
+
+**Runtime Security:**
+
+```bash
+# Run container with security restrictions
+docker run \
+  --user 1001:1001 \
+  --read-only \
+  --tmpfs /tmp \
+  --cap-drop ALL \
+  docdyhr/mcp-wordpress:latest
+```
+
+### Secrets Management
+
+**Docker Secrets:**
+
+```yaml
+# docker-compose.yml
+services:
+  mcp-wordpress:
+    secrets:
+      - wordpress_password
+secrets:
+  wordpress_password:
+    external: true
+```
+
+**Environment Variables:**
+
+```bash
+# Use external secret management
+docker run \
+  --env-file <(vault kv get -field=env secret/mcp-wordpress) \
+  docdyhr/mcp-wordpress:latest
+```
+
+## Security Monitoring
+
+### Audit Logging
+
+**Enable Comprehensive Logging:**
+
+```bash
+# Production logging configuration
+NODE_ENV=production
+LOG_LEVEL=warn
+AUDIT_LOG_ENABLED=true
+SECURITY_LOG_ENABLED=true
+```
+
+**Log Analysis:**
+
+```bash
+# Monitor authentication failures
+grep "Authentication failed" /var/log/mcp-wordpress.log
+
+# Monitor rate limiting
+grep "Rate limit exceeded" /var/log/mcp-wordpress.log
+
+# Monitor security validation failures
+grep "Security validation failed" /var/log/mcp-wordpress.log
+```
+
+### Security Metrics
+
+**Key Metrics to Monitor:**
+
+- Authentication failure rate
+- Rate limiting triggers
+- Invalid input attempts
+- Error response patterns
+- Connection source analysis
+
+### Alerting
+
+**Critical Security Events:**
+
+```bash
+# Set up alerts for:
+# - Multiple authentication failures
+# - Rate limiting exceeded
+# - Security validation failures
+# - Unusual access patterns
+# - Error rate spikes
+```
+
+## Incident Response
+
+### Security Incident Checklist
+
+1. **Immediate Response**
+   - Disable affected accounts
+   - Rotate compromised credentials
+   - Enable additional logging
+   - Document incident timeline
+
+2. **Investigation**
+   - Analyze access logs
+   - Check WordPress audit logs
+   - Review security monitoring
+   - Identify attack vectors
+
+3. **Remediation**
+   - Patch vulnerabilities
+   - Update credentials
+   - Strengthen security controls
+   - Update monitoring rules
+
+4. **Recovery**
+   - Verify system integrity
+   - Test security controls
+   - Update documentation
+   - Conduct lessons learned
+
+### Emergency Procedures
+
+**Credential Compromise:**
+
+```bash
+# 1. Immediately revoke WordPress application passwords
+# 2. Generate new application passwords
+# 3. Update MCP server configuration
+# 4. Restart MCP server
+# 5. Monitor for continued unauthorized access
+```
+
+**System Compromise:**
+
+```bash
+# 1. Isolate affected systems
+# 2. Preserve evidence
+# 3. Analyze attack vectors
+# 4. Rebuild from clean backups
+# 5. Implement additional security controls
+```
+
+## Secure Deployment
+
+### Production Checklist
+
+**Pre-Deployment:**
+
+- [ ] All credentials use Application Passwords
+- [ ] HTTPS configured and enforced
+- [ ] Rate limiting enabled
+- [ ] Input validation enabled
+- [ ] Security logging enabled
+- [ ] File permissions configured
+- [ ] Network access restricted
+
+**WordPress Security:**
+
+- [ ] WordPress core updated
+- [ ] Security plugins installed
+- [ ] User permissions audited
+- [ ] Application passwords rotated
+- [ ] Admin accounts secured
+- [ ] REST API access controlled
+
+**Infrastructure Security:**
+
+- [ ] Firewall configured
+- [ ] SSL certificates valid
+- [ ] Docker containers hardened
+- [ ] Secrets management deployed
+- [ ] Monitoring configured
+- [ ] Backup system secured
+
+### Security Updates
+
+**Update Schedule:**
+
+- **Critical Security Updates**: Immediate
+- **Security Patches**: Within 7 days
+- **Regular Updates**: Monthly
+- **Dependency Updates**: Bi-weekly
+
+**Update Process:**
+
+1. Review security advisories
+2. Test updates in staging
+3. Schedule maintenance window
+4. Deploy with rollback plan
+5. Verify security controls
+6. Update documentation
+
+## Compliance
+
+### Security Standards
+
+**Supported Standards:**
+
+- OWASP Top 10 compliance
+- WordPress security best practices
+- Docker security benchmarks
+- Node.js security guidelines
+
+### Data Protection
+
+**WordPress Data Handling:**
+
+- Minimal data collection
+- Encrypted data transmission
+- Secure credential storage
+- Access logging
+- Data retention policies
+
+### Privacy Considerations
+
+**User Data:**
+
+- Authentication data encrypted
+- No persistent storage of credentials
+- Audit trail maintained
+- Access controls enforced
+
+## Security Testing
+
+### Automated Testing
+
+**Test Suite Coverage:**
+
+```bash
+# Run security tests
+npm run test:security
+
+# Specific security validations
+npm run test:security:validation
+npm run test:security:penetration
+
+# Results: 40/40 security tests passing
+```
+
+### Manual Testing
+
+**Security Validation:**
+
+1. **Authentication Testing**
+   - Invalid credential handling
+   - Brute force protection
+   - Session management
+
+2. **Input Validation Testing**
+   - XSS prevention
+   - SQL injection protection
+   - Path traversal prevention
+
+3. **Network Security Testing**
+   - HTTPS enforcement
+   - Rate limiting effectiveness
+   - Access control validation
+
+### Penetration Testing
+
+**Regular Security Assessments:**
+
+- Quarterly penetration testing
+- Annual security audits
+- Continuous vulnerability scanning
+- Bug bounty program consideration
+
+## Security Support
+
+### Reporting Security Issues
+
+**Security Contact:**
+
+- Email: [Create security email]
+- GPG Key: [Provide GPG key for encrypted communication]
+- Response Time: 24 hours for critical issues
+
+**Disclosure Policy:**
+
+- Responsible disclosure encouraged
+- 90-day disclosure timeline
+- Security credit provided
+- Bug bounty consideration
+
+### Security Resources
+
+- **[OWASP WordPress Security](https://owasp.org/www-project-wordpress-security/)**
+- **[WordPress Security Handbook](https://developer.wordpress.org/plugins/security/)**
+- **[Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)**
+- **[Docker Security](https://docs.docker.com/engine/security/)**
+
+---
+
+**Security Concern?** [Report a security issue](mailto:security@example.com) or
+[open a confidential issue](https://github.com/docdyhr/mcp-wordpress/security/advisories/new).