Peer Isolation

Eclipse Attack

An eclipse attack is one of the most fundamental attacks against peer-to-peer networks. The attacker's goal is to completely isolate a target node from the honest network by controlling all of its peer connections.

In libp2p, this means filling the victim's Kademlia routing table and Connection Manager slots with attacker-controlled nodes, then severing all honest connections.

Documentation

Simulation Steps1 / 6

Healthy Network

A normal libp2p network where all peers are connected through honest mesh links. The yellow victim node has multiple honest connections for routing messages and discovering peers.

Attacker Reconnaissance

The attacker identifies the victim node and maps its connections. In libp2p, the Identify protocol (/ipfs/id/1.0.0) reveals a peer's listening addresses and supported protocols — giving the attacker the information needed to plan the eclipse.

Malicious Nodes Join

The attacker spawns malicious nodes that connect to the victim. Each Sybil node has a valid Ed25519 keypair — generating identities is cheap. They present themselves as normal peers with valid Peer IDs.

Connection Table Poisoning

Malicious nodes fill the victim's routing table (Kademlia k-buckets). They strategically choose Peer IDs close to the victim in XOR distance, increasing their probability of being selected for routing queries. The Connection Manager's high watermark forces old honest connections to be pruned.

routing_table.poisoned = 40%
victim.honest_connections -= 3

Eclipse Achieved

The victim is now fully eclipsed. All remaining honest connections are severed — the victim can only communicate through attacker-controlled nodes. Messages are censored, DHT lookups return false results, and the victim's view of the network is entirely fabricated.

victim.honest_connections = 0
victim.state = ECLIPSED
attacker.control = 100%

Defense: libp2p Mitigations

libp2p defends against eclipse attacks through: (1) Resource Manager — hard limits on per-peer connections, streams, and memory; (2) Connection Gater — filters connections at transport level; (3) GossipSub flood publishing — publishes to ALL peers above threshold, bypassing eclipsed mesh; (4) Peer scoring — low-scoring peers are pruned. These defenses make full eclipse extremely difficult in practice.

rcmgr.per_peer_limit = 16
conn_gater.blocked = [attacker_*]
gossipsub.flood_publish = true

Technical Details

Connection Manager

Maintains high/low watermarks for total connections. When the high watermark is exceeded, low-priority connections are pruned. An attacker exploits this by flooding connections.

Resource Manager

Provides defense through hard limits at system, transient, service, protocol, peer, and connection scopes. Per-peer limits prevent any single entity from consuming too many resources.

Connection Gater

Makes filtering decisions before resources are allocated. Can block connections from specific IP ranges (CIDR limits) and integrates with the Resource Manager.

Attack Simulation

The py-libp2p repository includes a full eclipse attack simulation with malicious peer behavior, bootnode poisoning, and real-time network degradation metrics.

Kademlia XOR Distance Metric

distance(a, b) = SHA256(a.id) ⊕ SHA256(b.id)

The attacker attempts to minimize this distance to 'surround' the victim's Peer ID in the Kademlia address space.