lanfence 0.1.0__py3-none-any.whl

lanfence/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026-present Stable State Consulting Ltd
+# SPDX-License-Identifier: MIT
+
+"""LAN Fence - defensive LAN device monitor."""
+
+__version__ = "0.1.0"

lanfence/alerts.py

@@ -0,0 +1,134 @@
+# Copyright (c) 2026-present Stable State Consulting Ltd
+# SPDX-License-Identifier: MIT
+
+"""Alert dispatch: syslog, email, webhook.
+
+LAN Fence never calls out to any third-party service on its own - the
+operator opts into each channel explicitly in config, and every channel here
+is a destination *they* configured (their own syslog daemon, mail relay, or
+webhook endpoint).
+"""
+
+from __future__ import annotations
+
+import json
+import smtplib
+import syslog
+import urllib.error
+import urllib.request
+from email.message import EmailMessage
+
+from lanfence.config import AlertConfig
+from lanfence.logging_config import get_logger
+from lanfence.models import Finding
+
+log = get_logger("alerts")
+
+_SEVERITY_RANK = {"info": 0, "medium": 1, "high": 2}
+
+_SYSLOG_FACILITIES = {
+    "user": syslog.LOG_USER,
+    "daemon": syslog.LOG_DAEMON,
+    "local0": syslog.LOG_LOCAL0,
+    "local1": syslog.LOG_LOCAL1,
+    "local2": syslog.LOG_LOCAL2,
+    "local3": syslog.LOG_LOCAL3,
+    "local4": syslog.LOG_LOCAL4,
+    "local5": syslog.LOG_LOCAL5,
+    "local6": syslog.LOG_LOCAL6,
+    "local7": syslog.LOG_LOCAL7,
+}
+
+_SYSLOG_SEVERITY = {
+    "high": syslog.LOG_ALERT,
+    "medium": syslog.LOG_WARNING,
+    "info": syslog.LOG_INFO,
+}
+
+
+def findings_to_alert(findings: list[Finding], cfg: AlertConfig) -> list[Finding]:
+    """Findings at or above ``cfg.min_severity``, worth dispatching."""
+
+    threshold = _SEVERITY_RANK[cfg.min_severity]
+    return [f for f in findings if _SEVERITY_RANK[f.severity] >= threshold]
+
+
+def send_syslog(findings: list[Finding], cfg: AlertConfig) -> None:
+    if not cfg.syslog.enabled or not findings:
+        return
+    facility = _SYSLOG_FACILITIES.get(cfg.syslog.facility, syslog.LOG_USER)
+    syslog.openlog(ident="lanfence", facility=facility)
+    try:
+        for finding in findings:
+            priority = _SYSLOG_SEVERITY.get(finding.severity, syslog.LOG_INFO)
+            syslog.syslog(priority, f"[{finding.severity.upper()}] {finding.title} (mac={finding.mac})")
+    finally:
+        syslog.closelog()
+
+
+def send_email(findings: list[Finding], cfg: AlertConfig) -> None:
+    if not cfg.email.enabled or not findings:
+        return
+    if not cfg.email.to_addrs or not cfg.email.from_addr:
+        log.warning("email alerts enabled but from_addr/to_addrs not configured; skipping")
+        return
+
+    lines = [f"LAN Fence: {len(findings)} finding(s)\n"]
+    for finding in findings:
+        lines.append(f"[{finding.severity.upper()}] {finding.title}")
+        lines.append(f"  MAC: {finding.mac}")
+        if finding.rationale:
+            lines.append(f"  {finding.rationale}")
+        if finding.recommendation:
+            lines.append(f"  Recommendation: {finding.recommendation}")
+        lines.append("")
+
+    msg = EmailMessage()
+    msg["Subject"] = f"LAN Fence: {len(findings)} finding(s) on your network"
+    msg["From"] = cfg.email.from_addr
+    msg["To"] = ", ".join(cfg.email.to_addrs)
+    msg.set_content("\n".join(lines))
+
+    try:
+        with smtplib.SMTP(cfg.email.smtp_host, cfg.email.smtp_port, timeout=10) as smtp:
+            if cfg.email.use_tls:
+                smtp.starttls()
+            if cfg.email.username and cfg.email.password:
+                smtp.login(cfg.email.username, cfg.email.password)
+            smtp.send_message(msg)
+    except (smtplib.SMTPException, OSError) as exc:
+        log.error("failed to send email alert: %s", exc)
+
+
+def send_webhook(findings: list[Finding], cfg: AlertConfig) -> None:
+    if not cfg.webhook.enabled or not findings:
+        return
+    if not cfg.webhook.url:
+        log.warning("webhook alerts enabled but no url configured; skipping")
+        return
+
+    payload = json.dumps({"findings": [f.model_dump(mode="json") for f in findings]}).encode("utf-8")
+    request = urllib.request.Request(
+        cfg.webhook.url,
+        data=payload,
+        headers={"Content-Type": "application/json", "User-Agent": "lanfence"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=cfg.webhook.timeout_seconds) as resp:  # noqa: S310
+            resp.read()
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        log.error("failed to send webhook alert: %s", exc)
+
+
+def dispatch(findings: list[Finding], cfg: AlertConfig) -> list[Finding]:
+    """Send every finding at or above ``cfg.min_severity`` to every enabled
+    channel. Returns the findings that were dispatched."""
+
+    to_send = findings_to_alert(findings, cfg)
+    if not to_send:
+        return []
+    send_syslog(to_send, cfg)
+    send_email(to_send, cfg)
+    send_webhook(to_send, cfg)
+    return to_send

lanfence/allowlist.py

@@ -0,0 +1,101 @@
+# Copyright (c) 2026-present Stable State Consulting Ltd
+# SPDX-License-Identifier: MIT
+
+"""The allowlist of devices you trust (``lanfence allow``).
+
+Findings about an allowlisted device are downgraded to ``info`` so your own
+router, phones and laptops stop showing up as "unknown device" every time they
+reconnect. This is just data - allowlisting a MAC does not verify it, and MAC
+addresses are trivially spoofed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from lanfence.fsutil import atomic_write
+from lanfence.logging_config import get_logger
+from lanfence.netutil import normalize_mac
+
+log = get_logger("allowlist")
+
+
+@dataclass
+class AllowEntry:
+    mac: str
+    name: str
+    notes: str = ""
+
+    def as_dict(self) -> dict:
+        row = {"mac": self.mac, "name": self.name}
+        if self.notes:
+            row["notes"] = self.notes
+        return row
+
+
+class Allowlist:
+    def __init__(self, entries: list[AllowEntry], path: Path | None = None) -> None:
+        self.entries = entries
+        self.path = path
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+    @classmethod
+    def load(cls, path: Path | str | None) -> "Allowlist":
+        if path is None:
+            return cls([], None)
+        path = Path(path)
+        if not path.is_file():
+            return cls([], path)
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        entries: list[AllowEntry] = []
+        for row in data.get("allow", []) or []:
+            try:
+                entries.append(
+                    AllowEntry(
+                        mac=normalize_mac(str(row["mac"])),
+                        name=str(row.get("name") or "unnamed"),
+                        notes=str(row.get("notes") or ""),
+                    )
+                )
+            except (KeyError, TypeError, ValueError):
+                log.warning("skipping malformed allowlist entry: %r", row)
+        return cls(entries, path)
+
+    def save(self) -> None:
+        if self.path is None:
+            raise ValueError("allowlist has no path to save to")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        body = yaml.safe_dump({"allow": [e.as_dict() for e in self.entries]}, sort_keys=False)
+        atomic_write(
+            self.path,
+            "# LAN Fence allowlist - devices you trust; their findings are\n"
+            "# downgraded to info. A MAC address is trivially spoofed, so this is\n"
+            "# a mute button, not proof of identity.\n" + body,
+            mode=0o644,
+        )
+
+    def match(self, mac: str) -> AllowEntry | None:
+        norm = normalize_mac(mac)
+        for entry in self.entries:
+            if entry.mac == norm:
+                return entry
+        return None
+
+    def add(self, mac: str, name: str, notes: str = "") -> AllowEntry:
+        norm = normalize_mac(mac)
+        entry = AllowEntry(norm, name, notes)
+        self.entries = [e for e in self.entries if e.mac != norm]
+        self.entries.append(entry)
+        return entry
+
+    def remove(self, mac: str) -> AllowEntry | None:
+        norm = normalize_mac(mac)
+        existing = self.match(norm)
+        if existing is not None:
+            self.entries = [e for e in self.entries if e.mac != norm]
+        return existing

lanfence/cli.py

@@ -0,0 +1,394 @@
+# Copyright (c) 2026-present Stable State Consulting Ltd
+# SPDX-License-Identifier: MIT
+
+"""LAN Fence command-line interface (Typer)."""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import sys
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from lanfence import __version__, alerts, scanner
+from lanfence.allowlist import Allowlist
+from lanfence.config import Config
+from lanfence.db import DeviceStore
+from lanfence.engine import build_findings, process_sighting, run_active_sweep
+from lanfence.fingerprint import SignatureSet, fingerprint_device
+from lanfence.logging_config import setup_logging
+from lanfence.models import Finding
+from lanfence.report import (
+    exit_code_for,
+    exit_code_for_findings,
+    render_events,
+    render_findings,
+    render_scan_result,
+)
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help=(
+        "LAN Fence - defensive LAN device monitor.\n\n"
+        "Scans for connected devices via ARP, tracks them against an allowlist "
+        "of devices you trust, and alerts when something unknown joins your "
+        "network. Observation only; LAN Fence never modifies the network."
+    ),
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"lanfence {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    pass
+
+
+def _load_config(config_path: Optional[Path]) -> Config:
+    try:
+        return Config.load(config_path)
+    except Exception as exc:  # noqa: BLE001
+        typer.secho(f"error: could not load config: {exc}", fg="red", err=True)
+        raise typer.Exit(code=2) from exc
+
+
+def _is_root() -> bool:
+    return hasattr(os, "geteuid") and os.geteuid() == 0
+
+
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}
+
+
+def _parse_since(value: str) -> datetime:
+    """Parse a duration like ``24h``, ``30m``, ``7d`` into a UTC cutoff datetime."""
+
+    value = value.strip().lower()
+    if value and value[-1] in _UNIT_SECONDS and value[:-1].replace(".", "", 1).isdigit():
+        amount = float(value[:-1])
+        seconds = amount * _UNIT_SECONDS[value[-1]]
+        return datetime.now(timezone.utc) - timedelta(seconds=seconds)
+    typer.secho(
+        f"error: could not parse --since {value!r} (expected e.g. 24h, 30m, 7d)",
+        fg="red", err=True,
+    )
+    raise typer.Exit(code=2)
+
+
+@app.command()
+def scan(
+    interface: Optional[str] = typer.Option(None, "--interface", "-i", help="Network interface to scan."),
+    subnet: Optional[str] = typer.Option(None, "--subnet", "-s", help="CIDR subnet to scan (default: auto-detect)."),
+    output_format: str = typer.Option("table", "--format", "-f", help="table | json"),
+    config: Optional[Path] = typer.Option(None, "--config", "-c", help="YAML config file."),
+    alert: bool = typer.Option(False, "--alert", help="Dispatch alerts for findings via configured channels."),
+    fail_on_findings: bool = typer.Option(
+        False, "--fail-on-findings", help="Exit non-zero when medium+ findings are present."
+    ),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+) -> None:
+    """One-time active ARP scan; shows connected devices and any findings."""
+
+    setup_logging(verbose)
+    cfg = _load_config(config)
+
+    if not _is_root():
+        typer.secho(
+            "warning: not running as root - active ARP scanning needs raw-socket "
+            "access. Re-run with sudo if this returns no devices.",
+            fg="yellow", err=True,
+        )
+
+    signatures = SignatureSet.load(cfg.rogue_signatures_file)
+    allowlist = Allowlist.load(cfg.resolved_allowlist_file())
+
+    with DeviceStore(cfg.resolved_db_path()) as store:
+        result = run_active_sweep(cfg, store, allowlist, signatures, interface=interface, subnet=subnet)
+
+    if alert:
+        alerts.dispatch(result.findings, cfg.alerts)
+
+    if output_format == "json":
+        typer.echo(result.to_json())
+    else:
+        render_scan_result(result)
+
+    if fail_on_findings:
+        raise typer.Exit(code=exit_code_for(result))
+
+
+def _emit_findings(findings: list[Finding], *, alert: bool, cfg: Config) -> None:
+    colour = {"high": "red", "medium": "yellow", "info": "cyan"}
+    for finding in findings:
+        typer.secho(
+            f"[{finding.severity.upper()}] {finding.title} (mac={finding.mac})",
+            fg=colour.get(finding.severity, "white"), bold=(finding.severity == "high"),
+        )
+        if finding.rationale:
+            typer.echo(f"    {finding.rationale}")
+        if finding.recommendation:
+            typer.secho(f"    Recommendation: {finding.recommendation}", fg="cyan")
+    if alert and findings:
+        alerts.dispatch(findings, cfg.alerts)
+
+
+@app.command()
+def monitor(
+    interface: Optional[str] = typer.Option(None, "--interface", "-i", help="Network interface to monitor."),
+    subnet: Optional[str] = typer.Option(None, "--subnet", "-s", help="CIDR subnet to actively sweep."),
+    interval: Optional[float] = typer.Option(None, "--interval", help="Active-sweep interval override (seconds)."),
+    passive: Optional[bool] = typer.Option(
+        None, "--passive/--no-passive", help="Also passively sniff ARP traffic between sweeps."
+    ),
+    config: Optional[Path] = typer.Option(None, "--config", "-c", help="YAML config file."),
+    alert: bool = typer.Option(True, "--alert/--no-alert", help="Dispatch alerts for findings as they occur."),
+    verbose: int = typer.Option(0, "--verbose", "-v", count=True),
+) -> None:
+    """Continuously watch for new/changed devices until interrupted (Ctrl+C)."""
+
+    setup_logging(verbose)
+    cfg = _load_config(config)
+    if interval is not None:
+        cfg.scan.scan_interval_seconds = interval
+    if passive is not None:
+        cfg.scan.passive = passive
+
+    if not _is_root():
+        typer.secho(
+            "warning: not running as root - ARP scanning/sniffing needs raw-socket "
+            "access. Re-run with sudo for full monitoring.",
+            fg="yellow", err=True,
+        )
+
+    signatures = SignatureSet.load(cfg.rogue_signatures_file)
+    allowlist = Allowlist.load(cfg.resolved_allowlist_file())
+    store = DeviceStore(cfg.resolved_db_path())
+
+    iface = interface or cfg.scan.interface or scanner.default_interface()
+    net = subnet or cfg.scan.subnet
+
+    typer.secho(f"LAN Fence {__version__} - monitoring (Ctrl+C to stop)", fg="green", bold=True)
+    typer.echo(
+        f"interface: {iface or '(auto)'}   scan interval: {cfg.scan.scan_interval_seconds:.0f}s   "
+        f"passive: {cfg.scan.passive}"
+    )
+
+    stop_event = threading.Event()
+    passive_queue: "queue.Queue[scanner.ArpSighting]" = queue.Queue()
+
+    def _run_passive() -> None:
+        try:
+            scanner.passive_sniff(on_sighting=passive_queue.put, interface=iface, stop_event=stop_event)
+        except scanner.ScannerUnavailable as exc:
+            typer.secho(f"passive monitoring unavailable: {exc}", fg="yellow", err=True)
+
+    passive_thread: threading.Thread | None = None
+    if cfg.scan.passive:
+        passive_thread = threading.Thread(target=_run_passive, daemon=True)
+        passive_thread.start()
+
+    try:
+        last_sweep = 0.0
+        while True:
+            now = time.monotonic()
+            if now - last_sweep >= cfg.scan.scan_interval_seconds:
+                result = run_active_sweep(cfg, store, allowlist, signatures, interface=iface, subnet=net)
+                last_sweep = now
+                for err in result.errors:
+                    typer.secho(f"error: {err}", fg="red", err=True)
+                _emit_findings(result.findings, alert=alert, cfg=cfg)
+
+            drained = 0
+            while drained < 200:
+                try:
+                    sighting = passive_queue.get_nowait()
+                except queue.Empty:
+                    break
+                drained += 1
+                _, _event_type, findings = process_sighting(
+                    mac=sighting.mac, ip=sighting.ip, seen_at=sighting.seen_at,
+                    store=store, allowlist=allowlist, signatures=signatures, cfg=cfg,
+                )
+                _emit_findings(findings, alert=alert, cfg=cfg)
+
+            time.sleep(1.0)
+    except KeyboardInterrupt:
+        typer.echo("\nstopping monitor...")
+    finally:
+        stop_event.set()
+        store.close()
+
+
+@app.command()
+def report(
+    since: str = typer.Option("24h", "--since", help="How far back to report, e.g. 30m, 24h, 7d."),
+    output_format: str = typer.Option("table", "--format", "-f", help="table | json"),
+    config: Optional[Path] = typer.Option(None, "--config", "-c", help="YAML config file."),
+    fail_on_findings: bool = typer.Option(
+        False, "--fail-on-findings", help="Exit non-zero when medium+ findings are present in the window."
+    ),
+) -> None:
+    """Summarize device activity (connects/disconnects/reappearances) since a point in time."""
+
+    cfg = _load_config(config)
+    since_dt = _parse_since(since)
+    signatures = SignatureSet.load(cfg.rogue_signatures_file)
+    allowlist = Allowlist.load(cfg.resolved_allowlist_file())
+
+    with DeviceStore(cfg.resolved_db_path()) as store:
+        events = store.events_since(since_dt)
+        devices_by_mac = {d.mac: d for d in store.all_devices()}
+
+    findings: list[Finding] = []
+    for event in events:
+        if event.event_type == "disconnected":
+            continue
+        device = devices_by_mac.get(event.mac)
+        if device is None:
+            continue
+        allow_entry = allowlist.match(event.mac)
+        device = device.model_copy(
+            update={
+                "allowlisted": allow_entry is not None,
+                "allowlist_name": allow_entry.name if allow_entry else None,
+            }
+        )
+        _, matches = fingerprint_device(
+            event.mac, device.hostname, signatures=signatures, vendor_file=cfg.vendor_file
+        )
+        findings.extend(build_findings(device, event.event_type, matches))
+
+    if output_format == "json":
+        payload = {
+            "since": since_dt.isoformat(),
+            "events": [e.model_dump(mode="json") for e in events],
+            "findings": [f.model_dump(mode="json") for f in findings],
+        }
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        typer.secho(f"LAN Fence report - since {since_dt.isoformat()}", fg="cyan", bold=True)
+        render_events(events)
+        typer.echo("")
+        render_findings(findings)
+
+    if fail_on_findings:
+        raise typer.Exit(code=exit_code_for_findings(findings))
+
+
+@app.command()
+def allow(
+    mac: Optional[str] = typer.Argument(None, help="MAC address to trust."),
+    name: Optional[str] = typer.Option(None, "--name", help="Label for this device."),
+    notes: Optional[str] = typer.Option(None, "--notes", help="Freeform notes."),
+    list_entries: bool = typer.Option(False, "--list", help="Show current allowlist entries."),
+    remove: Optional[str] = typer.Option(None, "--remove", help="MAC address to remove from the allowlist."),
+    config: Optional[Path] = typer.Option(None, "--config", "-c", help="YAML config file."),
+) -> None:
+    """Manage the allowlist of devices you trust.
+
+    Findings about an allowlisted device are downgraded to *info*, so your own
+    hardware stops shouting every time it reconnects. With no MAC and no
+    options, lists the current entries.
+    """
+
+    cfg = _load_config(config)
+    path = cfg.resolved_allowlist_file()
+    al = Allowlist.load(path)
+    al.path = path
+
+    if remove is not None:
+        entry = al.remove(remove)
+        if entry is None:
+            typer.secho(f"error: {remove} is not on the allowlist", fg="red", err=True)
+            raise typer.Exit(code=2)
+        al.save()
+        typer.secho(f"removed: {entry.name} ({entry.mac})", fg="green")
+        return
+
+    if list_entries or mac is None:
+        if not al.entries:
+            typer.echo(f"allowlist is empty ({path})")
+            return
+        typer.secho(f"Allowlist ({path}):\n", fg="cyan", bold=True)
+        for i, e in enumerate(al.entries, start=1):
+            tail = f"  {e.notes}" if e.notes else ""
+            typer.echo(f"  {i:>3}. {e.name:<28}  {e.mac}{tail}")
+        return
+
+    entry = al.add(mac, name or mac, notes or "")
+    al.save()
+    typer.secho(f"added: {entry.name}  ({entry.mac})", fg="green")
+
+
+@app.command()
+def check(
+    config: Optional[Path] = typer.Option(None, "--config", "-c", help="YAML config file."),
+) -> None:
+    """Check that this host can run LAN Fence (permissions, scapy, interface)."""
+
+    cfg = _load_config(config)
+
+    typer.secho("Host", fg="cyan", bold=True)
+    typer.echo(f"  root:        {_is_root()}")
+    typer.echo(f"  platform:    {sys.platform}")
+
+    typer.secho("\nScanning", fg="cyan", bold=True)
+    try:
+        import scapy  # noqa: F401
+
+        typer.secho("  ok       scapy is installed", fg="green")
+    except ImportError:
+        typer.secho(
+            "  MISSING  scapy is not installed (pip install 'lanfence[scan]')", fg="yellow"
+        )
+
+    iface = cfg.scan.interface or scanner.default_interface()
+    typer.echo(f"  interface:   {iface or '(could not auto-detect)'}")
+    net = cfg.scan.subnet or scanner.local_subnet(iface)
+    typer.echo(f"  subnet:      {net or '(could not auto-detect)'}")
+
+    typer.secho("\nStorage", fg="cyan", bold=True)
+    db_path = cfg.resolved_db_path()
+    try:
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        DeviceStore(db_path).close()
+        typer.secho(f"  ok       database writable: {db_path}", fg="green")
+        db_ok = True
+    except OSError as exc:
+        typer.secho(f"  FAIL     database not writable: {db_path} ({exc})", fg="red")
+        db_ok = False
+
+    allowlist_file = cfg.resolved_allowlist_file()
+    typer.echo(f"  allowlist:   {allowlist_file} ({'exists' if allowlist_file.is_file() else 'not created yet'})")
+
+    if not _is_root():
+        typer.secho(
+            "\nnot running as root: active/passive ARP scanning will likely fail. "
+            "Re-run with sudo for a full check.",
+            fg="yellow",
+        )
+
+    raise typer.Exit(code=0 if db_ok else 1)
+
+
+def main() -> None:  # pragma: no cover - entry point shim
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(app())