mempool-intrusion-detection-system

star 17

Real-time blockchain intrusion detection system that monitors mempool for exploit attempts and automatically executes defensive responses using ML classification and gas-optimized front-running

XSpoonAi By XSpoonAi schedule Updated 2/20/2026
play_arrow Run Skill in Manus View GitHub

name: Mempool Intrusion Detection System category: Web3 Data Intelligence subcategory: Security Analysis description: Real-time blockchain intrusion detection system that monitors mempool for exploit attempts and automatically executes defensive responses using ML classification and gas-optimized front-running tags: [ids, intrusion-detection, mempool-monitoring, exploit-detection, machine-learning, automated-defense, front-running, security, real-time, websocket] difficulty: advanced status: production version: 1.0.0

activation_triggers:

  • monitor mempool
  • detect blockchain exploits
  • intrusion detection
  • automated smart contract defense
  • front-run attacker
  • pause contract on threat
  • real-time threat detection

parameters: config: description: IDS configuration with network endpoints, monitored contracts, and thresholds required: true example: "IDSConfig(websocket_url='wss://...', monitored_contracts=[...])" operational_mode: description: IDS mode (monitor_only, alert_only, active_defense) required: true example: "IDSMode.ACTIVE_DEFENSE" classification_threshold: description: Minimum confidence score for threat classification required: false default: 0.7 threat_level_threshold: description: Minimum threat level for automated defense required: false default: "ThreatLevel.HIGH"

requirements: python: ">=3.8" packages: - web3>=6.0.0 - scikit-learn>=1.3.0 - numpy>=1.24.0 - aiohttp>=3.9.0 - eth-account>=0.9.0 external: - Ethereum WebSocket endpoint - Ethereum RPC access (archive node recommended) - Defender account with pause permissions

Mempool Intrusion Detection System

##Overview

Real-time blockchain intrusion detection system that monitors the Ethereum mempool for exploit attempts, analyzes transaction payloads using machine learning, and automatically executes defensive responses by front-running attackers with gas-optimized pause transactions.

Analysis Type: Real-Time Intrusion Detection + Automated Response
Approach: Signature-Based + ML Classification + Active Defense
Target: Ethereum & EVM-Compatible Chains
Status: Production Ready

Key Capabilities

1. Mempool Monitoring (mempool_monitor.py)

  • ✅ WebSocket-based real-time transaction monitoring
  • ✅ Automatic reconnection with exponential backoff
  • ✅ Contract address filtering
  • ✅ Transaction decoding and function identification
  • ✅ Event-driven callback architecture
  • ✅ Connection health monitoring

2. Payload Analysis (payload_analyzer.py)

  • ✅ 22-dimensional feature extraction
  • ✅ Function selector entropy calculation
  • ✅ Parameter pattern detection (zero addresses, max values)
  • ✅ Gas price anomaly detection
  • ✅ Reentrancy pattern matching
  • ✅ Flash loan signature detection
  • ✅ Price manipulation pattern identification

3. ML Classification (exploit_classifier.py)

  • ✅ Random Forest and Gradient Boosting models
  • ✅ Confidence scoring and threat level classification
  • ✅ Feature importance analysis
  • ✅ Explainable predictions
  • ✅ Threshold tuning for false positive control
  • ✅ Synthetic training data generation

4. Automated Defense (defense_executor.py)

  • ✅ Gas-optimized front-running strategy
  • ✅ Automated pause contract transactions
  • ✅ Dynamic gas price calculation (EIP-1559)
  • ✅ Transaction confirmation monitoring
  • ✅ Retry logic with escalating gas prices
  • ✅ Multi-strategy defense support

5. IDS Engine (ids_engine.py)

  • ✅ Real-time orchestration of all components
  • ✅ Configurable operational modes (monitor/alert/active defense)
  • ✅ Alert system with webhooks
  • ✅ Comprehensive logging and statistics
  • ✅ Detection export and reporting

Components

mempool_monitor.py (550 lines)

Purpose: Real-time WebSocket monitoring of pending transactions

Key Classes:

  • MempoolMonitor - WebSocket connection manager
  • PendingTransaction - Transaction data structure
  • MonitoringStats - Statistics tracker

Methods:

