Cobra
967fac5ce5
Parse nmap vendor name from MAC Address line (filtering out 'Unknown'). Fall back to socket.gethostbyaddr for IPs nmap didn't resolve a hostname for. Alert label is now: 'hostname (vendor)' | 'hostname' | 'vendor' | 'unknown', in that priority order.
308 lines
10 KiB
Python
308 lines
10 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
net_alerter.py — Presence-tracking network monitor.
|
|
Baseline on first run (silent). Alerts on join and rejoin.
|
|
"""
|
|
|
|
import json
|
|
import os
|
|
import re
|
|
import socket
|
|
import sqlite3
|
|
import subprocess
|
|
import sys
|
|
import urllib.parse
|
|
import urllib.request
|
|
from datetime import datetime, timezone
|
|
from pathlib import Path
|
|
|
|
# --- Config (overridable via env) ---
|
|
# Minimum consecutive missed scans before a device is considered gone and the
|
|
# tripwire resets. Uncomment to enable — set to 3 for 15-min grace at 5-min cron.
|
|
# ABSENT_THRESHOLD = int(os.getenv("NET_ALERTER_ABSENT_THRESHOLD", "3"))
|
|
|
|
MATRIX_HOMESERVER = os.getenv("MATRIX_HOMESERVER", "https://m.example.org")
|
|
MATRIX_ACCESS_TOKEN = os.getenv("MATRIX_ACCESS_TOKEN", "")
|
|
MATRIX_ROOM_ID = os.getenv("MATRIX_ROOM_ID", "!REDACTED:example.org")
|
|
MATRIX_USER = os.getenv("MATRIX_USER", "")
|
|
MATRIX_PASSWORD = os.getenv("MATRIX_PASSWORD", "")
|
|
DB_PATH = Path(os.getenv("NET_ALERTER_DB", "/opt/net_alerter/devices.db"))
|
|
ENV_PATH = Path(os.getenv("NET_ALERTER_ENV", "/opt/net_alerter/.env"))
|
|
|
|
|
|
def now_utc() -> str:
|
|
return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
|
|
|
|
|
def get_db() -> sqlite3.Connection:
|
|
DB_PATH.parent.mkdir(parents=True, exist_ok=True)
|
|
conn = sqlite3.connect(DB_PATH)
|
|
conn.execute("""
|
|
CREATE TABLE IF NOT EXISTS devices (
|
|
mac TEXT PRIMARY KEY,
|
|
ip TEXT,
|
|
name TEXT,
|
|
first_seen TEXT,
|
|
last_seen TEXT,
|
|
is_present INTEGER NOT NULL DEFAULT 1,
|
|
last_left TEXT
|
|
)
|
|
""")
|
|
# Migrate existing DBs that lack the new columns
|
|
existing = {row[1] for row in conn.execute("PRAGMA table_info(devices)")}
|
|
if "is_present" not in existing:
|
|
conn.execute("ALTER TABLE devices ADD COLUMN is_present INTEGER NOT NULL DEFAULT 1")
|
|
if "last_left" not in existing:
|
|
conn.execute("ALTER TABLE devices ADD COLUMN last_left TEXT")
|
|
# absent_count tracks consecutive missed scans (used by ABSENT_THRESHOLD)
|
|
if "absent_count" not in existing:
|
|
conn.execute("ALTER TABLE devices ADD COLUMN absent_count INTEGER NOT NULL DEFAULT 0")
|
|
conn.commit()
|
|
return conn
|
|
|
|
|
|
def refresh_token() -> str:
|
|
if not MATRIX_USER or not MATRIX_PASSWORD:
|
|
print("[error] Cannot refresh token: MATRIX_USER/MATRIX_PASSWORD not set", file=sys.stderr)
|
|
return ""
|
|
payload = json.dumps({
|
|
"type": "m.login.password",
|
|
"identifier": {"type": "m.id.user", "user": MATRIX_USER},
|
|
"password": MATRIX_PASSWORD,
|
|
"initial_device_display_name": "net-alerter",
|
|
}).encode()
|
|
req = urllib.request.Request(
|
|
f"{MATRIX_HOMESERVER}/_matrix/client/v3/login",
|
|
data=payload,
|
|
headers={"Content-Type": "application/json"},
|
|
method="POST",
|
|
)
|
|
try:
|
|
with urllib.request.urlopen(req, timeout=10) as r:
|
|
data = json.loads(r.read())
|
|
token = data.get("access_token", "")
|
|
if token and ENV_PATH.exists():
|
|
lines = ENV_PATH.read_text().splitlines()
|
|
lines = [
|
|
f"MATRIX_ACCESS_TOKEN={token}" if l.startswith("MATRIX_ACCESS_TOKEN=") else l
|
|
for l in lines
|
|
]
|
|
ENV_PATH.write_text("\n".join(lines) + "\n")
|
|
return token
|
|
except Exception as e:
|
|
print(f"[error] Token refresh failed: {e}", file=sys.stderr)
|
|
return ""
|
|
|
|
|
|
def _do_send(token: str, msg: str) -> int:
|
|
url = (
|
|
f"{MATRIX_HOMESERVER}/_matrix/client/v3/rooms/"
|
|
f"{urllib.parse.quote(MATRIX_ROOM_ID, safe='')}/send/m.room.message"
|
|
)
|
|
payload = json.dumps({"msgtype": "m.text", "body": msg}).encode()
|
|
req = urllib.request.Request(
|
|
url,
|
|
data=payload,
|
|
headers={
|
|
"Authorization": f"Bearer {token}",
|
|
"Content-Type": "application/json",
|
|
"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
|
|
},
|
|
method="POST",
|
|
)
|
|
try:
|
|
urllib.request.urlopen(req, timeout=10)
|
|
return 200
|
|
except urllib.error.HTTPError as e:
|
|
return e.code
|
|
except Exception as e:
|
|
print(f"[error] Matrix send exception: {e}", file=sys.stderr)
|
|
return 0
|
|
|
|
|
|
def send_matrix_alert(msg: str) -> None:
|
|
global MATRIX_ACCESS_TOKEN
|
|
if not MATRIX_ACCESS_TOKEN:
|
|
print("[warn] No MATRIX_ACCESS_TOKEN set, skipping alert", file=sys.stderr)
|
|
return
|
|
code = _do_send(MATRIX_ACCESS_TOKEN, msg)
|
|
if code == 401:
|
|
print("[info] Token expired, refreshing...", file=sys.stderr)
|
|
new_token = refresh_token()
|
|
if new_token:
|
|
MATRIX_ACCESS_TOKEN = new_token
|
|
_do_send(MATRIX_ACCESS_TOKEN, msg)
|
|
else:
|
|
print("[error] Could not refresh token, alert dropped", file=sys.stderr)
|
|
elif code == 403:
|
|
print("[error] Room permission denied (403) — check bot membership in room", file=sys.stderr)
|
|
elif code not in (200, 0):
|
|
print(f"[error] Matrix send failed with HTTP {code}", file=sys.stderr)
|
|
|
|
|
|
def get_local_subnets() -> list[str]:
|
|
try:
|
|
out = subprocess.check_output(["ip", "-o", "-4", "addr", "show"], text=True)
|
|
except Exception:
|
|
return []
|
|
|
|
subnets = []
|
|
for line in out.splitlines():
|
|
parts = line.split()
|
|
if len(parts) < 4:
|
|
continue
|
|
iface = parts[1]
|
|
cidr = parts[3]
|
|
if any(iface.startswith(p) for p in ("lo", "tailscale", "wg", "tun", "docker", "br-")):
|
|
continue
|
|
subnets.append(cidr)
|
|
return subnets
|
|
|
|
|
|
def scan_subnet(cidr: str) -> list[dict]:
|
|
try:
|
|
out = subprocess.check_output(
|
|
["sudo", "nmap", "-sn", "-PR", "--host-timeout", "5s", cidr],
|
|
text=True, stderr=subprocess.DEVNULL
|
|
)
|
|
except Exception:
|
|
return []
|
|
|
|
devices = []
|
|
current: dict = {}
|
|
for line in out.splitlines():
|
|
if line.startswith("Nmap scan report for"):
|
|
if current.get("mac"):
|
|
devices.append(current)
|
|
m = re.search(r"for (.+?)(?:\s+\((.+?)\))?$", line)
|
|
if m:
|
|
if m.group(2):
|
|
current = {"name": m.group(1), "ip": m.group(2), "mac": ""}
|
|
else:
|
|
current = {"name": "", "ip": m.group(1), "mac": ""}
|
|
elif "MAC Address:" in line:
|
|
m = re.search(r"MAC Address: ([0-9A-F:]{17})(?:\s+\((.+?)\))?", line)
|
|
if m:
|
|
current["mac"] = m.group(1).lower()
|
|
if m.group(2) and m.group(2) != "Unknown":
|
|
current["vendor"] = m.group(2)
|
|
|
|
if current.get("mac"):
|
|
devices.append(current)
|
|
|
|
return devices
|
|
|
|
|
|
def run() -> None:
|
|
conn = get_db()
|
|
ts = now_utc()
|
|
hostname = socket.gethostname()
|
|
|
|
subnets = get_local_subnets()
|
|
if not subnets:
|
|
print("[warn] No local subnets found", file=sys.stderr)
|
|
conn.close()
|
|
return
|
|
|
|
# Collect all MACs visible right now across all subnets
|
|
scan_results: dict[str, dict] = {}
|
|
for cidr in subnets:
|
|
for d in scan_subnet(cidr):
|
|
scan_results[d["mac"]] = d
|
|
|
|
# Is this the first run? (empty DB = baseline mode, no alerts)
|
|
row_count = conn.execute("SELECT COUNT(*) FROM devices").fetchone()[0]
|
|
baseline_mode = row_count == 0
|
|
if baseline_mode:
|
|
print(f"[info] Baseline run — seeding {len(scan_results)} devices, no alerts", file=sys.stderr)
|
|
|
|
alerts: list[tuple[str, dict]] = [] # (event_type, device_dict)
|
|
|
|
# Process devices currently on the network
|
|
for mac, d in scan_results.items():
|
|
row = conn.execute(
|
|
"SELECT is_present FROM devices WHERE mac=?", (mac,)
|
|
).fetchone()
|
|
|
|
if row is None:
|
|
# Brand new device
|
|
conn.execute(
|
|
"INSERT INTO devices (mac, ip, name, first_seen, last_seen, is_present, last_left) "
|
|
"VALUES (?,?,?,?,?,1,NULL)",
|
|
(mac, d["ip"], d["name"], ts, ts),
|
|
)
|
|
if not baseline_mode:
|
|
alerts.append(("NEW", d))
|
|
else:
|
|
is_present = row[0]
|
|
if is_present == 0:
|
|
# Known device rejoining
|
|
conn.execute(
|
|
"UPDATE devices SET ip=?, name=?, last_seen=?, is_present=1, last_left=NULL WHERE mac=?",
|
|
(d["ip"], d["name"], ts, mac),
|
|
)
|
|
if not baseline_mode:
|
|
alerts.append(("REJOIN", d))
|
|
else:
|
|
# Already present — just update last_seen, reset absent_count
|
|
conn.execute(
|
|
"UPDATE devices SET ip=?, name=?, last_seen=?, absent_count=0 WHERE mac=?",
|
|
(d["ip"], d["name"], ts, mac),
|
|
)
|
|
|
|
# Mark devices that were present but didn't appear in this scan as gone.
|
|
# absent_count increments each missed scan; is_present flips to 0 immediately
|
|
# (or after ABSENT_THRESHOLD consecutive misses if that option is enabled).
|
|
present_in_db = {
|
|
row[0]: row[1]
|
|
for row in conn.execute("SELECT mac, absent_count FROM devices WHERE is_present=1")
|
|
}
|
|
for mac, absent_count in present_in_db.items():
|
|
if mac in scan_results:
|
|
continue
|
|
new_count = absent_count + 1
|
|
# Uncomment the block below (and ABSENT_THRESHOLD above) to add a grace period:
|
|
# if new_count < ABSENT_THRESHOLD:
|
|
# conn.execute("UPDATE devices SET absent_count=? WHERE mac=?", (new_count, mac))
|
|
# continue
|
|
conn.execute(
|
|
"UPDATE devices SET is_present=0, last_left=?, absent_count=0 WHERE mac=?",
|
|
(ts, mac),
|
|
)
|
|
print(f"[info] Device left: {mac}", file=sys.stderr)
|
|
|
|
conn.commit()
|
|
conn.close()
|
|
|
|
# Send alerts
|
|
for event, d in alerts:
|
|
name = d.get("name", "")
|
|
vendor = d.get("vendor", "")
|
|
if not name:
|
|
try:
|
|
name = socket.gethostbyaddr(d["ip"])[0]
|
|
except Exception:
|
|
pass
|
|
if name and vendor:
|
|
label = f"{name} ({vendor})"
|
|
elif name:
|
|
label = name
|
|
elif vendor:
|
|
label = vendor
|
|
else:
|
|
label = "unknown"
|
|
tag = "NEW DEVICE" if event == "NEW" else "DEVICE REJOINED"
|
|
msg = (
|
|
f"[{hostname}] {tag}\n"
|
|
f" IP: {d['ip']}\n"
|
|
f" MAC: {d['mac']}\n"
|
|
f" Name: {label}\n"
|
|
f" Time: {ts}"
|
|
)
|
|
print(msg)
|
|
send_matrix_alert(msg)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
run()
|