Add initial Eclipse attack simulation module with metrics collection

docs/index.rst

@@ -18,6 +18,7 @@ The Python implementation of the libp2p networking stack
 
     Examples <examples>
     API <libp2p>
+    tls-support
 
 .. toctree::
     :maxdepth: 1

docs/tls-support.rst

@@ -0,0 +1,161 @@
+Py-libp2p – TLS Support Documentation
+======================================================
+
+.. contents::
+   :depth: 2
+   :local:
+
+Overview of TLS in Libp2p
+-------------------------
+
+**Purpose of TLS in P2P networking**
+
+- Encrypts data between peers.
+- Authenticates peer identity using certificates.
+- Prevents man-in-the-middle attacks.
+
+**Integration in libp2p security modules**
+
+- TLS is one of the supported secure channel protocols (alongside Noise).
+- Negotiated during connection setup.
+
+**Current status**
+
+- **py-libp2p**: Experimental, usable for local and interop tests.
+- **go-libp2p / js-libp2p**: Stable and production-ready.
+
+Installation Requirements
+-------------------------
+
+**Python requirements**
+
+- Python 3.8+
+
+**Install with TLS support**
+
+.. code-block:: bash
+
+   pip install "libp2p[tls]"
+
+**Additional dependencies**
+
+Ubuntu / Debian:
+
+.. code-block:: bash
+
+   sudo apt install build-essential python3-dev libffi-dev libssl-dev
+
+macOS:
+
+.. code-block:: bash
+
+   brew install openssl
+
+Enabling TLS in py-libp2p
+-------------------------
+
+**Working example – Listener and Dialer**
+
+Listener node:
+
+.. code-block:: python
+
+   import trio
+   from libp2p import new_host
+   from libp2p.security.tls.transport import TLSTransport
+
+   async def main():
+       host = await new_host(security_transports=[TLSTransport()])
+       await host.listen("/ip4/0.0.0.0/tcp/8000")
+       print("TLS-enabled listener at:", host.get_addrs())
+
+       await trio.sleep_forever()
+
+   if __name__ == "__main__":
+       trio.run(main())
+
+Dialer node:
+
+.. code-block:: python
+
+   import trio
+   from libp2p import new_host
+   from libp2p.security.tls.transport import TLSTransport
+   from libp2p.peer.peerinfo import info_from_p2p_addr
+
+   async def main():
+       host = await new_host(security_transports=[TLSTransport()])
+
+       addr = "/ip4/127.0.0.1/tcp/8000/p2p/QmPeerIDHere"
+       peer_info = info_from_p2p_addr(addr)
+
+       await host.connect(peer_info)
+       print("Connected securely to", peer_info.peer_id)
+
+   if __name__ == "__main__":
+       trio.run(main())
+
+**Defaults if no configuration is provided**
+
+- Generates a self-signed certificate automatically.
+
+Certificate Management
+----------------------
+
+**Generate a development certificate**
+
+.. code-block:: bash
+
+   openssl req -x509 -newkey rsa:2048 \
+     -keyout key.pem -out cert.pem \
+     -days 365 -nodes -subj "/CN=py-libp2p"
+
+- Store keys outside version control.
+- Rotate certificates every 90 days in production.
+
+Testing TLS Connections
+-----------------------
+
+**Local test steps**
+
+1. Run the listener example.
+2. Start the dialer with the listener's multiaddress.
+3. Confirm the secure connection in logs.
+
+**Interop testing**
+
+- Ensure both nodes advertise `/tls/1.0.0`.
+- Peer IDs must match certificate public keys.
+
+Security Considerations
+-----------------------
+
+- Never disable certificate verification in production.
+- Use TLS 1.3 or later.
+- Pin certificates for critical peers.
+
+Troubleshooting
+---------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - Problem
+     - Cause
+     - Solution
+   * - Certificate not trusted
+     - Self-signed without trust store entry
+     - Add cert to local trust store or disable verification **only** in testing.
+   * - Protocol negotiation failed
+     - One peer does not support `/tls/1.0.0`
+     - Enable TLS on both peers or use Noise.
+   * - SSL handshake failure
+     - TLS version mismatch or clock skew
+     - Enforce TLS 1.3, sync system clock.
+   * - `ImportError: No module named libp2p.security.tls`
+     - TLS extras not installed
+     - Run `pip install "libp2p[tls]"`.
+   * - Connection refused
+     - Port blocked or listener not running
+     - Check firewall rules and listener status.

