A peer-to-peer network attack where malicious actors isolate a target node from the honest network by controlling all of its incoming and outgoing connections, preventing it from receiving legitimate information. In KERI, eclipse attacks represent the primary threat vector that must be mitigated through watcher network expansion.
Related Concepts
No related concepts available
Comprehensive Explanation
eclipse-attack
Conceptual Definition
An eclipse attack is a network-layer attack specific to peer-to-peer (P2P) distributed systems where an adversary attempts to isolate a target node from the rest of the honest network by monopolizing all of its network connections. The attack derives its name from the metaphor of "eclipsing" or blocking the target's view of the legitimate network, effectively creating a false reality for the isolated node.
The fundamental vulnerability exploited by eclipse attacks stems from an inherent architectural constraint of P2P networks: nodes cannot maintain connections with all other nodes simultaneously. Instead, each node can only connect with a limited number of neighboring peers. This limitation creates an attack surface where a sufficiently resourced adversary can position themselves as all of a target's neighbors, thereby controlling all information flowing to and from that node.
In traditional blockchain networks like Bitcoin, this limitation manifests as specific connection constraints—typically a maximum of 117 incoming TCP connections and 8 outgoing TCP connections by default. While these numbers vary across different P2P implementations, the underlying principle remains: connection scarcity creates isolation vulnerability.
Historical Context
Eclipse attacks emerged as a recognized threat vector with the proliferation of P2P networks, particularly in cryptocurrency systems. The attack represents a more sophisticated evolution of network-layer attacks, moving beyond simple denial-of-service to information manipulation through isolation.
In blockchain contexts, eclipse attacks enable various secondary exploits:
Double-spend attacks: Isolated nodes can be fed conflicting transaction histories
Mining manipulation: Miners can be isolated to waste computational resources on orphaned blocks
Consensus disruption: Network partitioning can prevent consensus formation
Implementation Notes
Watcher Network Deployment
Infrastructure Requirements:
Deploy watchers across multiple cloud providers (AWS, Azure, GCP, etc.)
Use diverse geographic regions (different continents, legal jurisdictions)
Implement redundant network connectivity with multiple ISPs
Establish monitoring for watcher availability and connectivity health
Minimum Viable Watcher Network:
At least 3-5 watchers for basic protection
Geographic distribution across at least 2 continents
No shared infrastructure between watchers
Independent network paths to each watcher
Enterprise Watcher Network:
10+ watchers with global distribution
Multiple watchers per major geographic region
Diverse hosting providers and network infrastructure
Continuous monitoring and automated failover
Regular security audits and penetration testing
Witness Selection Strategy
Diversity Criteria:
Select witnesses from independent organizations
Avoid witnesses sharing infrastructure or network providers
Consider legal jurisdiction diversity
Evaluate witness operational security practices
Assess witness availability and reliability history
Witness Pool Configuration:
Minimum 3 witnesses for basic multi-signature protection
5-7 witnesses for standard deployments
10+ witnesses for high-security applications
Implement witness rotation schedules (quarterly or semi-annually)
Maintain backup witness relationships for rapid replacement
Connection Monitoring
Anomaly Detection:
Monitor connection counts to watchers and witnesses
Alert on sudden connectivity loss to multiple nodes
Track network topology changes
Detect unusual routing patterns
Implement automated health checks with configurable thresholds
Response Procedures:
Establish out-of-band communication channels (phone, Signal, etc.)
Document escalation procedures for suspected eclipse attacks
Maintain emergency contact information for witnesses and watcher operators
The difficulty of executing eclipse attacks varies significantly based on network topology, connection management policies, and the resources available to attackers. While theoretically possible due to connection limitations, successful eclipse attacks require substantial coordination and resources, making them non-trivial to execute against well-designed P2P networks.
KERI's Approach
According to KERI protocol designers Samuel Smith and Phil Feairheller, eclipse attacks represent the only viable attack vector against KERI systems. This remarkable assertion reflects KERI's success in cryptographically eliminating other common attack vectors through its architecture, leaving network-layer isolation as the remaining concern.
Why Eclipse Attacks Are KERI's Primary Threat
KERI's cryptographic security model successfully addresses:
Key compromise: Through pre-rotation and quantum-safe recovery mechanisms
History manipulation: Through hash-chained KEL structures with backward and forward chaining
Consensus attacks: Through duplicity-evident data structures rather than consensus mechanisms
However, KERI cannot cryptographically prevent an attacker from controlling the network connections of a target node. If an attacker successfully eclipses a validator or controller, they can:
KERI's defense against eclipse attacks centers on expanding watcher network reach. The security guarantee scales directly with watcher network size and diversity:
Watcher Network Properties:
Watchers operate in "promiscuous mode"—maintaining copies of KERLs without being designated by controllers
Each watcher provides an independent verification path for key events
Geographic and organizational diversity of watchers increases eclipse attack difficulty exponentially
Security Scaling:
The larger the watcher network reach, the more difficult eclipse attacks become. An attacker must not only isolate the target node but also prevent it from connecting to any watcher in the entire network. As watcher count and distribution increase, the resources required for successful eclipse attacks grow proportionally.
Resource Constraints:
The specification explicitly acknowledges that "the only limitation is a resource constraint." This means:
Security ceiling is determined by available resources for watcher infrastructure
No protocol-level limitation prevents arbitrary security scaling
Organizations can invest in watcher networks proportional to their security requirements
The trade-off is purely economic (operational costs) rather than architectural
Witness Pool Diversity
While watchers provide the primary defense, witness pools also contribute to eclipse attack resistance:
Controllers can designate geographically and organizationally diverse witnesses
Witness diversity makes it harder for attackers to eclipse all verification paths
Witness rotation allows controllers to change witness sets if compromise is suspected
Multi-witness configurations require attackers to eclipse connections to multiple independent entities
Leverage key pre-rotation for recovery if keys were compromised during eclipse
Document and analyze attack patterns for future prevention
Operational Best Practices
Network Diversity:
Never rely on single network providers
Implement multi-homing with diverse ISPs
Use overlay networks (Tor, I2P) as additional connection paths
Establish peer relationships with organizations in different networks
Monitoring and Alerting:
Continuous monitoring of watcher/witness connectivity
Automated alerts for connection anomalies
Regular verification of key state consistency across watchers
Periodic testing of recovery procedures
Governance and Policy:
Document acceptable risk levels for eclipse attacks
Establish incident response procedures
Define roles and responsibilities for attack detection and response
Regular security audits of network topology and connectivity
Conclusion
Eclipse attacks represent KERI's primary security concern precisely because KERI's cryptographic architecture has successfully eliminated other attack vectors. The defense strategy—expanding watcher network reach—provides a clear, scalable path to security that is bounded only by available resources rather than protocol limitations. Organizations deploying KERI must explicitly plan for eclipse attack mitigation through watcher network investment, witness diversity, and robust connectivity architecture. The security guarantee scales directly with investment in distributed verification infrastructure, creating a transparent and predictable security model.
Implement automated failover to backup connectivity paths
Regular testing of incident response procedures
Security Considerations
Risk Assessment:
Evaluate threat model specific to deployment context
Assess adversary capabilities and resources
Determine acceptable risk levels for eclipse attacks
Document security requirements and constraints
Regular review and update of risk assessments
Cost-Security Trade-offs:
Calculate operational costs for different watcher network sizes
Evaluate security benefits of additional watchers
Consider insurance or risk transfer mechanisms
Balance security investment with other operational priorities
Document rationale for security architecture decisions