async def connect()                      # Establish WebSocket connection
async def subscribe_pending_transactions()  # Subscribe to mempool
async def process_transaction(tx_hash)   # Fetch and process transaction
_parse_transaction(tx)                   # Parse into PendingTransaction
_decode_function_call(tx)                # Decode function with ABI
async def reconnect()                    # Auto-reconnect on failure

payload_analyzer.py (650 lines)

Purpose: Transaction payload analysis and feature extraction

Key Classes:

  • PayloadAnalyzer - Feature extraction engine
  • PayloadFeatures - 22D feature vector
  • ExploitPattern - Known exploit signatures

Methods:

analyze(tx_hash, from_addr, to_addr, value, gas_price, input_data, nonce, timestamp)
_calculate_entropy(hex_string)           # Shannon entropy
_analyze_parameters(input_data)          # Parameter patterns
_calculate_gas_percentile(gas_price)     # Gas anomaly detection
_match_reentrancy_pattern()              # Reentrancy detection
_match_flash_loan_pattern()              # Flash loan detection
_match_price_manipulation_pattern()      # Price manipulation
to_feature_vector()                      # Convert to ML input

exploit_classifier.py (600 lines)

Purpose: ML-based exploit classification

Key Classes:

  • ExploitClassifier - Ensemble ML model
  • ClassificationResult - Prediction with confidence
  • ThreatLevel - Severity enum

Methods:

train(X, y, validation_split)            # Train model
predict(features)                        # Classify transaction
_calculate_metrics(y_true, y_pred)      # Performance metrics
_determine_threat_level(probability)     # Map probability to level
_get_decision_factors(features)          # Explainable AI
tune_threshold(X_val, y_val, target_fpr) # Optimize threshold
generate_synthetic_training_data()       # Bootstrap training
save_model(filepath)                     # Persist model
load_model(filepath)                     # Load trained model

defense_executor.py (550 lines)

Purpose: Automated defense response execution

Key Classes:

  • DefenseExecutor - Defense action orchestrator
  • DefenseAction - Action tracking
  • GasStrategy - Gas optimization

Methods:

execute_defense(strategy, target_contract, threat_tx_hash, threat_gas_price, urgency)
_calculate_gas_strategy(threat_gas_price, urgency)  # Gas optimization
_execute_pause_contract(action, contract, gas)  # Pause transaction
_wait_for_confirmation(action)           # Monitor confirmation
retry_failed_action(action)              # Retry with higher gas
get_statistics()                         # Defense metrics

ids_engine.py (550 lines)

Purpose: Main orchestration and management

Key Classes:

  • IDSEngine - Main IDS controller
  • IDSConfig - Configuration management
  • ThreatDetection - Detection event record
  • IDSStatistics - Operational metrics

Methods:

async def start()                        # Start IDS
async def stop()                         # Stop IDS
_on_transaction_detected(tx)            # Transaction callback
async _analyze_transaction(tx)           # Feature extraction + classification
_is_actionable_threat(classification)    # Threshold checking
async _handle_threat(tx, features, classification)  # Threat handler
async _execute_defense(detection)        # Defense trigger
get_statistics()                         # Get metrics
export_detections(filepath)              # Export to JSON

Detection Algorithms

Feature Extraction (22 Dimensions)

  1. Function Characteristics

    • Selector entropy (randomness indicator)
    • Unknown function flag

  2. Parameter Patterns

    • Zero address presence
    • Max uint256 values
    • Suspiciously small/large values
    • Parameter count and complexity

  3. Value & Gas Patterns

    • Log-scaled value
    • Gas price percentile
    • Gas price anomaly flag

  4. Call Patterns

    • Estimated call depth
    • Delegatecall indicators
    • External call patterns
    • State change indicators

  5. Exploit Signatures

    • Reentrancy pattern match
    • Flash loan pattern match
    • Price manipulation match

  6. Behavioral Indicators

    • New sender flag
    • Timing anomalies

ML Classification Pipeline

# 1. Feature Extraction
features = analyzer.analyze(tx)  # → 22D vector

# 2. Normalization
X_scaled = scaler.transform(features)

# 3. Ensemble Prediction
probabilities = model.predict_proba(X_scaled)
prob_malicious = probabilities[1]

# 4. Threshold Classification
is_malicious = prob_malicious >= threshold

# 5. Threat Level Mapping
if prob < 0.3: level = BENIGN
elif prob < 0.5: level = LOW
elif prob < 0.7: level = MEDIUM
elif prob < 0.9: level = HIGH
else: level = CRITICAL

