completed event entropy analyzer spam detection

[buggythanos]

Description

This PR adds an Event Entropy Analyzer for detecting spam patterns in blockchain events on BNB Smart Chain (BSC). The tool analyzes Transfer and Approval events from smart contracts using Shannon entropy calculations to identify suspicious patterns that indicate automated spam activity.

By measuring the randomness and diversity of event data (addresses and values), the analyzer can distinguish between legitimate activity and spam. It calculates entropy scores, detects repetitive patterns, and provides actionable recommendations for security teams and developers.

Key Features:

• Shannon Entropy Calculation: Measures randomness/diversity in event data (addresses and values)
• Pattern Detection: Identifies repeated addresses, values, and sequential block patterns
• Spam Scoring System: Combines entropy and patterns into a 0-100 spam likelihood score
• Spam Level Classification: Categorizes results as LOW, MEDIUM, HIGH, or CRITICAL
• Intelligent Recommendations: Provides actionable insights based on detected patterns
• Support for Multiple Event Types: Analyzes both Transfer and Approval events
• Modern Web UI: Dark mode interface with interactive analysis visualization
• RESTful API: /api/analyze endpoint for programmatic access
• CLI Support: Command-line interface for batch analysis

Spam Detection Indicators:

• Many events from the same address (bot activity)
• Many events to the same address (airdrop spam)
• Identical values across multiple events
• Events occurring in sequential blocks
• Low unique address ratio relative to total events
• Low entropy (lack of diversity in data)

Spam Score Components:

• Entropy Component (40 points): Lower entropy = higher spam score
• Repetition Component (30 points): Higher repetition = higher spam score
• Sequential Blocks (20 points): More sequential blocks = higher spam score
• Unique Address Ratio (10 points): Lower ratio = higher spam score

Fixes # (issue)

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

The implementation includes a comprehensive test suite with 33 unit tests covering:

1. Entropy Calculation:

   • Empty array handling (returns 0)
   • Single value handling (returns 0)
   • All identical values (returns 0)
   • Maximum entropy for all unique values
   • Correct entropy calculation for mixed values
   • Large array handling (performance testing)

2. Pattern Analysis:

   • Empty events handling (returns zeros)
   • Repeated address detection (from and to)
   • Repeated value detection
   • Sequential block detection
   • Non-sequential block handling

3. Spam Score Calculation:

   • Zero score for no events
   • High score for low entropy scenarios
   • Low score for high entropy scenarios
   • Score bounds validation (0-100)
   • Score increase with high repetition

4. Spam Level Classification:

   • LOW level for scores < 40
   • MEDIUM level for scores 40-59
   • HIGH level for scores 60-79
   • CRITICAL level for scores >= 80

5. Recommendation Generation:

   • Recommendations for high spam levels
   • Detection of repeated from address patterns
   • Detection of repeated to address patterns
   • Detection of repeated value patterns
   • Detection of sequential blocks patterns
   • Low entropy detection
   • Low unique addresses ratio detection
   • Positive messages for normal patterns

6. Complete Event Entropy Analysis:

   • Default analysis for empty events
   • Analysis of events with high diversity
   • Spam detection in repetitive events
   • Correct unique address calculation
   • Recommendations included in results

Test execution:

npm test

All 33 tests pass successfully. The test suite uses Jest with comprehensive edge case coverage to ensure reliable spam detection across various scenarios.

Manual testing:

• Web UI tested by accessing http://localhost:3000 and analyzing various contract addresses and block ranges
• API endpoint tested via POST requests to /api/analyze with different contract addresses, event types, and block ranges
• CLI mode tested with different contract addresses, event types (Transfer/Approval), and block ranges
• Server mode tested by running npm start without arguments and accessing the web interface
• Tested with real BSC contracts including USDT and other high-volume tokens
• Validated spam detection accuracy with known spam patterns and legitimate activity

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Additional notes:

