convez.ai
MCP ServerSegurançaIntermediário
starman69

MCP Sanitizer

starman69/mcp-sanitizer

Sanitização de segurança robusta para servidores MCP com defesa em profundidade

Ver no GitHub
BomPluginScore · de 0 a 100

Biblioteca de sanitização de segurança abrangente para servidores MCP que previne vetores de ataque comuns como injeção de comando, SQL injection, traversal de diretório e execução de código. Oferece proteção em múltiplas camadas com políticas de segurança pré-configuradas (STRICT, MODERATE, PERMISSIVE, DEVELOPMENT, PRODUCTION) e integração com frameworks populares como Express, Fastify e Koa.

Instalação

$npx convez-ai starman69/mcp-sanitizer

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
1
Saúde
71%
Último commit
há 2 dias
Versão
v1.4.4
Issues abertas
1
Contribuidores
1

Casos de uso

  • Proteger MCP servers contra injeção de SQL e command injection
  • Validar entrada de usuário em aplicações críticas de segurança
  • Implementar políticas de sanitização customizadas por ambiente (dev, prod)
  • Detectar e bloquear tentativas de traversal de diretório e homoglyph attacks

Veredito

Solução sólida e bem-testada (1100+ testes) para hardening de MCP servers. Defesa-em-profundidade com suporte a múltiplas políticas de segurança é prático, mas requer integração deliberada em cada endpoint — não é aplicado automaticamente a todo tráfego.

README

A tradução para o português deste README ainda está na fila.

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.

npm version License: MIT Security Tests

🔒 Security Features

MCP Sanitizer provides comprehensive, defense-in-depth protection:

  • ✅ Multi-layered Protection: Command injection, SQL injection, XSS, NoSQL injection, path traversal
  • ✅ Advanced Unicode Defense: Homograph detection, multi-pass normalization, zero-width removal
  • ✅ Context-aware Validation: Specialized rules for file paths, URLs, commands, and SQL queries
  • ✅ Database-specific SQL Protection: PostgreSQL, MySQL, MSSQL, Oracle validation and escaping
  • ✅ Framework Integration: Express, Fastify, and Koa middleware with skipPaths support
  • ✅ Security Policies: Pre-configured policies (STRICT, MODERATE, PERMISSIVE, DEVELOPMENT, PRODUCTION)
  • ✅ Comprehensive Validation: Checking 42+ attack vectors across 12 validation layers in <1ms
  • ✅ Comprehensive Testing: 1114 tests with 93% code coverage, sub-millisecond performance

Security Philosophy

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

  • No security solution is 100% bulletproof against unknown threats
  • Zero-day vulnerabilities may emerge in the future
  • Defense-in-depth is essential (use multiple security layers)
  • Regular updates are crucial for evolving threat landscape

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

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:

PolicyUse CaseString LimitProtocolsBlocking Level
STRICTHigh-security, untrusted input1,000 charsHTTPS onlyMedium+
MODERATEBalanced production security5,000 charsHTTP, HTTPS, MCPHigh+
PERMISSIVETrusted environments50,000 charsHTTP, HTTPS, FTP, MCP, FileCritical only
DEVELOPMENTDevelopment with debugging20,000 charsHTTP, HTTPS, MCP, FileHigh+
PRODUCTIONProduction environments8,000 charsHTTPS, MCPHigh+
// Use a security policy
const sanitizer = new MCPSanitizer('PRODUCTION');

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

Framework Middleware

Express.js

const express = require('express');
const { createExpressMiddleware } = require('mcp-sanitizer/middleware/express');

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

// Apply middleware with defaults
app.use(createExpressMiddleware());

// Or specify configuration
app.use(createExpressMiddleware({
  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 mcpSanitizerPlugin = require('mcp-sanitizer/middleware/fastify');

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

Koa

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

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 - Relative path escapes, absolute system paths, UNC paths
  • Command Injection - Shell metacharacters, chained commands, pipe redirection
  • SQL Injection - Union-based, boolean-based, time-based, stacked queries, comment injection
  • Prototype Pollution - Proto/constructor manipulation, deep property injection
  • Template Injection - Server-side template engines, JNDI lookups, expression languages
  • Code Execution - Dynamic evaluation, module loading, function constructors

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:

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

  • Sub-millisecond Validation: <1ms average latency for complete validation (12 layers checking 40+ attack vectors)
  • High Throughput: 7,500+ operations/second average, scales linearly with CPU cores
  • Industry-Leading Libraries: escape-html (31M ops/sec), sqlstring (44M ops/sec), shell-quote (2.5M ops/sec)
  • Production Ready: Sub-millisecond response times enable real-time validation without user-perceivable delays
  • Memory Efficient: Configurable limits prevent exhaustion (<100MB under attack, typical usage <60MB)
  • Zero Overhead: No artificial delays, pure validation logic only
  • Scalable: Stateless design allows horizontal scaling across multiple cores/instances

Performance Metrics

MetricValueDetails
Average Latency<1ms0.447ms - 0.84ms depending on input complexity
Throughput7,500+ ops/secPer CPU core, scales linearly
Attack Detection0.28ms - 2.39msAll 42 attack vectors blocked
Memory Usage<60MB typical<100MB maximum under stress
CPU EfficiencyOptimizedNo busy-wait loops, pure validation

Validation Layers: Command injection, SQL injection (4 databases), NoSQL injection, XSS, path traversal, prototype pollution, template injection, Unicode normalization (4 passes), multi-layer encoding detection, file extension validation, protocol validation

Optimization Options: Use skipPaths middleware to exempt low-risk routes (health checks, static assets, metrics endpoints)

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');
}

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

🛡️ Run Security Benchmarks

Run comprehensive security benchmarks to validate protection:

# Quick demo (10 attack vectors + performance test)
node benchmark/quick-demo.js

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

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

Expected Results:

  • All 42 attack vectors blocked (100%)
  • Average latency: <1ms
  • Throughput: 7,500+ ops/sec
  • Memory usage: <60MB

🔒 Security Testing Coverage

CategoryCoverage
XSS VectorsDOM-based, attribute injection, polyglots
SQL InjectionAll major databases, blind/time-based, bypass techniques
Command InjectionShell metacharacters, environment vars, process substitution
Path TraversalDirectory traversal, absolute paths, UNC
ReDoS ProtectionPolynomial backtracking, timeout guards
Prototype Pollution__proto__, constructor, prototype, encoding bypass
Memory SafetyBounded memory usage under attack

🎯 Security Best Practices

  1. ✅ Use STRICT or PRODUCTION policy for untrusted input
  2. ✅ Update regularly for latest security patches
  3. ✅ Monitor blocked attempts in production for security insights
  4. ✅ Implement defense-in-depth - multiple security layers
  5. ✅ Test with your attack vectors using provided benchmarks
  6. ✅ Enable rate limiting at infrastructure layer

📝 Security Resources

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


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

Ver o original no GitHub

Bom para

Relacionados