DeviceTrust

LAN-based network security monitor with device fingerprinting, firewall integration, and a web dashboard. Detects unknown devices on your network, alerts you, and gives you one-click block/allow controls.

Windows-first, with Linux client support via hardware fingerprinting.

---

Features

Server (runs on one trusted machine on the LAN)

• Connection monitor — watches netstat/live TCP connections to detect new devices
• Announcement listener — UDP listener that accepts hardware fingerprints broadcast from client machines
• Trust database — maintains trusted, pending, and blocked device lists
• Firewall integration — when running as Administrator, blocks untrusted IPs via Windows Firewall rules (DeviceTrust_ prefixed)
• Desktop notifications — Windows toast alert whenever a new unknown device appears
• Web dashboard — local web UI at http://127.0.0.1:9998 with live device feed, approve/block buttons, event log
• Tray icon — quick access to dashboard, mute/unmute notifications
• Event log — persistent audit log of trust decisions and first-seen events

Client (runs on every machine that should be auto-trusted)

• Hardware fingerprint — cross-platform (Windows + Linux) device ID derived from stable hardware identifiers
• Periodic UDP announcement — broadcasts fingerprint to the server on port 9999
• Zero-config LAN discovery — no server IP needed; broadcasts to subnet

---

Ports

Port	Direction	Purpose
9999/UDP	Inbound on server	Device fingerprint announcements
9998/TCP	localhost only	Web dashboard

---

Install

Prebuilt Windows installer

Run DeviceTrust_Setup.exe on the machine you want to be the server. Run DeviceTrustClient_Setup.exe on every other machine on the LAN.

From source

pip install -r requirements.txt

# Server (needs admin for firewall blocking)
python -m server.main

# Client (any user)
python -m client.main

The server creates data/config.json, data/trusted_devices.json, and data/event_log.json on first run. These are gitignored — your trust state stays on disk.

---

Configuration

data/config.json (auto-generated on first run):

{
  "self_ip": "10.0.0.241",
  "lan_subnet": "10.0.0.",
  "setup_complete": true
}

• self_ip — the server's own IP (auto-detected)
• lan_subnet — subnet prefix used to filter out non-LAN traffic

---

Architecture

┌──────────────────────────┐       UDP 9999         ┌──────────────────────────┐
│   Trusted Client         │ ─────fingerprint─────► │   DeviceTrust Server     │
│   (Windows / Linux)      │                        │                          │
│                          │                        │ ┌──────────────────────┐ │
│  client/main.py          │                        │ │ AnnouncementServer   │ │
│    - hardware ID         │                        │ │ ConnectionMonitor    │ │
│    - broadcast every 30s │                        │ │ Trust DB             │ │
└──────────────────────────┘                        │ │ Firewall rules       │ │
                                                    │ │ Web dashboard :9998  │ │
                                                    │ │ Tray app             │ │
                                                    │ └──────────────────────┘ │
                                                    └──────────────────────────┘
                                                                │
                                                                │ Win firewall (admin only)
                                                                ▼
                                                    ┌──────────────────────────┐
                                                    │ Untrusted device blocked │
                                                    └──────────────────────────┘

---

Build

The repo includes PyInstaller specs and NSIS installer scripts for building Windows installers:

# Build server + client executables
build.bat

# Installers (requires NSIS)
makensis installer.nsi
makensis installer_client.nsi

Artifacts land in dist/ and build/ — both .gitignored.

---

Files

DeviceTrust/
├── server/
│   ├── main.py                    server entrypoint
│   ├── announcement_server.py     UDP listener for fingerprints
│   ├── connection_monitor.py      watches TCP connections
│   ├── database.py                trust DB (JSON-backed)
│   ├── firewall.py                Windows Firewall rule management
│   ├── notifications.py           toast alerts
│   ├── tray.py                    system tray icon
│   ├── web_dashboard.py           Flask dashboard
│   ├── static/                    dashboard UI assets
│   └── templates/
├── client/
│   ├── main.py                    client entrypoint
│   ├── fingerprint_windows.py     WMI-based hardware ID
│   └── fingerprint_linux.py       /sys-based hardware ID
├── requirements.txt
├── build.bat                      build both executables
├── installer.nsi                  NSIS installer (server)
└── installer_client.nsi           NSIS installer (client)

---

License

Copyright (c) 2025-2026 Colin McDonough.

Personal and non-commercial use permitted with attribution. Commercial use requires written consent. Contact: cmcdonough@50words.com.