Add SSDP/UPnP scanner

Introduce a new SSDP/UPnP network scanner alongside the existing ARP and
mDNS scanners:

- New scanner module under scanners/ssdp (finder, scanner, status)
- Wire the scanner into the main scan loop
- Add Ssdp variant to DeviceEventScanner
- Add SsdpScanner settings with a configurable probe timeout
- Expose /api/ssdp_scanner/status and wire it into OpenAPI generation
- Add a lint.sh helper and point CLAUDE.md at it

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -23,7 +23,7 @@ For Flutter/Dart code:
 - `cd backend && ./run.sh` from the `backend/` folder - Run the backend
 - `cd frontend && ./run.sh` from the `frontend/` folder - Run the front-end for the web
 - `cd backend && ./run_tests.sh` - Run the backend tests
-- `cargo clippy` - Run the clippy linter for Rust code
+- `cd backend && ./lint.sh` - Run the clippy linter for Rust code
 - `dart analyze` - Run the Dart linter
 - `cd backend/data && ./update_mac_vendors --llm` - Update the MAC vendors list from the web and re-calculate the vedors -> device type list
 

TODO.md

@@ -7,7 +7,9 @@
 - [x] Add the scanner that triggered the event to the device_events table
 - [x] Improve notifications layout/text
 - [ ] Implement the pushover API call directly to support HTML content and review notification text to use it
-- [ ] Add uPNP scanner
+- [x] Add SSDP/uPNP scanner
+  - [ ] Make sure the new config options are in the TOML files and Nix module
+  - [ ] Document in README.md the port needs/bindings
 - [ ] Add DHCP scanner
 
 ## Frontend

backend/lint.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+sudo CARGO_HOME=$HOME/.cargo cargo clippy

backend/src/main.rs

@@ -59,11 +59,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Initialize scanner status tracking
     scanners::arp::status::init();
     scanners::mdns::status::init();
+    scanners::ssdp::status::init();
 
     // Start the device scanners, web server, and retention cleaner in parallel
     tokio::join!(
         scanners::arp::scanner::scan(),
         scanners::mdns::scanner::listen(),
+        scanners::ssdp::scanner::listen(),
         web_server::serve(),
         retention::run()
     )

backend/src/model/device_events.rs