tests/conftest.py

@@ -1,5 +1,6 @@
 import pytest
 
+
 @pytest.fixture
 def security_protocol():
-    return None
+    return None

tests/security/attack_simulation/README.md

@@ -0,0 +1,215 @@
+# Network Attack Simulation Module (py-libp2p)
+
+This module provides a **network attack simulation framework** for py-libp2p, focused on testing **P2P network security**. It is implemented as a **submodule** inside py-libp2p to simulate attacks, measure metrics, and analyze network resilience.
+
+______________________________________________________________________
+
+## Table of Contents
+
+1. [Module Overview](#module-overview)
+1. [Module Structure](#module-structure)
+1. [Setup and Usage](#setup-and-usage)
+1. [Testing](#testing)
+1. [Implementation Details](#implementation-details)
+1. [Metrics and Analysis](#metrics-and-analysis)
+1. [Roadmap](#roadmap)
+1. [Eclipse Attack Flow](#eclipse-attack-flow)
+1. [Contributing](#contributing)
+
+______________________________________________________________________
+
+## Module Overview
+
+This module simulates network attacks in a controlled py-libp2p environment. Current focus:
+
+- **Eclipse attacks** by poisoning DHTs
+- Metrics collection for network health and attack effectiveness
+- Configurable attack scenarios and network topologies
+- Foundation for future attack types (Sybil, flooding, protocol exploits)
+
+All work is **local in py-libp2p** with a planned migration path to `libp2p/interop`.
+
+______________________________________________________________________
+
+## Module Structure
+
+```
+tests/security/attack_simulation/
+├── eclipse_attack/
+│   ├── test_eclipse_simulation.py      # Main test suite for Eclipse attacks
+│   ├── malicious_peer.py               # Malicious peer behavior implementation
+│   ├── metrics_collector.py            # Collects attack metrics during simulation
+│   ├── attack_scenarios.py             # Defines Eclipse attack scenarios
+│   ├── network_builder.py              # Builds test networks with honest/malicious nodes
+│   ├── real_network_builder.py         # Real libp2p host integration
+│   ├── real_metrics_collector.py       # Real network performance metrics
+│   └── test_real_eclipse_simulation.py # Integration tests with actual DHTs
+├── utils/
+│   ├── attack_metrics.py               # Metrics calculation utilities
+│   ├── peer_behavior_simulator.py      # Simulates peer behaviors (honest and malicious)
+│   └── network_monitor.py              # Monitors network state and connectivity
+├── config/
+│   ├── attack_configs.py               # Configuration options for attacks
+│   └── network_topologies.py           # Predefined network topologies
+└── README.md                           # Module documentation and usage guide
+```
+
+______________________________________________________________________
+
+## Setup and Usage
+
+1. **Activate py-libp2p virtual environment**:
+
+```bash
+source .venv/bin/activate
+```
+
+2. **Run the simulation framework tests**:
+
+```bash
+pytest -v tests/security/attack_simulation/eclipse_attack/test_eclipse_simulation.py
+```
+
+3. **Run the REAL integration tests** (🆕 **Actual libp2p network attacks**):
+
+```bash
+pytest -v tests/security/attack_simulation/eclipse_attack/test_real_eclipse_simulation.py
+```
+
+4. **Run individual attack demo**:
+
+```bash
+python tests/security/attack_simulation/eclipse_attack/test_real_eclipse_simulation.py demo
+```
+
+> Tests validate both simulated and real network attack scenarios.
+
+______________________________________________________________________
+
+## Testing
+
+The module provides **two levels** of testing:
+
+### **Level 1: Simulation Framework** (Original Implementation)
+- Eclipse attack tests (`eclipse_attack/test_eclipse_simulation.py`)
+- Utilities: metrics, network monitoring, peer behavior
+- **Fast execution**, **conceptual validation**
+
+### **Level 2: Real Integration Tests** 🆕 (New Enhancement)
+- Real libp2p host creation using `HostFactory`
+- Actual DHT manipulation with `KadDHT` instances  
+- Real network performance measurement
+- **Slower execution**, **actual security testing**
+
+Passing tests confirm:
+
+- ✅ **Simulation Framework**: Network setup, malicious behaviors, metrics collection  
+- ✅ **Real Integration**: Actual libp2p attacks, DHT poisoning, performance degradation
+
+______________________________________________________________________
+
+## Implementation Details
+
+### **Simulation Layer** (Original)
+
+#### Malicious Peer
+```python
+class MaliciousPeer:
+    """Simulates malicious peer behavior"""
+```
+
+#### Network Builder
+```python
+class AttackNetworkBuilder:
+    """Constructs configurable test networks for attack simulations"""
+```
+
+### **Real Integration Layer** 🆕 (New Enhancement)
+
+#### Real Malicious Peer
+```python
+class RealMaliciousPeer(MaliciousPeer):
+    """Real malicious peer that manipulates actual DHT instances"""
+
+    async def poison_real_dht_entries(self, target_dht: KadDHT):
+        # Actually poison real DHT routing tables
+
+    async def flood_real_peer_table(self, target_dht: KadDHT):  
+        # Flood real DHT with malicious entries
+```
+
+#### Real Network Builder
+```python  
+class RealNetworkBuilder(AttackNetworkBuilder):
+    """Builds networks with real libp2p hosts and DHT instances"""
+
+    async def create_real_eclipse_test_network(self):
+        # Uses HostFactory to create actual libp2p hosts
+        # Creates real KadDHT instances
+        # Forms realistic network topologies
+```
+
+#### Real Metrics Collector
+```python
+class RealAttackMetrics(AttackMetrics):
+    """Collects actual performance metrics from real libp2p networks"""
+
+    async def measure_complete_attack_cycle(self):
+        # Measures real DHT lookup degradation
+        # Tracks actual network connectivity loss
+        # Calculates genuine recovery metrics
+```
+
+______________________________________________________________________
+
+## Metrics and Analysis
+
+Tracked metrics:
+
+- DHT lookup success/failure rates
+- Peer table contamination
+- Network connectivity
+- Attack effectiveness and recovery metrics
+
+```python
+class AttackMetrics:
+    """Metrics collection and analysis framework"""
+```
+
+______________________________________________________________________
+
+## Roadmap
+
+**Phase 1 (Current)**: Eclipse attack simulation
+
+**Phase 2**: Extended attacks (Sybil, flooding, connection exhaustion)
+
+**Phase 3**: Cross-implementation testing in `libp2p/interop`
+
+______________________________________________________________________
+
+## Eclipse Attack Flow
+
+```mermaid
+flowchart TD
+    A[Network Builder] --> B[Honest Peers]
+    A --> C[Malicious Peers]
+    C --> D[Poison DHT Entries]
+    C --> E[Flood Peer Tables]
+    B --> F[Perform Lookups]
+    D --> F
+    E --> F
+    F --> G[Metrics Collector]
+    G --> H[Attack Analysis & Reporting]
+```
+
+> This flow illustrates the lifecycle of an Eclipse attack: the network is built, malicious peers poison the DHT and flood peer tables, honest peers perform lookups, and metrics are collected and analyzed.
+
+______________________________________________________________________
+
+## Contributing
+
+1. Add new Eclipse attack scenarios under eclipse_attack, and shared utilities for any attack under utils.
+1. Implement new metrics or monitoring tools
+1. Write corresponding pytest tests
+1. Submit PR to py-libp2p for review