manta-node 0.5b0.dev337__py3-none-any.whl → 0.5b0.dev342__py3-none-any.whl

manta_node/cli/commands/network.py

@@ -0,0 +1,1174 @@
+"""Network management command implementation for WireGuard SDN.
+
+Provides CLI tools for troubleshooting and managing WireGuard networks on the node.
+Uses wireguard-tools Python library for programmatic access to WireGuard state.
+Uses icmplib for network connectivity testing.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+
+console = Console()
+
+
+def _load_node_config():
+    """Load the node's config manager and node_id.
+
+    Returns (config_manager, node_id) or (None, None) if no config found.
+    """
+    import glob
+
+    config_files = glob.glob(str(Path.home() / ".manta/nodes/*.toml"))
+    if not config_files:
+        return None, None
+
+    try:
+        from manta_node.infrastructure.config.node_config_manager import (
+            NodeConfigManager,
+        )
+
+        config_manager = NodeConfigManager(config_files[0])
+        node_id = (
+            config_manager.config.identity.alias
+            or config_manager.config.metadata.name
+            or Path(config_files[0]).stem
+        )
+        return config_manager, node_id
+    except Exception as e:
+        console.print(f"[dim]Warning: Could not load node config: {e}[/dim]")
+        return None, None
+
+
+def list_interfaces() -> list[str]:
+    """List all WireGuard interfaces using wireguard-tools."""
+    try:
+        from wireguard_tools import WireguardDevice
+
+        devices = list(WireguardDevice.list())
+        return [device.interface for device in devices]
+    except ImportError:
+        console.print("[red]Error: wireguard-tools library not installed[/red]")
+        console.print("Install with: [cyan]pip install wireguard-tools[/cyan]")
+        return []
+    except Exception as e:
+        console.print(f"[red]Error listing interfaces: {e}[/red]")
+        return []
+
+
+def get_device_info(interface: str) -> dict | None:
+    """Get detailed device information using wireguard-tools."""
+    try:
+        from wireguard_tools import WireguardDevice, WireguardKey
+
+        device = WireguardDevice.get(interface)
+        config = device.get_config()
+
+        public_key_str = None
+        if hasattr(config, "private_key") and config.private_key:
+            # Derive public key from private key
+            private_key_obj = WireguardKey(config.private_key)
+            public_key_str = str(private_key_obj.public_key())
+        elif hasattr(config, "public_key") and config.public_key:
+            # Fallback when public_key is exposed directly on the config object
+            public_key_str = str(config.public_key)
+
+        return {
+            "interface": device.interface,
+            "public_key": public_key_str,
+            "listen_port": config.listen_port
+            if hasattr(config, "listen_port")
+            else None,
+            "fwmark": config.fwmark if hasattr(config, "fwmark") else None,
+            "peers": list(config.peers.values()) if hasattr(config, "peers") else [],
+        }
+    except ImportError:
+        console.print("[red]Error: wireguard-tools library not installed[/red]")
+        console.print("Install with: [cyan]pip install wireguard-tools[/cyan]")
+        return None
+    except Exception as e:
+        console.print(f"[red]Error getting device info: {e}[/red]")
+        return None
+
+
+def list_networks_command(args: list[str]) -> int:
+    """List all WireGuard networks on this node."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network list", description="List all active WireGuard networks"
+    )
+    parser.add_argument(
+        "--plain", action="store_true", help="Use plain text output instead of table"
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    interfaces = list_interfaces()
+
+    if not interfaces:
+        console.print("[yellow]No WireGuard interfaces found.[/yellow]")
+        console.print(
+            "\nNetworks are created when swarms with network requirements are deployed."
+        )
+        return 0
+
+    if parsed_args.plain:
+        console.print(f"Found {len(interfaces)} WireGuard interface(s):")
+        for iface in interfaces:
+            console.print(f"  - {iface}")
+    else:
+        table = Table(title="WireGuard Networks")
+        table.add_column("Interface", style="cyan")
+        table.add_column("Network ID", style="magenta")
+        table.add_column("Status", style="green")
+
+        for iface in interfaces:
+            # Extract network_id from interface name (format: wg-{swarm_id})
+            network_id = iface if iface.startswith("wg-") else f"wg-{iface}"
+            table.add_row(iface, network_id, "active")
+
+        console.print(table)
+
+    return 0
+
+
+def show_network_command(args: list[str]) -> int:
+    """Show detailed information about a specific network."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network show",
+        description="Show detailed information about a WireGuard network",
+    )
+    parser.add_argument("interface", help="Interface name (e.g., wg-abc123)")
+    parser.add_argument("--json", action="store_true", help="Output in JSON format")
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    info = get_device_info(parsed_args.interface)
+
+    if not info:
+        console.print(
+            f"[red]Interface '{parsed_args.interface}' not found or not accessible[/red]"
+        )
+        return 1
+
+    if parsed_args.json:
+        import json
+
+        console.print(json.dumps(info, indent=2))
+    else:
+        # Display formatted information
+        console.print(
+            Panel(
+                f"[bold cyan]{info['interface']}[/bold cyan]",
+                title="WireGuard Network",
+                expand=False,
+            )
+        )
+
+        console.print("\n[bold]Interface Configuration:[/bold]")
+        console.print(f"  Public Key:    {info.get('public_key', 'N/A')}")
+        console.print(f"  Listen Port:   {info.get('listen_port', 'N/A')}")
+        if info.get("fwmark"):
+            console.print(f"  Firewall Mark: {info['fwmark']}")
+
+        peer_count = len(info.get("peers", []))
+        console.print(f"\n[bold]Peers:[/bold] {peer_count} connected")
+
+        if peer_count == 0:
+            console.print("  [dim]No peers configured[/dim]")
+
+    return 0
+
+
+def list_peers_command(args: list[str]) -> int:
+    """List all peers for a specific network."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network peers",
+        description="List all peers in a WireGuard network",
+    )
+    parser.add_argument("interface", help="Interface name (e.g., wg-abc123)")
+    parser.add_argument(
+        "--plain", action="store_true", help="Use plain text output instead of table"
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    info = get_device_info(parsed_args.interface)
+
+    if not info:
+        console.print(f"[red]Interface '{parsed_args.interface}' not found[/red]")
+        return 1
+
+    peers = info.get("peers", [])
+
+    if not peers:
+        console.print(
+            f"[yellow]No peers configured for {parsed_args.interface}[/yellow]"
+        )
+        return 0
+
+    if parsed_args.plain:
+        console.print(f"Peers for {parsed_args.interface}:")
+        for i, peer in enumerate(peers, 1):
+            console.print(f"\n  Peer {i}:")
+            for key, value in peer.items():
+                console.print(f"    {key}: {value}")
+    else:
+        table = Table(title=f"Peers for {parsed_args.interface}")
+        table.add_column("Public Key", style="cyan", max_width=40)
+        table.add_column("Endpoint", style="magenta")
+        table.add_column("Allowed IPs", style="green")
+        table.add_column("Latest Handshake", style="yellow")
+        table.add_column("Transfer", style="blue")
+
+        for peer in peers:
+            # Handle both wireguard-tools format and fallback format
+            if hasattr(peer, "public_key"):
+                # wireguard-tools WireguardPeer object
+                pubkey = str(peer.public_key)[:20] + "..."
+                endpoint = str(peer.endpoint) if peer.endpoint else "N/A"
+                allowed_ips = ", ".join(str(ip) for ip in peer.allowed_ips)
+                handshake = (
+                    str(peer.latest_handshake) if peer.latest_handshake else "Never"
+                )
+                transfer = (
+                    f"↓{peer.rx_bytes} ↑{peer.tx_bytes}"
+                    if hasattr(peer, "rx_bytes")
+                    else "N/A"
+                )
+            else:
+                # Fallback dict format
+                pubkey = peer.get("public_key", "N/A")[:20] + "..."
+                endpoint = peer.get("endpoint", "N/A")
+                allowed_ips = peer.get("allowed ips", "N/A")
+                handshake = peer.get("latest handshake", "Never")
+                transfer_rx = peer.get("transfer", {}).get("received", "0 B")
+                transfer_tx = peer.get("transfer", {}).get("sent", "0 B")
+                transfer = f"↓{transfer_rx} ↑{transfer_tx}"
+
+            table.add_row(pubkey, endpoint, allowed_ips, handshake, transfer)
+
+        console.print(table)
+
+    return 0
+
+
+def show_peer_command(args: list[str]) -> int:
+    """Show detailed information about a specific peer."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network peer",
+        description="Show detailed information about a peer",
+    )
+    parser.add_argument("interface", help="Interface name (e.g., wg-abc123)")
+    parser.add_argument("peer_pubkey", help="Peer public key (or partial match)")
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    info = get_device_info(parsed_args.interface)
+
+    if not info:
+        console.print(f"[red]Interface '{parsed_args.interface}' not found[/red]")
+        return 1
+
+    # Find matching peer
+    peers = info.get("peers", [])
+    matching_peer = None
+
+    for peer in peers:
+        pubkey = (
+            str(peer.public_key)
+            if hasattr(peer, "public_key")
+            else peer.get("public_key", "")
+        )
+        if (
+            pubkey.startswith(parsed_args.peer_pubkey)
+            or parsed_args.peer_pubkey in pubkey
+        ):
+            matching_peer = peer
+            break
+
+    if not matching_peer:
+        console.print(
+            f"[red]Peer with public key matching '{parsed_args.peer_pubkey}' not found[/red]"
+        )
+        return 1
+
+    # Display peer information
+    console.print(
+        Panel(
+            "[bold cyan]Peer Details[/bold cyan]",
+            title=f"Network: {parsed_args.interface}",
+            expand=False,
+        )
+    )
+
+    if hasattr(matching_peer, "public_key"):
+        console.print("\n[bold]Identity:[/bold]")
+        console.print(f"  Public Key: {matching_peer.public_key}")
+        console.print("\n[bold]Connection:[/bold]")
+        console.print(f"  Endpoint:           {matching_peer.endpoint or 'N/A'}")
+        console.print(
+            f"  Allowed IPs:        {', '.join(str(ip) for ip in matching_peer.allowed_ips)}"
+        )
+        console.print(
+            f"  Latest Handshake:   {matching_peer.latest_handshake or 'Never'}"
+        )
+        console.print(
+            f"  Persistent Keepalive: {matching_peer.persistent_keepalive or 'Off'}"
+        )
+        if hasattr(matching_peer, "rx_bytes"):
+            console.print("\n[bold]Transfer:[/bold]")
+            console.print(f"  Received: {matching_peer.rx_bytes} bytes")
+            console.print(f"  Sent:     {matching_peer.tx_bytes} bytes")
+    else:
+        for key, value in matching_peer.items():
+            console.print(f"  {key}: {value}")
+
+    return 0
+
+
+def test_connectivity_command(args: list[str]) -> int:
+    """Test connectivity to a peer."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network test",
+        description="Test connectivity to a peer via WireGuard",
+    )
+    parser.add_argument("interface", help="Interface name (e.g., wg-abc123)")
+    parser.add_argument("peer_ip", help="Peer IP address to ping")
+    parser.add_argument(
+        "--count",
+        type=int,
+        default=4,
+        help="Number of ping packets to send (default: 4)",
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    # Check interface exists
+    interfaces = list_interfaces()
+    if parsed_args.interface not in interfaces:
+        console.print(f"[red]Interface '{parsed_args.interface}' not found[/red]")
+        return 1
+
+    console.print(
+        f"Testing connectivity to {parsed_args.peer_ip} via {parsed_args.interface}..."
+    )
+
+    try:
+        from icmplib import ping
+
+        # Try unprivileged ping first (works if ping_group_range is configured)
+        # Fall back to privileged mode if that fails
+        host = None
+        privileged_mode = False
+
+        try:
+            host = ping(
+                parsed_args.peer_ip,
+                count=parsed_args.count,
+                interval=1,
+                timeout=2,
+                privileged=False,  # Try unprivileged first
+            )
+        except (PermissionError, OSError):
+            # Unprivileged failed, try privileged mode
+            try:
+                host = ping(
+                    parsed_args.peer_ip,
+                    count=parsed_args.count,
+                    interval=1,
+                    timeout=2,
+                    privileged=True,  # Requires root/sudo or CAP_NET_RAW
+                )
+                privileged_mode = True
+            except (PermissionError, OSError):
+                console.print(
+                    "[red]Error: Insufficient permissions for ICMP ping[/red]"
+                )
+                console.print("\n[bold]To enable unprivileged ping, configure:[/bold]")
+                console.print(
+                    "  [cyan]echo 'net.ipv4.ping_group_range = 0 2147483647' | sudo tee -a /etc/sysctl.conf[/cyan]"
+                )
+                console.print("  [cyan]sudo sysctl -p[/cyan]")
+                console.print("\n[bold]Or run with sudo:[/bold]")
+                console.print("  [cyan]sudo manta_node network test ...[/cyan]")
+                return 1
+
+        # Display results
+        console.print(f"\n[bold]PING {parsed_args.peer_ip}[/bold]")
+        if privileged_mode:
+            console.print("  [dim](using privileged ICMP sockets)[/dim]")
+        else:
+            console.print("  [dim](using unprivileged ping)[/dim]")
+
+        console.print(f"  Packets sent:     {host.packets_sent}")
+        console.print(f"  Packets received: {host.packets_received}")
+        console.print(f"  Packet loss:      {host.packet_loss * 100:.1f}%")
+
+        if host.packets_received > 0:
+            console.print(f"  Min RTT:          {host.min_rtt:.2f} ms")
+            console.print(f"  Avg RTT:          {host.avg_rtt:.2f} ms")
+            console.print(f"  Max RTT:          {host.max_rtt:.2f} ms")
+
+        if host.is_alive:
+            console.print("\n[green]✓ Connectivity successful[/green]")
+            return 0
+        else:
+            console.print("\n[red]✗ Connectivity failed (no response)[/red]")
+            return 1
+
+    except ImportError:
+        console.print("[red]Error: icmplib library not installed[/red]")
+        console.print("Install with: [cyan]pip install icmplib[/cyan]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        return 1
+
+
+def show_config_command(args: list[str]) -> int:
+    """Show WireGuard configuration file."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network config",
+        description="Show WireGuard configuration file",
+    )
+    parser.add_argument("interface", help="Interface name (e.g., wg-abc123)")
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    config_path = Path(f"/etc/wireguard/{parsed_args.interface}.conf")
+
+    if not config_path.exists():
+        console.print(f"[red]Configuration file not found: {config_path}[/red]")
+        return 1
+
+    try:
+        config_content = config_path.read_text()
+
+        syntax = Syntax(config_content, "ini", theme="monokai", line_numbers=True)
+
+        console.print(
+            Panel(syntax, title=f"Configuration: {parsed_args.interface}", expand=False)
+        )
+
+        return 0
+    except PermissionError:
+        console.print(f"[red]Permission denied reading {config_path}[/red]")
+        console.print("Try running with sudo")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error reading config: {e}[/red]")
+        return 1
+
+
+def generate_key_command(args: list[str]) -> int:
+    """Generate WireGuard keypair."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network generate-key",
+        description="Generate a WireGuard keypair",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        help="Output file for private key (public key goes to <file>.pub)",
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    try:
+        from wireguard_tools import WireguardKey
+
+        # Generate keypair
+        private_key = WireguardKey.generate()
+        public_key = private_key.public_key()
+
+        if parsed_args.output:
+            # Write to files
+            private_file = Path(parsed_args.output)
+            public_file = Path(f"{parsed_args.output}.pub")
+
+            # Check if files exist
+            if private_file.exists() or public_file.exists():
+                console.print("[yellow]Warning: File(s) already exist[/yellow]")
+                response = input("Overwrite? (y/N): ").strip().lower()
+                if response != "y":
+                    console.print("[dim]Operation cancelled[/dim]")
+                    return 0
+
+            # Write private key, pre-restricted so it is never world/group readable
+            private_file.touch(mode=0o600)
+            private_file.write_text(str(private_key))
+
+            # Write public key
+            public_file.write_text(str(public_key))
+            public_file.chmod(0o644)
+
+            console.print(f"[green]✓[/green] Private key written to: {private_file}")
+            console.print(f"[green]✓[/green] Public key written to: {public_file}")
+        else:
+            # Print to console
+            console.print("\n[bold]Private Key:[/bold]")
+            console.print(f"[cyan]{private_key}[/cyan]")
+            console.print("\n[bold]Public Key:[/bold]")
+            console.print(f"[cyan]{public_key}[/cyan]")
+            console.print("\n[dim]Tip: Use --output to save keys to files[/dim]")
+
+        return 0
+
+    except ImportError:
+        console.print("[red]Error: wireguard-tools library not installed[/red]")
+        console.print("Install with: [cyan]pip install wireguard-tools[/cyan]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error generating keypair: {e}[/red]")
+        return 1
+
+
+def create_network_command(args: list[str]) -> int:
+    """Create a new WireGuard network interface."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network create",
+        description="Create a new WireGuard network interface",
+    )
+    parser.add_argument("interface", help="Interface name (e.g., wg-test)")
+    parser.add_argument(
+        "--ip",
+        required=True,
+        help="Assigned IP address with CIDR (e.g., 10.100.0.5/24)",
+    )
+    parser.add_argument(
+        "--port", type=int, default=51820, help="Listen port (default: 51820)"
+    )
+    parser.add_argument("--mtu", type=int, default=1420, help="MTU (default: 1420)")
+    parser.add_argument(
+        "--private-key", help="Private key (will generate if not provided)"
+    )
+    parser.add_argument(
+        "--force", action="store_true", help="Skip confirmation prompts"
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    interface = parsed_args.interface
+    assigned_ip = parsed_args.ip
+    listen_port = parsed_args.port
+    mtu = parsed_args.mtu
+    private_key = parsed_args.private_key
+
+    # Check if interface already exists
+    existing_interfaces = list_interfaces()
+    if interface in existing_interfaces:
+        console.print(f"[red]Error: Interface {interface} already exists[/red]")
+        return 1
+
+    # Confirm operation
+    if not parsed_args.force:
+        console.print("\n[bold]Create WireGuard Network:[/bold]")
+        console.print(f"  Interface: [cyan]{interface}[/cyan]")
+        console.print(f"  IP:        [cyan]{assigned_ip}[/cyan]")
+        console.print(f"  Port:      [cyan]{listen_port}[/cyan]")
+        console.print(f"  MTU:       [cyan]{mtu}[/cyan]")
+        response = input("\nProceed? (y/N): ").strip().lower()
+        if response != "y":
+            console.print("[dim]Operation cancelled[/dim]")
+            return 0
+
+    try:
+        from pyroute2 import IPRoute
+        from wireguard_tools import WireguardConfig, WireguardDevice, WireguardKey
+
+        # Generate or parse private key
+        if not private_key:
+            console.print("[dim]Generating keypair...[/dim]")
+            priv_key_obj = WireguardKey.generate()
+            pub_key_obj = priv_key_obj.public_key()
+            private_key = str(priv_key_obj)
+            console.print(f"Public key: [cyan]{pub_key_obj}[/cyan]")
+        else:
+            priv_key_obj = WireguardKey(private_key)
+            pub_key_obj = priv_key_obj.public_key()
+
+        # Parse IP address
+        ip_addr, prefix_len = assigned_ip.split("/")
+
+        # Create interface using pyroute2
+        console.print(f"[dim]Creating interface {interface}...[/dim]")
+        with IPRoute() as ip:
+            # Create interface
+            ip.link("add", ifname=interface, kind="wireguard")
+
+            # Get interface index
+            idx = ip.link_lookup(ifname=interface)[0]
+
+            # Set MTU
+            ip.link("set", index=idx, mtu=mtu)
+
+            # Add IP address
+            ip.addr("add", index=idx, address=ip_addr, prefixlen=int(prefix_len))
+
+            # Bring interface up
+            ip.link("set", index=idx, state="up")
+
+        # Configure WireGuard-specific parameters
+        console.print("[dim]Configuring WireGuard...[/dim]")
+        device = WireguardDevice.get(interface)
+        config = WireguardConfig(
+            private_key=private_key,
+            listen_port=listen_port,
+            peers={},
+        )
+        device.set_config(config)
+
+        # Persist state to keyring + TOML config
+        try:
+            import keyring
+
+            from manta_node.infrastructure.config.node_config_manager import (
+                WireGuardNetworkState,
+            )
+
+            config_manager, node_id = _load_node_config()
+            if config_manager and node_id:
+                keyring_service = "manta_node_wireguard"
+                keyring_key = f"{node_id}:{interface}"
+                keyring.set_password(keyring_service, keyring_key, private_key)
+
+                wg_state = WireGuardNetworkState(
+                    network_id=interface,
+                    interface_name=interface,
+                    private_key_ref=keyring_key,
+                    assigned_ip=assigned_ip,
+                    network_cidr=assigned_ip,
+                    listen_port=listen_port,
+                    mtu=mtu,
+                    peers=[],
+                )
+                config_manager.config.wireguard.networks[interface] = wg_state
+                config_manager.save()
+                console.print("[dim]Persisted network state to config + keyring[/dim]")
+            else:
+                console.print(
+                    "[dim]Warning: No node config found — state not persisted[/dim]"
+                )
+        except Exception as e:
+            console.print(f"[yellow]Warning: Could not persist state: {e}[/yellow]")
+            console.print("[dim]Interface is up but keys won't survive reboot[/dim]")
+
+        console.print(
+            f"\n[green]✓[/green] Created WireGuard network: [cyan]{interface}[/cyan]"
+        )
+        console.print(f"  IP:         {assigned_ip}")
+        console.print(f"  Public key: {pub_key_obj}")
+        console.print(f"  Port:       {listen_port}")
+
+        console.print("\n[bold]Next steps:[/bold]")
+        console.print("  1. Share your public key with peers")
+        console.print(
+            f"  2. Add peers: [cyan]manta_node network add-peer {interface} --pubkey <KEY> --endpoint <IP:PORT> --allowed-ips <CIDR>[/cyan]"
+        )
+        console.print(
+            f"  3. Test connectivity: [cyan]manta_node network test {interface} <PEER_IP>[/cyan]"
+        )
+
+        return 0
+
+    except ImportError as e:
+        console.print(f"[red]Error: Required library not installed: {e}[/red]")
+        console.print("Install with: [cyan]pip install wireguard-tools pyroute2[/cyan]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error creating interface: {e}[/red]")
+        return 1
+
+
+def delete_network_command(args: list[str]) -> int:
+    """Delete a WireGuard network interface."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network delete",
+        description="Delete a WireGuard network interface",
+    )
+    parser.add_argument("interface", help="Interface name to delete")
+    parser.add_argument(
+        "--force", action="store_true", help="Skip confirmation prompts"
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    interface = parsed_args.interface
+
+    # Check if interface exists
+    existing_interfaces = list_interfaces()
+    if interface not in existing_interfaces:
+        console.print(f"[red]Error: Interface {interface} not found[/red]")
+        return 1
+
+    # Confirm operation
+    if not parsed_args.force:
+        console.print(
+            f"\n[yellow]Warning: This will delete interface {interface}[/yellow]"
+        )
+        response = input("Proceed? (y/N): ").strip().lower()
+        if response != "y":
+            console.print("[dim]Operation cancelled[/dim]")
+            return 0
+
+    try:
+        from pyroute2 import IPRoute
+
+        console.print(f"[dim]Deleting interface {interface}...[/dim]")
+
+        with IPRoute() as ip:
+            # Get interface index
+            idx = ip.link_lookup(ifname=interface)
+
+            if idx:
+                # Delete the interface
+                ip.link("del", index=idx[0])
+                console.print(
+                    f"[green]✓[/green] Deleted interface: [cyan]{interface}[/cyan]"
+                )
+            else:
+                console.print(f"[red]Error: Interface {interface} not found[/red]")
+                return 1
+
+        # Clean up persisted state from keyring + TOML config
+        try:
+            config_manager, _ = _load_node_config()
+            if config_manager and interface in config_manager.config.wireguard.networks:
+                wg_state = config_manager.config.wireguard.networks[interface]
+
+                # Delete private key from keyring
+                try:
+                    import keyring
+
+                    keyring.delete_password(
+                        "manta_node_wireguard", wg_state.private_key_ref
+                    )
+                    console.print("[dim]Removed key from keyring[/dim]")
+                except Exception as e:
+                    console.print(
+                        f"[dim]Warning: Could not remove keyring entry: {e}[/dim]"
+                    )
+
+                # Remove network from config
+                del config_manager.config.wireguard.networks[interface]
+                config_manager.save()
+                console.print("[dim]Removed network from config[/dim]")
+        except Exception as e:
+            console.print(
+                f"[yellow]Warning: Could not clean up persisted state: {e}[/yellow]"
+            )
+
+        return 0
+
+    except ImportError:
+        console.print("[red]Error: pyroute2 library not installed[/red]")
+        console.print("Install with: [cyan]pip install pyroute2[/cyan]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error deleting interface: {e}[/red]")
+        return 1
+
+
+def add_peer_command(args: list[str]) -> int:
+    """Add a peer to a WireGuard network."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network add-peer",
+        description="Add a peer to a WireGuard network",
+    )
+    parser.add_argument("interface", help="Interface name")
+    parser.add_argument("--pubkey", required=True, help="Peer's public key")
+    parser.add_argument("--endpoint", help="Peer endpoint (IP:PORT)")
+    parser.add_argument(
+        "--allowed-ips",
+        required=True,
+        help="Comma-separated list of allowed IPs (e.g., 10.100.0.2/32)",
+    )
+    parser.add_argument(
+        "--keepalive",
+        type=int,
+        default=25,
+        help="Persistent keepalive interval in seconds (default: 25)",
+    )
+    parser.add_argument(
+        "--force", action="store_true", help="Skip confirmation prompts"
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    interface = parsed_args.interface
+    public_key = parsed_args.pubkey
+    endpoint = parsed_args.endpoint
+    allowed_ips = [ip.strip() for ip in parsed_args.allowed_ips.split(",")]
+    keepalive = parsed_args.keepalive
+
+    # Check if interface exists
+    existing_interfaces = list_interfaces()
+    if interface not in existing_interfaces:
+        console.print(f"[red]Error: Interface {interface} not found[/red]")
+        console.print("\nCreate the interface first:")
+        console.print(
+            f"  [cyan]manta_node network create {interface} --ip <IP/CIDR>[/cyan]"
+        )
+        return 1
+
+    # Confirm operation
+    if not parsed_args.force:
+        console.print("\n[bold]Add Peer:[/bold]")
+        console.print(f"  Interface:    [cyan]{interface}[/cyan]")
+        console.print(f"  Public key:   [cyan]{public_key[:32]}...[/cyan]")
+        console.print(f"  Endpoint:     [cyan]{endpoint or 'None'}[/cyan]")
+        console.print(f"  Allowed IPs:  [cyan]{', '.join(allowed_ips)}[/cyan]")
+        response = input("\nProceed? (y/N): ").strip().lower()
+        if response != "y":
+            console.print("[dim]Operation cancelled[/dim]")
+            return 0
+
+    try:
+        from pyroute2 import IPRoute
+        from wireguard_tools import (
+            WireguardDevice,
+            WireguardKey,
+        )
+        from wireguard_tools import (
+            WireguardPeer as WGPeer,
+        )
+
+        console.print(f"[dim]Adding peer to {interface}...[/dim]")
+
+        # Parse endpoint string (e.g., "192.168.104.1:51820") into host/port
+        endpoint_host = None
+        endpoint_port = None
+        if endpoint:
+            parts = endpoint.rsplit(":", 1)
+            endpoint_host = parts[0]
+            endpoint_port = int(parts[1]) if len(parts) > 1 else None
+
+        # Get current device configuration
+        device = WireguardDevice.get(interface)
+        config = device.get_config()
+
+        # config.peers is a dict[WireguardKey, WireguardPeer]
+        peer_key = WireguardKey(public_key)
+        peer_exists = peer_key in config.peers
+
+        config.peers[peer_key] = WGPeer(
+            public_key=peer_key,
+            endpoint_host=endpoint_host,
+            endpoint_port=endpoint_port,
+            allowed_ips=allowed_ips,
+            persistent_keepalive=keepalive,
+        )
+
+        # Apply configuration
+        device.set_config(config)
+
+        # Add routes for allowed_ips
+        console.print("[dim]Adding routes...[/dim]")
+        with IPRoute() as ip:
+            idx = ip.link_lookup(ifname=interface)[0]
+
+            for allowed_ip in allowed_ips:
+                try:
+                    # Add route
+                    ip.route("add", dst=allowed_ip, oif=idx)
+                except Exception as e:
+                    # Route might already exist
+                    console.print(
+                        f"[dim]Route for {allowed_ip} may already exist: {e}[/dim]"
+                    )
+
+        # Persist peer to TOML config
+        try:
+            from manta_node.infrastructure.config.node_config_manager import (
+                WireGuardPeerState,
+            )
+
+            config_manager, _ = _load_node_config()
+            if config_manager and interface in config_manager.config.wireguard.networks:
+                network_state = config_manager.config.wireguard.networks[interface]
+                new_peer = WireGuardPeerState(
+                    node_id="",
+                    public_key=public_key,
+                    endpoint=endpoint,
+                    allowed_ips=allowed_ips,
+                    persistent_keepalive=keepalive,
+                )
+
+                # Update existing peer or append new one
+                updated = False
+                for i, existing in enumerate(network_state.peers):
+                    if existing.public_key == public_key:
+                        network_state.peers[i] = new_peer
+                        updated = True
+                        break
+                if not updated:
+                    network_state.peers.append(new_peer)
+
+                config_manager.save()
+                console.print("[dim]Persisted peer to config[/dim]")
+        except Exception as e:
+            console.print(f"[yellow]Warning: Could not persist peer: {e}[/yellow]")
+
+        action = "Updated" if peer_exists else "Added"
+        console.print(f"\n[green]✓[/green] {action} peer on [cyan]{interface}[/cyan]")
+        console.print(f"  Public key:  {public_key[:32]}...")
+        console.print(f"  Allowed IPs: {', '.join(allowed_ips)}")
+
+        if endpoint:
+            console.print("\n[bold]Test connectivity:[/bold]")
+            peer_ip = allowed_ips[0].split("/")[0]  # Get first IP without CIDR
+            console.print(
+                f"  [cyan]manta_node network test {interface} {peer_ip}[/cyan]"
+            )
+
+        return 0
+
+    except ImportError as e:
+        console.print(f"[red]Error: Required library not installed: {e}[/red]")
+        console.print("Install with: [cyan]pip install wireguard-tools pyroute2[/cyan]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error adding peer: {e}[/red]")
+        return 1
+
+
+def remove_peer_command(args: list[str]) -> int:
+    """Remove a peer from a WireGuard network."""
+    parser = argparse.ArgumentParser(
+        prog="manta_node network remove-peer",
+        description="Remove a peer from a WireGuard network",
+    )
+    parser.add_argument("interface", help="Interface name")
+    parser.add_argument("--pubkey", required=True, help="Peer's public key to remove")
+    parser.add_argument(
+        "--force", action="store_true", help="Skip confirmation prompts"
+    )
+
+    try:
+        parsed_args = parser.parse_args(args)
+    except SystemExit:
+        return 1
+
+    interface = parsed_args.interface
+    public_key = parsed_args.pubkey
+
+    # Check if interface exists
+    existing_interfaces = list_interfaces()
+    if interface not in existing_interfaces:
+        console.print(f"[red]Error: Interface {interface} not found[/red]")
+        return 1
+
+    # Confirm operation
+    if not parsed_args.force:
+        console.print(f"\n[yellow]Remove peer from {interface}?[/yellow]")
+        console.print(f"  Public key: [cyan]{public_key[:32]}...[/cyan]")
+        response = input("\nProceed? (y/N): ").strip().lower()
+        if response != "y":
+            console.print("[dim]Operation cancelled[/dim]")
+            return 0
+
+    try:
+        from pyroute2 import IPRoute
+        from wireguard_tools import WireguardDevice, WireguardKey
+
+        console.print(f"[dim]Removing peer from {interface}...[/dim]")
+
+        # Get current device configuration
+        device = WireguardDevice.get(interface)
+        config = device.get_config()
+
+        # config.peers is a dict[WireguardKey, WireguardPeer]
+        peer_key = WireguardKey(public_key)
+        peer_allowed_ips = []
+
+        if peer_key not in config.peers:
+            console.print(f"[yellow]Warning: Peer not found in {interface}[/yellow]")
+            return 1
+
+        existing_peer = config.peers[peer_key]
+        peer_allowed_ips = (
+            list(existing_peer.allowed_ips) if existing_peer.allowed_ips else []
+        )
+        del config.peers[peer_key]
+
+        device.set_config(config)
+
+        # Remove routes for peer's allowed_ips
+        if peer_allowed_ips:
+            console.print("[dim]Removing routes...[/dim]")
+            with IPRoute() as ip:
+                idx = ip.link_lookup(ifname=interface)[0]
+
+                for allowed_ip in peer_allowed_ips:
+                    try:
+                        # Remove route
+                        ip.route("del", dst=allowed_ip, oif=idx)
+                    except Exception as e:
+                        # Route might not exist
+                        console.print(
+                            f"[dim]Route for {allowed_ip} may not exist: {e}[/dim]"
+                        )
+
+        console.print(f"\n[green]✓[/green] Removed peer from [cyan]{interface}[/cyan]")
+        console.print(f"  Public key: {public_key[:32]}...")
+
+        return 0
+
+    except ImportError as e:
+        console.print(f"[red]Error: Required library not installed: {e}[/red]")
+        console.print("Install with: [cyan]pip install wireguard-tools pyroute2[/cyan]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error removing peer: {e}[/red]")
+        return 1
+
+
+def network_command(args: list[str]) -> int:
+    """Handle network command with subcommands.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    if not args or args[0] in ["-h", "--help", "help"]:
+        show_network_help()
+        return 0
+
+    subcommand = args[0]
+    subcommand_args = args[1:]
+
+    # Route to appropriate subcommand
+    if subcommand == "list":
+        return list_networks_command(subcommand_args)
+    elif subcommand == "show":
+        return show_network_command(subcommand_args)
+    elif subcommand == "peers":
+        return list_peers_command(subcommand_args)
+    elif subcommand == "peer":
+        return show_peer_command(subcommand_args)
+    elif subcommand == "test":
+        return test_connectivity_command(subcommand_args)
+    elif subcommand == "config":
+        return show_config_command(subcommand_args)
+    elif subcommand == "generate-key":
+        return generate_key_command(subcommand_args)
+    elif subcommand == "create":
+        return create_network_command(subcommand_args)
+    elif subcommand == "delete":
+        return delete_network_command(subcommand_args)
+    elif subcommand == "add-peer":
+        return add_peer_command(subcommand_args)
+    elif subcommand == "remove-peer":
+        return remove_peer_command(subcommand_args)
+    else:
+        console.print(f"[red]Unknown subcommand: {subcommand}[/red]")
+        console.print("\nUse 'manta_node network help' to see available subcommands")
+        return 1
+
+
+def show_network_help():
+    """Show network command help."""
+    help_text = """
+[bold cyan]Manta Node Network Management[/bold cyan]
+
+Manage and troubleshoot WireGuard SDN networks on this node.
+
+[bold]Usage:[/bold]
+  manta_node network <subcommand> [options]
+
+[bold]Read Operations (Query):[/bold]
+  [cyan]list[/cyan]                          List all active WireGuard networks
+  [cyan]show <interface>[/cyan]              Show detailed network information
+  [cyan]peers <interface>[/cyan]             List all peers in a network
+  [cyan]peer <interface> <pubkey>[/cyan]     Show detailed peer information
+  [cyan]test <interface> <ip>[/cyan]         Test connectivity to a peer
+  [cyan]config <interface>[/cyan]            Show WireGuard configuration file
+
+[bold]Write Operations (Manage):[/bold]
+  [cyan]generate-key[/cyan]                  Generate a WireGuard keypair
+  [cyan]create <interface> --ip <CIDR>[/cyan] Create a new WireGuard network
+  [cyan]delete <interface>[/cyan]            Delete a WireGuard network
+  [cyan]add-peer <interface> ...[/cyan]      Add a peer to a network
+  [cyan]remove-peer <interface> ...[/cyan]   Remove a peer from a network
+
+[bold]Examples:[/bold]
+  [dim]# Read operations[/dim]
+  manta_node network list
+  manta_node network show wg-abc123
+  manta_node network peers wg-abc123
+  manta_node network test wg-abc123 10.100.0.2
+
+  [dim]# Write operations[/dim]
+  manta_node network generate-key --output /tmp/wg-key
+  manta_node network create wg-test --ip 10.100.0.1/24 --port 51820
+  manta_node network add-peer wg-test --pubkey <KEY> --endpoint 192.0.2.1:51820 --allowed-ips 10.100.0.2/32
+  manta_node network remove-peer wg-test --pubkey <KEY>
+  manta_node network delete wg-test
+
+[bold]Permissions:[/bold]
+  Most commands require elevated permissions to access WireGuard devices.
+
+  [bold]Option 1: Run with sudo[/bold]
+    sudo manta_node network <subcommand>
+
+  [bold]Option 2: One-time setup (recommended)[/bold]
+    Run the setup script to enable group-based access:
+    sudo ./scripts/setup-wireguard-access.sh
+
+    This configures:
+    - wireguard group membership
+    - Unprivileged ping support
+    - WireGuard socket permissions
+
+[bold]Notes:[/bold]
+  - Networks are automatically created when swarms are deployed via the manager
+  - Manual network creation is useful for testing or standalone deployments
+  - Network IDs follow the format: wg-<swarm_id> for managed networks
+  - Write operations require root/sudo privileges
+  - Use --force flag to skip confirmation prompts in scripts
+
+For more help on a specific subcommand:
+  manta_node network <subcommand> --help
+"""
+    console.print(help_text)
+
+
+if __name__ == "__main__":
+    sys.exit(network_command(sys.argv[1:]))