feat(loki): Add regex-based log masking for sensitive data protection

[Marie673]

feat(loki): Add server-side log masking for sensitive data protection

Summary

Add regex-based log masking capability to the Loki log query tool. This feature automatically masks sensitive information (PII, authentication tokens, etc.) in log data before returning results to AI assistants, enhancing security and compliance.

Key Design Decision: Masking configuration is set at server startup by system administrators. AI/LLM cannot modify or override masking settings via tool calls. This ensures organizational security policies are enforced consistently and prevents unintended data exposure.

Changes

New Files

File	Description
tools/loki_masking.go	Core masking logic and builtin pattern definitions
tools/loki_masking_unit_test.go	Comprehensive unit tests, benchmarks, SLO compliance tests

Modified Files

File	Description
tools/loki.go	Integration of masking processing via Context-based masker injection
tools/loki_test.go	Integration tests for masking functionality
mcpgrafana.go	LokiMaskingConfig struct, WithMasker/MaskerFromContext context functions
cmd/mcp-grafana/main.go	CLI flags, environment variable support, masker initialization
mcpgrafana_test.go	Context management tests
README.md	Documentation for masking feature and configuration
examples/tls_example.go	Context function signature updates

Features

Server-Level Configuration

Masking is configured at server startup via environment variables:

# Enable masking
export LOKI_MASKING_ENABLED=true

# Specify patterns (comma-separated)
export LOKI_MASKING_PATTERNS=email,credit_card,ip_address,jwt_token

Or via CLI flags:

./mcp-grafana \
  --loki-masking-enabled \
  --loki-masking-patterns=email,credit_card,ip_address,jwt_token

Or via Docker Compose:

environment:
  - LOKI_MASKING_ENABLED=true
  - LOKI_MASKING_PATTERNS=email,credit_card,ip_address,jwt_token

Builtin Patterns

The following sensitive data patterns are provided as predefined options:

Pattern ID	Description	Example
email	Email addresses	user@example.com → [MASKED:email]
phone	E.164 international phone numbers	+819012345678 → [MASKED:phone]
credit_card	Credit card numbers	4111-1111-1111-1111 → [MASKED:credit_card]
ip_address	IPv4/IPv6 addresses	192.168.1.1 → [MASKED:ip_address]
mac_address	MAC addresses	00:1A:2B:3C:4D:5E → [MASKED:mac_address]
api_key	API keys/tokens	api_key=abc123... → [MASKED:api_key]
jwt_token	JWT tokens	eyJ... → [MASKED:jwt_token]

Security Model

Aspect	Detail
Configuration by	System administrators only
Configuration timing	Server startup only
Configuration method	Environment variables / CLI flags
AI/LLM access to settings	Not possible
Modification via tool calls	Not possible (no masking parameter in API)

Architecture

Context-Based Masker Injection

Server Startup → Load Config → Create LogMasker → Inject into Context
                                                         ↓
MCP Client → query_loki_logs → Fetch Logs → Apply Masker from Context → Return Masked Logs

The masking is applied automatically when enabled - AI assistants receive masked logs without any ability to bypass or modify the masking configuration.

Technical Details

Performance

• Maximum pattern count: 20
• SLO: 100 entries × 20 patterns completed within 100ms
• Regex patterns compiled once at server startup (RE2 engine with linear time guarantee)

Error Handling

• Invalid builtin pattern identifier at startup → Warning log, skip invalid patterns
• Pattern count exceeds limit → Warning log, apply first 20 patterns only
• Masking failure at runtime → Return error, never return unmasked data

Backward Compatibility

• Masking is disabled by default (LOKI_MASKING_ENABLED=false)
• When disabled, behavior is identical to previous versions
• No changes to query_loki_logs tool API (no new parameters added)

Breaking Changes

• ComposedStdioContextFunc, ComposedSSEContextFunc, ComposedHTTPContextFunc signatures changed (added masker any parameter)
• If using these functions directly from external code, pass nil as the second argument to maintain existing behavior

Test Plan

Unit Tests

• Builtin pattern matching tests (positive/negative cases for each pattern)
• LogMasker masking behavior tests
• MaskingConfig validation tests
• Pattern compilation and caching verification
• Performance benchmarks (SLO compliance)

Integration Tests

• Query execution with masking enabled
• Backward compatibility with masking disabled
• Context-based masker injection verification

Non-Goals (Intentionally Not Supported)

• Custom regex patterns (for security and simplicity)
• Tool-level masking parameter (AI cannot modify settings)
• Local phone number formats (E.164 international format only)
• Label value masking (log body only)

[CLAassistant]

All committers have signed the CLA.