[New Plugin] - net/os-netmap

[Rush-er]

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

[Monviech]

The netmap name is a bit unfortunate as it's already taken by a core kernel component of freebsd.
https://man.freebsd.org/cgi/man.cgi?query=netmap

If you plan on opening a pull request, the plugin should wrap around an existing binary that has a freebsd upstream port.
Meta plugins like yours will not be able to be reviewed or merged as their scope is too broad.

[sopex]

This could also leverage the interfaces: neighbors and become an improved way to visualize discovered and manual hosts.