Skill: port-scanner CLI

# Skill: port-scanner CLI

## When to use

Use this skill when you need to scan TCP ports on localhost or LAN hosts from the terminal, list or view previous scan results, compare two scans to detect changed open ports, or integrate port scanning into a shell script or CI check.

## Prerequisites

- Node.js 20 or later
- port-scanner-dashboard API server running on `http://127.0.0.1:7601`
- For LAN scanning: `PORTSCANNER_ALLOW_LAN=1` must be set

## Installation

```
npm install -g port-scanner-dashboard
```

Or run without installing:

```
npx port-scanner-dashboard
```

The `npx port-scanner-dashboard` command starts the API server and opens the dashboard. The `port-scan` binary provides the CLI.

## Quick start

```
# start the server
npx port-scanner-dashboard

# scan common ports on localhost
port-scan scan 127.0.0.1 --ports 1-1024 --label "common ports"

# list all scans
port-scan list

# view open ports for a scan
port-scan show <id>

# cancel a running scan
port-scan cancel <id>
```

## Usage patterns

### Scan specific port lists

```
# web ports
port-scan scan 127.0.0.1 --ports 80,443,3000,8000,8080,8443 --label "web ports"

# database ports
port-scan scan 127.0.0.1 --ports 3306,5432,6379,27017 --label "db ports"

# full scan
port-scan scan 127.0.0.1 --ports 1-65535 --label "full scan"
```

### Increase speed for large ranges

```
port-scan scan 127.0.0.1 --ports 1-65535 --concurrency 200 --timeout 200
```

Higher concurrency and lower timeout find open ports faster but may increase false filtered results.

### Scan a LAN host

```
PORTSCANNER_ALLOW_LAN=1 port-scan scan 192.168.1.1 --ports 1-1024 --label "router"
```

LAN scanning must be explicitly enabled. Scanning hosts you do not own or have permission to scan may be illegal.

### View only filtered ports

```
port-scan show <id> --state filtered
```

### Compare two scans

```
port-scan list   # find IDs to compare
port-scan compare <baseline-id> <comparison-id>
```

Output shows ports that appeared (+) and ports that disappeared (-) between the two scans.

### Delete old scans

```
port-scan delete <id>
```

### Export results as JSON

```
port-scan show <id> --json
```

## CLI reference

| Command | Description |
|---|---|
| `port-scan scan <target>` | Start a new scan |
| `port-scan list` | List all scans |
| `port-scan show <id>` | Show results for a scan |
| `port-scan compare <id> <id>` | Compare open ports between two scans |
| `port-scan cancel <id>` | Cancel a running scan |
| `port-scan delete <id>` | Delete a scan and its results |
| `port-scan status` | Show server status |

## Flag reference

### `port-scan scan`

| Flag | Default | Description |
|---|---|---|
| `--ports <range>` | `1-1024` | Port range or list to scan |
| `--label <name>` | - | Display name for the scan |
| `--timeout <ms>` | `300` | TCP connect timeout per port |
| `--concurrency <n>` | `100` | Parallel TCP attempts |
| `--no-progress` | - | Suppress progress output |
| `--json` | - | Output results as JSON stream |

### `port-scan show`

| Flag | Default | Description |
|---|---|---|
| `--state open|closed|filtered|all` | `open` | Which port states to show |
| `--limit <n>` | `100` | Max rows per page |
| `--json` | - | Output as JSON array |

### `port-scan list`

| Flag | Description |
|---|---|
| `--state running|complete|cancelled|error` | Filter by scan state |
| `--json` | Output as JSON array |

## Port range syntax

| Format | Example | Ports |
|---|---|---|
| Range | `1-1024` | 1 through 1024 inclusive |
| List | `22,80,443` | Only those three ports |
| Mixed | `1-100,443,8000-8080` | Combined |
| Named presets | `web`, `db`, `common` | Expands to a built-in list |

Named preset expansions:
- `web`: `80,443,3000,8000,8080,8443`
- `db`: `3306,5432,6379,27017,9200,6432`
- `common`: `21,22,23,25,53,80,110,143,443,445,3306,5432,6379,8080,27017`

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `PORTSCANNER_URL` | `http://127.0.0.1:7601` | API server URL used by the CLI |
| `PORTSCANNER_PORT` | `7601` | Server listen port (server-side) |
| `PORTSCANNER_HOST` | `127.0.0.1` | Server bind host |
| `PORTSCANNER_DATA_DIR` | `~/.port-scanner` | Data directory for SQLite DB |
| `PORTSCANNER_ALLOW_LAN` | `0` | Set to `1` to allow scanning LAN hosts |
| `PORTSCANNER_CONCURRENCY` | `100` | Default parallel connections |
| `PORTSCANNER_TIMEOUT_MS` | `300` | Default TCP connect timeout |
| `PORTSCANNER_RATE_LIMIT` | `500` | Max new connections per second |
| `PORTSCANNER_MAX_PORTS` | `65535` | Max ports per scan |

## Port state meanings

| State | Meaning |
|---|---|
| `open` | TCP SYN-ACK received - a service is listening |
| `closed` | TCP RST received - no service, but host responded |
| `filtered` | Connect timed out - firewall or no response |

## Troubleshooting

### "Cannot connect to port-scanner server"

The API server is not running. Start it with `npx port-scanner-dashboard`. Check the URL: `echo $PORTSCANNER_URL`.

### Scan completes very slowly

Reduce `--concurrency` and check that `--timeout` is not set too high. For a full 65535-port scan with `--timeout 300` and `--concurrency 100`, expect 3-5 minutes.

### Many ports show as filtered

Filtered means the TCP connect timed out without a RST. On localhost this is unusual and may indicate a firewall rule (e.g. `pf` or `iptables`) is silently dropping connections. Try increasing `--timeout` to 1000ms.

### "Target is a public IP address"

Public IPs are blocked by default. Only loopback and RFC-1918 ranges are allowed. If you intended to scan a LAN host that happens to be in an unusual range, set `PORTSCANNER_ALLOW_LAN=1`.

### Scan shows 0 open ports but services are running

Verify the service is listening on `127.0.0.1` and not just on a specific interface. Run `ss -tlnp` or `lsof -i TCP -sTCP:LISTEN` to check.