Add v0.6.0: Security Validation System

[KeshavVarad]

Summary

Implements comprehensive security validation for MCP server manifests with clear warnings about limitations. This adds the ability to automatically check manifests for common security vulnerabilities before deployment.

⚠️ Important Security Context

This validator is designed to catch obvious security issues in manifest structure but should NOT be considered a complete security solution. It is intended as ONE LAYER in a defense-in-depth security strategy.

What This Validator DOES:

✅ Detects dangerous operation names (delete, execute, admin, etc.)
✅ Identifies missing input validation (unbounded strings, unconstrained objects)
✅ Flags potential injection vulnerabilities (SQL, command, path traversal)
✅ Detects SSRF risks and sensitive data exposure
✅ Assesses overall risk with CWE mapping

What This Validator CANNOT Do:

❌ Detect malicious code in server implementation
❌ Verify authentication/authorization is properly enforced
❌ Detect business logic flaws or runtime vulnerabilities
❌ Prevent supply chain attacks or sophisticated exploits

Features Added

🔒 Security Validation Module

• ManifestValidator class for static analysis of MCP manifests
• Risk-based scoring: CRITICAL, HIGH, MEDIUM, LOW, INFO levels
• CWE ID mapping for industry-standard vulnerability classification
• Context-aware detection to minimize false positives

🛠️ CLI Integration

New mcp validate command with multiple options:

# Validate from file
mcp validate manifest.json

# Generate and validate from app
mcp validate --app server.py

# CI/CD integration with fail thresholds
mcp validate manifest.json --fail-on high

# JSON output for automation
mcp validate manifest.json --json

📚 Examples & Documentation

• 3 complete example servers in examples/security_validation/:

  • secure_server.py - Demonstrates security best practices
  • insecure_server.py - Shows vulnerabilities (educational, marked "DO NOT USE")
  • validate_custom.py - Custom validation script for CI/CD pipelines

• Comprehensive documentation with:

  • Security warnings prominently displayed
  • Clear explanation of validator limitations
  • Defense-in-depth best practices
  • CI/CD integration examples

🧪 Test Coverage

• 31 new test cases for security validation (100% passing)
• 394 total tests across entire project (all passing)
• Covers all vulnerability types, risk scoring, and real-world scenarios

Security Checks Implemented

Category	Detection	Risk Level
Dangerous Operations	delete, execute, admin, sudo, etc.	HIGH
Input Validation	Unbounded strings, unconstrained objects	MEDIUM
Path Traversal	Unvalidated file/path parameters	CRITICAL
SQL Injection	SQL query parameters (context-aware)	CRITICAL
Command Injection	Command execution parameters	CRITICAL
SSRF	Unvalidated URL parameters	HIGH
Sensitive Data	Password, token, secret mentions	HIGH
Attack Surface	Large number of exposed tools	MEDIUM

Design Decisions

1. Static Analysis Only - Focuses on manifest structure (Tier 1 MVP approach)
2. Context-Aware - SQL injection detection only flags "query" when SQL-related
3. Enum Recognition - Recognizes enum constraints as valid bounds
4. Explicit Limitations - Prominent warnings about what validator cannot do
5. Defense-in-Depth - Designed as one layer in comprehensive security strategy

Files Changed

Core Implementation

• nextmcp/security/__init__.py - Module exports with security warnings
• nextmcp/security/validation.py - Core validator (850+ lines)
• nextmcp/cli.py - Enhanced with mcp validate command

Tests

• tests/test_security_validation.py - 31 comprehensive test cases

Examples

• examples/security_validation/README.md - Complete guide
• examples/security_validation/secure_server.py - Best practices example
• examples/security_validation/insecure_server.py - Vulnerability examples
• examples/security_validation/validate_custom.py - CI/CD integration

Documentation

• README.md - Updated with security validation section and warnings

Testing

All 394 tests pass, including:

• Structure validation tests
• Risk assessment tests for all vulnerability types
• Edge case handling
• Real-world scenario testing
• JSON string parsing
• File validation

Example Output

$ mcp validate examples/security_validation/insecure_manifest.json

⚠️  SECURITY VALIDATION REPORT

📊 Overall Risk: CRITICAL (score: 85/100)

🔴 CRITICAL Issues (3):
  • Unvalidated file path parameter: file_path
  • Potential SQL injection: query
  • Potential command injection: command

🟠 HIGH Issues (2):
  • Dangerous operation detected: execute_command
  • Potential sensitive data handling: password

💡 Run with --json for detailed report suitable for CI/CD integration

Breaking Changes

None - This is a new feature with no impact on existing functionality.

Migration Guide

N/A - This is a new opt-in feature.

Checklist

• All tests passing (394/394)
• Code formatted with black
• Linting passed with ruff
• Documentation updated
• Examples provided
• Security warnings prominently displayed
• Pre-commit hooks passing

Related Issues

Addresses user request for manifest security validation capabilities.

---

🤖 Generated with Claude Code