Leak Secure MCP Server

Copyright 2025 Chris Bunting [email protected]

Enterprise-grade MCP (Model Context Protocol) server for detecting secrets and sensitive information in code repositories. This server provides AI agents with powerful tools to scan GitHub repositories and code snippets for over 35 types of secrets, including API keys, passwords, tokens, and credentials.

Features

• 35+ Secret Types Detection: Comprehensive pattern matching for AWS keys, GitHub tokens, database credentials, API keys, private keys, and more
• GitHub Integration: Scan entire repositories or specific paths with automatic file traversal
• Security Analysis: Risk scoring, compliance status, and detailed remediation recommendations
• Enterprise-Grade Architecture: Production-ready with enterprise-level reliability and security
• MCP Protocol: Standardized interface for AI agents to interact with security scanning tools

Enterprise-Grade Features

• Rate Limiting: Token bucket algorithm for GitHub API calls with configurable limits (default: 5000/hour, burst: 100)
• Retry Logic: Exponential backoff with jitter for automatic retry of failed requests (configurable: 3 retries, 1s-30s delays)
• Circuit Breaker: Prevents cascading failures with automatic recovery detection (CLOSED/OPEN/HALF_OPEN states)
• Timeout Handling: Configurable timeouts for API requests (30s) and scan operations (5 minutes)
• Input Validation: Zod-based schema validation for all tool inputs with sanitization
• Structured Logging: Enterprise logging system with automatic secret sanitization and log levels
• Error Handling: Custom error types with operational vs programming error distinction
• Memory Efficiency: Batch processing, file size limits, and maximum file count protection
• Graceful Shutdown: Handles SIGTERM/SIGINT with proper cleanup and operation completion
• Enhanced Security: Advanced secret masking, input sanitization, and secure error messages

Supported Secret Types

The server detects secrets across multiple categories:

• Cloud Provider: AWS, Google Cloud, Azure credentials
• Version Control: GitHub tokens, OAuth tokens
• Database: PostgreSQL, MySQL, MongoDB connection strings
• Payment: Stripe, PayPal API keys
• Communication: Twilio, SendGrid, Mailgun, Slack tokens
• Social Media: Twitter, Facebook API keys
• Cryptography: RSA, SSH, ECDSA private keys
• Authentication: JWT tokens, OAuth tokens, access tokens
• Generic: API keys, secrets, passwords

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn
• GitHub Personal Access Token (optional, for private repositories)

Install from npm (Recommended)

Install the package globally or locally:

# Global installation
npm install -g leak-secure-mcp

# Or local installation
npm install leak-secure-mcp

The setup script will automatically run after installation and prompt you for your GitHub Personal Access Token. You can:

• Enter your token when prompted (recommended)
• Press Enter to skip and configure it later
• Run npm run setup manually at any time to configure or update your token

Install from Source

1. Clone the repository:

git clone <repository-url>
cd leak-secure-mcp

2. Install dependencies:

npm install

The setup script will automatically run after installation and prompt you for your GitHub Personal Access Token.

3. Build the project:

npm run build

Usage

Running the Server

The MCP server runs on stdio and communicates via the Model Context Protocol:

npm start

For development with auto-reload:

npm run dev

MCP Tools

The server provides the following tools:

1. scan_repository

Scan a GitHub repository for secrets with enterprise-grade reliability features including rate limiting, retry logic, and circuit breaker protection.

Parameters:

• owner (required): GitHub repository owner (username or organization) - validated and sanitized
• repo (required): Repository name - validated and sanitized
• branch (optional): Branch to scan (default: "main") - validated format
• path (optional): Specific path within repository to scan

Features:

• Automatic rate limiting to respect GitHub API limits
• Retry logic with exponential backoff for transient failures
• Circuit breaker protection against cascading failures
• Batch processing for memory efficiency (50 files per batch)
• Timeout protection (5 minute default)
• Maximum file limit protection (10,000 files default)

Example:

{
  "owner": "octocat",
  "repo": "Hello-World",
  "branch": "main"
}

2. scan_code

Scan a code snippet or file content for secrets with enhanced validation and false positive reduction.

Parameters:

