threesearch/netmon repository overview

NetMon - Network Monitoring & Alert System

Description: NetMon is a lightweight network monitoring tool designed to detect new devices connecting to your network. It periodically runs ARP scan and sends alert email when an unknown device is detected. It also provides a simple local web interface to visualize the list of devices on your network, allowing you to name each device with an easy-to-remember name instead of MAC address.

Features:

✅ Runs ARP scan every X seconds (configurable via SCAN_SECONDS).

✅ Detects new devices connecting to the network.

✅ Sends alert emails using SMTP (Gmail SMTP or Sendgrid SMTP).

✅ Provides a web interface to visualize devices on the network.

✅ Name your devices with friendly names instead of MAC addresses.

✅ Lightweight & easy to deploy in a Docker container.

Configuration Parameters:

TZ: Timezone

SMTP_HOST: smtp.gmail.com or smtp.sendgrid.net

SMTP_PORT: 587

FROM_EMAIL_ADDRESS: Email address used for sending alerts.

SMTP_USER: Your Gmail account. If you use sendgrid, it will be apikey.

SMTP_PASSWORD: App password for Gmail SMTP authentication. You will need to generate an app password in your google account security. If you use sendgrid, it will be your sendgrid API key.

TO_EMAIL_ADRESS: Email address to receive alerts.

SCAN_SECONDS: How often (in seconds) to scan the network. Recommend: 300 seconds (5 minutes).

⁠📌 How to Use

⁠1️⃣ Run with Docker Compose or Portainer Stack

Use the following docker-compose.yml file:

volumes:
  netmondb:

services:
  netmon:
    image: threesearch/netmon:latest
    container_name: netmon
    environment:
      # Display First Seen and Last Seen of network device in local timezone
      - TZ=Asia/Singapore
      # gmail smtp
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - [email protected]
      - [email protected]
      - SMTP_PASSWORD=your gmail appl pass
      # sendgrid smtp
      #- SMTP_HOST=smtp.sendgrid.net
      #- SMTP_PORT=587
      #- [email protected]
      #- SMTP_USER=apikey
      #- SMTP_PASSWORD=DM.9fE4SXRCT5KL3rko7oSjvQ.ww34WinkE1GHrdfD9D3l0yjwv3KCmLFHeNwcY80zpDE
      - [email protected]
      - SCAN_SECONDS=300
    volumes:
      - netmondb:/db
    network_mode: "host"

2️⃣ Access the Web Interface
Open your browser and visit:

http://DOCKER_HOST_IP_ADDRESS

🔹 You will see a list of devices on your network.
🔹 You can assign friendly name to each device for easy identification.