@@ -118,6 +118,7 @@ impl FromSql for DeviceEventType {
 pub enum DeviceEventScanner {
     Arp,
     Mdns,
+    Ssdp,
 }
 
 impl fmt::Display for DeviceEventScanner {
@@ -125,6 +126,7 @@ impl fmt::Display for DeviceEventScanner {
         match self {
             Self::Arp => write!(f, "ARP"),
             Self::Mdns => write!(f, "mDNS"),
+            Self::Ssdp => write!(f, "SSDP"),
         }
     }
 }
@@ -147,6 +149,7 @@ impl FromStr for DeviceEventScanner {
         match s {
             "ARP" => Ok(DeviceEventScanner::Arp),
             "mDNS" => Ok(DeviceEventScanner::Mdns),
+            "SSDP" => Ok(DeviceEventScanner::Ssdp),
             _ => Err(DeviceEventScannerParseError),
         }
     }

backend/src/scanners.rs

@@ -1,3 +1,4 @@
 pub mod arp;
 pub mod error;
 pub mod mdns;
+pub mod ssdp;

backend/src/scanners/ssdp.rs

@@ -0,0 +1,3 @@
+pub mod finder;
+pub mod scanner;
+pub mod status;

backend/src/scanners/ssdp/finder.rs

@@ -0,0 +1,209 @@
+use std::net::{Ipv4Addr, SocketAddrV4};
+
+use log::{debug, info};
+use pnet::datalink;
+use pnet::ipnetwork::IpNetwork;
+use socket2::{Domain, Protocol, Socket, Type};
+use tokio::net::UdpSocket;
+
+use crate::utils::network::select_interface;
+
+const SSDP_GROUP: Ipv4Addr = Ipv4Addr::new(239, 255, 255, 250);
+const SSDP_PORT: u16 = 1900;
+
+/// Open a UDP socket that passively listens for SSDP/UPnP multicast announcements on the given
+/// interface. The socket is bound with address/port reuse so it coexists with other SSDP
+/// responders (e.g. minidlna, gssdp-scan) already using port 1900.
+pub fn open_socket(interface: Option<String>) -> Result<UdpSocket, Box<dyn std::error::Error>> {
+    let all_interfaces = datalink::interfaces();
+    let iface = select_interface(&all_interfaces, &interface)
+        .ok_or("No suitable interface found for the SSDP listener")?;
+    let iface_ip = iface
+        .ips
+        .iter()
+        .find_map(|el| match el {
+            IpNetwork::V4(v4) => Some(v4.ip()),
+            _ => None,
+        })
+        .ok_or("Selected interface has no IPv4 address")?;
+
+    let socket = Socket::new(Domain::IPV4, Type::DGRAM, Some(Protocol::UDP))?;
+    socket.set_reuse_address(true)?;
+    #[cfg(unix)]
+    socket.set_reuse_port(true)?;
+    socket.bind(&SocketAddrV4::new(Ipv4Addr::UNSPECIFIED, SSDP_PORT).into())?;
+    socket.join_multicast_v4(&SSDP_GROUP, &iface_ip)?;
+    socket.set_nonblocking(true)?;
+
+    let udp = UdpSocket::from_std(socket.into())?;
+    info!(
+        "SSDP listener bound to port {SSDP_PORT} on interface {} ({iface_ip})",
+        iface.name
+    );
+    Ok(udp)
+}
+
+/// The contents of an SSDP NOTIFY announcement relevant to device discovery.
+pub struct Announcement {
+    /// SERVER header value (e.g. `Linux/3.14 UPnP/1.1 MiniDLNA/1.3.0`). Used as a name hint.
+    pub server: Option<String>,
+    /// NT header values describing the device/service type
+    /// (e.g. `urn:schemas-upnp-org:device:MediaServer:1`).
+    pub device_types: Vec<String>,
+}
+
+/// Parse a raw SSDP packet into an `Announcement`. Returns `None` for anything that is not a
+/// live device announcement (byebye, M-SEARCH requests, HTTP responses, unparseable garbage).
+///
+/// SSDP messages are text-based HTTP/1.x style. We accept both `ssdp:alive` and `ssdp:update`
+/// (UPnP 1.1 bootID change) as "device is alive" signals.
+pub fn parse_announcement(buf: &[u8]) -> Option<Announcement> {
+    let text = match std::str::from_utf8(buf) {
+        Ok(t) => t,
+        Err(err) => {
+            debug!("Ignoring non-UTF8 SSDP packet: {err}");
+            return None;
+        }
+    };
+
+    // Tolerate bare-LF line endings (some embedded devices) by splitting on `\n` and stripping
+    // any trailing `\r`.
+    let mut lines = text.split('\n').map(|l| l.strip_suffix('\r').unwrap_or(l));
+
+    let first_line = lines.next().unwrap_or("");
+    if !first_line.to_ascii_uppercase().starts_with("NOTIFY ") {
+        return None;
+    }
+
+    let mut server: Option<String> = None;
+    let mut device_types: Vec<String> = Vec::new();
+    let mut nts: Option<String> = None;
+
+    for line in lines {
+        if line.is_empty() {
+            continue;
+        }
+        let mut parts = line.splitn(2, ':');
+        let key = match parts.next() {
+            Some(k) => k.trim().to_ascii_lowercase(),
+            None => continue,
+        };
+        let value = match parts.next() {
+            Some(v) => v.trim().to_string(),
+            None => continue,
+        };
+        if value.is_empty() {
+            continue;
+        }
+        match key.as_str() {
+            "nts" => nts = Some(value.to_ascii_lowercase()),
+            "nt" => device_types.push(value),
+            "server" => server = Some(value),
+            _ => {}
+        }
+    }
+
+    match nts.as_deref() {
+        Some("ssdp:alive") | Some("ssdp:update") => Some(Announcement {
+            server,
+            device_types,
+        }),
+        _ => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn alive_packet() -> Vec<u8> {
+        let body = "NOTIFY * HTTP/1.1\r\n\
+                    HOST: 239.255.255.250:1900\r\n\
+                    CACHE-CONTROL: max-age=1800\r\n\
+                    LOCATION: http://192.168.1.100:49152/rootDesc.xml\r\n\
+                    NT: urn:schemas-upnp-org:device:MediaServer:1\r\n\
+                    NTS: ssdp:alive\r\n\
+                    SERVER: Linux/3.14 UPnP/1.1 MiniDLNA/1.3.0\r\n\
+                    USN: uuid:abcd::urn:schemas-upnp-org:device:MediaServer:1\r\n\r\n";
+        body.as_bytes().to_vec()
+    }
+
+    #[test]
+    fn test_parse_alive_extracts_server_and_nt() {
+        let announcement = parse_announcement(&alive_packet()).expect("alive packet");
+        assert_eq!(
+            announcement.server.as_deref(),
+            Some("Linux/3.14 UPnP/1.1 MiniDLNA/1.3.0")
+        );
+        assert_eq!(
+            announcement.device_types,
+            vec!["urn:schemas-upnp-org:device:MediaServer:1".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_parse_alive_preserves_location_with_embedded_colons() {
+        // Just ensure LOCATION with `:` in the value does not corrupt subsequent header parsing.
+        let announcement = parse_announcement(&alive_packet()).expect("alive packet");
+        assert!(announcement.server.is_some());
+        assert!(!announcement.device_types.is_empty());
+    }
+
+    #[test]
+    fn test_parse_update_accepted() {
+        let body = "NOTIFY * HTTP/1.1\r\n\
+                    HOST: 239.255.255.250:1900\r\n\
+                    NT: upnp:rootdevice\r\n\
+                    NTS: ssdp:update\r\n\
+                    SERVER: Foo/1.0\r\n\
+                    USN: uuid:abcd::upnp:rootdevice\r\n\r\n";
+        let announcement = parse_announcement(body.as_bytes()).expect("update packet");
+        assert_eq!(announcement.server.as_deref(), Some("Foo/1.0"));
+    }
+
+    #[test]
+    fn test_parse_byebye_returns_none() {
+        let body = "NOTIFY * HTTP/1.1\r\n\
+                    HOST: 239.255.255.250:1900\r\n\
+                    NT: upnp:rootdevice\r\n\
+                    NTS: ssdp:byebye\r\n\
+                    USN: uuid:abcd::upnp:rootdevice\r\n\r\n";
+        assert!(parse_announcement(body.as_bytes()).is_none());
+    }
+
+    #[test]
+    fn test_parse_http_response_returns_none() {
+        let body = "HTTP/1.1 200 OK\r\n\
+                    CACHE-CONTROL: max-age=1800\r\n\
+                    SERVER: Foo/1.0\r\n\r\n";
+        assert!(parse_announcement(body.as_bytes()).is_none());
+    }
+
+    #[test]
+    fn test_parse_garbage_returns_none() {
+        assert!(parse_announcement(&[0xff, 0x00, 0x13]).is_none());
+    }
+
+    #[test]
+    fn test_parse_missing_server_header() {
+        let body = "NOTIFY * HTTP/1.1\r\n\
+                    HOST: 239.255.255.250:1900\r\n\
+                    NT: upnp:rootdevice\r\n\
+                    NTS: ssdp:alive\r\n\
+                    USN: uuid:abcd::upnp:rootdevice\r\n\r\n";
+        let announcement = parse_announcement(body.as_bytes()).expect("alive packet");
+        assert!(announcement.server.is_none());
+        assert_eq!(announcement.device_types, vec!["upnp:rootdevice".to_string()]);
+    }
+
+    #[test]
+    fn test_parse_bare_lf_line_endings() {
+        let body = "NOTIFY * HTTP/1.1\n\
+                    HOST: 239.255.255.250:1900\n\
+                    NT: upnp:rootdevice\n\
+                    NTS: ssdp:alive\n\
+                    SERVER: Bar/2.0\n\n";
+        let announcement = parse_announcement(body.as_bytes()).expect("alive packet");
+        assert_eq!(announcement.server.as_deref(), Some("Bar/2.0"));
+    }
+}

backend/src/scanners/ssdp/scanner.rs

@@ -0,0 +1,122 @@
+use std::net::{IpAddr, Ipv4Addr};
+use std::time::Duration;
+
+use chrono::Local;
+use log::{debug, error, info, warn};
+
+use super::finder;
+use super::status;
+use crate::data::mac_vendor_finder;
+use crate::data::vendor_device_type_finder;
+use crate::db;
+use crate::events;
+use crate::model::device_events::DeviceEventScanner;
+use crate::model::devices::Device;
+use crate::settings::get_settings;
+
+/// Passively listen for SSDP/UPnP NOTIFY announcements and feed discovered devices into the same
+/// pipeline used by the ARP and mDNS scanners (devices table + events + notifications).
+pub async fn listen() -> Result<(), Box<dyn std::error::Error>> {
+    let interface = get_settings().networking.interface.clone();
+    let socket = finder::open_socket(interface.clone())?;
+    status::set_listening();
+    info!("SSDP scanner listening for announcements");
+
+    let probe_timeout = Duration::from(get_settings().ssdp_scanner.probe_timeout);
+
+    let mut buf = [0u8; 4096];
+    loop {
+        let (len, src) = match socket.recv_from(&mut buf).await {
+            Ok(value) => value,
+            Err(err) => {
+                warn!("SSDP socket receive error: {err}");
+                continue;
+            }
+        };
+
+        let src_ip = match src.ip() {
+            IpAddr::V4(ip) => ip,
+            IpAddr::V6(_) => continue, // the device model is IPv4-only
+        };
+
+        let announcement = match finder::parse_announcement(&buf[..len]) {
+            Some(a) => a,
+            None => continue, // byebye, M-SEARCH, HTTP response, garbage
+        };
+
+        process_announcement(
+            src_ip,
+            announcement.server,
+            announcement.device_types,
+            interface.clone(),
+            probe_timeout,
+        )
+        .await;
+    }
+}
+
+async fn process_announcement(
+    src_ip: Ipv4Addr,
+    server_hint: Option<String>,
+    device_types: Vec<String>,
+    interface: Option<String>,
+    probe_timeout: Duration,
+) {
+    let mac =
+        match crate::utils::network::resolve_mac_address(src_ip, interface, probe_timeout).await {
+            Some(mac) => mac.to_string(),
+            None => {
+                debug!("Could not resolve MAC for SSDP device {src_ip}; skipping");
+                return;
+            }
+        };
+
+    let mut vendor = mac_vendor_finder::find(mac.get(0..8).unwrap_or("").to_string());
+    // Privacy MACs are locally administered and have no real OUI, so the lookup above fails.
+    // Fall back to the vendor-specific service strings the device advertises (SSDP NT URNs
+    // typically won't match this lookup, but the call shape mirrors the mDNS scanner).
+    if vendor.is_empty() && crate::utils::network::is_locally_administered(&mac) {
+        vendor = crate::data::service_vendor_finder::find(&device_types);
+    }
+    let mut device = Device::new(
+        mac.clone(),
+        src_ip.to_string(),
+        vendor,
+        Local::now().to_utc(),
+    );
+    device.device_type = vendor_device_type_finder::find(&device.vendor);
+    device.name = server_hint;
+
+    match db::devices::read(mac.clone()) {
+        Some(recorded) => {
+            debug!("SSDP sighting of known device {mac}; updating");
+            // Keep the previously stored name (likely a proper hostname from mDNS) rather than
+            // overwriting it with the SERVER header string.
+            if recorded.name.is_some() {
+                device.name = recorded.name.clone();
+            }
+            if let Err(err) = db::devices::seen(
+                device.mac_address.clone(),
+                device.ipv4_address.clone(),
+                device.vendor.clone(),
+                device.device_type.clone(),
+                device.name.clone(),
+            ) {
+                error!("Failed to update SSDP device {mac}: {err}");
+                return;
+            }
+            // Ignoring errors: do not stop the listener if notification delivery fails
+            events::trigger_existing_device(recorded, device, DeviceEventScanner::Ssdp).ok();
+        }
+        None => {
+            debug!("New device {mac} discovered via SSDP; inserting");
+            if let Err(err) = db::devices::insert(device.clone()) {
+                error!("Failed to insert SSDP device {mac}: {err}");
+                return;
+            }
+            events::trigger_new_device(device, DeviceEventScanner::Ssdp).ok();
+        }
+    }
+
+    status::record_discovery();
+}

backend/src/scanners/ssdp/status.rs

@@ -0,0 +1,105 @@
+use chrono::{DateTime, Utc};
+use once_cell::sync::OnceCell;
+use std::sync::Mutex;
+
+pub struct SsdpScannerStatus {
+    pub is_listening: bool,
+    pub listening_since: Option<DateTime<Utc>>,
+    pub devices_discovered: u64,
+    pub last_discovery_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Clone)]
+pub struct SsdpScannerStatusSnapshot {
+    pub is_listening: bool,
+    pub listening_since: Option<DateTime<Utc>>,
+    pub devices_discovered: u64,
+    pub last_discovery_at: Option<DateTime<Utc>>,
+}
+
+static STATUS: OnceCell<Mutex<SsdpScannerStatus>> = OnceCell::new();
+
+pub fn init() {
+    STATUS
+        .set(Mutex::new(SsdpScannerStatus {
+            is_listening: false,
+            listening_since: None,
+            devices_discovered: 0,
+            last_discovery_at: None,
+        }))
+        .ok();
+}
+
+pub fn set_listening() {
+    if let Some(m) = STATUS.get() {
+        let mut s = m.lock().unwrap();
+        s.is_listening = true;
+        s.listening_since = Some(Utc::now());
+    }
+}
+
+pub fn record_discovery() {
+    if let Some(m) = STATUS.get() {
+        let mut s = m.lock().unwrap();
+        s.devices_discovered += 1;
+        s.last_discovery_at = Some(Utc::now());
+    }
+}
+
+pub fn get() -> Option<SsdpScannerStatusSnapshot> {
+    STATUS.get().map(|m| {
+        let s = m.lock().unwrap();
+        SsdpScannerStatusSnapshot {
+            is_listening: s.is_listening,
+            listening_since: s.listening_since,
+            devices_discovered: s.devices_discovered,
+            last_discovery_at: s.last_discovery_at,
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn reset_for_test() {
+        if let Some(m) = STATUS.get() {
+            let mut s = m.lock().unwrap();
+            s.is_listening = false;
+            s.listening_since = None;
+            s.devices_discovered = 0;
+            s.last_discovery_at = None;
+        } else {
+            init();
+        }
+    }
+
+    #[test]
+    fn test_set_listening() {
+        reset_for_test();
+        set_listening();
+        let snapshot = get().unwrap();
+        assert!(snapshot.is_listening);
+        assert!(snapshot.listening_since.is_some());
+    }
+
+    #[test]
+    fn test_record_discovery() {
+        reset_for_test();
+        record_discovery();
+        record_discovery();
+        let snapshot = get().unwrap();
+        assert_eq!(snapshot.devices_discovered, 2);
+        assert!(snapshot.last_discovery_at.is_some());
+    }
+
+    #[test]
+    fn test_initial_state() {
+        reset_for_test();
+        let snapshot = get().unwrap();
+        assert!(!snapshot.is_listening);
+        assert!(snapshot.listening_since.is_none());
+        assert_eq!(snapshot.devices_discovered, 0);
+        assert!(snapshot.last_discovery_at.is_none());
+    }
+}

backend/src/settings.rs

@@ -41,6 +41,19 @@ impl Default for MdnsScanner {
     }
 }
 
+#[derive(Debug, Deserialize, Clone)]
+pub struct SsdpScanner {
+    pub probe_timeout: DurationString,
+}
+
+impl Default for SsdpScanner {
+    fn default() -> Self {
+        SsdpScanner {
+            probe_timeout: DurationString::try_from("2s".to_string()).unwrap(),
+        }
+    }
+}
+
 #[derive(Debug, Deserialize, Clone)]
 pub struct Pushover {
     pub token: String,
@@ -86,6 +99,8 @@ pub struct Settings {
     pub retention: Retention,
     #[serde(default)]
     pub mdns_scanner: MdnsScanner,
+    #[serde(default)]
+    pub ssdp_scanner: SsdpScanner,
 }
 // End configuration structure
 // -----------------------------------------------------------

backend/src/web_server.rs

@@ -7,6 +7,7 @@ use crate::settings::get_settings;
 use crate::web_server::arp_scanner::ArpScannerStatusResponse;
 use crate::web_server::devices::{RegisterDevicePayload, UpdateDevicePayload};
 use crate::web_server::mdns_scanner::MdnsScannerStatusResponse;
+use crate::web_server::ssdp_scanner::SsdpScannerStatusResponse;
 use axum::Json;
 use axum::extract::Request;
 use axum::http::StatusCode;
@@ -28,6 +29,7 @@ pub mod device_events;
 pub mod devices;
 pub mod mdns_scanner;
 pub mod notifications;
+pub mod ssdp_scanner;
 pub mod utils;
 
 #[derive(OpenApi)]
@@ -53,6 +55,7 @@ pub mod utils;
         device_events::list,
         arp_scanner::status,
         mdns_scanner::status,
+        ssdp_scanner::status,
     ),
     components(schemas(
         Device,
@@ -66,6 +69,7 @@ pub mod utils;
         DeviceEventScanner,
         ArpScannerStatusResponse,
         MdnsScannerStatusResponse,
+        SsdpScannerStatusResponse,
     )),
     modifiers(&SecurityAddon),
     tags(
@@ -74,6 +78,7 @@ pub mod utils;
         (name = "device_events", description = "Device event history"),
         (name = "arp_scanner", description = "ARP scanner process status"),
         (name = "mdns_scanner", description = "mDNS/Bonjour scanner process status"),
+        (name = "ssdp_scanner", description = "SSDP/UPnP scanner process status"),
     )
 )]
 struct ApiDoc;
@@ -119,6 +124,7 @@ pub async fn serve() -> Result<(), Box<dyn Error>> {
         )
         .route("/api/arp_scanner/status", get(arp_scanner::status))
         .route("/api/mdns_scanner/status", get(mdns_scanner::status))
+        .route("/api/ssdp_scanner/status", get(ssdp_scanner::status))
         .route("/api/notifications", get(notifications::list))
         .route(
             "/api/notifications/mark_all_as_old",

backend/src/web_server/ssdp_scanner.rs

@@ -0,0 +1,57 @@
+use axum::{Json, http::StatusCode};
+use chrono::Utc;
+use log::error;
+use serde::Serialize;
+use utoipa::ToSchema;
+
+#[derive(Serialize, ToSchema)]
+pub struct SsdpScannerStatusResponse {
+    pub is_listening: bool,
+    /// Seconds the listener has been running (only set when is_listening is true)
+    pub listening_for_seconds: Option<f64>,
+    /// Total device announcements processed since the listener started
+    pub devices_seen: u64,
+    /// Seconds since the last device was seen (None if none seen yet)
+    pub last_device_seen_seconds_ago: Option<f64>,
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/ssdp_scanner/status",
+    tag = "ssdp_scanner",
+    responses(
+        (status = 200, description = "SSDP scanner status", body = SsdpScannerStatusResponse),
+        (status = 500, description = "Internal server error"),
+    ),
+    security(("bearer_auth" = []))
+)]
+pub async fn status() -> Result<Json<SsdpScannerStatusResponse>, StatusCode> {
+    let snapshot = match crate::scanners::ssdp::status::get() {
+        Some(s) => s,
+        None => {
+            error!("SSDP scanner status not initialized");
+            return Err(StatusCode::INTERNAL_SERVER_ERROR);
+        }
+    };
+
+    let now = Utc::now();
+
+    let listening_for_seconds = if snapshot.is_listening {
+        snapshot
+            .listening_since
+            .map(|t| (now - t).num_milliseconds() as f64 / 1000.0)
+    } else {
+        None
+    };
+
+    let last_device_seen_seconds_ago = snapshot
+        .last_discovery_at
+        .map(|t| ((now - t).num_milliseconds() as f64 / 1000.0).max(0.0));
+
+    Ok(Json(SsdpScannerStatusResponse {
+        is_listening: snapshot.is_listening,
+        listening_for_seconds,
+        devices_seen: snapshot.devices_discovered,
+        last_device_seen_seconds_ago,
+    }))
+}