• code (required): Code content to scan (max 10MB) - validated size
• filePath (optional): File path for context - helps with false positive reduction

Features:

• Input size validation (10MB maximum)
• Enhanced false positive detection
• Adaptive secret masking based on length
• Performance optimizations (skips empty lines and comments)

Example:

{
  "code": "const apiKey = 'sk_live_1234567890abcdef'",
  "filePath": "config.js"
}

3. analyze_security

Perform comprehensive security analysis on a repository with risk scoring, compliance status, and remediation steps.

Parameters:

• owner (required): GitHub repository owner
• repo (required): Repository name
• branch (optional): Branch to analyze (default: "main")

Returns:

• Risk score (0-100)
• Compliance status (compliant/at_risk/non_compliant)
• Severity breakdown (critical/high/medium/low)
• Detailed remediation steps
• Security recommendations

4. get_secret_types

Get list of all supported secret types (35+ types) with categories, descriptions, and severity levels.

5. validate_secret

Validate if a detected secret is still active with structured recommendations.

Parameters:

• secretType (required): Type of secret (validated against supported types)
• value (required): The secret value to validate (max 10KB, sanitized)

MCP Resources

The server provides the following resources:

• leak-secure://secret-types: List of all supported secret types
• leak-secure://patterns: Detection patterns and regular expressions

Configuration

Environment Variables

The server can be configured using environment variables in a .env file or system environment:

Required

• GITHUB_TOKEN (optional): GitHub Personal Access Token for accessing repositories

Optional Configuration

Server Configuration:

• NODE_ENV: Environment mode (development, production, test) - default: production
• LOG_LEVEL: Logging level (DEBUG, INFO, WARN, ERROR) - default: INFO

Rate Limiting:

• GITHUB_RATE_LIMIT_PER_HOUR: Maximum API calls per hour - default: 5000
• GITHUB_RATE_LIMIT_BURST: Burst capacity for rate limiter - default: 100

Timeouts (milliseconds):

• GITHUB_REQUEST_TIMEOUT: Timeout for individual GitHub API requests - default: 30000 (30s)
• SCAN_TIMEOUT: Timeout for entire repository scans - default: 300000 (5 minutes)

Retry Configuration:

• MAX_RETRIES: Maximum retry attempts for failed requests - default: 3
• RETRY_DELAY_BASE: Base delay for exponential backoff (ms) - default: 1000 (1s)
• RETRY_DELAY_MAX: Maximum delay between retries (ms) - default: 30000 (30s)

File Processing:

• MAX_FILE_SIZE: Maximum file size to process (bytes) - default: 10485760 (10MB)
• MAX_FILES_PER_SCAN: Maximum files to scan per repository - default: 10000

Circuit Breaker:

• CIRCUIT_BREAKER_THRESHOLD: Failure threshold before opening circuit - default: 5
• CIRCUIT_BREAKER_TIMEOUT: Time before attempting recovery (ms) - default: 60000 (1 minute)

GitHub Token

A GitHub Personal Access Token is optional but recommended for:

• Accessing private repositories
• Higher rate limits (5000/hour vs 60/hour unauthenticated)
• Better reliability and reduced rate limit errors

To create a token:

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scopes: repo (for private repos) or public_repo (for public repos)
4. Copy the token and add it to your .env file:

   GITHUB_TOKEN=your_token_here

Configuration Example

Create a .env file in the project root:

# GitHub Configuration
GITHUB_TOKEN=ghp_your_token_here

# Server Configuration
NODE_ENV=production
LOG_LEVEL=INFO

# Rate Limiting
GITHUB_RATE_LIMIT_PER_HOUR=5000
GITHUB_RATE_LIMIT_BURST=100

# Timeouts (milliseconds)
GITHUB_REQUEST_TIMEOUT=30000
SCAN_TIMEOUT=300000

# Retry Configuration
MAX_RETRIES=3
RETRY_DELAY_BASE=1000
RETRY_DELAY_MAX=30000

# File Processing
MAX_FILE_SIZE=10485760
MAX_FILES_PER_SCAN=10000

# Circuit Breaker
CIRCUIT_BREAKER_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT=60000

Security Considerations

Secret Protection

