Skip to content

usage.md

Latest commit

 

History

History
150 lines (107 loc) · 4.31 KB

usage.md

File metadata and controls

150 lines (107 loc) · 4.31 KB
Raw

Port Scanner Usage

Legal and ethical use

Use this tool only on hosts and networks you own or have explicit permission to test. Unauthorized scanning or exploitation is prohibited.

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Basic Scan

Scan a host with default ports and connect mode (dev/service ports):

./build/pulsescan-cpp localhost

Scan specific ports:

./build/pulsescan-cpp localhost -p 22,80,443,8000-8010

Use banner mode:

./build/pulsescan-cpp localhost -m banner --banner-timeout 1.0 --banner-bytes 256

Use UDP mode:

./build/pulsescan-cpp localhost -m udp -t 1.5

Scan multiple hosts:

./build/pulsescan-cpp localhost 127.0.0.1 ::1 -p 22,80

JSON output (one JSON object per line):

./build/pulsescan-cpp localhost --output json

Default output (text) uses a report-style summary for one-shot scans.

Ping Mode

Repeat scans on an interval and only report changes:

./build/pulsescan-cpp localhost --ping --interval 2

The first pass prints all results. Subsequent passes only print CHANGE ... lines.

ICMP Ping

ICMP echo ping (requires root or CAP_NET_RAW):

sudo ./build/pulsescan-cpp 192.168.1.1 --icmp-ping

Ping a range or CIDR:

sudo ./build/pulsescan-cpp 192.168.1.50-70 --icmp-ping -c 3
sudo ./build/pulsescan-cpp 192.168.1.0/24 --icmp-ping -c 1

Options

  • host: target host(s) (IP or DNS)
  • -p, --ports: comma list and ranges (example: 22,80,8000-8010)
  • --top-ports: scan top N common ports from the built-in list (example: --top-ports 20)
  • -t, --timeout: per-connection timeout in seconds
  • --max-inflight: max concurrent attempts
  • -m, --mode: connect, banner, or udp
  • --output: output format (text or json)
  • --version: print version information
  • --banner-timeout: banner wait timeout in seconds
  • --banner-bytes: max banner bytes
  • --ping: enable ping mode
  • --interval: ping interval in seconds
  • --open: only print open ports
  • --debug-dns: log DNS resolution results
  • -v, --verbose: verbose tracing
  • -4: IPv4 only
  • -6: IPv6 only
  • --icmp-ping: ICMP echo ping mode
  • -c, --icmp-count: ICMP echo count per host
  • --reverse-dns: resolve PTR records for target IPs
  • Sandboxing is enabled by default (Landlock on Linux, Capsicum on FreeBSD). On FreeBSD, Capsicum applies to numeric IP, IPv4 CIDR, and IPv4 range targets; hostname and --reverse-dns scans require DNS and therefore run without Capsicum.

Bash Completion

Install completion (after cmake --install):

sudo cp scripts/completions/pulsescan-cpp.bash /usr/share/bash-completion/completions/pulsescan-cpp

Enable in your shell:

source /usr/share/bash-completion/completions/pulsescan-cpp

Default Ports

When --ports is not specified, the scanner uses a built-in set of development and service ports:

22,80,443,3000,3001,3002,4000,4200,5000,5001,5173,5432,5672,6379,8000,8080,8081,8082,8443,9000,9090,9092,9200,9300,11211,15672,2181,27017,3306,6006,9222,9229

Input and range limits

Ports must be complete integers in 1..65535. Port ranges may be reversed; repeated ports are scanned once. Empty lists and malformed tokens are rejected. --max-inflight accepts 1..65535, and --banner-bytes accepts 1..512. Timeouts and the repeat interval must be finite and between 0.001 and 2147483.647 seconds.

IPv4 ranges and the combined resolved targets in a scan cycle are limited to 65,536 addresses. Larger ranges (including /0) are rejected before allocation. Address/port pairs are generated on demand. Text reports appear as each address finishes, so their ordering can differ from input order.

Banner output encoding

Terminal banner text displays printable ASCII directly and escapes other bytes as \xNN. Backslashes are doubled. This prevents server-supplied escape sequences from changing the terminal or injecting extra lines.

JSON banner results include banner_text (the same sanitized display form) and banner_base64 (the exact received bytes, encoded with standard padded Base64). These fields are absent when no banner was received. detail is display text; use banner_base64 for binary processing. Other JSON string fields preserve valid UTF-8 and replace malformed bytes with U+FFFD.