diff --git a/README.md b/README.md index 4bef196b..c302b22b 100644 --- a/README.md +++ b/README.md @@ -91,11 +91,13 @@ Network intelligence dashboard with DPI for OpenWrt. Configure different network operation modes with one click. **Features:** -- ๐Ÿ” **Sniffer Mode**: Transparent bridge for traffic analysis -- ๐Ÿ“ถ **Access Point**: WiFi AP with 802.11r/k/v roaming -- ๐Ÿ”„ **Relay/Extender**: Network relay with WireGuard -- ๐ŸŒ **Router Mode**: Full router with proxy and HTTPS frontend -- ๐ŸŽ›๏ธ One-click mode switching with auto-backup +- ๐Ÿ” **Sniffer Bridge Mode**: Transparent inline bridge for traffic analysis with Netifyd DPI +- ๐Ÿ‘๏ธ **Sniffer Passive Mode**: Out-of-band monitoring via SPAN/TAP for zero-impact forensics +- ๐Ÿ“ถ **Access Point**: WiFi AP with 802.11r/k/v roaming and band steering +- ๐Ÿ”„ **Relay/Extender**: Network relay with WireGuard VPN and MTU optimization +- ๐ŸŒ **Router Mode**: Full router with proxy, HTTPS frontend, and virtual hosts +- ๐ŸŽ›๏ธ One-click mode switching with automatic backup +- ๐Ÿ“Š Real-time interface and service status monitoring [View Details](luci-app-network-modes/README.md) diff --git a/luci-app-network-modes/README.md b/luci-app-network-modes/README.md index 3fda857e..42da922f 100644 --- a/luci-app-network-modes/README.md +++ b/luci-app-network-modes/README.md @@ -10,12 +10,118 @@ Configure your OpenWrt router for different network operation modes with a moder ## ๐ŸŽฏ Network Modes -### ๐Ÿ” Sniffer / Passthrough Mode -Transparent Ethernet bridge without IP address for passive network analysis. -- **Bridge mode** without IP configuration -- **Promiscuous mode** for all traffic capture +### ๐Ÿ” Sniffer Bridge Mode (Inline / Passthrough) +Transparent Ethernet bridge without IP address for in-line traffic analysis. All traffic passes through the device. + +**Network Configuration:** +- **Transparent bridge** mode (br-lan) without IP address assignment +- **Promiscuous mode** enabled on all bridged interfaces +- **No DHCP server** - invisible on the network +- **No routing** - pure layer 2 forwarding +- **Inline deployment** - device inserted in traffic path +- Perfect insertion point between gateway and network devices + +**Traffic Analysis Features:** +- **Netifyd integration** for real-time Deep Packet Inspection (DPI) +- **Application detection** (Netflix, YouTube, Zoom, torrent, etc.) +- **Protocol identification** (HTTP/HTTPS, DNS, QUIC, SSH, etc.) +- **Flow tracking** with source/destination analysis +- **Bandwidth monitoring** per application and protocol + +**Use Cases:** +- ๐Ÿ“Š **Network forensics** - Capture all traffic passing through +- ๐Ÿ” **Security monitoring** - Detect anomalies and threats inline +- ๐ŸŽฏ **Bandwidth analysis** - Identify bandwidth hogs +- ๐Ÿงช **Protocol debugging** - Debug network issues +- ๐Ÿ“ˆ **Compliance monitoring** - Log all network activity + +**Physical Setup (Inline):** +``` +Internet Router (Gateway) + โ†“ + [WAN Port] OpenWrt (Bridge Mode) [LAN Ports] + โ†“ + Network Devices (Switches, APs, Clients) +``` + +**Advantages:** +- โœ… Sees 100% of network traffic +- โœ… Can apply firewall rules if needed +- โœ… Can perform traffic shaping +- โš ๏ธ Single point of failure (if device fails, network is down) + +--- + +### ๐Ÿ‘๏ธ Sniffer Passive Mode (Out-of-band / Monitor Only) +Pure passive monitoring without affecting network traffic. Device only listens, traffic doesn't flow through it. + +**Network Configuration:** +- **Monitor mode** interface (no bridge, no forwarding) +- **Promiscuous mode** for packet capture +- **No IP address** on monitoring interface +- **Read-only** - cannot affect network traffic +- Connected via **SPAN/mirror port** or **network TAP** + +**Traffic Analysis Features:** - **Netifyd integration** for Deep Packet Inspection -- Perfect for network forensics and traffic analysis +- **Full packet capture** with tcpdump/Wireshark +- **Application and protocol detection** +- **Flow analysis** and bandwidth monitoring +- **Zero network impact** - invisible to network + +**Use Cases:** +- ๐Ÿ”ฌ **Pure forensics** - Monitor without any network impact +- ๐Ÿ›ก๏ธ **IDS/IPS** - Intrusion detection without inline risk +- ๐Ÿ“ก **Network TAP monitoring** - Dedicated monitoring infrastructure +- ๐Ÿ”’ **Secure environments** - No risk of disrupting production traffic +- ๐Ÿ“Š **Long-term monitoring** - Continuous passive observation + +**Physical Setup Options:** + +**Option 1: Switch SPAN/Mirror Port** +``` +Internet Router + โ†“ + Managed Switch (with port mirroring) + โ”œโ”€โ†’ [Port 1-23] Normal traffic + โ””โ”€โ†’ [Port 24 SPAN] โ”€โ”€โ†’ OpenWrt [eth0] (Monitor) +``` + +**Option 2: Network TAP** +``` +Internet Router โ”€โ”€โ†’ [TAP Device] โ”€โ”€โ†’ Switch + โ†“ + OpenWrt [eth0] (Monitor) +``` + +**Option 3: Hub (Legacy)** +``` +Internet Router โ”€โ”€โ†’ [Hub] โ”€โ”€โ†’ Switch + โ†“ + OpenWrt [eth0] (Monitor) +``` + +**Advantages:** +- โœ… Zero network impact - no single point of failure +- โœ… Completely invisible to network +- โœ… Cannot be detected or attacked +- โœ… Perfect for compliance and security monitoring +- โš ๏ธ Requires SPAN port, TAP, or hub +- โš ๏ธ May miss traffic depending on setup + +**Integration with SecuBox:** +Both modes work seamlessly with: +- **Netifyd Dashboard** for DPI visualization +- **CrowdSec** for threat detection +- **Netdata** for metrics and graphs +- **Client Guardian** for access control decisions + +**Advanced Options:** +- Capture to PCAP files for offline analysis +- Export to SIEM (Elasticsearch, Splunk, etc.) +- Filter specific protocols or ports +- Traffic replay for testing +- Long-term packet storage on USB/NAS ### ๐Ÿ“ถ Access Point Mode WiFi access point with advanced optimizations. @@ -161,9 +267,16 @@ config network-modes 'config' option backup_config '1' config mode 'sniffer' + option mode_type 'bridge' # 'bridge' or 'passive' option bridge_interface 'br-lan' + option monitor_interface 'eth0' # For passive mode option netifyd_enabled '1' option promiscuous '1' + option pcap_capture '0' + option pcap_path '/tmp/captures' + option mirror_port '' + option capture_filter '' + option span_port_source '' # For passive mode with SPAN config mode 'accesspoint' option wifi_channel 'auto' @@ -184,6 +297,279 @@ config mode 'router' option https_frontend '0' ``` +## Sniffer Mode Examples + +### Basic Sniffer Bridge Setup (Inline) + +1. **Enable Sniffer Bridge Mode** via LuCI: + - Navigate to **Network โ†’ Network Modes** + - Select **Sniffer Bridge Mode (Inline)** + - Enable **Netifyd Integration** + - Click **Apply Mode** + +2. **Physical Connection**: + ``` + Modem/ISP โ†’ [WAN] OpenWrt [LAN1-4] โ†’ Switch/Devices + ``` + +3. **Verify Configuration**: + ```bash + # Check bridge status + brctl show br-lan + + # Verify no IP on bridge + ip addr show br-lan + + # Check promiscuous mode + ip link show br-lan | grep PROMISC + + # Verify Netifyd is running + /etc/init.d/netifyd status + ``` + +--- + +### Passive Sniffer Setup (Out-of-band) + +#### Option A: Using Switch SPAN Port + +1. **Configure Switch SPAN/Mirror Port**: + - Access your managed switch configuration + - Configure port mirroring: + - **Source ports**: Ports to monitor (e.g., uplink port) + - **Destination port**: Port connected to OpenWrt (e.g., port 24) + - **Direction**: Both (ingress + egress) + +2. **Configure OpenWrt Passive Mode**: + ```bash + # Via UCI + uci set network-modes.sniffer.mode_type='passive' + uci set network-modes.sniffer.monitor_interface='eth0' + uci set network-modes.sniffer.netifyd_enabled='1' + uci commit network-modes + + # Apply configuration + ubus call network-modes apply_mode '{"mode":"sniffer"}' + ``` + +3. **Configure Monitor Interface**: + ```bash + # Remove IP from monitoring interface + ip addr flush dev eth0 + + # Enable promiscuous mode + ip link set eth0 promisc on + + # Bring interface up + ip link set eth0 up + + # Verify interface state + ip link show eth0 + ``` + +4. **Start Netifyd on Monitor Interface**: + ```bash + # Edit /etc/netifyd.conf + { + "interfaces": { + "internal": [], + "external": ["eth0"] + }, + "enable_sink": true + } + + # Restart Netifyd + /etc/init.d/netifyd restart + ``` + +5. **Verify Passive Capture**: + ```bash + # Test with tcpdump + tcpdump -i eth0 -c 100 + + # Check Netifyd is seeing traffic + ubus call luci.netifyd status + + # Monitor live flows + ubus call luci.netifyd flows | jq '.flows | length' + ``` + +#### Option B: Using Network TAP + +1. **Physical Setup**: + ``` + Router [eth0] โ”€โ”€โ†’ [TAP IN] + โ†“ + [TAP MONITOR] โ”€โ”€โ†’ OpenWrt [eth0] + โ†“ + [TAP OUT] โ”€โ”€โ†’ Switch + ``` + +2. **Configure OpenWrt**: + ```bash + # Same as SPAN port configuration above + uci set network-modes.sniffer.mode_type='passive' + uci set network-modes.sniffer.monitor_interface='eth0' + uci commit network-modes + ``` + +3. **Advantages of TAP**: + - โœ… Hardware-based, zero packet loss + - โœ… Full duplex monitoring (both directions) + - โœ… No switch configuration needed + - โœ… Cannot be remotely disabled + - โš ๏ธ Requires physical TAP device + +#### Option C: Using Hub (Budget Option) + +1. **Physical Setup**: + ``` + Router โ”€โ”€โ†’ [Hub Port 1] + [Hub Port 2] โ”€โ”€โ†’ Switch + [Hub Port 3] โ”€โ”€โ†’ OpenWrt [eth0] + ``` + +2. **Configure OpenWrt**: + ```bash + # Same passive configuration + uci set network-modes.sniffer.mode_type='passive' + uci set network-modes.sniffer.monitor_interface='eth0' + uci commit network-modes + ``` + +3. **Limitations**: + - โš ๏ธ Only works with 10/100Mbps networks + - โš ๏ธ Half-duplex only + - โš ๏ธ Adds latency + - โš ๏ธ Not recommended for modern networks + +### Advanced Capture Configuration + +**Capture HTTP traffic to PCAP:** +```bash +# Via UCI +uci set network-modes.sniffer.pcap_capture='1' +uci set network-modes.sniffer.pcap_path='/mnt/usb/captures' +uci set network-modes.sniffer.capture_filter='port 80 or port 443' +uci commit network-modes + +# Manual tcpdump +tcpdump -i br-lan -w /tmp/capture.pcap port 80 or port 443 +``` + +**Monitor specific applications:** +```bash +# Watch Netflix traffic +tcpdump -i br-lan -n 'host nflxvideo.net or host netflix.com' + +# Monitor DNS queries +tcpdump -i br-lan -n 'port 53' + +# Capture BitTorrent +tcpdump -i br-lan -n 'port 6881:6889' +``` + +**Real-time bandwidth per IP:** +```bash +# Using iftop +iftop -i br-lan -P + +# Using nethogs (if installed) +nethogs br-lan + +# Using Netifyd API +ubus call luci.netifyd flows | jq '.flows[] | select(.bytes_total > 1000000)' +``` + +### Integration Examples + +**Export to Elasticsearch:** +```bash +# Netifyd can export to Elasticsearch for centralized logging +# Configure in /etc/netifyd.conf +{ + "sink": { + "type": "elasticsearch", + "url": "http://elastic.local:9200", + "index": "netifyd" + } +} +``` + +**Feed data to Grafana:** +```bash +# Netifyd exports Prometheus metrics +curl http://192.168.1.1:8081/metrics +``` + +**Integrate with CrowdSec:** +```bash +# CrowdSec can parse Netifyd logs for threat detection +# Configure in /etc/crowdsec/acquis.yaml +filenames: + - /var/log/netifyd.log +labels: + type: netifyd +``` + +### Performance Tuning + +**Optimize for high-bandwidth networks (1Gbps+):** +```bash +# Increase ring buffer size +ethtool -G eth0 rx 4096 tx 4096 +ethtool -G eth1 rx 4096 tx 4096 + +# Disable hardware offloading for accurate capture +ethtool -K eth0 gro off gso off tso off +ethtool -K eth1 gro off gso off tso off + +# Set bridge to forwarding mode +echo 1 > /proc/sys/net/bridge/bridge-nf-call-iptables +``` + +**USB Storage for PCAP captures:** +```bash +# Mount USB drive +mkdir -p /mnt/usb +mount /dev/sda1 /mnt/usb + +# Configure rotation +uci set network-modes.sniffer.pcap_path='/mnt/usb/captures' +uci set network-modes.sniffer.pcap_rotation='daily' +uci set network-modes.sniffer.pcap_retention='7' +uci commit network-modes +``` + +### Troubleshooting + +**No traffic visible:** +```bash +# Verify bridge members +brctl show + +# Check interface states +ip link show + +# Test with tcpdump +tcpdump -i br-lan -c 10 + +# Check Netifyd logs +logread | grep netifyd +``` + +**High CPU usage:** +```bash +# Disable DPI if not needed +uci set network-modes.sniffer.netifyd_enabled='0' + +# Reduce capture scope with filters +tcpdump -i br-lan 'not port 22' -w /dev/null + +# Check for hardware offloading +ethtool -k eth0 | grep offload +``` + ## Security - Mode switching creates automatic backups