feat(net-scan): align gateway scans with local planning

Adds selected network scan sources, explicit target/range planning, interface-aware scan execution, the v1 result format, and gateway API/OpenAPI support while preserving the legacy event format.

ARP/NDP discovery and MAC enrichment are intentionally excluded from this review slice and remain available on backup-feat-network-scan-improvement-with-arp-ndp.

Author: irvingoujAtDevolution

Cargo.lock

@@ -17,6 +17,9 @@ socket2 = { version = "0.5", features = ["all"] }
 thiserror = "2"
 tracing = "0.1"
 
+[target.'cfg(any(target_os = "linux", target_os = "macos"))'.dependencies]
+libc = "0.2"
+
 [dev-dependencies]
 tracing-cov-mark = { path = "../tracing-cov-mark" }
 tracing-subscriber = "0.3"

crates/network-scanner-net/Cargo.toml

@@ -52,6 +52,24 @@ impl AsyncRawSocket {
         self.socket.bind(addr)
     }
 
+    /// Bind this socket to a specific network interface by OS index.
+    ///
+    /// Per-platform mechanism:
+    ///
+    /// | Platform | Option used                              | Notes                       |
+    /// |----------|------------------------------------------|-----------------------------|
+    /// | Linux    | `IP_UNICAST_IF` / `IPV6_UNICAST_IF`      | No `CAP_NET_RAW` required.  |
+    /// | macOS    | `IP_BOUND_IF` / `IPV6_BOUND_IF`          | Apple-specific socket opts. |
+    /// | Windows  | `IP_UNICAST_IF` / `IPV6_UNICAST_IF`      | Via `ws2_32!setsockopt`.    |
+    ///
+    /// Other platforms return [`std::io::ErrorKind::Unsupported`]. Taking a
+    /// [`std::num::NonZeroU32`] makes it impossible to pass the
+    /// "unbind / use default routing" sentinel by accident — drop the call
+    /// site instead of binding to ifindex 0.
+    pub fn bind_to_interface(&self, family: socket2::Domain, if_index: std::num::NonZeroU32) -> std::io::Result<()> {
+        bind_socket_to_interface(&self.socket, family, if_index)
+    }
+
     pub async fn set_ttl(&self, ttl: u32) -> std::io::Result<()> {
         self.socket.set_ttl(ttl)
     }
@@ -65,6 +83,132 @@ impl AsyncRawSocket {
     }
 }
 
