[New Plugin] - net/os-netmap

Important notices
Before you add a new report, we ask you kindly to acknowledge the following:

• I have read the contributing guide lines at https://github.com/opnsense/plugins/blob/master/CONTRIBUTING.md
• I have searched the existing issues, open and closed, and I'm convinced that mine is new.
• When the request is meant for an existing plugin, I've added its name to the title.

Is your feature request related to a problem? Please describe.
No

Describe the solution you'd like
Adds a new diagnostic plugin under Interfaces → Diagnostics → Network Map that renders an
interactive network topology as a tidy tree (default) or force-directed graph.

Host discovery

• Reads discovered hosts from the hostwatch SQLite DB (/var/db/hostwatch/hosts.db, v_hosts view) — IPv4 only; IPv6 link-local addresses filtered out
• Resolves hostnames via a three-source priority chain: dnsmasq.leases → Unbound PTR records (/var/unbound/host_entries.conf) → static DHCP mappings from config.xml <dhcpd> (each source overwrites the previous)

VPN topology

• Parses config.xml for OpenVPN server instances and reads their status logs (/tmp/openvpn_serverN_status.log) to enumerate connected clients
• Parses WireGuard server/peer config from the config.xml OPNsense node

NetFlow enrichment

• Queries OPNsense Insight SQLite DBs (/var/netflow/src_addr_*.sqlite) — selects the finest-granularity DB that covers the requested window (5 min / 1 h / 24 h / 7 d)
• direction='out' rows (router→host) mapped to download; direction='in' (host→router) to upload

Async nmap scan

• scan_start.py (configd entry point) spawns scan_run.py detached so configd does not block
• scan_run.py re-validates IP and job UUID before exec; invokes nmap as a subprocess list (no shell interpolation), --top-ports 1000 -sV -O
• Rate-limited per IP (300 s) via a local SQLite DB at /var/db/netmap_rate.sqlite
• Scan target must be IPv4 and belong to a locally configured subnet

Describe alternatives you've considered
This is a new plugin, no alternative found.

Additional context
Implementation constraints

• Uses \SQLite3 PHP class directly — pdo_sqlite is absent on OPNsense 26.x; all handles opened SQLITE3_OPEN_READONLY
• Cache files written atomically (tmp + rename): 60 s TTL for topology, 120 s for flow data
• Frontend uses the system d3.min.js (D3 v3) — layout.tree, layout.force, svg.diagonal; no additional JS bundles required
• All HTML output sanitised with htmlspecialchars() / escH(); panel and canvas use CSS custom properties for OPNsense light/dark theme compatibility

AI disclosure
Developed with AI assistance: Claude Sonnet 4.6 (Anthropic) and Gemini Pro 3.1 (Google)

You can find the repo folder here: https://github.com/bitwire-it/os-netmap

Start with CONTRIBUTING.md, then inspect the existing plugin structure and the mentioned scan_start.py and scan_run.py entry points. Trace the hostwatch, VPN, NetFlow and config.xml data sources before implementing the diagnostic page. Done means the plugin renders the requested topology and enrichment views while safely performing the asynchronous, rate-limited IPv4 scan.