macOS-first network scanning and monitoring app powered by Nmap.
git clone https://github.com/techmore/TM-NmapUI.git
cd TM-NmapUI
./install.sh
sudo npm startThe app will open its local UI automatically. If you need to access it directly, use the loopback URL shown by the launcher, usually http://127.0.0.1:9000.
npm start also checks for missing Node packages and installs them automatically, so a clean checkout will recover if node_modules/ has not been created yet.
| Layer | Technology |
|---|---|
| Runtime | Node.js |
| Desktop Shell | Swift menu bar app |
| Web Framework | Express |
| Real-time | Socket.IO |
| Scanner | Nmap + NSE (Nmap Scripting Engine) |
| PDF Generation | wkhtmltopdf / Chromium |
| XML Processing | xml2js |
| Scheduling | node-cron |
| HTTP Client | axios |
| Cloud Sync | Google Drive helper |
- macOS (primary target)
- Homebrew (for package management)
- Node.js (via Homebrew)
- Nmap (with script database updated)
- wkhtmltopdf or Chromium (for PDF generation)
- xsltproc (for HTML report styling)
All dependencies are installed automatically by install.sh.
-
Clone the repository:
git clone https://github.com/techmore/NmapUI.git cd NmapUI -
Build and launch the menu bar app:
open NmapUIMenuBar.app
After launch, look for the network icon in your macOS menu bar. The app serves NmapUI on a local loopback URL, defaulting to
http://127.0.0.1:9000and falling back to the next available local port if needed. The menu bar app now exposes aLaunch at Logintoggle and anUninstall NmapUImenu action. Uninstall removes the login item registration first and then moves the app bundle to the Trash.Prerequisites: Xcode Command Line Tools (
xcode-select --install) and Homebrew are needed byinstall.shto pull innmap,arp-scan, etc.
If you want a more atomic install path, the repository now includes a container build that packages the Node runtime with its scan/report tooling.
Build the image:
docker build -t nmapui:container .Run it with Docker Compose:
docker compose up --buildThe container listens on 0.0.0.0:9000 and persists runtime data in /data. The app now reads mutable files from that directory, so scan history, settings, reports, and temporary scan artifacts survive restarts. If you want to override defaults locally, set NMAPUI_DATA_DIR, NMAPUI_PORT, or PORT in your shell or a compose .env file.
Notes:
- The container includes
nmap,xsltproc,wkhtmltopdf, Chromium,traceroute, andpython3for the helper scripts. - Network scanning still depends on the runtime’s network permissions. The bundled compose file adds
NET_ADMINandNET_RAW, which are typically required for fuller scan capabilities. - For environments like Apple Container Machines, the same image can be used as a starting point, but you may need to adjust network exposure or host access based on the target runtime’s policies.
- The container healthcheck hits
/api/app-identity, which is a lightweight readiness signal for orchestration.
- Root: stable entrypoints and runtime files such as
server.js,install.sh, anddeploy.sh NmapUI.app/andNmapUIMenuBar.app/: macOS app bundles produced by the current packaging flowpackaging/macos/: Swift/AppKit shell scaffold for the macOS-native directiondocs/guides/: user and maintainer guidesdocs/notes/: internal implementation notes and working analysisdocs/audits/: deeper audit writeups that are not part of the main setup flow
Runtime-only files such as auto_scan_config.json, generated scan outputs, local wrapper binaries, and ad hoc scratch directories should stay untracked.
Export the runtime database from the Settings tab, or download it directly:
curl -OJ http://127.0.0.1:9000/api/runtime/exportIf you are migrating an existing runtime database into the menu bar app bundle, copy the runtime data directory into the bundle resources before launch:
cp /path/to/runtime.sqlite3 NmapUIMenuBar.app/Contents/Resources/data/runtime.sqlite3The current repository does not include the old build.sh installer flow referenced in earlier notes.
sudo npm startThe launcher starts the local runtime on port 9000 by default and opens the app shell around it. On the macOS wrapper, the menu bar icon is the primary way back into the app.
- Quick Scan - Fast discovery of live hosts on the network
- Complete Scan - Full port scan with OS detection and vulnerability scripts
- Dragnet Scan - Scan all hosts from previous discovery with exhaustive options
Schedule automatic scans to run daily, weekly, monthly, or hourly. Results are saved to reports_archive/ and optionally synced to Google Drive.
HTML and PDF reports are generated after each scan. Reports include:
- Discovered hosts with IP, MAC, hostname, vendor
- Open ports and service versions
- Detected CVEs with CVSS scores
- Network topology fingerprint
.
├── server.js # Main local runtime
├── install.sh # Dependency installer
├── package.json # Node dependencies
├── google_drive.py # Google Drive sync helper
├── nmap-modern.xsl # Report stylesheet
├── config.json # App configuration
├── history.json # Scan history
├── reports_archive/ # Generated reports
└── static/ # Frontend assets
MIT