#!/usr/bin/env python3
"""
estate_scan.py - discover everything on the home LAN and build/refresh an
inventory CSV ("network estate") for planning VLANs, Semaphore and PatchMon.

Sources combined:
  1. nmap ARP sweep + SYN scan of a few role-hinting ports (needs root)
  2. Pi-hole DHCP leases (catches sleepy devices that didn't answer the sweep)
  3. Reverse DNS via Pi-hole

Re-running is safe: rows are keyed on MAC, your planning columns are kept,
discovery columns are refreshed, and devices not seen this run are flagged.

Usage:
  sudo ./estate_scan.py --subnet 10.0.10.0/24 --dns 10.0.10.1
  sudo ./estate_scan.py --leases-ssh pihole --out estate.csv
  ./estate_scan.py --from-xml scan.xml --leases-file dhcp.leases   # offline
"""
import argparse
import csv
import datetime
import ipaddress
import os
import shutil
import subprocess
import sys
import xml.etree.ElementTree as ET

SUBNET = "10.0.10.0/24"   # change to your LAN
DNS = "10.0.10.1"         # your Pi-hole, for reverse DNS names
# 22 ssh, 53 dns, 80/443 web, 1883 mqtt, 3000 grafana, 8080 alt-web,
# 8086/8181 influxdb, 9100 node-exporter, 6052 esphome dashboard
PORTS = "22,53,80,443,1883,3000,6052,8080,8086,8181,9100"

# Column order = spreadsheet order: identity, planning (yours), housekeeping
COLS = [
    "ip", "hostname", "mac", "vendor", "category_guess", "open_ports", "ssh",
    # --- planning columns: filled in by you, never overwritten ---
    "friendly_name", "role", "location", "connection",
    "current_vlan", "target_vlan", "semaphore_group", "patchmon", "notes",
    # --- housekeeping ---
    "dns_name", "dhcp_name", "mac_randomised",
    "seen_this_run", "first_seen", "last_seen",
]
PLANNING = {"friendly_name", "role", "location", "connection", "current_vlan",
            "target_vlan", "semaphore_group", "patchmon", "notes"}


# ---------------------------------------------------------------- discovery
def run_nmap(subnet, dns, ports):
    if os.geteuid() != 0:
        sys.exit("Run with sudo - nmap needs root for ARP (MACs) and SYN scans.")
    if not shutil.which("nmap"):
        sys.exit("nmap not found:  sudo apt install nmap")
    cmd = ["nmap", "-sS", "-p", ports, "-T4", "--dns-servers", dns,
           "-oX", "-", subnet]
    print("Running:", " ".join(cmd), file=sys.stderr)
    return subprocess.run(cmd, capture_output=True, text=True,
                          check=True).stdout


def parse_nmap_xml(xml_text):
    hosts = []
    for h in ET.fromstring(xml_text).findall("host"):
        if h.find("status").get("state") != "up":
            continue
        rec = {"ip": "", "mac": "", "vendor": "", "dns_name": "", "open_ports": ""}
        for a in h.findall("address"):
            if a.get("addrtype") == "ipv4":
                rec["ip"] = a.get("addr")
            elif a.get("addrtype") == "mac":
                rec["mac"] = a.get("addr").lower()
                rec["vendor"] = a.get("vendor", "")
        hn = h.find("hostnames/hostname")
        if hn is not None:
            rec["dns_name"] = hn.get("name", "")
        rec["open_ports"] = " ".join(
            p.get("portid") for p in h.findall("ports/port")
            if p.find("state").get("state") == "open")
        hosts.append(rec)
    return hosts


def read_leases(path=None, ssh_host=None,
                remote_path="/etc/pihole/dhcp.leases"):
    """dnsmasq lease format: <expiry> <mac> <ip> <hostname|*> <client-id>"""
    if ssh_host:
        cmd = ["ssh", "-o", "BatchMode=yes", ssh_host, "cat", remote_path]
        # Under sudo, ssh as the real user so your keys / SSH CA cert are used
        if os.environ.get("SUDO_USER"):
            cmd = ["sudo", "-u", os.environ["SUDO_USER"]] + cmd
        try:
            text = subprocess.run(cmd, capture_output=True, text=True,
                                  check=True).stdout
        except subprocess.CalledProcessError as e:
            print(f"WARN: couldn't read leases from {ssh_host}: "
                  f"{e.stderr.strip()}", file=sys.stderr)
            return {}
    elif path:
        with open(path) as f:
            text = f.read()
    else:
        return {}
    leases = {}
    for line in text.splitlines():
        parts = line.split()
        if len(parts) < 4 or parts[0] == "duid":
            continue
        _, mac, ip, name = parts[:4]
        leases[mac.lower()] = {"ip": ip, "dhcp_name": "" if name == "*" else name}
    return leases


