⚡ A modern, blazing-fast TUI port scanner built with Textual.

Auto-selects the best backend available — Nmap → Scapy → raw sockets — so it works everywhere, root or not.

Install • Quick Start • Features • Backends • Keybindings • Exports • CLI • Architecture

---

Warning

Authorized-use only. pacPortScanner is built for legitimate security testing, CTFs, and learning on your own infrastructure. Scanning networks you do not own or have written permission to test is illegal in most jurisdictions.

---

✨ Features

🎯  Scanning Single IP, hostname, or CIDR ranges Port presets: top100, top1000, all, or custom Streaming results — no batch waiting Service detection + banner grabbing Optional ping sweep to skip dead hosts Concurrency up to 500 sockets	🛡️  Intelligence OS fingerprinting (Nmap) + TTL fallback CVE lookup via cve.circl.lu & NVD Version & CPE extraction from banners Severity highlighting (CRITICAL → LOW) No API keys required In-memory cache avoids duplicate calls
🎨  Interface Textual-powered modern TUI Orange-on-dark custom theme (#FF6B00) Live-updating results table Slide-in detail drawer per row Live log & status bar with pps / ETA Full keyboard shortcuts + help overlay	📦  Output JSON — structured, every field CSV — spreadsheet-friendly HTML — styled, self-contained report Auto-saved to ./data/ with timestamps 4 curated profiles (Stealth → Vuln) CLI prefill for scripted kicks-off

---

📸 Preview

┌── ⊙ pacPortScanner ──────────────────────────────────────────────────────┐
│ Target: 192.168.1.0/24          │ HOST          PORT    STATE  SERVICE  │
│ Ports : top1000                 │ 192.168.1.1   22/tcp  open   ssh      │
│ Profile: vulnerability          │ 192.168.1.1   80/tcp  open   http     │
│ [✓] ping sweep                  │ 192.168.1.5   443/tcp open   https    │
│ [✓] banner grab                 │ 192.168.1.5   3306    open   mysql ⚠3 │
│ [✓] CVE lookup                  │ 192.168.1.7   22/tcp  open   ssh      │
│                                 │                                       │
│  ▶ Start scan  (s)              │                                       │
├─────────────────────────────────┴───────────────────────────────────────┤
│ backend: nmap · ports/s: 842 · open: 12 · elapsed: 4.2s · ██████░░ 74% │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Install

🛠️ From source

git clone https://github.com/demirgitbuh/pacPortScanner.git
cd pacPortScanner
pip install -e ".[full]"

🪟 Windows (PowerShell)

git clone https://github.com/demirgitbuh/pacPortScanner.git
cd pacPortScanner
pip install -e ".[full]"
pacportscanner

On Windows, the Scapy backend requires Npcap with WinPcap API compatibility enabled.

---

🚀 Quick Start

# launch the TUI
pacportscanner

# prefill a target and profile
pacports scanme.nmap.org -p top1000 --profile vulnerability

# force a specific backend
pacports 10.0.0.0/24 --backend socket --no-cve

📝 Step-by-step

1. Launch with pacportscanner.
2. Enter a target in the left panel (IP, hostname, or CIDR).
3. Pick a port preset or type a custom spec (e.g. 22,80,443 or 1-1024).
4. Choose a profile and press s to start.
5. Results stream into the table in real time. Press Enter on a row for full detail.
6. Press e to export — three reports land in ./data/.

---

🔌 Backend Auto-Fallback

On startup, pacPortScanner probes available backends in priority order:

#	Backend	Needs	SYN	UDP	OS Detect	Root
1	Nmap	python-nmap + nmap binary	✅	✅	✅	optional
2	Scapy	scapy	✅	❌	❌	✅ required
3	Socket	stdlib only	❌ (connect)	❌	❌	❌ not needed

flowchart LR
    A[Start] --> B{Nmap available?}
    B -- yes --> N[🟠 Nmap backend]
    B -- no  --> C{Scapy + root?}
    C -- yes --> S[🟠 Scapy backend]
    C -- no  --> K[🟠 Socket backend]
    N --> R[(Streaming results)]
    S --> R
    K --> R

Loading

The active backend is shown in the status bar — or force one with --backend.

---

🎛️ Scan Profiles

Profile	Ports	Techniques
🥷 stealth	top 100	SYN (if available) · slow timing
⚡ fast	top 100	Connect scan · aggressive timing
🔬 full	1–65535	Connect scan · service + banner grab
🛡️ vulnerability	top 1000	Full + OS detect + CVE lookup

---

⌨️ Keybindings

Key	Action
s	Start / stop the current scan
e	Export results (JSON + CSV + HTML)
p	Cycle scan profile
d	Toggle detail drawer
l	Toggle live log panel
Enter	Open detail drawer on selected row
Tab	Cycle focus between widgets
?	Show help overlay
q	Quit

---

📁 Exports

Pressing e writes three files to a data/ folder in your working directory:

data/
├── pacportscanner_20260418_142301.json   # structured, every field
├── pacportscanner_20260418_142301.csv    # spreadsheet-friendly
└── pacportscanner_20260418_142301.html   # styled standalone report

✨ The HTML report is self-contained (inline CSS, no external assets) — safe to email, attach, or archive.

📄 JSON shape

{
  "tool": "pacPortScanner",
  "generated_at": "2026-04-18T14:23:01Z",
  "backend": "nmap",
  "config": { "targets": ["192.168.1.0/24"], "profile": "vulnerability" },
  "summary": { "total": 24, "open": 12, "closed": 8, "filtered": 4, "with_cves": 3 },
  "results": [
    {
      "host": "192.168.1.5",
      "port": 3306,
      "state": "open",
      "service": "mysql",
      "version": "MySQL 5.7.32",
      "banner": "5.7.32-0ubuntu0.18.04.1",
      "cves": ["CVE-2021-2144", "CVE-2021-2154", "CVE-2021-2166"]
    }
  ]
}

---

🖥️ CLI

pacportscanner [target] [options]

positional:
  target                  Prefill target (IP, hostname, or CIDR)

options:
  -p, --ports SPEC        Port spec (top100 / top1000 / all / 1-1024 / 22,80,443)
  --profile PROFILE       stealth | fast | full | vulnerability
  --backend BACKEND       auto | nmap | scapy | socket
  --no-cve                Disable CVE lookup
  --version               Print version
  -h, --help              Show help

---

⚙️ Configuration (optional)

Drop a config at ~/.config/pacportscanner/config.toml:

[defaults]
profile      = "fast"
timeout      = 1.5
concurrency  = 500
ping_sweep   = true

[cve]
enabled = true
api     = "https://cve.circl.lu/api"

---

🏛️ Architecture

pacportscanner/
├── 🔍 scanner/          backend ABC + engine + nmap/scapy/socket implementations
│   ├── engine.py            auto-fallback + streaming AsyncIterator[PortResult]
│   ├── nmap_backend.py
│   ├── scapy_backend.py
│   └── socket_backend.py
├── 🎨 ui/               Textual App, screens, widgets, and TCSS theme
│   ├── screens/
│   ├── widgets/
│   └── pacportscanner.tcss
├── 🛡️ cve/              async CVE lookup (cve.circl.lu + NVD fallback)
├── 📦 export/           JSON / CSV / HTML exporters
└── main.py              CLI entry point

🧬 Every backend implements a common ScannerBackend abstract base class and yields PortResult objects through an AsyncIterator — so the UI streams results as they arrive instead of blocking on a full batch.

---

🛡️ CVE Disclaimer

Caution

CVE data is fetched from public APIs (cve.circl.lu, nvd.nist.gov) and is best-effort. Matches may be incomplete, outdated, or version-mismatched. Never treat a clean scan as proof of security. Always verify findings manually.

---

🤝 Contributing

Contributions welcome! Please:

1. 🍴 Fork the repo and create a feature branch
2. ✨ Keep changes focused; add a test for any fix
3. 🎨 Run ruff check pacportscanner before submitting
4. 📝 Open a PR with a clear description

pip install -e ".[dev]"
ruff check pacportscanner
mypy pacportscanner
pytest

---

📜 License

Released under the MIT License — use it, ship it, break it, fix it.

---

⚖️ Ethical Use

pacPortScanner is intended for authorized security testing, CTF competitions, and learning on your own infrastructure only. Unauthorized scanning is illegal in most jurisdictions. The authors accept no liability for misuse.

---

⭐ If you find pacPortScanner useful, star the repo — it helps a lot!

_{Built with 🐍 Python · 🎨 Textual · ⚡ asyncio · ☕ coffee}

_{⬆ back to top}