Install

Install globally from npm:

npm install -g pacportscanner

Run it with either command:

pacportscanner
pacports

Running without a target opens the interactive setup screen first. It asks for the target/IP, ports, profile, backend, timeout, concurrency, and scan toggles before starting.

Start the browser-based localhost UI:

pacportscanner web

The server binds to 127.0.0.1 and chooses port 43110, or the next available port if that one is busy. You can also choose a port:

pacportscanner web --port 43111

Run without installing globally:

npx pacportscanner 127.0.0.1 --backend socket

Quick Start

npm install -g pacportscanner
pacportscanner

For a one-shot non-interactive scan that auto-exports reports:

pacportscanner 127.0.0.1 --backend socket --no-tui

Scan a host, CIDR range, or custom port list:

pacportscanner 192.168.1.0/24 -p top100 --backend auto
pacports example.com --profile vulnerability
pacportscanner scanme.nmap.org -p 22,80,443

Open the web UI:

pacportscanner web

Why It Feels Fast

| Layer | What happens | | --- | --- | | Streaming engine | Results are yielded through AsyncIterable<PortResult> as soon as each probe finishes. | | Auto backend | The scanner tries nmap, then privileged raw sockets, then Node TCP connect. | | High concurrency | TCP connect scans can run up to 500 concurrent probes. | | Live TUI | Ink renders a live table, status bar, log panel, details drawer, and help overlay. | | Export pipeline | JSON, CSV, and self-contained HTML reports are written to ./data/. |

Backend Fallback

auto
  |
  |-- nmap        rich service, UDP, OS support when nmap exists
  |-- raw         SYN scan path when raw-socket and privileges are available
  '-- socket      Node.js TCP connect fallback, no root required

Features

| Area | Details | | --- | --- | | Targets | Single IP, hostname, IPv4 CIDR ranges | | Ports | top100, top1000, all, ranges like 1-1024, lists like 22,80,443 | | Detection | Service hints, banner grabbing, Nmap service/version parsing | | Intelligence | Optional CVE lookup with in-memory cache and public API fallback | | Profiles | stealth, fast, full, vulnerability | | Platforms | Linux, macOS, Windows | | Theme | Orange-on-dark, using #FF6B00 for highlights and branding |

CLI

Usage: pacportscanner [target] [options]
       pacportscanner web [options]

Options:
  -p, --ports <spec>       top100 | top1000 | all | 1-1024 | 22,80,443
  --profile <profile>      stealth | fast | full | vulnerability
  --backend <backend>      auto | nmap | raw | socket
  --no-cve                 Disable CVE lookup
  --no-tui                 Run once and export reports
  --version                Print version
  -h, --help               Show help

Web:
  pacportscanner web       Start localhost web UI
  --port <port>            Choose web UI port
  --host <host>            Bind host, defaults to 127.0.0.1

Web UI

pacportscanner web

Then open the printed localhost URL, for example:

http://127.0.0.1:43110

The web UI includes the same core workflow as the TUI: target and port setup, profile/backend selection, timeout/concurrency controls, scan toggles, start/stop, live table, detail drawer, live log panel, status metrics, help overlay, and JSON/CSV/HTML export.

TUI Controls

Setup screen:

Type        Edit target, ports, timeout, and concurrency fields
Up/Down     Move between setup fields
Tab         Move to the next setup field
Space       Toggle booleans or cycle profile/backend
Left/Right  Cycle profile/backend
Enter       Move next, or start from the last field
Ctrl+S      Start scan
?           Help overlay
q           Quit

Scan screen:

s       Start / stop scan
e       Export 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
?       Help overlay
q       Quit

Profiles

| Profile | Ports | Technique | | --- | --- | --- | | stealth | top100 | SYN if available, slower timing | | fast | top100 | TCP connect scan, aggressive timing | | full | 1-65535 | Connect scan, service detection, banner grab | | vulnerability | top1000 | Full scan, OS hints, CVE lookup |

Reports

Reports are saved automatically to ./data/.

pacportscanner_YYYYMMDD_HHMMSS.json
pacportscanner_YYYYMMDD_HHMMSS.csv
pacportscanner_YYYYMMDD_HHMMSS.html

JSON output follows this shape:

{
  "tool": "pacPortScanner",
  "generated_at": "ISO 8601 UTC",
  "backend": "nmap | raw | socket",
  "config": {
    "targets": ["192.168.1.0/24"],
    "profile": "vulnerability"
  },
  "summary": {
    "total": 0,
    "open": 0,
    "closed": 0,
    "filtered": 0,
    "with_cves": 0
  },
  "results": []
}

Configuration

Optional config file:

# ~/.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

src/
  scanner/
    engine.ts            auto-fallback and streaming orchestration
    backend.ts           shared ScannerBackend interface
    nmapBackend.ts       nmap XML wrapper
    rawSocketBackend.ts  optional privileged SYN backend
    socketBackend.ts     rootless TCP connect backend
  ui/
    App.tsx              Ink root component
    widgets/             table, drawer, log, status, help
  cve/
    lookup.ts            CVE lookup and cache
  export/
    json.ts
    csv.ts
    html.ts
  main.tsx               CLI entrypoint

Development

npm install
npm test
npm run lint
npm run build
npm run dev -- 127.0.0.1 --profile fast

Safety Notice

pacPortScanner is built for legitimate security testing, CTFs, and learning on infrastructure you own or have written permission to test. Scanning networks without authorization is illegal in most jurisdictions.

CVE data is best-effort from public APIs. A clean scan is not proof of security.