Feature: Implement audit logging for security and compliance

[basher83]

Feature Request

Add comprehensive audit logging for security-relevant operations and compliance tracking.

Context

This feature was identified in issue #17 but intentionally deferred as a future enhancement. The core security features (URL validation, input sanitization, parameter validation) have been implemented.

Proposed Implementation

1. Audit Log Events

Log the following security-relevant operations:

• Authentication Events:
  • Successful/failed authentication attempts
  • Token validation results
  • User identity changes
• API Operations:
  • Ticket creation/updates/deletion
  • User searches and lookups
  • Attachment downloads (with ticket/file IDs)
  • Sensitive data access
• Security Events:
  • URL validation failures (potential SSRF attempts)
  • Input sanitization triggers (potential XSS attempts)
  • Parameter validation failures
  • Rate limit violations (when implemented)

2. Log Format

Structured JSON logging with standard fields:

{
  "timestamp": "2025-11-16T20:30:00Z",
  "event_type": "ticket_update",
  "user": "user@example.com",
  "action": "update_ticket",
  "resource_type": "ticket",
  "resource_id": "12345",
  "client_ip": "192.168.1.100",
  "success": true,
  "details": {
    "changed_fields": ["state", "priority"],
    "old_state": "open",
    "new_state": "closed"
  }
}

3. Storage Options

• File-based: Append to structured log files (JSON lines)
• Syslog: Forward to centralized syslog server
• External Service: Send to logging service (e.g., Elasticsearch, Splunk)
• Configurable destination via environment variables

4. Configuration

ZAMMAD_AUDIT_LOG_ENABLED=true
ZAMMAD_AUDIT_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
ZAMMAD_AUDIT_LOG_FILE=/var/log/zammad-mcp/audit.log
ZAMMAD_AUDIT_LOG_FORMAT=json  # json, text
ZAMMAD_AUDIT_LOG_DESTINATION=file  # file, syslog, http
ZAMMAD_AUDIT_LOG_RETENTION_DAYS=90

5. Privacy Considerations

• PII Protection: Redact/mask sensitive fields (passwords, tokens, email domains)
• GDPR Compliance: Support for data retention policies
• Opt-out: Configuration to disable specific event types
• Sanitization: Remove sensitive data from logs

Technical Implementation

1. Audit Logger Module

Create mcp_zammad/audit.py:

class AuditLogger:
    def log_event(self, event_type: str, user: str, action: str, **kwargs):
        # Structure and write audit event
        pass
    
    def log_auth_attempt(self, user: str, success: bool, reason: str = None):
        pass
    
    def log_api_operation(self, operation: str, resource_type: str, resource_id: int):
        pass

2. Decorator Pattern

@audit_log(event_type="ticket_update")
def update_ticket(...):
    # Automatically log on entry/exit
    pass

3. Integration Points

• Add audit logging to all MCP tools in server.py
• Log authentication events in client.py
• Log validation failures in models.py

Acceptance Criteria

• All security-relevant operations are logged
• Structured JSON log format
• Configurable log destination (file/syslog/http)
• PII redaction/masking capabilities
• Log rotation and retention policies
• Performance impact < 5% overhead
• Unit tests for audit logger
• Documentation in README.md and SECURITY.md

Priority

Low - Useful for compliance and forensics in production environments

References

• Deferred from issue Security: Implement URL validation and input sanitization #17
• Related to CLAUDE.md "Security Notes"
• GDPR compliance considerations
• OWASP Logging Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html

Related Issues

• Feature: Implement rate limiting for API requests #120 (Rate Limiting) - for logging rate limit violations