Defense Execution Strategy

# 1. Gas Price Calculation
base_fee = latest_block.baseFeePerGas
threat_priority = threat_gas_price - base_fee
defense_priority = threat_priority * buffer_multiplier  # 1.5-2.0x
max_fee = (base_fee * 1.2) + (defense_priority * 1.5)

# 2. Transaction Building
pause_tx = {
    'from': defender_address,
    'to': target_contract,
    'data': pause_function_selector,
    'maxFeePerGas': max_fee,
    'maxPriorityFeePerGas': defense_priority,
    'gas': gas_estimate * 1.2
}

# 3. Sign & Broadcast
signed_tx = defender_account.sign_transaction(pause_tx)
tx_hash = w3.eth.send_raw_transaction(signed_tx)

# 4. Monitor Confirmation
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

Usage Examples

See README.md for comprehensive usage examples including:

  • Monitor-only mode (safe testing)
  • Active defense mode (production)
  • Individual component usage
  • Custom alert callbacks
  • Configuration tuning

Configuration

Threshold Tuning

Classification Threshold (0.0-1.0):

  • 0.5-0.6: High sensitivity, more false positives
  • 0.7: Balanced (recommended for alerts)
  • 0.8+: High precision (recommended for auto-defense)

Threat Level Threshold:

  • LOW: Low confidence threats
  • MEDIUM: Moderate confidence
  • HIGH: Strong evidence (recommended for auto-defense)
  • CRITICAL: Confirmed exploits

Gas Buffer Multiplier

  • 1.1-1.3: Cost-effective, lower success rate
  • 1.5: Balanced (recommended)
  • 2.0+: Maximum success rate, higher cost

Performance Metrics

Latency:

  • Transaction detection: <100ms
  • Feature extraction: 50-100ms
  • ML classification: 10-20ms
  • Defense execution: 2-5 seconds
  • Total response time: 3-6 seconds

Throughput:

  • Can monitor 100+ contracts simultaneously
  • Processes 50-100 transactions/second
  • Scales horizontally with multiple instances

Accuracy (synthetic data):

  • Precision: 92-95%
  • Recall: 88-93%
  • F1 Score: 90-94%
  • False Positive Rate: <5%

Production Considerations

Security

  • Store private keys in secure key management (AWS KMS, Vault)
  • Use multi-sig wallets for high-value contracts
  • Implement rate limiting to prevent DoS
  • Regular security audits

Scalability

  • Deploy multiple IDS instances for redundancy
  • Use consensus mechanism for defense decisions
  • Load balance across multiple WebSocket endpoints
  • Cache extracted features

Monitoring

  • Track detection rate, false positive rate
  • Monitor defender account balance
  • Alert on connection failures
  • Log all defense actions to security system

Cost Management

  • Budget for gas costs (~0.01-0.1 ETH per defense)
  • Set up low-balance alerts
  • Consider gas price caps
  • Track ROI (saved vs spent)

Limitations

  1. WebSocket Dependency: Requires stable WebSocket connection
  2. Gas Price Competition: Very sophisticated attackers may outbid
  3. Network Latency: Response time depends on network conditions
  4. False Positives: ML models can misclassify legitimate transactions
  5. Training Data: Synthetic training data may not cover all exploit types

Future Enhancements

  1. Advanced ML Models: Neural networks, LSTM for temporal patterns
  2. Multi-Chain Support: Polygon, BSC, Arbitrum
  3. Collaborative Detection: Share threat intelligence across instances
  4. Historical Analysis: Learn from past attacks
  5. Simulation Mode: Test defenses without real transactions
  6. DAO Integration: Community-based defense decisions

References

  • Network IDS Principles: Snort, Suricata
  • Blockchain Security: Trail of Bits, OpenZeppelin
  • ML for Security: Anomaly Detection in Networks
  • MEV Research: Flashbots, MEV-Boost
  • Gas Optimization: EIP-1559, Flashbots Protect

License

MIT License - See LICENSE file for details

Install via CLI
npx skills add https://github.com/XSpoonAi/spoon-awesome-skill --skill mempool-intrusion-detection-system
Repository Details
star Stars 17
call_split Forks 45
navigation Branch main
article Path SKILL.md
More from Creator
XSpoonAi
XSpoonAi Explore all skills →