netscan

A modern network scanning utility for Apple platforms, built with Swift and SwiftUI.

This application is designed to discover devices and services on your local network. It provides a clean and simple interface to visualize network information.

Features

• Local Network Scanning: Discovers active hosts on the local network.
• ARP & Ping Discovery: On macOS we harvest the route table (no shell tools required) and nudge hosts with UDP; on iOS we lean on SimplePingKit for fast ICMP sweeps.
• Service Discovery: Uses Bonjour browsing/resolution along with ARP/Ping to surface advertised services in real time.
• Discovery Controls: Built-in toolbar lets you start/stop Bonjour, trigger an on-demand scan, and manually persist the current snapshot.
• Configurable Detail View: Toggle fingerprint data visibility from Settings on macOS and iOS.
• Device Intelligence: Normalises IP, MAC, and service data into a unified model with classification heuristics.
• Modern UI: Built with SwiftUI for a responsive and modern user experience across all target platforms.

Technology Stack

• Language: Swift
• UI: SwiftUI
• Networking: Combines the Network framework, SystemConfiguration route-table APIs, and SimplePingKit for platform-appropriate discovery.

Getting Started

To build and run this project:

1. Clone the repository:

   git clone https://github.com/vernonstinebaker/netscan.git

2. Open the project in Xcode:

   cd netscan
   xed .

3. Select a target (iOS or macOS) and run the application.

iOS Checklist (Bonjour/Local Network)

To enable discovery features on iOS, ensure the following:

• Info.plist keys
  • NSLocalNetworkUsageDescription: A user-facing string explaining why the app needs local network access.
  • NSBonjourServices: Array of service types you plan to browse (e.g., _http._tcp., _ssh._tcp., etc.). If you use dynamic DNS‑SD type discovery, include the superset of types your app may browse.
• Entitlements (optional)
  • Multicast Networking is only required if you add protocols beyond Bonjour that depend on multicast (e.g., SSDP). Bonjour browsing/resolution works with the current entitlement set.
• Notes
  • macOS discovery reads the ARP/route table directly (works inside App Sandbox) and sends lightweight UDP probes to keep entries fresh.
  • iOS discovery uses SimplePingKit; on first launch, iOS will prompt the user to allow Local Network access.

Bonjour Architecture & Logging

The unified scanner decomposes Bonjour (mDNS) handling into layered services:

• Browse: BonjourBrowseService maintains curated + wildcard NetServiceBrowser instances. Dynamic service types discovered via the wildcard browser are capped to avoid runaway browser creation. Logs tagged with browse: show lifecycle (start, wildcard discovery, cap skips, emissions).
• Resolve: BonjourResolveService launches per-type browsers only when needed and applies a cooldown to suppress excessive resolves of the same service instance. Logs tagged with resolve: include discovery events, resolution starts, cooldown skips, and successful resolution details (IPs, port, TXT size).
• Aggregation: DiscoveryProvider merges resolved service data into Device models via SnapshotService.upsert, triggering classification updates when pertinent fields (services, ports, vendor) change.

Logging Control:

• LoggingService.setMinimumLevel(.debug) enables verbose output; default is .info.
• Emission format: [Scan][LEVEL] message with consistent prefixes (browse:, resolve:, enqueue, ping, ARP etc.).
• For deterministic test logging, use await LoggingService.setMinimumLevelSync(.debug).

Offline Detection & Filtering:

• SnapshotService honours offlineCheckInterval and onlineGraceInterval, and automatically marks devices back online whenever fresh Bonjour or Ping data is received.
• Loopback, link-local, and off-subnet addresses are filtered out so the UI only surfaces devices that truly live on the active network(s).
• Fingerprint TXT records are mined for vendor/model hints, with OUI lookup filling gaps when MAC data is available.

Roadmap

• OUI Lookup Integration: ingest the vendor prefix database (oui.csv) and use fingerprint data to tighten classification heuristics.
• Port Scanning: Bring back the multi-tier port scanner with themed status pills and cancellation controls.
• Discovery Audit: Evaluate additional mechanisms (SSDP, WS-Discovery) for inclusion or removal.
• Service Helpers: Enhance service actions (open in browser, copy SSH, custom handlers for AirPlay/HomeKit/etc.).
• Structured Logging: Replace ad-hoc debug prints with channelled, toggleable log streams.

---

This README was generated by the Gemini CLI.