+/// Bind a `socket2::Socket` to a specific interface index.
+///
+/// Per-platform mechanism (`IP_UNICAST_IF` on Linux + Windows,
+/// `IP_BOUND_IF` on macOS — see [`AsyncRawSocket::bind_to_interface`] for
+/// the full table). Returns [`std::io::ErrorKind::Unsupported`] elsewhere.
+fn bind_socket_to_interface(
+    socket: &Socket,
+    family: socket2::Domain,
+    if_index: std::num::NonZeroU32,
+) -> std::io::Result<()> {
+    let if_index = if_index.get();
+
+    #[cfg(any(target_os = "linux", target_os = "macos"))]
+    {
+        use std::os::fd::AsRawFd;
+
+        // Resolve (level, name, value) per platform / family. Linux and
+        // macOS share the libc::setsockopt call shape, only the constants
+        // and IPv4 byte-order differ.
+        let (level, name, value): (libc::c_int, libc::c_int, u32) = match (family, cfg!(target_os = "linux")) {
+            // Linux
+            #[cfg(target_os = "linux")]
+            (socket2::Domain::IPV4, _) => {
+                // IPPROTO_IP, IP_UNICAST_IF; the kernel expects net-order.
+                (0, 50, if_index.to_be())
+            }
+            #[cfg(target_os = "linux")]
+            (socket2::Domain::IPV6, _) => {
+                // IPPROTO_IPV6, IPV6_UNICAST_IF; host byte order.
+                (41, 76, if_index)
+            }
+            // macOS
+            #[cfg(target_os = "macos")]
+            (socket2::Domain::IPV4, _) => {
+                // IPPROTO_IP, IP_BOUND_IF
+                (0, 25, if_index)
+            }
+            #[cfg(target_os = "macos")]
+            (socket2::Domain::IPV6, _) => {
+                // IPPROTO_IPV6, IPV6_BOUND_IF
+                (41, 125, if_index)
+            }
+            _ => {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::InvalidInput,
+                    "interface bind only supported for IPv4 / IPv6 sockets",
+                ));
+            }
+        };
+
+        let fd = socket.as_raw_fd();
+        // SAFETY: `fd` is a valid descriptor borrowed from `socket`;
+        // `&value` is a stack pointer valid for the duration of the call.
+        let ret = unsafe {
+            libc::setsockopt(
+                fd,
+                level,
+                name,
+                &value as *const u32 as *const libc::c_void,
+                size_of::<u32>() as libc::socklen_t,
+            )
+        };
+        if ret == 0 {
+            Ok(())
+        } else {
+            Err(std::io::Error::last_os_error())
+        }
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        // Windows IP_UNICAST_IF (option 31) takes a u32: net-order for IPv4,
+        // host-order for IPv6.
+        use std::os::windows::io::AsRawSocket;
+        const IPPROTO_IP: i32 = 0;
+        const IPPROTO_IPV6: i32 = 41;
+        const IP_UNICAST_IF: i32 = 31;
+        const IPV6_UNICAST_IF: i32 = 31;
+        // `SOCKET` is u64 in the Windows headers; on 32-bit Windows it
+        // still fits in `usize` since SOCKET handles never exceed pointer
+        // width.
+        let raw: usize = usize::try_from(socket.as_raw_socket())
+            .map_err(|_| std::io::Error::other("Windows socket handle does not fit in usize on this target"))?;
+        let (level, name, value): (i32, i32, u32) = if family == socket2::Domain::IPV4 {
+            (IPPROTO_IP, IP_UNICAST_IF, if_index.to_be())
+        } else if family == socket2::Domain::IPV6 {
+            (IPPROTO_IPV6, IPV6_UNICAST_IF, if_index)
+        } else {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                "interface bind only supported for IPv4 / IPv6 sockets",
+            ));
+        };
+        // setsockopt takes optlen as i32; size_of::<u32>() is 4 — the cast
+        // is infallible, but try_from documents intent and avoids a lint.
+        let optlen = i32::try_from(size_of::<u32>()).expect("size of u32 fits in i32");
+        // SAFETY: setsockopt is invoked on a valid Windows socket handle
+        // that outlives this call; `&value` lives on the stack across it.
+        let ret = unsafe { windows_setsockopt(raw, level, name, &value as *const u32 as *const u8, optlen) };
+        if ret == 0 {
+            Ok(())
+        } else {
+            Err(std::io::Error::last_os_error())
+        }
+    }
+
+    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+    {
+        let _ = (socket, family, if_index);
+        Err(std::io::Error::new(
+            std::io::ErrorKind::Unsupported,
+            "interface bind not supported on this platform",
+        ))
+    }
+}
+
+#[cfg(target_os = "windows")]
+unsafe extern "system" {
+    /// `setsockopt` from `ws2_32.dll`. We deliberately bind the symbol here
+    /// instead of pulling in the full `windows-sys` crate so the only
+    /// network-scanner-net Windows dependency stays within libstd's
+    /// already-linked import library.
+    #[link_name = "setsockopt"]
+    fn windows_setsockopt(s: usize, level: i32, optname: i32, optval: *const u8, optlen: i32) -> i32;
+}
+
 impl<'a> AsyncRawSocket {
     #[tracing::instrument(skip(self, buf))]
     pub fn recv_from(

crates/network-scanner-net/src/socket.rs

@@ -1,3 +1,15 @@
+//! Wire-format helpers for the protocols the network scanner speaks.
+//!
+//! - [`icmp_v4`] / [`icmp_v6`] — ICMP echo and friends used by ping.
+//! - [`netbios`] — NetBIOS-over-UDP name service queries.
+//!
+//! All modules are pure byte-level: they neither own sockets nor perform
+//! I/O. The companion `network-scanner` crate composes them with raw
+//! sockets to send and receive packets.
+
 pub mod icmp_v4;
 pub mod icmp_v6;
 pub mod netbios;
+
+#[cfg(test)]
+mod tests;