# ---------------------------------------------------------------- enrichment
def mac_is_randomised(mac):
    # Locally-administered bit set => 2nd hex digit is 2, 6, A or E
    return bool(mac) and mac[1].lower() in "26ae"


def guess_category(rec):
    v, h = rec["vendor"].lower(), rec["hostname"].lower()
    if h.startswith("uk0"):          # my meteor cameras' station-ID hostnames
        return "GMN meteor camera"
    if "raspberry" in v:
        return "Raspberry Pi"
    if "espressif" in v:
        return "ESP32 / IoT"
    if any(x in v for x in ("gl technologies", "tp-link", "zyxel", "cisco",
                            "netgear", "ubiquiti")):
        return "Network kit"
    if rec["mac_randomised"] == "yes":
        return "Phone/tablet (random MAC)"
    if "1883" in rec["open_ports"].split():
        return "MQTT broker"
    return ""


def key_for(rec):
    return rec["mac"] or f"ip:{rec['ip']}"  # scanning host has no MAC in nmap


def ip_sort(row):
    try:
        return (0, ipaddress.ip_address(row["ip"]))
    except ValueError:
        return (1, ipaddress.ip_address("0.0.0.0"))


# ---------------------------------------------------------------- merge/write
def build_current(nmap_hosts, leases):
    current = {}
    for h in nmap_hosts:
        lease = leases.get(h["mac"], {})
        h["dhcp_name"] = lease.get("dhcp_name", "")
        h["seen_this_run"] = "yes"
        current[key_for(h)] = h
    # Lease-only devices: asleep, offline, or didn't answer ARP in time
    for mac, lease in leases.items():
        if mac not in current:
            current[mac] = {"ip": lease["ip"], "mac": mac, "vendor": "",
                            "dns_name": "", "open_ports": "",
                            "dhcp_name": lease["dhcp_name"],
                            "seen_this_run": "lease only"}
    for rec in current.values():
        rec["hostname"] = rec["dhcp_name"] or rec["dns_name"].split(".")[0]
        rec["ssh"] = "yes" if "22" in rec["open_ports"].split() else ""
        rec["mac_randomised"] = "yes" if mac_is_randomised(rec["mac"]) else ""
        rec["category_guess"] = guess_category(rec)
    return current


def merge(existing_rows, current, today):
    merged = {key_for(r): r for r in existing_rows}
    for k, row in merged.items():          # assume gone until proven present
        row["seen_this_run"] = "no"
    for k, rec in current.items():
        row = merged.get(k, {c: "" for c in COLS})
        if not row.get("first_seen"):
            row["first_seen"] = today
        for c, v in rec.items():
            if c in COLS and c not in PLANNING:
                # keep a known vendor/name if this run didn't find one
                if v or c in ("open_ports", "ssh", "seen_this_run"):
                    row[c] = v
        if rec["seen_this_run"] == "yes":
            row["last_seen"] = today
        if not row.get("current_vlan"):
            row["current_vlan"] = "1 (flat LAN)"
        merged[k] = row
    return sorted(merged.values(), key=ip_sort)


def main():
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--subnet", default=SUBNET)
    ap.add_argument("--dns", default=DNS)
    ap.add_argument("--ports", default=PORTS)
    ap.add_argument("--leases-ssh", default="pihole",
                    help="ssh host for Pi-hole leases ('' to skip)")
    ap.add_argument("--leases-file", help="local copy of dhcp.leases instead")
    ap.add_argument("--from-xml", help="parse saved nmap -oX output, no scan")
    ap.add_argument("--out", default="network_estate.csv")
    args = ap.parse_args()

    xml_text = (open(args.from_xml).read() if args.from_xml
                else run_nmap(args.subnet, args.dns, args.ports))
    hosts = parse_nmap_xml(xml_text)
    leases = read_leases(path=args.leases_file,
                         ssh_host=None if args.leases_file else (args.leases_ssh or None))
    current = build_current(hosts, leases)

    existing = []
    if os.path.exists(args.out):
        with open(args.out, newline="") as f:
            existing = list(csv.DictReader(f))
        shutil.copy2(args.out, args.out + ".bak")

    rows = merge(existing, current, datetime.date.today().isoformat())
    with open(args.out, "w", newline="") as f:
        w = csv.DictWriter(f, fieldnames=COLS, extrasaction="ignore")
        w.writeheader()
        w.writerows(rows)

    # Hand the file back to the real user if we ran under sudo
    if os.environ.get("SUDO_UID"):
        os.chown(args.out, int(os.environ["SUDO_UID"]), int(os.environ["SUDO_GID"]))

    seen = sum(r["seen_this_run"] == "yes" for r in rows)
    lease_only = sum(r["seen_this_run"] == "lease only" for r in rows)
    gone = sum(r["seen_this_run"] == "no" for r in rows)
    print(f"{len(rows)} devices -> {args.out}  "
          f"(up: {seen}, lease only: {lease_only}, not seen: {gone})")


if __name__ == "__main__":
    main()
