Nmap Real-time Terminal Dashboard

A high-performance, multi-threaded real-time CLI dashboard wrapper for the Nmap Security Scanner. It replaces Nmap's raw terminal log with a premium, live-updating dashboard featuring a progress bar, elapsed timer, rotating spinner, and a clean list of discovered open ports.

---

Features

• ⚡ True Real-time Rendering: Implements a multi-threaded architecture (UI rendering at 12.5 FPS, subprocess streaming in the background) to prevent terminal freezing.
• 🟢 Clean Discovered Ports: Discovered open ports are immediately printed as permanent green links (🟢 IP:port (Service) - open), while closed/filtered ports and other noise are hidden.
• 📊 Dynamic Scan Timing: Intercepts Nmap's statistics engine (matching both Stats: and native Timing: lines) to render a live block progress bar (▰▰▰▱▱) with the active completion percentage.
• ⚙️ Transparent Passthrough: Standard flags like --help, --version, or malformed commands bypass the UI and execute raw Nmap directly.

---

Installation

1. Prerequisites

Ensure you have the standard Nmap Scanner installed via Homebrew:

brew install nmap

2. Install the Wrapper

Clone this repository and save the wrapper script to your local binaries folder (e.g., ~/.local/bin):

# Create local bin directory if it doesn't exist
mkdir -p ~/.local/bin

# Copy the script
cp nmap ~/.local/bin/nmap

# Make it executable
chmod +x ~/.local/bin/nmap

3. Update PATH Priority

Make sure your Zsh configuration prioritizes local binaries. Open ~/.zshrc and ensure this line is present at the top:

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell:

source ~/.zshrc

---

Usage

Simply run it exactly as you would normally run nmap! The wrapper intercepts your call and loads the dashboard automatically.

# Scan a host for specific ports
nmap -p 22,80,443 scanme.nmap.org

# Run a larger port scan
nmap -p 1-1000 scanme.nmap.org

---

How It Works Under the Hood

1. Subprocess Streaming: The wrapper executes the real Nmap binary in a background process, injecting -v (verbose) and --stats-every 1s to capture real-time scan events.
2. ConcurrentNode Processing: A dedicated background thread reads Nmap's standard output stream in real-time, parsing port discoveries and timing updates.
3. Cursor-Movement UI: The main thread uses ANSI escape sequences (\033[A to move up, \033[K to clear lines) to redraw the progress panel in-place at the bottom of your screen, while writing permanent findings to the terminal history above.

---

License

Distributed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0). See LICENSE for more information.