CyberMind-FR
9ce67f2da5
- Changed form sections from type 'secubox' to match actual UCI config - General/Dashboard/Module/Notification sections now use type 'core' - Alert Thresholds section now uses type 'diagnostics' - Security Settings section now uses type 'security' - Advanced Settings section uses type 'core' - Fixes "This section contains no values yet" errors 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
339 lines
11 KiB
Markdown
339 lines
11 KiB
Markdown
# SecuBox Netifyd Deep Packet Inspection Interface
|
|
|
|
Complete LuCI interface for Netifyd DPI engine with real-time flow monitoring, application detection, and network analytics.
|
|
|
|
## Features
|
|
|
|
### Real-Time Monitoring
|
|
- **Live Flow Tracking**: Monitor active network flows in real-time via socket interface
|
|
- **Socket Integration**: Connect to Netifyd via TCP or Unix domain socket
|
|
- **Auto-Refresh**: Configurable polling intervals for live updates
|
|
|
|
### Application & Protocol Detection
|
|
- **Deep Packet Inspection**: Leverage Netifyd's DPI engine
|
|
- **Application Identification**: Detect and track applications (HTTP, HTTPS, SSH, DNS, etc.)
|
|
- **Protocol Analysis**: Identify network protocols and analyze traffic patterns
|
|
- **SSL/TLS Inspection**: Extract SSL certificate information and cipher details
|
|
|
|
### Device Tracking
|
|
- **Network Discovery**: Automatically detect devices on the network
|
|
- **Traffic Analytics**: Track upload/download statistics per device
|
|
- **MAC/IP Mapping**: Correlate MAC addresses with IP addresses
|
|
- **Last Seen Tracking**: Monitor device activity timestamps
|
|
|
|
### Service Management
|
|
- **Start/Stop/Restart**: Full control of Netifyd service
|
|
- **Enable/Disable**: Configure auto-start on boot
|
|
- **Status Monitoring**: View service health and uptime
|
|
- **Configuration**: Manage Netifyd settings via UCI
|
|
|
|
### Analytics & Reporting
|
|
- **Top Applications**: Visual charts of most-used applications
|
|
- **Top Protocols**: Protocol usage statistics
|
|
- **Traffic Statistics**: Total bytes, packets, and flow counts
|
|
- **Export Functionality**: Export flows to JSON or CSV format
|
|
|
|
## Requirements
|
|
|
|
- OpenWrt 21.02 or later
|
|
- LuCI (luci-base)
|
|
- netifyd package installed
|
|
- jq (for JSON processing)
|
|
- secubox-core
|
|
|
|
## Installation
|
|
|
|
### Via SecuBox App Store
|
|
```bash
|
|
# From LuCI Admin panel
|
|
Navigate to SecuBox → App Store → Search for "Netifyd"
|
|
Click "Install"
|
|
```
|
|
|
|
### Manual Installation
|
|
```bash
|
|
opkg update
|
|
opkg install luci-app-secubox-netifyd
|
|
service rpcd restart
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Basic Setup
|
|
|
|
1. Install netifyd:
|
|
```bash
|
|
opkg install netifyd
|
|
```
|
|
|
|
2. Configure netifyd socket (edit `/etc/netifyd.conf`):
|
|
```ini
|
|
[socket]
|
|
listen_path[0] = /var/run/netifyd/netifyd.sock
|
|
listen_address[0] = 127.0.0.1:7150
|
|
```
|
|
|
|
3. Start netifyd:
|
|
```bash
|
|
service netifyd start
|
|
service netifyd enable
|
|
```
|
|
|
|
4. Access LuCI interface:
|
|
```
|
|
Navigate to: SecuBox → Network Intelligence
|
|
```
|
|
|
|
### Advanced Configuration
|
|
|
|
Configure via LuCI Settings page or UCI:
|
|
|
|
```bash
|
|
uci set secubox-netifyd.settings.socket_address='127.0.0.1'
|
|
uci set secubox-netifyd.settings.socket_port='7150'
|
|
uci set secubox-netifyd.settings.auto_start='1'
|
|
uci set secubox-netifyd.monitoring.enable_app_detection='1'
|
|
uci set secubox-netifyd.analytics.enabled='1'
|
|
uci commit secubox-netifyd
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Dashboard
|
|
- View real-time service status
|
|
- Monitor active flows, devices, and applications
|
|
- Quick statistics overview
|
|
- Service control buttons
|
|
|
|
### Live Flows
|
|
- Real-time flow table with auto-refresh
|
|
- Source/destination IP and ports
|
|
- Protocol and application detection
|
|
- Traffic statistics (bytes, packets, duration)
|
|
- Export flows to JSON/CSV
|
|
|
|
### Applications
|
|
- Top applications by traffic volume
|
|
- Flow counts per application
|
|
- Traffic percentage visualization
|
|
- Sortable application list
|
|
|
|
### Devices
|
|
- Active device list with MAC/IP addresses
|
|
- Upload/download statistics per device
|
|
- Last seen timestamps
|
|
- Total traffic tracking
|
|
|
|
### Settings
|
|
- Socket configuration (TCP/Unix)
|
|
- Flow retention and limits
|
|
- Monitoring toggles
|
|
- Analytics preferences
|
|
- Alert configuration
|
|
|
|
## API Methods
|
|
|
|
### Service Control
|
|
- `get_service_status` - Get Netifyd service status
|
|
- `service_start` - Start Netifyd service
|
|
- `service_stop` - Stop Netifyd service
|
|
- `service_restart` - Restart Netifyd service
|
|
- `service_enable` - Enable auto-start
|
|
- `service_disable` - Disable auto-start
|
|
|
|
### Data Retrieval
|
|
- `get_realtime_flows` - Get live flow data
|
|
- `get_flow_statistics` - Get flow statistics
|
|
- `get_top_applications` - Get top applications
|
|
- `get_top_protocols` - Get top protocols
|
|
- `get_detected_devices` - Get detected devices
|
|
- `get_dashboard` - Get dashboard summary
|
|
|
|
### Configuration
|
|
- `get_config` - Get current configuration
|
|
- `update_config` - Update configuration
|
|
- `get_interfaces` - Get monitored interfaces
|
|
|
|
### Utilities
|
|
- `clear_cache` - Clear flow cache
|
|
- `export_flows` - Export flows (JSON/CSV)
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ LuCI Frontend (JavaScript) │
|
|
│ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
|
|
│ │Dashboard│ │ Flows │ │Applications/ │ │
|
|
│ │ │ │ │ │ Devices │ │
|
|
│ └─────────┘ └──────────┘ └──────────────┘ │
|
|
└──────────────────┬──────────────────────────┘
|
|
│ RPC Calls
|
|
┌──────────────────▼──────────────────────────┐
|
|
│ RPCD Backend (Shell) │
|
|
│ luci.secubox-netifyd │
|
|
│ ┌────────────────────────────────────────┐ │
|
|
│ │ Service Control │ Data Aggregation │ │
|
|
│ │ Config Management │ Statistics │ │
|
|
│ └────────────────────────────────────────┘ │
|
|
└──────────────────┬──────────────────────────┘
|
|
│ Socket/CLI
|
|
┌──────────────────▼──────────────────────────┐
|
|
│ Netifyd DPI Engine │
|
|
│ ┌────────────────────────────────────────┐ │
|
|
│ │ Deep Packet Inspection │ │
|
|
│ │ Application Detection │ │
|
|
│ │ Protocol Analysis │ │
|
|
│ │ Flow Tracking │ │
|
|
│ └────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Netifyd Socket Interface
|
|
|
|
Netifyd streams JSON data via:
|
|
- **TCP Socket**: `127.0.0.1:7150` (default)
|
|
- **Unix Socket**: `/var/run/netifyd/netifyd.sock`
|
|
|
|
### Example Flow Data Structure
|
|
```json
|
|
{
|
|
"ip_orig": "192.168.1.100",
|
|
"ip_resp": "93.184.216.34",
|
|
"port_orig": 54321,
|
|
"port_resp": 443,
|
|
"protocol": "TCP",
|
|
"application": "HTTPS",
|
|
"bytes_orig": 12345,
|
|
"bytes_resp": 98765,
|
|
"packets_orig": 45,
|
|
"packets_resp": 123,
|
|
"duration": 120,
|
|
"ssl_sni": "example.com"
|
|
}
|
|
```
|
|
|
|
## Flow Plugin Integration
|
|
|
|
SecuBox can emit the plugin configurations referenced in the Netify.ai examples for tagging BitTorrent traffic with IP sets and pushing verdicts into nftables. After copying the relevant Netify plugin binaries into `/usr/lib/netifyd/`, open the **Flow Export → Flow Plugins** section in LuCI to enable the `mark-bittorrent-with-ip-sets` and `block-traffic-with-nftables` templates. Hit **Apply Flow Plugins** to regenerate `/etc/netifyd/plugins.d/secubox-*.conf` and restart Netifyd so the new ipsets and nftables chains are activated.
|
|
|
|
Refer to the upstream examples for exact `ipset`/`chain` rules:
|
|
- https://www.netify.ai/documentation/netify-plugins/v5/examples/mark-bittorrent-with-ip-sets
|
|
- https://www.netify.ai/documentation/netify-plugins/v5/examples/block-traffic-with-nftables
|
|
|
|
## Troubleshooting
|
|
|
|
### Netifyd Not Starting
|
|
```bash
|
|
# Check netifyd installation
|
|
which netifyd
|
|
|
|
# Check configuration
|
|
cat /etc/netifyd.conf
|
|
|
|
# View logs
|
|
logread | grep netifyd
|
|
|
|
# Restart manually
|
|
/etc/init.d/netifyd restart
|
|
```
|
|
|
|
### Socket Connection Failed
|
|
```bash
|
|
# Test TCP socket
|
|
nc -z 127.0.0.1 7150
|
|
|
|
# Check netifyd process
|
|
ps | grep netifyd
|
|
|
|
# Verify socket configuration
|
|
grep listen /etc/netifyd.conf
|
|
```
|
|
|
|
### No Flow Data
|
|
```bash
|
|
# Check if netifyd is capturing
|
|
netifyd -s
|
|
|
|
# Verify interfaces
|
|
grep interface /etc/netifyd.conf
|
|
|
|
# Check dump file
|
|
cat /run/netifyd/sink-request.json
|
|
```
|
|
|
|
## Performance Considerations
|
|
|
|
- **Flow Limit**: Default 10,000 flows (configurable)
|
|
- **Retention**: Default 1 hour (configurable)
|
|
- **Polling Interval**: 3-10 seconds (configurable)
|
|
- **Display Limit**: 100 flows in UI (full export available)
|
|
|
|
## Security Notes
|
|
|
|
- Socket listens on localhost by default
|
|
- No external access without explicit configuration
|
|
- Flow data contains sensitive network information
|
|
- Recommend firewall rules if exposing socket externally
|
|
|
|
## Development
|
|
|
|
### File Structure
|
|
```
|
|
luci-app-secubox-netifyd/
|
|
├── Makefile
|
|
├── README.md
|
|
├── root/
|
|
│ ├── etc/config/secubox-netifyd
|
|
│ └── usr/
|
|
│ ├── libexec/rpcd/luci.secubox-netifyd
|
|
│ └── share/
|
|
│ ├── rpcd/acl.d/luci-app-secubox-netifyd.json
|
|
│ └── luci/menu.d/luci-app-secubox-netifyd.json
|
|
└── htdocs/luci-static/resources/
|
|
├── secubox-netifyd/
|
|
│ ├── api.js
|
|
│ └── netifyd.css
|
|
└── view/secubox-netifyd/
|
|
├── dashboard.js
|
|
├── flows.js
|
|
├── applications.js
|
|
├── devices.js
|
|
└── settings.js
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - Copyright (C) 2025 CyberMind.fr
|
|
|
|
## Links
|
|
|
|
- [Netifyd Official Site](https://www.netify.ai/)
|
|
- [Netifyd Documentation](https://www.netify.ai/documentation/)
|
|
- [OpenWrt Packages](https://openwrt.org/packages/)
|
|
- [SecuBox Project](https://github.com/CyberMind-FR/secubox-openwrt)
|
|
|
|
## Credits
|
|
|
|
- **Netify by eGloo**: Deep packet inspection engine
|
|
- **SecuBox Team**: LuCI integration and interface design
|
|
- **OpenWrt Community**: Platform and package ecosystem
|
|
## Collector Setup Script
|
|
|
|
Use `/usr/bin/netifyd-collector-setup` to enable the flow exporter and install the cron job
|
|
that runs `/usr/bin/netifyd-collector` every minute. The script accepts:
|
|
|
|
```
|
|
/usr/bin/netifyd-collector-setup [unix|tcp] [path_or_host[:port]]
|
|
```
|
|
|
|
Examples:
|
|
|
|
```
|
|
/usr/bin/netifyd-collector-setup unix /tmp/netifyd-flows.json
|
|
/usr/bin/netifyd-collector-setup tcp 127.0.0.1:9501
|
|
```
|
|
|
|
Each invocation updates `/etc/config/secubox-netifyd`, writes `/etc/netifyd.d/secubox-sink.conf`,
|
|
creates the cron entry (`* * * * * /usr/bin/netifyd-collector`), and restarts `netifyd`.
|