• Includes comprehensive README.md with setup instructions, usage examples, API documentation, and technical details
• Includes setup.sh script for one-command installation and setup
• Includes env.template for environment variable configuration
• TypeScript implementation with full type safety and comprehensive interfaces
• Uses ethers.js v6 for blockchain interactions and event parsing
• Express server with RESTful API endpoints
• Modern, responsive web UI with dark mode styling
• Graceful error handling for network issues, rate limits, and invalid inputs
• Support for both Transfer and Approval event types
• Efficient entropy calculation using Shannon entropy formula: H(X) = -Σ P(x) * log2(P(x))
• Weighted entropy calculation combining address entropy (70%) and value entropy (30%)
• Comprehensive pattern detection for various spam indicators
• Actionable recommendations based on detected patterns

[vivixu-cmd]

Congratulations! You have received a Cookbook reward. Please reply with your BSC wallet address.Thanks

[buggythanos]

Hi there, thank you!
0x4e5d4a29F7b02c8cf1310D112A42231Bde049180

[Shemse1]

0x811009f3aB27f5Ea1292decD152325103b249bdc

[Dominicanopic5]

Descripción

Esta solicitud de extracción añade un analizador de entropía de eventos para detectar patrones de spam en los eventos de la cadena de bloques de BNB Smart Chain (BSC). La herramienta analiza los eventos de transferencia y aprobación de los contratos inteligentes mediante cálculos de entropía de Shannon para identificar patrones sospechosos que indiquen actividad de spam automatizada.

Al medir la aleatoriedad y la diversidad de los datos de eventos (direcciones y valores), el analizador puede distinguir entre actividad legítima y spam. Calcula puntuaciones de entropía, detecta patrones repetitivos y proporciona recomendaciones prácticas para los equipos de seguridad y los desarrolladores.

Características principales:

• Cálculo de la entropía de Shannon : Mide la aleatoriedad/diversidad en los datos de eventos (direcciones y valores).
• Detección de patrones : Identifica direcciones, valores y patrones de bloques secuenciales repetidos.
• Sistema de puntuación de spam : Combina la entropía y los patrones en una puntuación de probabilidad de spam de 0 a 100.
• Clasificación del nivel de spam : Categoriza los resultados como BAJO, MEDIO, ALTO o CRÍTICO.
• Recomendaciones inteligentes : Proporciona información práctica basada en patrones detectados.
• Compatibilidad con múltiples tipos de eventos : analiza tanto los eventos de transferencia como los de aprobación.
• Interfaz web moderna : Interfaz en modo oscuro con visualización de análisis interactivo.
• API RESTful : /api/analyzepunto final para acceso programático
• Soporte CLI : Interfaz de línea de comandos para análisis por lotes

Indicadores de detección de spam:

• Muchos eventos desde la misma dirección (actividad de bots)
• Muchos eventos a la misma dirección (spam de airdrop)
• Valores idénticos en múltiples eventos
• Eventos que ocurren en bloques secuenciales
• Baja proporción de direcciones únicas en relación con el total de eventos.
• Baja entropía (falta de diversidad en los datos)

Componentes de la puntuación de spam:

• Componente de entropía (40 puntos): Menor entropía = mayor puntuación de spam
• Componente de repetición (30 puntos): Mayor repetición = mayor puntuación de spam
• Bloques secuenciales (20 puntos): Más bloques secuenciales = mayor puntuación de spam
• Índice de direcciones únicas (10 puntos): Un índice menor equivale a una puntuación de spam más alta.

Soluciona el problema #

Tipo de cambio

Por favor, elimine las opciones que no sean relevantes.

• Nueva función (cambio que no afecta la compatibilidad y que añade funcionalidad)
• Corrección de errores (cambio que no afecta la funcionalidad y que soluciona un problema)
• Cambio incompatible (corrección o característica que provocaría que la funcionalidad existente no funcione como se espera).
• Este cambio requiere una actualización de la documentación.

¿Cómo se ha probado esto?

La implementación incluye un conjunto completo de pruebas con 33 pruebas unitarias que cubren:

1. Cálculo de la entropía :

   • Manejo de matrices vacías (devuelve 0)
   • Manejo de valores únicos (devuelve 0)
   • Todos los valores idénticos (devuelve 0)
   • Entropía máxima para todos los valores únicos
   • Cálculo correcto de la entropía para valores mixtos
   • Manejo de matrices grandes (pruebas de rendimiento)