• Adaptive Secret Masking: Secrets are automatically masked with adaptive length (shows first 4-6 and last 4-6 characters based on secret length)
• Log Sanitization: All secrets are automatically sanitized in logs - never logged in full
• Secure Error Messages: Error messages never expose sensitive data or full secret values
• Input Sanitization: All inputs are sanitized to prevent injection attacks

False Positive Reduction

• Enhanced Validation: Multiple layers of validation to reduce false positives
• Pattern-Specific Validators: Custom validators for specific secret types
• Context-Aware Detection: File path context helps improve accuracy
• Common False Positive Filtering: Filters out example, test, placeholder values

API Security

• Rate Limiting: Automatic rate limiting respects GitHub API limits and prevents abuse
• Retry Logic: Smart retry only for operational errors, prevents infinite loops
• Circuit Breaker: Prevents cascading failures and protects against API outages
• Timeout Protection: Prevents hanging requests and resource exhaustion
• Access Control: Use GitHub tokens with minimal required permissions (principle of least privilege)

Operational Security

• Structured Logging: All logs are structured and sanitized for security compliance
• Error Classification: Distinguishes between operational and programming errors
• Graceful Degradation: Server continues operating even when some operations fail
• Memory Protection: Limits on file sizes and counts prevent memory exhaustion attacks

Development

Project Structure

leak-secure-mcp/
├── src/
│   ├── index.ts                 # Main MCP server entry point
│   ├── detectors/
│   │   ├── SecretDetector.ts    # Core detection engine with enhanced security
│   │   └── patterns/
│   │       └── SecretPatterns.ts # 35+ secret detection patterns
│   ├── github/
│   │   └── GitHubClient.ts      # GitHub API integration with rate limiting & retries
│   ├── analyzer/
│   │   └── SecurityAnalyzer.ts  # Security analysis and risk assessment
│   └── utils/                   # Enterprise-grade utilities
│       ├── validation.ts        # Zod-based input validation schemas
│       ├── logger.ts            # Structured logging with secret sanitization
│       ├── config.ts            # Centralized configuration management
│       ├── errors.ts            # Custom error types and error handling
│       ├── rateLimiter.ts       # Token bucket rate limiting
│       ├── retry.ts             # Exponential backoff retry logic
│       └── circuitBreaker.ts    # Circuit breaker pattern implementation
├── dist/                        # Compiled JavaScript
├── scripts/                     # Setup and utility scripts
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Linting

npm run lint

Testing

npm test

API Response Format

Scan Results

{
  "repository": "owner/repo",
  "branch": "main",
  "path": "entire repository",
  "totalFilesScanned": 150,
  "filesWithSecrets": 5,
  "totalSecretsFound": 12,
  "results": [
    {
      "file": "config.js",
      "detections": [
        {
          "type": "aws_access_key_id",
          "category": "Cloud Provider",
          "severity": "critical",
          "value": "AKIA****1234",
          "line": 42,
          "column": 15,
          "context": "...",
          "pattern": "AKIA[0-9A-Z]{16}",
          "recommendation": "Rotate AWS access keys immediately"
        }
      ],
      "severity": "critical"
    }
  ],
  "summary": {
    "totalFiles": 5,
    "filesWithSecrets": 5,
    "totalSecrets": 12,
    "severityBreakdown": {
      "critical": 3,
      "high": 5,
      "medium": 4,
      "low": 0
    },
    "topSecretTypes": [
      { "type": "aws_access_key_id", "count": 3 },
      { "type": "github_token", "count": 2 }
    ]
  }
}

Security Analysis Results

{
  "repository": "owner/repo",
  "branch": "main",
  "totalFilesScanned": 150,
  "filesWithSecrets": 5,
  "totalSecretsFound": 12,
  "results": [...],
  "analysis": {
    "riskScore": 75,
    "complianceStatus": "non_compliant",
    "criticalIssues": 3,
    "highIssues": 5,
    "mediumIssues": 4,
    "lowIssues": 0,
    "remediationSteps": [
      "URGENT: Address critical security issues immediately",
      "Rotate all exposed critical secrets",
      "Implement secret management solution"
    ],
    "recommendations": [
      "Most common secret types found: aws_access_key_id, github_token",
      "Consider implementing a security review process",
      "Enable secret scanning in your development workflow"
    ]
  },
  "riskScore": 75,
  "complianceStatus": "non_compliant",
  "remediationSteps": [...]
}

