MCP Scanner

Version: 1.1.0
Date: 2025-01-XX

We're excited to announce MCP Gateway v1.1.0, introducing a comprehensive Security Scanner system that provides proactive protection against malicious and risky MCP servers!

🔍 New Feature: Advanced Security Scanner

MCP Gateway now includes a powerful security scanner that analyzes MCP servers for potential risks before they're loaded into your system, providing an additional layer of protection through multi-dimensional security analysis.

Key Capabilities:

• 🛡️ Reputation Analysis - Evaluates server reputation using marketplace (Smithery, NPM) and GitHub data with sophisticated scoring algorithms
• 🔍 Tool Description Scanning - Detects hidden instructions, sensitive file patterns, and malicious actions in tool descriptions using advanced pattern matching
• ⚡ Automatic Blocking - Blocks risky MCPs based on reputation scores (threshold: 30) and security analysis results
• 📝 Configuration Updates - Automatically updates your MCP configuration file with scan results and blocking status
• 🌐 Multi-Platform Support - Supports NPM registry and Smithery marketplace analysis with GitHub integration
• 📊 Comprehensive Logging - Detailed logging to ~/.mcp-gateway/scanner.log for audit and debugging purposes

🚀 Security Analysis Components

Reputation Scoring System

The scanner uses a sophisticated multi-factor scoring algorithm (0-100 scale) that evaluates:

GitHub Owner Metrics:

• Follower count and public repositories
• Account age and verification status
• Organization status and social presence
• Blog and Twitter verification

Repository Metrics:

• Stars and forks (logarithmic scaling)
• License compatibility (MIT, Apache-2.0, BSD-3-Clause, ISC)
• Repository age and activity

Marketplace Metrics:

• NPM: Download counts, version history, maintainer count, package age
• Smithery: Monthly tool usage, verification status, license information

Tool Description Analysis

Advanced pattern matching detects:

Hidden Instructions:

• Attempts to bypass security constraints
• Secret or confidential operation requests
• Instructions to hide actions from users

Sensitive File Patterns:

• Environment files (.env, config files)
• Authentication keys and certificates
• SSH keys and credential stores
• System configuration files

Malicious Actions:

• Shell command execution patterns
• Database manipulation attempts
• Network scanning and reconnaissance
• Privilege escalation attempts
• Data exfiltration patterns

🔧 Configuration Management

The scanner automatically updates your MCP configuration with blocking statuses:

Status Values:

• "passed" - Server passed all security checks and is safe to use
• "blocked" - Server failed security checks and will be blocked from loading
• "skipped" - Server scanning was skipped (manual override)
• null - Server not yet scanned or previously blocked server now considered safe

Before scanning:

{
    "mcpServers": {
        "mcp-gateway": {
            "command": "mcp-gateway",
            "args": ["--mcp-json-path", "~/.cursor/mcp.json", "--scan"],
            "servers": {
                "filesystem": {
                    "command": "npx",
                    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
                }
            }
        }
    }
}

After scanning:

{
    "mcpServers": {
        "mcp-gateway": {
            "command": "mcp-gateway",
            "args": ["--mcp-json-path", "~/.cursor/mcp.json", "--scan"],
            "servers": {
                "filesystem": {
                    "command": "npx",
                    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
                    "blocked": "passed"
                }
            }
        }
    }
}

🚀 Getting Started

1. Enable the scanner:

   mcp-gateway --mcp-json-path ~/.cursor/mcp.json --scan

2. With additional plugins:

   mcp-gateway --mcp-json-path ~/.cursor/mcp.json --scan -p basic -p lasso

3. Docker configuration:

   {
       "mcpServers": {
           "mcp-gateway": {
               "command": "docker",
               "args": [
                   "run", "--rm",
                   "--mount", "type=bind,source=/path/to/config,target=/app",
                   "-i",
                   "-v", "/Users/user/.cursor/mcp.json:/config/mcp.json:ro",
                   "mcp/gateway:latest",
                   "--mcp-json-path", "/config/mcp.json",
                   "--scan",
                   "--plugin", "basic"
               ],
               "servers": {
                   "filesystem": {
                       "command": "npx",
                       "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
                   }
               }
           }
       }
   }

📊 Logging and Monitoring

The scanner provides comprehensive logging:

• Location: ~/.mcp-gateway/scanner.log
• Components: Reputation scores, tool analysis results, blocking decisions
• Format: Structured logging with timestamps and component names
• Debugging: Enable with LOGLEVEL=DEBUG mcp-gateway --scan

Example log output:

2025-01-XX 10:30:45 - scanner - INFO - MCP filesystem reputation score: 85.2
2025-01-XX 10:30:45 - scanner - INFO - MCP filesystem is safe with score 85.2
2025-01-XX 10:30:45 - scanner - INFO - MCP SERVER 'filesystem' is safe.

🔧 Manual Override

You can manually override scanner decisions by changing the blocked status:

{
    "blocked": "skipped"  // Manually skip scanning for this server
}

🛠️ Technical Architecture

Data Collectors

• NPMCollector: Fetches package metadata from npm registry and downloads API
• SmitheryFetcher: Scrapes Smithery marketplace using BeautifulSoup
• GithubFetcher: Retrieves repository and owner data via GitHub API

Analysis Engine

• ProjectAnalyzer: Calculates weighted reputation scores using logarithmic scaling
• ToolAnalyzer: Performs regex-based pattern matching on tool descriptions
• Scanner: Orchestrates the entire scanning process and config updates

Configuration Constants

• Scoring Thresholds: Configurable reputation score limits (default: 30)
• Pattern Libraries: Comprehensive regex patterns for threat detection
• Marketplace Support: Extensible architecture for additional marketplaces

🔒 Security Benefits

• Proactive Protection: Blocks malicious servers before they can execute
• Multi-Vector Analysis: Combines reputation, behavioral, and content analysis
• Transparent Operations: Detailed logging and clear blocking reasons
• Manual Control: Override capabilities for trusted but low-scoring servers
• Continuous Updates: Automatic re-evaluation of previously blocked servers

What's Changed

• Feat: Advanced Security Scanner with reputation analysis by @barlanyado in #6
• Feat: Tool description analysis for malicious pattern detection by @barlanyado in #6
• Feat: Multi-marketplace support (NPM, Smithery, GitHub) by @barlanyado in #6
• Feat: Automatic configuration file updates with scan results by @barlanyado in #6
• Feat: Comprehensive logging system for scanner operations by @barlanyado in #6
• Enhancement: Sophisticated scoring algorithms with logarithmic scaling by @barlanyado in #6
• Enhancement: Pattern matching for hidden instructions and sensitive actions by @barlanyado in #6
• Enhancement: Docker support for scanner operations by @barlanyado in #6
• Docs: Updated README with scanner configuration examples by @barlanyado in #6
• Docs: Added comprehensive scanner documentation by @barlanyado in #6

New Contributors

• @barlanyado made their first contribution in #6

🚧 Important Notes

• Performance: Initial scan may take longer as it fetches data from multiple sources
• Rate Limits: Respects GitHub and NPM API rate limits with appropriate timeouts
• Manual Review: Low-scoring legitimate servers can be manually overridden
• Continuous Improvement: Pattern libraries and scoring algorithms are regularly updated

The Security Scanner represents a significant step forward in MCP security, providing enterprise-grade protection while maintaining ease of use and transparency.