feat: nmap host-timeout, device OS filter, first-launch empty state

backend/app/scanner/nmap_scan.py

@@ -56,6 +56,7 @@ def run_nmap_scan(
         return []
 
     iface = interface or os.environ.get("NETWORK_INTERFACE", "eth0")
+    host_timeout = os.environ.get("NMAP_HOST_TIMEOUT", "30s")
 
     with tempfile.NamedTemporaryFile(suffix=".xml", delete=False) as tmp:
         xml_path = tmp.name
@@ -67,6 +68,8 @@ def run_nmap_scan(
             # -O (OS detection) intentionally omitted: nmap hard-codes geteuid()==0
             # for OS fingerprinting regardless of file capabilities, so it always
             # quits when running as non-root uid 1000.  os_guess will be empty.
+            "--host-timeout",
+            host_timeout,
             "--top-ports",
             "1000",
             "-e",

backend/tests/test_scanner.py

@@ -454,3 +454,37 @@ def test_uses_env_vars_for_interface_and_subnet(self, monkeypatch):
             orchestrate_scan()
 
         mock_arp.assert_called_once_with(interface="bond0", subnet="172.16.0.0/12")
+
+    @pytest.mark.unit
+    def test_host_timeout_default_in_command(self):
+        """--host-timeout 30s must appear in the nmap command by default."""
+        fixture_xml = _fixture("nmap_two_hosts.xml")
+
+        def fake_run(cmd, **kwargs):
+            idx = cmd.index("-oX")
+            Path(cmd[idx + 1]).write_text(fixture_xml)
+            return MagicMock(returncode=0, stdout="", stderr="")
+
+        with patch("app.scanner.nmap_scan.subprocess.run", side_effect=fake_run) as mock_run:
+            run_nmap_scan(hosts=["192.168.1.1"], interface="eth0")
+
+        cmd = mock_run.call_args[0][0]
+        assert "--host-timeout" in cmd
+        assert cmd[cmd.index("--host-timeout") + 1] == "30s"
+
+    @pytest.mark.unit
+    def test_host_timeout_env_override(self, monkeypatch):
+        """NMAP_HOST_TIMEOUT env var must override the default 30s value."""
+        monkeypatch.setenv("NMAP_HOST_TIMEOUT", "60s")
+        fixture_xml = _fixture("nmap_two_hosts.xml")
+
+        def fake_run(cmd, **kwargs):
+            idx = cmd.index("-oX")
+            Path(cmd[idx + 1]).write_text(fixture_xml)
+            return MagicMock(returncode=0, stdout="", stderr="")
+
+        with patch("app.scanner.nmap_scan.subprocess.run", side_effect=fake_run) as mock_run:
+            run_nmap_scan(hosts=["192.168.1.1"], interface="eth0")
+
+        cmd = mock_run.call_args[0][0]
+        assert cmd[cmd.index("--host-timeout") + 1] == "60s"

frontend/src/pages/DashboardPage.tsx

@@ -159,6 +159,7 @@ export function DashboardPage() {
 
   const lastScan = scans[0] ?? null;
   const loading = devLoading || scanLoading || summaryLoading;
+  const noScansYet = !loading && scans.length === 0;
 
   const handleTrigger = async () => {
     const result = await trigger();
@@ -199,6 +200,27 @@ export function DashboardPage() {
 
       <PageHeader title="Dashboard" action={triggerButton} />
 
+      {noScansYet && (
+        <Card className="mb-6 flex flex-col items-center gap-4 py-10 text-center">
+          <div className="text-4xl">🛡️</div>
+          <h2 className="text-lg font-semibold text-[var(--color-text-primary)]">
+            Welcome to NetworkCrawler
+          </h2>
+          <p className="max-w-md text-sm text-[var(--color-text-secondary)]">
+            Discover every device on your LAN, identify misconfigurations, and
+            get actionable hardening advice — all locally, with no data leaving
+            your network.
+          </p>
+          <button
+            onClick={handleTrigger}
+            disabled={triggering}
+            className="mt-2 rounded-lg bg-[var(--color-accent-primary)] px-6 py-2 text-sm font-semibold text-white hover:opacity-90 disabled:opacity-50"
+          >
+            {triggering ? "Starting…" : "Run your first scan"}
+          </button>
+        </Card>
+      )}
+
       {loading ? (
         <div className="mb-6 grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
           {Array.from({ length: 4 }).map((_, i) => (

frontend/src/pages/DevicesPage.tsx

@@ -62,6 +62,7 @@ export function DevicesPage() {
   const { devices, loading, error } = useDevices();
   const { risks } = useRisks();
   const [filter, setFilter] = useState("");
+  const [osFilter, setOsFilter] = useState("");
   const [sortKey, setSortKey] = useState<SortKey>("ip_address");
   const [sortDir, setSortDir] = useState<SortDir>("asc");
 
@@ -73,16 +74,25 @@ export function DevicesPage() {
     return counts;
   }, [risks]);
 
+  const osOptions = useMemo(() => {
+    const seen = new Set<string>();
+    for (const d of devices) {
+      if (d.os_guess) seen.add(d.os_guess);
+    }
+    return Array.from(seen).sort();
+  }, [devices]);
+
   const filtered = useMemo(() => {
     const q = filter.toLowerCase();
     return devices.filter(
       (d) =>
-        d.ip_address.includes(q) ||
-        (d.hostname ?? "").toLowerCase().includes(q) ||
-        (d.mac_address ?? "").toLowerCase().includes(q) ||
-        (d.os_guess ?? "").toLowerCase().includes(q),
+        (d.ip_address.includes(q) ||
+          (d.hostname ?? "").toLowerCase().includes(q) ||
+          (d.mac_address ?? "").toLowerCase().includes(q) ||
+          (d.os_guess ?? "").toLowerCase().includes(q)) &&
+        (osFilter === "" || d.os_guess === osFilter),
     );
-  }, [devices, filter]);
+  }, [devices, filter, osFilter]);
 
   const sorted = useMemo(
     () => sortDevices(filtered, riskCounts, sortKey, sortDir),
@@ -111,14 +121,31 @@ export function DevicesPage() {
             : undefined
         }
         action={
-          <input
-            type="search"
-            placeholder="Filter by IP, hostname, OS…"
-            value={filter}
-            onChange={(e) => setFilter(e.target.value)}
-            aria-label="Filter devices"
-            className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-1.5 text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-secondary)] focus:outline-none focus:ring-1 focus:ring-[var(--color-accent-primary)] sm:w-64"
-          />
+          <div className="flex flex-wrap gap-2">
+            <input
+              type="search"
+              placeholder="Filter by IP, hostname, OS…"
+              value={filter}
+              onChange={(e) => setFilter(e.target.value)}
+              aria-label="Filter devices"
+              className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-1.5 text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-secondary)] focus:outline-none focus:ring-1 focus:ring-[var(--color-accent-primary)] sm:w-56"
+            />
+            {osOptions.length > 0 && (
+              <select
+                value={osFilter}
+                onChange={(e) => setOsFilter(e.target.value)}
+                aria-label="Filter by OS"
+                className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-1.5 text-sm text-[var(--color-text-primary)] focus:outline-none focus:ring-1 focus:ring-[var(--color-accent-primary)]"
+              >
+                <option value="">All OS</option>
+                {osOptions.map((os) => (
+                  <option key={os} value={os}>
+                    {os}
+                  </option>
+                ))}
+              </select>
+            )}
+          </div>
         }
       />