November 19, 2026
NucMap: Self-Hosted Attack Surface Management for Homelabs and Internal Networks
Why I wanted a lightweight bridge between Nmap and Nuclei β and how state-based drift detection turns point-in-time scans into continuousβ¦

By JΓΆrg Stephan
5 min read
Why I wanted a lightweight bridge between Nmap and Nuclei β and how state-based drift detection turns point-in-time scans into continuous visibility.
Imagined by a human and created by AI Β· Open Source (MIT License) Β· Version 0.1.2
If you run a homelab, manage internal infrastructure, or maintain self-hosted services on Proxmox or Docker, your network rarely stands still. A new container gets spun up for testing, a reverse proxy exposes an admin port you forgot about, a TLS certificate quietly creeps toward expiration, or a default service configuration slips into production.
Yet when you look for tooling to keep an eye on your own attack surface, you usually hit two extremes:
- Heavyweight enterprise security suites that require significant RAM, external SaaS accounts, or complex licensing just to monitor a handful of subnets.
- Ad-hoc CLI scans where you manually run
nmapornucleiin a terminal, read the output once, and immediately lose track of what changed between last week and today.
That gap is why NucMap exists.
The idea behind NucMap was simple: take two of the sharpest open-source security tools available β Nmap and ProjectDiscovery Nuclei β and connect them inside a self-hosted web platform that remembers every scan, highlights what drifted, and runs happily inside a lightweight Proxmox LXC container or Docker host.
The Core Idea: From One-Off Scans to Attack Surface Drift
Running a port scanner once tells you what is open right now. What actually matters for operational security is change over time β knowing the exact moment a new port appears, a service banner changes, or a newly synced vulnerability template triggers on an existing host.
NucMap treats every scan as a versioned snapshot stored in a local SQLite database (running in WAL mode). Rather than forcing you to mentally diff terminal logs, NucMap compares consecutive scans for each monitored asset and turns the results into concrete drift events and optional real-time alerts.
Equally important was keeping the platform 100% self-contained. Every UI asset β including the local Tailwind CSS engine β is served directly from the NucMap instance itself. There are zero calls to external CDNs, tracking scripts, or third-party font servers, so the dashboard works reliably in air-gapped labs or behind strict DNS blockers like Pi-hole and AdGuard Home.
How NucMap Works: The Three-Stage Pipeline
At the heart of NucMap is an orchestrated pipeline that separates discovery from verification and historical comparison.
Stage 1: Discovery, Fingerprinting, and TLS Inspection (Nmap + Vulscan)
When a scan starts, NucMap runs Nmap with service and version detection (-sV) according to the chosen scan profile. It collects open TCP ports, service banners, CPE strings, and live SSL/TLS certificate metadata (including expiry tracking), with optional offline banner CVE lookup via vulscan.nse.
Because homelabs frequently run inside unprivileged containers where raw socket privileges may be restricted, NucMap handles environment constraints gracefully: if a SYN scan (-sS) or raw ARP sweep cannot execute, it automatically falls back to TCP Connect (-sT) and resolves MAC addresses and hardware vendors via kernel /proc/net/arp, IEEE OUI lookups, and parallel reverse DNS.
Stage 2: Active Template Verification (ProjectDiscovery Nuclei)
Banner matching alone creates noise. Once Stage 1 finishes mapping open services, NucMap automatically pipes discovered HTTP/HTTPS endpoints β and optionally non-HTTP network services β into ProjectDiscovery Nuclei.
Using Wappalyzer-based automatic technology matching (-as) alongside targeted exposed-panel, exposure, default-login, and network templates, Nuclei actively verifies real issues while avoiding slow external OAST callbacks (-ni).
You are not locked into running the whole pipeline every time, either. NucMap lets you run Stage 1 Only (ports & TLS), Stage 2 Only (re-testing Nuclei against previously saved ports), or click Redo Stage 1, Redo Stage 2, or Re-verify Port directly on a single port card without rescanning an entire host.
Stage 3: Consecutive Diffing and Drift Events
Once both stages complete, NucMap's diff engine compares the new snapshot against the asset's previous completed scan and records structured drift events:
NEW_PORTβ A previously closed TCP port is now listening.CLOSED_PORTβ A previously observed port is no longer exposed.BANNER_CHANGEDβ A service product or version string changed on an existing port.NEW_VULNβ A new CVE, exposed panel, or misconfiguration finding appeared.RESOLVED_VULNβ A previously reported finding is no longer detected.
Built for Practical Day-to-Day Operations
Beyond the scanning pipeline itself, NucMap focuses on reducing friction across daily workflows:
- Multi-Probe Subnet Discovery Wizard: Auto-detects local network interfaces and
/24CIDRs, then lets you choose between a fast ICMP + 15-port TCP probe sweep or a deep port-assisted sweep (-Pn --top-ports 25) to uncover firewalled hosts and preview MAC vendors and hostnames before importing. - Sortable, Multi-Faceted Asset Inventory: Filter monitored hosts by search text, custom tags (
LAN,DMZ,IoT), security state, or profile β and sort every column, including numerical IPv4 sorting (so192.168.1.2properly precedes192.168.1.10) and severity-weighted vulnerability ranking. - 7 Built-in Scan Profiles + Visual Port Builder: Choose from
web,web-backend,server,quick,standard,deep, andstealthpresets, or build custom profiles with your own port sets and Nmap/Nuclei arguments. - Parallel Worker Pool & Automated Schedules: Scan
1xto5xhosts concurrently with live status polling and cancellation, or schedule recurring scans (hourly, 6h, 12h, daily, weekly) scoped by tags, single targets, or all assets. - Finding Triage & Noise Suppression: Expected internal findings β such as self-signed certificates on internal appliances β can be marked as Accepted Risk or False Positive so they stop inflating Critical/High counters or triggering alerts.
- Extensible via
NucMap-scripts: During setup and signature updates, NucMap syncs custom Nmap.nseLua scripts, Nuclei.yamltemplates, and shell helpers from the companion NucMap-scripts library, making them available both automatically in scans and on-demand in the Web UI. - JSON Syslog, Webhooks & Email Alerts: Emit structured RFC5424 JSON Syslog events locally or to remote collectors (Graylog, Wazuh, Splunk, ELK, Loki), and send instant push alerts for new ports or high-severity findings via Webhooks (Ntfy, Discord, Slack, Gotify, Home Assistant) or local Postfix SMTP.
Security First β Even on Your Internal Network
A tool that executes network scanners on your behalf has to be careful with input handling. NucMap validates every target against strict RFC-1123 FQDN, IPv4, and CIDR rules, enforces Nmap flag allowlists, and invokes scanner binaries via Node's child_process.spawn(..., { shell: false }) to eliminate shell injection paths.
It also ships with built-in per-IP API rate limiting, strict security headers (X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer), and optional HTTP Basic Auth (NUCMAP_PASSWORD) and API key protection (NUCMAP_API_KEY) for securing both the Web UI and REST endpoints.
Deploying NucMap in Minutes
NucMap can run via a one-line Proxmox VE LXC helper script, Docker Compose, or a standalone Debian/Ubuntu installer.
Proxmox VE LXC (Recommended for Homelabs)
Run this directly in your Proxmox VE Host Shell to create an unprivileged Debian container (automatically matching amd64 or arm64), inherit your Proxmox host's authorized SSH keys, and install Nmap, Nuclei, Vulscan, and NucMap:
bash -c "$(wget -qLO - https://raw.githubusercontent.com/johestephan/NucMap/main/proxmox/nucmap.sh)"bash -c "$(wget -qLO - https://raw.githubusercontent.com/johestephan/NucMap/main/proxmox/nucmap.sh)"When future releases land, updating takes a single command from your Proxmox host while preserving your SQLite database, scan history, profiles, and schedules:
pct exec <CTID> -- updatepct exec <CTID> -- updateDocker Compose
Prefer Docker? Clone the repository and bring it up with host networking (for Layer-2 discovery and raw SYN scans):
git clone https://github.com/johestephan/NucMap.git
cd NucMap
docker compose up -d --buildgit clone https://github.com/johestephan/NucMap.git
cd NucMap
docker compose up -d --buildImagined by a Human and Created by AI
NucMap is an experiment as much as a utility β imagined by a human and created by AI, built around real homelab pain points and released openly under the MIT License.
If you want lightweight, self-hosted visibility into what is listening on your network and how it changes over time, check out the code, try a subnet sweep, or contribute templates and scripts:
- GitHub Repository: github.com/johestephan/NucMap
- Custom Scripts Library: github.com/johestephan/NucMap-scripts