Metadata-Version: 2.4
Name: nmapui
Version: 3.0.0
Summary: A modern, learnable GUI for nmap — scan profiles, vuln highlighting, scan diff, a built-in flag explainer, and guided lessons.
Home-page: https://github.com/shivduttchoubey/nmapui
Author: Your Name
Author-email: Shiv Dutt Choubey <shivduttchoubey@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/shivduttchoubey/nmapui
Project-URL: Issues, https://github.com/shivduttchoubey/nmapui/issues
Project-URL: Changelog, https://github.com/shivduttchoubey/nmapui/blob/main/CHANGELOG.md
Keywords: nmap,network,scanner,security,gui,tkinter,learning
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Networking
Classifier: Topic :: Security
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Education
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# nmapui

**A modern, learnable GUI for nmap.** Replaces Zenmap with a dark-themed
interface that teaches you nmap as you use it — no command memorization,
no manual lookups, persistent settings across sessions.

```bash
pip install nmapui
nmapui
```

[![tests](https://github.com/shivduttchoubey/nmapui/actions/workflows/tests.yml/badge.svg)](https://github.com/shivduttchoubey/nmapui/actions)
![License](https://img.shields.io/badge/license-MIT-blue)

---

## Why this exists

Zenmap (the official nmap GUI) hasn't meaningfully changed in over a decade.
Using it well still means knowing `-sV`, `-T4`, `--script vuln`, etc. by heart.
nmapui keeps the real power of nmap but removes the memorization requirement —
and adds the pieces a learner or a day-to-day sysadmin actually wants:
favorites, history that survives a restart, vulnerability triage, and a
built-in tutorial.

| | Zenmap | nmapui |
|---|---|---|
| Dark, modern UI | ✗ | ✓ |
| Plain-English scan profiles | partial | ✓ 10 profiles |
| Live command preview | ✗ | ✓ |
| Flag-by-flag command explainer | ✗ | ✓ |
| Guided lessons / practice mode | ✗ | ✓ |
| Vulnerability tab (CVE + severity) | ✗ | ✓ |
| Scan diff / compare | ✗ | ✓ |
| Favorite targets | ✗ | ✓ |
| Settings/history persist across restarts | ✗ | ✓ (`~/.nmapui/`) |
| Export CSV / JSON | ✗ | ✓ |
| Searchable cheatsheet | ✗ | ✓ |
| Zero third-party dependencies | ✓ | ✓ |

---

## Requirements

- Python 3.9+ (tkinter ships with most standard installs)
- The `nmap` binary on your PATH
  - macOS: `brew install nmap`
  - Ubuntu/Debian: `sudo apt install nmap`
  - Windows: [nmap.org/download](https://nmap.org/download) (check "Add to PATH" during install)
  - Winget on Windows: winget install -e --id Insecure.Nmap


---

## Features

### Scanner
10 plain-English scan profiles (Quick Ping, Common Ports, Full Port Scan,
Service Detection, OS Detection, Intense, Stealth SYN, UDP, Vuln Scripts,
Custom), a live command preview that updates as you adjust options, and a
results view split into Summary / Ports / Raw Output / Export tabs.

### Favorites
Save a target with a name ("Home Router", "Lab Server") from the Scanner
tab. Favorites persist in `~/.nmapui/favorites.json` and show up in a
dropdown next to the target field — no more retyping IPs.

### Explain
Paste any nmap command — your own, or one you copied from a forum post —
and get a flag-by-flag plain-English breakdown before you run it, including
a warning note on flags that are noisy, intrusive, or privileged.

```
Input:  nmap -sS -T4 -A --script vuln 192.168.1.0/24

-sS   → TCP SYN scan ("stealth" scan)... [Note: Requires root/admin privileges]
-T4   → Aggressive timing...
-A    → Aggressive scan, shorthand for -O -sV -sC --traceroute... [Note: noisy]
--script vuln → Run NSE vulnerability-category scripts... [Note: intrusive]
```

### Learn
A short guided curriculum: what a port scan actually is, how to pick the
right scan for a situation, how to read the results, and how to scan
responsibly. Each lesson has a "Try it" button that loads a real command
against `scanme.nmap.org` — the official Nmap project practice host — so
you can learn without needing your own server or anyone's permission.

### Vulns
After any scan using `--script vuln` (or the Vuln Scripts profile), NSE
output is automatically parsed into a sortable, filterable table:
severity (CRITICAL/HIGH/MEDIUM/LOW/INFO), CVE numbers, CVSS scores, and a
detail panel with the full script output for each finding.

### Diff
Run two scans — say, before and after a firewall change — then compare
them. See exactly which hosts appeared or vanished, which ports opened or
closed, and which service versions changed.

### History
Every scan is logged with timestamp, target, command, and result counts.
Summary metadata (not full raw output) persists to disk in
`~/.nmapui/history.json`, so your log survives closing the app.

### Cheatsheet
24 common nmap flags with plain-English descriptions, instant search
filter, click-to-copy.

---

## CLI

```bash
nmapui                  # launch the GUI
nmapui --version        # print version
nmapui --config-dir     # print where settings/history/favorites live
nmapui --reset-config   # reset saved settings to defaults
```

---

## Project layout

```
nmapui/
├── nmapui/
│   ├── __init__.py     # package root (lazy-imports the GUI)
│   ├── __main__.py     # CLI entry point
│   ├── gui.py          # Tkinter application (UI layer)
│   ├── vuln_parser.py  # NSE output parsing + severity classification
│   ├── diff.py         # Scan comparison engine
│   ├── explainer.py    # Flag-by-flag command explanations
│   ├── lessons.py       # Content for the Learn tab
│   └── storage.py       # Persistent settings/favorites/history
├── tests/               # Unit tests (no tkinter required to run)
├── .github/workflows/    # CI
├── pyproject.toml
├── LICENSE
├── CHANGELOG.md
└── CONTRIBUTING.md
```

The logic modules (`diff.py`, `vuln_parser.py`, `explainer.py`, `storage.py`)
have no tkinter dependency and are independently unit tested — `gui.py` is
the only file that needs a display.

---

## Running tests

```bash
pip install -e ".[dev]"
pytest
```

33 tests, no `nmap` binary or display required.

---

## Publishing to PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

---

## Legal note

nmapui is a GUI front-end only — all scanning is performed by the `nmap`
binary on your system. Only scan networks and hosts you own or have
explicit permission to test. Unauthorized network scanning may be illegal
in your jurisdiction. The Learn tab's practice exercises use
`scanme.nmap.org`, a host the Nmap project explicitly maintains for this
purpose — be reasonable with it (light scans only).

## License

MIT — see [LICENSE](LICENSE).
