portscout

A fast, readable TCP port scanner for developers and NOC engineers. Give it a list of hosts and it tells you which ports are open, closed, or filtered — with color-coded output and latency measurements.

Disclaimer: portscout is a developer diagnostic tool intended for use on your own infrastructure or networks you have explicit permission to scan. Unauthorized port scanning may be illegal in your jurisdiction.

---

Why portscout?

Raw nmap output is powerful but verbose. portscout gives you a clean terminal table focused on the ports you care about, with no configuration files required.

---

Installation

From npm (once published)

npm install -g portscout

Local build

git clone https://github.com/yourname/portscout.git
cd portscout
npm install
npm run build
# Run directly:
node dist/index.js scan hosts.txt
# Or link globally:
npm link
portscout scan hosts.txt

---

Usage

Create a hosts.txt file with one hostname or IP per line. Lines beginning with # and empty lines are ignored.

# hosts.txt
192.168.1.1
10.0.0.10
example.com

Scan default ports (top 20 common ports)

portscout scan hosts.txt

Scan specific ports

portscout scan hosts.txt --ports 80,443,8080

Scan a port range

portscout scan hosts.txt --ports 1-1000

Mixed ports and ranges

portscout scan hosts.txt --ports 22,80-82,443,8080-8090

---

Sample Output

┌───────────────┬──────┬──────────┬─────────┐
│ HOST          │ PORT │ STATUS   │ LATENCY │
├───────────────┼──────┼──────────┼─────────┤
│ 192.168.1.1   │  22  │ OPEN     │  3ms    │
│ 192.168.1.1   │  80  │ OPEN     │  2ms    │
│ 192.168.1.1   │ 443  │ CLOSED   │  1ms    │
│ 10.0.0.10     │  22  │ FILTERED │  —      │
│ 10.0.0.10     │  80  │ FILTERED │  —      │
└───────────────┴──────┴──────────┴─────────┘

Scanned 2 hosts × 3 ports — 2 open, 1 closed, 2 filtered

Colors: green = OPEN, red = CLOSED, yellow = FILTERED

---

Port Status Meanings

Status	Meaning
OPEN	TCP connection succeeded
CLOSED	Connection refused immediately by the host
FILTERED	No response within the 3-second timeout

---

Default Ports

When --ports is omitted, portscout scans these 20 common ports:

21, 22, 23, 25, 53, 80, 110, 143, 443, 445, 3306, 3389, 5432, 5900, 6379, 8080, 8443, 8888, 27017, 27018

---

Tech Stack

Component	Library
Language	TypeScript (strict)
CLI framework	Commander.js
Colors	chalk
Table output	cli-table3
Spinner	ora
Build	tsup
TCP scanning	Node.js net module
Tests	Vitest

---

Development

npm install
npm run dev -- scan hosts.txt   # Run with ts-node
npm test                         # Run Vitest unit tests
npm run build                    # Compile to dist/

---

License

MIT