2. Análisis de patrones :

   • Manejo de eventos vacíos (devuelve ceros)
   • Detección de direcciones repetidas (desde y hacia)
   • Detección de valores repetidos
   • Detección de bloques secuenciales
   • Manejo de bloques no secuenciales

3. Cálculo de la puntuación de spam :

   • Puntuación cero por ningún evento
   • Puntuación alta para escenarios de baja entropía.
   • Puntuación baja para escenarios de alta entropía.
   • Validación de los límites de puntuación (0-100)
   • La puntuación aumenta con la repetición.

4. Clasificación del nivel de spam :

   • Nivel BAJO para puntuaciones < 40
   • Nivel MEDIO para puntuaciones de 40 a 59.
   • Nivel ALTO para puntuaciones de 60 a 79
   • Nivel CRÍTICO para puntuaciones >= 80

5. Generación de recomendaciones :

   • Recomendaciones para niveles altos de spam
   • Detección de patrones de direcciones repetidas
   • Detección de patrones repetidos para dirigirse a
   • Detección de patrones de valores repetidos
   • Detección de patrones de bloques secuenciales
   • detección de baja entropía
   • Detección de baja proporción de direcciones únicas
   • Mensajes positivos para patrones normales

6. Análisis completo de la entropía del evento :

   • Análisis predeterminado para eventos vacíos
   • Análisis de eventos con alta diversidad
   • Detección de spam en eventos repetitivos
   • Cálculo correcto de la dirección única
   • Recomendaciones incluidas en los resultados

Ejecución de la prueba:

npm test

Las 33 pruebas se superaron con éxito. El conjunto de pruebas utiliza Jest con una cobertura exhaustiva de casos extremos para garantizar una detección de spam fiable en diversos escenarios.

Pruebas manuales:

• La interfaz web se probó accediendo http://localhost:3000y analizando diversas direcciones de contrato y rangos de bloques.
• El punto final de la API se probó mediante solicitudes POST /api/analyzecon diferentes direcciones de contrato, tipos de eventos y rangos de bloques.
• Modo CLI probado con diferentes direcciones de contrato, tipos de eventos (Transferencia/Aprobación) y rangos de bloques.
• Se probó el modo servidor ejecutándolo npm startsin argumentos y accediendo a la interfaz web.
• Probado con contratos BSC reales, incluidos USDT y otros tokens de alto volumen.
• Precisión de detección de spam validada con patrones de spam conocidos y actividad legítima

Lista de verificación:

• Mi código sigue las directrices de estilo de este proyecto.
• He realizado una autoevaluación de mi propio código.
• He comentado mi código, especialmente en las áreas difíciles de entender.
• He realizado los cambios correspondientes en la documentación.
• Mis cambios no generan nuevas advertencias.
• He añadido pruebas que demuestran que mi solución es efectiva o que mi función funciona.
• Las pruebas unitarias nuevas y existentes pasan localmente con mis cambios.

Notas adicionales:

• Incluye un archivo README.md completo con instrucciones de configuración, ejemplos de uso, documentación de la API y detalles técnicos.
• Incluye setup.shscript para instalación y configuración con un solo comando.
• Incluye env.templatela configuración de variables de entorno.
• Implementación de TypeScript con seguridad de tipos completa e interfaces exhaustivas.
• Utiliza ethers.js v6 para las interacciones con la cadena de bloques y el análisis de eventos.
• Servidor Express con puntos finales de API RESTful
• Interfaz de usuario web moderna y adaptable con estilo de modo oscuro.
• Manejo de errores adecuado para problemas de red, límites de velocidad y entradas no válidas.
• Compatibilidad con los tipos de eventos de transferencia y aprobación.
• Cálculo eficiente de la entropía mediante la fórmula de entropía de Shannon:H(X) = -Σ P(x) * log2(P(x))
• Cálculo de entropía ponderada que combina la entropía de la dirección (70%) y la entropía del valor (30%).
• Detección integral de patrones para diversos indicadores de spam
• Recomendaciones prácticas basadas en patrones detectados