Error Response Format

{
  "error": "ValidationError",
  "code": "VALIDATION_ERROR",
  "message": "Invalid input parameters",
  "context": {
    "field": "owner",
    "issue": "Invalid owner format"
  }
}

Performance & Reliability

Rate Limiting

• Token Bucket Algorithm: Efficient rate limiting with automatic token refill
• Configurable Limits: Adjustable per-hour and burst limits
• Automatic Waiting: Server automatically waits for rate limit tokens when needed

Retry Logic

• Exponential Backoff: Smart retry delays increase exponentially (1s → 2s → 4s → 8s...)
• Jitter: Random jitter prevents thundering herd problems
• Selective Retry: Only retries operational errors (network, timeouts, rate limits)
• Maximum Retries: Configurable retry attempts (default: 3)

Circuit Breaker

• Three States: CLOSED (normal), OPEN (failing), HALF_OPEN (testing recovery)
• Automatic Recovery: Detects when service has recovered
• Failure Threshold: Configurable failure count before opening circuit
• Timeout Protection: Prevents hanging on unresponsive services

Memory Management

• Batch Processing: Files processed in batches (50 per batch) to manage memory
• File Size Limits: Configurable maximum file size (default: 10MB)
• File Count Limits: Maximum files per scan (default: 10,000)
• Efficient Scanning: Skips binary files, large files, and common directories

Timeout Protection

• Request Timeouts: Individual API requests timeout after 30 seconds
• Operation Timeouts: Full repository scans timeout after 5 minutes
• Graceful Handling: Timeouts return proper error responses

Error Handling

The server implements comprehensive error handling with custom error types:

• ValidationError: Input validation failures (400)
• GitHubAPIError: GitHub API communication errors (502)
• RateLimitError: Rate limit exceeded (429)
• TimeoutError: Operation timeout (504)
• RepositoryAccessError: Repository access denied (403)
• CircuitBreakerError: Circuit breaker open (503)

All errors are:

• Properly typed and classified
• Sanitized (no sensitive data)
• Structured for easy handling
• Logged with appropriate levels

Contributing

This is an enterprise-grade, production-ready implementation. When contributing:

1. Code Quality: Maintain high code quality and security standards
2. Testing: Add comprehensive tests for new features
3. Documentation: Update documentation for all changes
4. TypeScript: Follow TypeScript best practices and strict typing
5. Security: Ensure all secrets are properly masked in outputs and logs
6. Error Handling: Use custom error types from utils/errors.ts
7. Logging: Use structured logging from utils/logger.ts (never log secrets)
8. Validation: Use Zod schemas from utils/validation.ts for all inputs
9. Configuration: Add new config options to utils/config.ts with validation
10. Performance: Consider memory and performance implications of changes

License

MIT License

Support

For issues, questions, or contributions, please contact: [email protected]

Architecture Highlights

Enterprise Patterns Implemented

1. Rate Limiting: Token bucket algorithm for API call management
2. Retry Logic: Exponential backoff with jitter for resilience
3. Circuit Breaker: Prevents cascading failures
4. Input Validation: Zod schemas for type-safe validation
5. Structured Logging: JSON logging with secret sanitization
6. Error Handling: Custom error types with proper classification
7. Configuration Management: Centralized, validated configuration
8. Graceful Shutdown: Proper cleanup and operation completion
9. Memory Management: Batch processing and resource limits
10. Timeout Protection: Prevents resource exhaustion

Security Features

• Zero-trust secret handling (never logged, always masked)
• Input sanitization and validation
• Secure error messages (no sensitive data)
• Rate limiting to prevent abuse
• Memory protection against DoS attacks
• Timeout protection against hanging operations

Acknowledgments

Built with:

• Model Context Protocol SDK - MCP protocol implementation
• Octokit - GitHub API integration
• Zod - TypeScript-first schema validation
• Enterprise security and reliability best practices