langprotect-mcp-gateway 1.2.6__tar.gz → 1.3.0__tar.gz

{langprotect_mcp_gateway-1.2.6 → langprotect_mcp_gateway-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langprotect-mcp-gateway
-Version: 1.2.6
+Version: 1.3.0
 Summary: Security gateway for Model Context Protocol (MCP) to protect AI tool interactions
 Author-email: LangProtect Security Team <security@langprotect.com>
 License: MIT
@@ -32,8 +32,44 @@ Dynamic: license-file
 
 [![PyPI version](https://badge.fury.io/py/langprotect-mcp-gateway.svg)](https://pypi.org/project/langprotect-mcp-gateway/)
 
+## 🆕 What's New in v1.3.0
+
+### Layer 2: Output Scanning 🔍
+- **Automatic secret masking** in AI-generated responses
+- **30+ secret types detected**: AWS, Google Cloud, Azure, Stripe, GitHub, JWTs, DB credentials, private keys
+- **Non-blocking warnings** - never interrupts workflow
+- **Preserves structure** - masks secrets while keeping code/content readable
+
+### Enhanced Security Controls 🔐
+- **Fail-closed mode** - Block requests on scan failures (optional)
+- **Configurable timeouts** - Control scan performance
+- **High-entropy detection** - Catch unknown secret formats
+
+### Example
+
+**Before** (v1.2.6):
+```bash
+AI: Here's your AWS deployment script:
+export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
+export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG..."
+```
+
+**After** (v1.3.0):
+```bash
+AI: Here's your AWS deployment script:
+export AWS_ACCESS_KEY_ID="<REDACTED:AWS_ACCESS_KEY:1a5d44a2>"
+export AWS_SECRET_ACCESS_KEY="<REDACTED:AWS_SECRET_KEY:73ec276f>"
+```
+✅ **Secrets masked** | 🔒 **Code structure preserved** | 📝 **Audit trail maintained**
+
+---
+
 ## Features
 
+✅ **Two-Layer Protection**
+- **Layer 1 (Input)**: Blocks dangerous requests before sending to MCP server
+- **Layer 2 (Output)**: Masks secrets in AI responses
+
 ✅ **Automatic Threat Detection** - Scans all MCP requests for security risks  
 ✅ **Access Control** - Whitelist/blacklist MCP servers and tools  
 ✅ **Full Audit Trail** - Logs all AI interactions for compliance  
@@ -83,6 +119,60 @@ Reload VS Code and you're done! LangProtect will now protect all your workspaces
 
 ---
 
+## ⚙️ Configuration Options (v1.3.0+)
+
+Configure security behavior with environment variables in your wrapper script:
+
+```bash
+# Security Controls
+export LANGPROTECT_ENABLE_MASKING=true      # Enable output masking (default: true)
+export LANGPROTECT_FAIL_CLOSED=false        # Block on scan errors (default: false = fail-open)
+export LANGPROTECT_SCAN_TIMEOUT=5.0         # Scan timeout in seconds (default: 5.0)
+export LANGPROTECT_ENTROPY_DETECTION=true   # Detect unknown secrets via entropy (default: true)
+
+# Backend Connection
+export LANGPROTECT_URL="http://localhost:8000"
+export LANGPROTECT_EMAIL="your.email@company.com"
+export LANGPROTECT_PASSWORD="your-password"
+```
+
+### Security Modes
+
+**Fail-Open (Default)** - Recommended for development:
+```bash
+export LANGPROTECT_FAIL_CLOSED=false
+```
+- If scan times out or fails → **Allow request** (log warning)
+- Won't block your workflow
+- Best for development environments
+
+**Fail-Closed** - Recommended for production:
+```bash
+export LANGPROTECT_FAIL_CLOSED=true
+```
+- If scan times out or fails → **Block request**
+- Maximum security
+- Best for production/sensitive environments
+
+### Output Masking
+
+Control how AI-generated secrets are handled:
+
+```bash
+# Enable masking (default)
+export LANGPROTECT_ENABLE_MASKING=true
+
+# Disable masking (see secrets in plain text - not recommended)
+export LANGPROTECT_ENABLE_MASKING=false
+```
+
+**Masked format**: `<REDACTED:SECRET_TYPE:hash>`
+- Example: `<REDACTED:AWS_ACCESS_KEY:1a5d44a2>`
+- Hash allows deduplication across logs
+- Preserves code structure
+
+---
+
 ## 🏗️ Manual Setup (Per-Workspace)
 
 If you prefer to enable LangProtect only for a specific project, you can use a local `.vscode/mcp.json` file.

{langprotect_mcp_gateway-1.2.6 → langprotect_mcp_gateway-1.3.0}/README.md

@@ -4,8 +4,44 @@
 
 [![PyPI version](https://badge.fury.io/py/langprotect-mcp-gateway.svg)](https://pypi.org/project/langprotect-mcp-gateway/)
 
+## 🆕 What's New in v1.3.0
+
+### Layer 2: Output Scanning 🔍
+- **Automatic secret masking** in AI-generated responses
+- **30+ secret types detected**: AWS, Google Cloud, Azure, Stripe, GitHub, JWTs, DB credentials, private keys
+- **Non-blocking warnings** - never interrupts workflow
+- **Preserves structure** - masks secrets while keeping code/content readable
+
+### Enhanced Security Controls 🔐
+- **Fail-closed mode** - Block requests on scan failures (optional)
+- **Configurable timeouts** - Control scan performance
+- **High-entropy detection** - Catch unknown secret formats
+
+### Example
+
+**Before** (v1.2.6):
+```bash
+AI: Here's your AWS deployment script:
+export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
+export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG..."
+```
+
+**After** (v1.3.0):
+```bash
+AI: Here's your AWS deployment script:
+export AWS_ACCESS_KEY_ID="<REDACTED:AWS_ACCESS_KEY:1a5d44a2>"
+export AWS_SECRET_ACCESS_KEY="<REDACTED:AWS_SECRET_KEY:73ec276f>"
+```
+✅ **Secrets masked** | 🔒 **Code structure preserved** | 📝 **Audit trail maintained**
+
+---
+
 ## Features
 
+✅ **Two-Layer Protection**
+- **Layer 1 (Input)**: Blocks dangerous requests before sending to MCP server
+- **Layer 2 (Output)**: Masks secrets in AI responses
+
 ✅ **Automatic Threat Detection** - Scans all MCP requests for security risks  
 ✅ **Access Control** - Whitelist/blacklist MCP servers and tools  
 ✅ **Full Audit Trail** - Logs all AI interactions for compliance  
@@ -55,6 +91,60 @@ Reload VS Code and you're done! LangProtect will now protect all your workspaces
 
 ---
 
+## ⚙️ Configuration Options (v1.3.0+)
+
+Configure security behavior with environment variables in your wrapper script:
+
+```bash
+# Security Controls
+export LANGPROTECT_ENABLE_MASKING=true      # Enable output masking (default: true)
+export LANGPROTECT_FAIL_CLOSED=false        # Block on scan errors (default: false = fail-open)
+export LANGPROTECT_SCAN_TIMEOUT=5.0         # Scan timeout in seconds (default: 5.0)
+export LANGPROTECT_ENTROPY_DETECTION=true   # Detect unknown secrets via entropy (default: true)
+
+# Backend Connection
+export LANGPROTECT_URL="http://localhost:8000"
+export LANGPROTECT_EMAIL="your.email@company.com"
+export LANGPROTECT_PASSWORD="your-password"
+```
+
+### Security Modes
+
+**Fail-Open (Default)** - Recommended for development:
+```bash
+export LANGPROTECT_FAIL_CLOSED=false
+```
+- If scan times out or fails → **Allow request** (log warning)
+- Won't block your workflow
+- Best for development environments
+
+**Fail-Closed** - Recommended for production:
+```bash
+export LANGPROTECT_FAIL_CLOSED=true
+```
+- If scan times out or fails → **Block request**
+- Maximum security
+- Best for production/sensitive environments
+
+### Output Masking
+
+Control how AI-generated secrets are handled:
+
+```bash
+# Enable masking (default)
+export LANGPROTECT_ENABLE_MASKING=true
+
+# Disable masking (see secrets in plain text - not recommended)
+export LANGPROTECT_ENABLE_MASKING=false
+```
+
+**Masked format**: `<REDACTED:SECRET_TYPE:hash>`
+- Example: `<REDACTED:AWS_ACCESS_KEY:1a5d44a2>`
+- Hash allows deduplication across logs
+- Preserves code structure
+
+---
+
 ## 🏗️ Manual Setup (Per-Workspace)
 
 If you prefer to enable LangProtect only for a specific project, you can use a local `.vscode/mcp.json` file.

{langprotect_mcp_gateway-1.2.6 → langprotect_mcp_gateway-1.3.0}/langprotect_mcp_gateway/gateway.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """
 LangProtect MCP Gateway - Security Gateway for MCP Servers
+Enhanced with Pre-LLM Scanning and Response Masking
 """
 
 import sys
@@ -13,6 +14,9 @@ from datetime import datetime, timedelta
 from typing import Dict, List, Any, Optional
 import logging
 
+# Import response masker
+from .response_masker import ResponseMasker, get_masker
+
 log_level = os.environ.get("LOGLEVEL", "DEBUG" if os.getenv('DEBUG', 'false').lower() == 'true' else "INFO").upper()
 logging.basicConfig(level=getattr(logging, log_level), format='[%(asctime)s] %(levelname)s: %(message)s', handlers=[logging.StreamHandler(sys.stderr)])
 logger = logging.getLogger('langprotect-gateway')
@@ -97,12 +101,15 @@ class MCPServer:
 
 
 class LangProtectAuth:
-    def __init__(self, url: str, email: str, password: str):
+    def __init__(self, url: str, email: str, password: str, scan_timeout: float = 5.0, fail_closed: bool = False):
         self.url = url
         self.email = email
         self.password = password
         self.jwt_token: Optional[str] = None
         self.token_expiry: Optional[datetime] = None
+        self.scan_timeout = scan_timeout  # Maximum wait time for scans
+        self.fail_closed = fail_closed    # Block on scan failure if True
+        logger.info(f"Auth initialized: timeout={scan_timeout}s, fail_closed={fail_closed}")
     
     def login(self) -> bool:
         try:
@@ -126,34 +133,168 @@ class LangProtectAuth:
             return self.login()
         return True
     
-    def scan(self, tool_name: str, arguments: Dict, server_name: str) -> Dict:
+    def scan_input(self, tool_name: str, arguments: Dict, server_name: str) -> Dict:
+        """
+        Scan user input BEFORE forwarding to MCP server (blocking scan).
+        Uses the new Group Scan API with policy-based scanning.
+        """
         self.ensure_token()
         try:
-            # Use MCP-specific endpoint with proper payload structure
+            # Convert tool call to prompt string for scanning
+            prompt = f"Tool: {tool_name}\nServer: {server_name}\nArguments: {json.dumps(arguments, indent=2)}"
+            
             payload = {
-                'method': 'tools/call',
-                'params': {'name': tool_name, 'arguments': arguments},
-                'server_url': server_name,
-                'agent_id': 'langprotect-gateway',
-                'client_ip': '127.0.0.1',
-                'user_agent': f'LangProtect-MCP-Gateway/1.0 (server={server_name})'
+                'prompt': prompt,
+                'metadata': {
+                    'tool_name': tool_name,
+                    'server_name': server_name,
+                    'source': 'mcp-gateway-input',
+                    'scan_type': 'input'
+                }
             }
-            response = requests.post(f"{self.url}/v1/group-logs/mcp/scan", json=payload, headers={'Authorization': f'Bearer {self.jwt_token}', 'Content-Type': 'application/json'}, timeout=5)
+            
+            logger.debug(f"🛡️ INPUT SCAN: {tool_name} on {server_name}")
+            
+            response = requests.post(
+                f"{self.url}/v1/group-logs/scan",
+                json=payload,
+                headers={
+                    'Authorization': f'Bearer {self.jwt_token}',
+                    'Content-Type': 'application/json'
+                },
+                timeout=self.scan_timeout
+            )
+            
             if response.status_code != 200:
-                logger.warning(f"Backend returned {response.status_code}, allowing request (fail-open)")
-                return {'status': 'allowed', 'error': f'Backend error: {response.status_code}'}
+                logger.warning(f"Backend returned {response.status_code}")
+                if self.fail_closed:
+                    return {
+                        'status': 'blocked',
+                        'reason': f'Scan service unavailable (HTTP {response.status_code}) - fail-closed mode'
+                    }
+                else:
+                    logger.warning("Allowing request (fail-open mode)")
+                    return {'status': 'allowed', 'error': f'Backend error: {response.status_code}'}
+            
             result = response.json()
-            # Handle scan service timeout - fail open
+            
+            # Handle scan service timeout - respect fail mode
             if result.get('detections', {}).get('error') == 'Scan service timeout':
-                logger.warning("Scan service timeout, allowing request (fail-open)")
-                return {'status': 'allowed', 'id': result.get('id'), 'error': 'Scan timeout'}
+                logger.warning("Scan service timeout detected")
+                if self.fail_closed:
+                    return {
+                        'status': 'blocked',
+                        'reason': 'Scan service timeout - fail-closed mode'
+                    }
+                else:
+                    logger.warning("Allowing request despite timeout (fail-open)")
+                    return {'status': 'allowed', 'id': result.get('id'), 'error': 'Scan timeout'}
+            
             return result
+        
         except requests.exceptions.Timeout:
-            logger.warning("Backend scan timeout, allowing request (fail-open)")
-            return {'status': 'allowed', 'error': 'Request timeout'}
+            logger.error(f"Backend scan timeout after {self.scan_timeout}s")
+            if self.fail_closed:
+                return {
+                    'status': 'blocked',
+                    'reason': f'Scan timeout after {self.scan_timeout}s - fail-closed mode'
+                }
+            else:
+                logger.warning("Allowing request despite timeout (fail-open)")
+                return {'status': 'allowed', 'error': 'Request timeout'}
+        
         except Exception as e:
             logger.error(f"Scan error: {e}")
-            return {'status': 'allowed', 'error': str(e)}
+            if self.fail_closed:
+                return {
+                    'status': 'blocked',
+                    'reason': f'Scan error: {str(e)} - fail-closed mode'
+                }
+            else:
+                logger.warning(f"Allowing request despite error (fail-open): {e}")
+                return {'status': 'allowed', 'error': str(e)}
+    
+    def scan_output(self, tool_name: str, output_content: str, prompt: str = None, metadata: Dict = None) -> Dict:
+        """
+        Scan LLM/MCP output AFTER receiving from server (non-blocking, masking scan).
+        Uses the new Group Scan API with output scanning support.
+        
+        Args:
+            tool_name: Name of the MCP tool that generated the output
+            output_content: The output text to scan for secrets
+            prompt: Original user prompt (optional)
+            metadata: Additional context (optional)
+        
+        Returns:
+            Scan result with masked_content field if secrets detected
+        """
+        self.ensure_token()
+        try:
+            payload = {
+                'prompt': prompt or f"Tool: {tool_name}",
+                'output': output_content,
+                'metadata': {
+                    'tool_name': tool_name,
+                    'source': 'mcp-gateway-output',
+                    'scan_type': 'output',
+                    **(metadata or {})
+                }
+            }
+            
+            logger.debug(f"🔍 OUTPUT SCAN: {tool_name} ({len(output_content)} chars)")
+            
+            response = requests.post(
+                f"{self.url}/v1/group-logs/scan",
+                json=payload,
+                headers={
+                    'Authorization': f'Bearer {self.jwt_token}',
+                    'Content-Type': 'application/json'
+                },
+                timeout=self.scan_timeout
+            )
+            
+            if response.status_code != 200:
+                logger.warning(f"Output scan failed: HTTP {response.status_code}")
+                # For output scanning, fail-open (don't block, return original)
+                return {
+                    'status': 'allowed',
+                    'output': output_content,
+                    'masked': False,
+                    'error': f'Scan failed: {response.status_code}'
+                }
+            
+            result = response.json()
+            
+            # Extract masked content from MCPResponseScanner details
+            mcp_response = result.get('detections', {}).get('MCPResponseScanner', {})
+            if mcp_response.get('is_detected'):
+                masked_content = mcp_response.get('details', {}).get('masked_content', output_content)
+                logger.warning(f"🔒 OUTPUT MASKED: {tool_name} (score={mcp_response.get('score')})")
+                return {
+                    'status': result.get('status'),
+                    'output': masked_content,
+                    'masked': True,
+                    'risk_score': result.get('risk_score'),
+                    'scan_id': result.get('id'),
+                    'detections': mcp_response.get('details', {}).get('detections', [])
+                }
+            else:
+                # No secrets detected, return original
+                return {
+                    'status': 'safe',
+                    'output': output_content,
+                    'masked': False
+                }
+        
+        except Exception as e:
+            logger.error(f"Output scan error: {e}")
+            # Fail-open for output scanning - return original content
+            return {
+                'status': 'allowed',
+                'output': output_content,
+                'masked': False,
+                'error': str(e)
+            }
 
 
 class LangProtectGateway:
@@ -165,6 +306,12 @@ class LangProtectGateway:
         self.email = os.getenv('LANGPROTECT_EMAIL')
         self.password = os.getenv('LANGPROTECT_PASSWORD')
         
+        # Security configuration
+        self.scan_timeout = float(os.getenv('LANGPROTECT_SCAN_TIMEOUT', '5.0'))
+        self.fail_closed = os.getenv('LANGPROTECT_FAIL_CLOSED', 'false').lower() == 'true'
+        self.enable_masking = os.getenv('LANGPROTECT_ENABLE_MASKING', 'true').lower() == 'true'
+        self.enable_entropy_detection = os.getenv('LANGPROTECT_ENTROPY_DETECTION', 'true').lower() == 'true'
+        
         # Try to load credentials from mcp.json env section (like Lasso)
         if mcp_json_path and (not self.email or not self.password):
             self._load_env_from_config(mcp_json_path)
@@ -173,8 +320,21 @@ class LangProtectGateway:
         self.mcp_servers: Dict[str, MCPServer] = {}
         self.tool_to_server: Dict[str, str] = {}
         self.all_tools: List[Dict] = []
+        
+        # Initialize response masker
+        self.masker: Optional[ResponseMasker] = None
+        if self.enable_masking:
+            self.masker = get_masker(
+                enable_entropy=self.enable_entropy_detection,
+                entropy_threshold=4.5
+            )
+            logger.info("✅ Response masking ENABLED")
+        else:
+            logger.warning("⚠️ Response masking DISABLED")
+        
         logger.debug(f"LANGPROTECT_URL: {self.langprotect_url}")
         logger.debug(f"LANGPROTECT_EMAIL: {self.email}")
+        logger.info(f"Security config: timeout={self.scan_timeout}s, fail_closed={self.fail_closed}, masking={self.enable_masking}")
     
     def _load_env_from_config(self, path: str):
         """Load credentials from mcp.json env section (Lasso/VS Code style)"""
@@ -204,7 +364,13 @@ class LangProtectGateway:
     
     def initialize(self) -> bool:
         if self.email and self.password:
-            self.auth = LangProtectAuth(self.langprotect_url, self.email, self.password)
+            self.auth = LangProtectAuth(
+                self.langprotect_url,
+                self.email,
+                self.password,
+                scan_timeout=self.scan_timeout,
+                fail_closed=self.fail_closed
+            )
             if not self.auth.login():
                 logger.error("Failed to authenticate with LangProtect backend")
                 return False
@@ -214,12 +380,13 @@ class LangProtectGateway:
             return False
         if not self.start_servers():
             return False
-        logger.info("=" * 50)
-        logger.info("LangProtect Gateway initialized")
+        logger.info("=" * 60)
+        logger.info("🛡️  LangProtect Gateway initialized")
         logger.info(f"Backend: {self.langprotect_url}")
         logger.info(f"Servers: {len(self.mcp_servers)}")
         logger.info(f"Tools: {len(self.all_tools)}")
-        logger.info("=" * 50)
+        logger.info(f"Security: fail_closed={self.fail_closed}, masking={self.enable_masking}")
+        logger.info("=" * 60)
         return True
     
     def load_servers(self) -> bool:
@@ -338,30 +505,156 @@ class LangProtectGateway:
         tool_name = params.get('name', '')
         arguments = params.get('arguments', {})
         server_name = self.tool_to_server.get(tool_name)
+        
         if not server_name:
             return {'jsonrpc': '2.0', 'id': request_id, 'error': {'code': -32602, 'message': f'Unknown tool: {tool_name}'}}
+        
         server = self.mcp_servers.get(server_name)
         if not server:
             return {'jsonrpc': '2.0', 'id': request_id, 'error': {'code': -32602, 'message': f'Server not found: {server_name}'}}
+        
         logger.info(f"Tool call: {server_name}.{tool_name}")
+        
+        # 🛡️ LAYER 1: INPUT SCAN (synchronous blocking scan)
+        scan_result = None
         if self.auth:
-            scan_result = self.auth.scan(tool_name, arguments, server_name)
+            scan_result = self.auth.scan_input(tool_name, arguments, server_name)
             status = scan_result.get('status', '').lower()
+            
             if status == 'blocked':
-                reason = scan_result.get('detections', {}).get('MCPActionControl', {}).get('reason', 'Policy violation')
-                logger.warning(f"BLOCKED: {tool_name} - {reason}")
-                return {'jsonrpc': '2.0', 'id': request_id, 'error': {'code': -32000, 'message': f'LangProtect: {reason}'}}
-            logger.info(f"ALLOWED (log_id={scan_result.get('id')})")
+                reason = scan_result.get('reason', 'Policy violation')
+                logger.warning(f"🚫 INPUT BLOCKED: {tool_name} - {reason}")
+                return {
+                    'jsonrpc': '2.0',
+                    'id': request_id,
+                    'error': {
+                        'code': -32000,
+                        'message': f'🛡️ LangProtect: {reason}'
+                    }
+                }
+            
+            logger.info(f"✅ INPUT ALLOWED (log_id={scan_result.get('id')})")
+        
+        # Input scan passed or no auth - forward to MCP server
         try:
             response = server.call('tools/call', {'name': tool_name, 'arguments': arguments})
+            
+            # 🛡️ LAYER 2: OUTPUT SCAN (scan response content for secrets)
+            if self.auth and self.enable_masking and 'result' in response:
+                # Extract text content from response
+                result_content = response.get('result', {})
+                output_text = self._extract_text_from_result(result_content)
+                
+                if output_text:
+                    logger.debug(f"� Scanning output: {len(output_text)} chars")
+                    output_scan = self.auth.scan_output(
+                        tool_name=tool_name,
+                        output_content=output_text,
+                        prompt=json.dumps(arguments),
+                        metadata={'server_name': server_name}
+                    )
+                    
+                    if output_scan.get('masked'):
+                        # Replace output with masked version
+                        masked_text = output_scan.get('output', output_text)
+                        logger.warning(f"🔒 OUTPUT MASKED: {tool_name} (risk={output_scan.get('risk_score')})")
+                        response['result'] = self._replace_text_in_result(result_content, masked_text)
+            
+            # Return formatted response
             if 'result' in response:
                 return {'jsonrpc': '2.0', 'id': request_id, 'result': response['result']}
             elif 'error' in response:
                 return {'jsonrpc': '2.0', 'id': request_id, 'error': response['error']}
             return response
+        
         except Exception as e:
+            logger.error(f"Error executing {tool_name}: {e}")
             return {'jsonrpc': '2.0', 'id': request_id, 'error': {'code': -32603, 'message': f'Error executing tool: {e}'}}
     
+    def _extract_text_from_result(self, result: Any) -> str:
+        """Extract text content from MCP tool result for scanning."""
+        if isinstance(result, str):
+            return result
+        elif isinstance(result, dict):
+            # MCP results typically have 'content' field
+            if 'content' in result:
+                content = result['content']
+                if isinstance(content, str):
+                    return content
+                elif isinstance(content, list):
+                    # Extract text from content array
+                    texts = []
+                    for item in content:
+                        if isinstance(item, dict) and item.get('type') == 'text':
+                            texts.append(item.get('text', ''))
+                        elif isinstance(item, str):
+                            texts.append(item)
+                    return '\n'.join(texts)
+            # Fallback: convert whole dict to string
+            return json.dumps(result)
+        elif isinstance(result, list):
+            return '\n'.join(str(item) for item in result)
+        return str(result)
+    
+    def _replace_text_in_result(self, result: Any, masked_text: str) -> Any:
+        """Replace text content in MCP tool result with masked version."""
+        if isinstance(result, str):
+            return masked_text
+        elif isinstance(result, dict):
+            result_copy = result.copy()
+            if 'content' in result_copy:
+                content = result_copy['content']
+                if isinstance(content, str):
+                    result_copy['content'] = masked_text
+                elif isinstance(content, list):
+                    # Replace text in content array
+                    masked_lines = masked_text.split('\n')
+                    new_content = []
+                    line_idx = 0
+                    for item in content:
+                        if isinstance(item, dict) and item.get('type') == 'text':
+                            if line_idx < len(masked_lines):
+                                new_item = item.copy()
+                                new_item['text'] = masked_lines[line_idx]
+                                new_content.append(new_item)
+                                line_idx += 1
+                        else:
+                            new_content.append(item)
+                    result_copy['content'] = new_content
+            return result_copy
+        return masked_text
+    
+    def _log_mask_events(self, mask_events: List[Dict], scan_id: Optional[str], tool_name: str):
+        """Log masked secrets to backend for audit trail"""
+        if not self.auth or not mask_events:
+            return
+        
+        try:
+            self.auth.ensure_token()
+            payload = {
+                'scan_id': scan_id,
+                'tool_name': tool_name,
+                'mask_events': mask_events,
+                'timestamp': datetime.now().isoformat(),
+                'gateway_version': '1.0.0'
+            }
+            
+            # Fire-and-forget (don't block on logging)
+            response = requests.post(
+                f"{self.langprotect_url}/v1/mask-events",
+                json=payload,
+                headers={'Authorization': f'Bearer {self.auth.jwt_token}'},
+                timeout=2  # Short timeout for logging
+            )
+            
+            if response.status_code == 200:
+                logger.debug(f"Logged {len(mask_events)} mask events to backend")
+            else:
+                logger.warning(f"Failed to log mask events: {response.status_code}")
+        
+        except Exception as e:
+            logger.warning(f"Failed to log mask events: {e}")
+    
     def run(self):
         try:
             for line in sys.stdin: