ntopng HA Bridge

A bridge that connects ntopng network monitoring to Home Assistant.

Features

• 🔌 Dual deployment options: Native HACS integration or Docker/MQTT bridge
• 📊 Real-time network throughput monitoring (upload/download)
• 🖥️ Active hosts and flows tracking
• ⚠️ Alert and anomaly monitoring
• 📉 TCP health metrics (retransmissions, lost packets)
• 🌍 Geographic flow analysis (unique countries)
• 🔒 Security indicators (blacklisted hosts, risk scores)
• 🩺 Health monitoring with API latency and error tracking
• ⚙️ Works with ntopng Community Edition (no paid license required)

Sensors

Traffic Sensors

Sensor	Description	Unit
Network Throughput	Combined throughput	bit/s
Upload Speed	Upload throughput	bit/s
Download Speed	Download throughput	bit/s
Total Bytes	Total bytes transferred	bytes
Bytes Uploaded	Upload volume	bytes
Bytes Downloaded	Download volume	bytes
LAN to WAN Traffic	Outbound from local network	bytes
WAN to LAN Traffic	Inbound to local network	bytes
Total Packets	Packets processed	packets
Packet Drops	Dropped packets	packets

Network Sensors

Sensor	Description	Unit
Active Hosts	Number of active hosts	hosts
Local Hosts	Number of local hosts	hosts
Active Flows	Number of active flows	flows

Alert & Anomaly Sensors

Sensor	Description	Unit
Engaged Alerts	Total active alerts	alerts
Critical Alerts	Error-level alerts	alerts
Warning Alerts	Warning-level alerts	alerts
Alerted Flows	Flows with alerts	flows
Remote Host Anomalies	Remote anomalies detected	anomalies
Local Host Anomalies	Local anomalies detected	anomalies

TCP Health Sensors

Sensor	Description	Unit
TCP Retransmissions	Retransmitted packets	packets
TCP Lost	Lost packets	packets
TCP Out of Order	Out-of-order packets	packets

Flow Analysis Sensors

Sensor	Description	Unit
Top Protocol	Most common L7 protocol	-
Top Protocol by Traffic	Highest bandwidth protocol	-
Unique Countries	Countries in active flows	countries
UDP Flows	Count of UDP flows	flows
TCP Flows	Count of TCP flows	flows

Security Sensors

Sensor	Description	Unit
Blacklisted Hosts	Hosts on blacklists	hosts
Total Risk Score	Aggregate risk score	-

System Sensors

Sensor	Description	Unit
CPU Load	ntopng host CPU	%
Memory Used	Memory usage	MB
Memory Total	Total memory	MB
ntopng Memory	Process memory	MB
Uptime	Human-readable uptime	-
Uptime Seconds	Numeric uptime	seconds

Binary Sensors

Sensor	Description
API Healthy	API connectivity status
Has Alerts	Alert problem indicator
Has Blacklisted Hosts	Security indicator

Requirements

• ntopng (Community Edition or higher)
• Home Assistant 2024.1.0 or higher
• For HACS installation: HACS 1.30.0 or higher
• For Docker installation: MQTT broker (e.g., Mosquitto)

Installation

Option 1: HACS (Recommended)

1. Open HACS in Home Assistant
2. Click the three dots in the top right → Custom repositories
3. Add https://github.com/pentafive/ntopng-ha-bridge as an Integration
4. Search for "ntopng" and install
5. Restart Home Assistant
6. Go to Settings → Devices & Services → Add Integration → ntopng

Option 2: Manual Installation

1. Copy custom_components/ntopng/ to your Home Assistant config/custom_components/ directory
2. Restart Home Assistant
3. Go to Settings → Devices & Services → Add Integration → ntopng

Option 3: Docker (Standalone MQTT Bridge)

Use this method if you prefer to run a standalone bridge that publishes to MQTT.

1. Clone the repository:

git clone https://github.com/pentafive/ntopng-ha-bridge.git
cd ntopng-ha-bridge

2. Copy and configure environment:

cp .env.example .env
# Edit .env with your settings

3. Build and run:

docker-compose up -d

Configuration

HACS Integration Configuration

When adding the integration, you'll need:

Field	Description
URL	ntopng server URL (e.g., https://192.168.1.1:3000)
Username	ntopng username (default: admin)
Password	ntopng password
Verify SSL	Enable for trusted certificates (disable for self-signed)
Interface	Select which network interface to monitor

Note: The integration uses HTTP Basic Authentication, which is the standard ntopng API authentication method.

Docker Bridge Environment Variables

Variable	Description	Default
NTOPNG_URL	ntopng server URL	https://localhost:3000
NTOPNG_USERNAME	ntopng username	admin
NTOPNG_PASSWORD	ntopng password	(required)
NTOPNG_IFID	Interface ID to monitor	0
NTOPNG_VERIFY_SSL	Verify SSL certificate	false
HA_MQTT_BROKER	MQTT broker hostname	homeassistant.local
HA_MQTT_PORT	MQTT broker port	1883
HA_MQTT_USER	MQTT username	ntopng-ha-bridge
HA_MQTT_PASS	MQTT password	(required)
POLL_INTERVAL_SECONDS	Polling interval	60
DEBUG_MODE	Enable debug logging	false

Finding the Interface ID

1. Open ntopng web interface
2. Look at the URL when viewing an interface
3. The ifid parameter is your interface ID (e.g., ifid=0)

Example Dashboard Card

Entity IDs follow the pattern: sensor.ntopng_{interface}_{sensor_name}

type: entities
title: Network Monitor
entities:
  - entity: sensor.ntopng_eth0_network_throughput
    name: Network Throughput
  - entity: sensor.ntopng_eth0_upload_speed
    name: Upload Speed
  - entity: sensor.ntopng_eth0_download_speed
    name: Download Speed
  - entity: sensor.ntopng_eth0_active_hosts
    name: Active Hosts
  - entity: sensor.ntopng_eth0_active_flows
    name: Active Flows
  - entity: sensor.ntopng_eth0_top_protocol
    name: Top Protocol
  - entity: sensor.ntopng_eth0_unique_countries
    name: Countries
  - entity: binary_sensor.ntopng_eth0_api_healthy
    name: API Status

Test Mode (Docker)

Run a quick test without starting the monitoring loop:

# With environment variables set
TEST_MODE=true python3 ntopng-ha-bridge.py

# Or with Docker
docker run --rm -e NTOPNG_URL=... -e NTOPNG_TOKEN=... -e TEST_MODE=true ntopng-ha-bridge

Troubleshooting

API Connection Issues

1. Verify ntopng is accessible: curl -k https://your-ntopng:3000
2. Test API token: curl -k -H "Authorization: Token YOUR_TOKEN" https://your-ntopng:3000/lua/rest/v2/get/ntopng/info.lua
3. Check interface ID is correct

MQTT Connection Issues (Docker mode)

1. Verify MQTT broker is running
2. Test with mosquitto_pub / mosquitto_sub
3. Check Home Assistant MQTT integration logs

No Sensors in Home Assistant

HACS mode:

1. Check Home Assistant logs for errors
2. Verify the integration shows as loaded in Settings → Devices & Services

Docker mode:

1. Check MQTT broker receives messages (use MQTT Explorer)
2. Verify discovery prefix matches HA configuration
3. Look for errors in Home Assistant logs

License

Apache License 2.0 - See LICENSE for details.

Contributing

Contributions welcome! Please open an issue or pull request.

Related Projects

• pskr-ha-bridge - PSKReporter to Home Assistant bridge
• wspr-ha-bridge - WSPR to Home Assistant bridge
• ntopng - The network monitoring tool this bridge integrates with