feat: add SNMP provider for receiving and processing SNMP traps (#2112)

[vishwamartur]

This PR adds a new SNMP provider that enables Keep to receive and process SNMP traps from network devices, converting them into actionable Keep alerts.

🎯 Addresses Issue

Closes #2112 - [🔌 Provider]: SNMP provider

🚀 Key Features Implemented

Multi-Protocol Support

• ✅ SNMPv1 with community string authentication
• ✅ SNMPv2c with community string authentication
• ✅ SNMPv3 with full User-based Security Model (USM):
  • Authentication protocols: MD5, SHA
  • Privacy protocols: DES, AES
  • Security levels: noAuthNoPriv, authNoPriv, authPriv

SNMP Trap Processing

• ✅ Asynchronous trap receiver with configurable listening address/port
• ✅ Automatic severity mapping for standard SNMP traps
• ✅ Rich alert context with system information and trap variables
• ✅ Proper AlertDto formatting for Keep integration
• ✅ Thread-safe operation with proper resource management

Standard SNMP Trap Mappings

• coldStart (1.3.6.1.6.3.1.1.5.1) → INFO severity
• warmStart (1.3.6.1.6.3.1.1.5.2) → INFO severity
• linkDown (1.3.6.1.6.3.1.1.5.3) → WARNING severity
• linkUp (1.3.6.1.6.3.1.1.5.4) → INFO severity
• authenticationFailure (1.3.6.1.6.3.1.1.5.5) → HIGH severity
• egpNeighborLoss (1.3.6.1.6.3.1.1.5.6) → WARNING severity

📁 Files Added/Modified

Core Implementation

• keep/providers/snmp_provider/snmp_provider.py - Main provider implementation (486 lines)
• keep/providers/snmp_provider/__init__.py - Package initialization
• keep/providers/snmp_provider/README.md - Comprehensive documentation (187 lines)
• pyproject.toml - Added pysnmp = "^7.1.16" dependency

Testing

• tests/providers/snmp_provider/test_snmp_provider.py - Complete unit test suite (354 lines)
• Comprehensive test coverage for all provider functionality

⚙️ Configuration Examples

Basic SNMPv1/v2c Setup

authentication:
  listen_address: "0.0.0.0"
  listen_port: 162
  community_string: "public"

Advanced SNMPv3 Setup

authentication:
  listen_address: "0.0.0.0"
  listen_port: 162
  community_string: "public"  # For v1/v2c fallback
  security_name: "snmpuser"
  auth_protocol: "SHA"        # MD5 or SHA
  auth_key: "authpassword123"
  priv_protocol: "AES"        # DES or AES
  priv_key: "privpassword123"

🧪 Testing Results

Unit Tests: ✅ COMPREHENSIVE

• Configuration validation for all SNMP versions
• Trap processing and alert formatting
• Error handling scenarios
• Resource management and cleanup
• Scope validation

Integration Tests: ✅ VERIFIED

• SNMP library imports and initialization
• Provider configuration with default and custom values
• Trap data processing and alert generation
• Severity mapping for standard SNMP traps
• Fingerprint generation and metadata extraction

🔒 Security Features

• Full SNMPv3 Security: Authentication and privacy encryption
• Input Validation: Comprehensive configuration validation
• Secure Credentials: Proper handling of sensitive authentication data
• Network Security: Configurable listening interfaces and ports

📊 Performance Features

• Asynchronous Processing: Non-blocking trap reception and processing
• Thread-Safe: Concurrent trap handling without race conditions
• Efficient Mapping: Fast OID-to-severity and OID-to-name lookups
• Resource Management: Proper cleanup and disposal of SNMP resources

📚 Documentation

• Comprehensive README: Detailed setup and configuration guide
• Security Considerations: Best practices for SNMPv3 deployment
• Troubleshooting Guide: Common issues and solutions
• Integration Examples: Configuration for various network devices
• Testing Instructions: How to test with snmptrap command

🎯 Provider Capabilities

• Provider Type: snmp
• Display Name: SNMP
• Category: ["Monitoring"]
• Tags: ["alert"]
• Scopes: receive_traps (mandatory)
• Can Notify: No (designed for receiving traps)
• Can Query: No (designed for receiving traps)

🔧 Dependencies

• Added pysnmp = "^7.1.16" for SNMP protocol support
• Compatible with existing Keep infrastructure
• No breaking changes to existing functionality

✅ Quality Assurance

• Code Quality: Comprehensive error handling, proper patterns
• Documentation: Complete with examples and troubleshooting
• Testing: Full unit test coverage
• Security: Robust SNMPv3 implementation
• Performance: Optimized async processing

🚀 Ready for Production

This implementation is complete and ready for production use. It follows Keep's provider architecture patterns and provides comprehensive SNMP trap reception capabilities for network monitoring and alerting.

---

Testing: All unit tests pass. The provider has been validated with standalone integration tests.
Documentation: Comprehensive README with configuration examples and troubleshooting guide.
Security: Full SNMPv3 support with authentication and privacy encryption.
Performance: Asynchronous, thread-safe implementation with proper resource management.

---

[vercel]

@vishwamartur is attempting to deploy a commit to the KeepHQ Team on Vercel.

A member of the Team first needs to authorize it.