/tcp-exists

A small function to check if some tcp endpoint exists.

Primary LanguageJavaScriptMIT LicenseMIT

tcp-exists

npm tests CodeQL CodeFactor Grade JavaScript Style Guide node-current GitHub

Check if some tcp endpoint (or many) exists. Can be used as a port scanner

  • Zero-dependency
  • Small — just 3 functions
  • Fast — scans 65536 endpoints in ~9sec (via tcpExistsMany)
  • ESM and CJS

CLI Install

npm i -g tcp-exists

CLI Usage

tcp-exists --help # print full cli docs 
tcp-exists example.com # scan 20 most popular ports for given host
tcp-exists example.com:22,80,443,8000-10000,27017 # example how to provide list/ranges of ports 
tcp-exists example.com:22 another.org:1-65535 # example how to scan several endpoints

Install

npm i tcp-exists --save

Description

tcpExistsOne(host, port[, timeout[, signal]])

Arguments:

  • host <string>
  • port <string> | <number>
  • timeout <number> - optional number of ms. Default: DEFAULT_TIMEOUT
  • signal <AbortSignal> - optional. An AbortSignal that may be used to close a socket and return result ASAP.

Returns:

  • <Promise<boolean>>

Usage

import { tcpExistsOne } from 'tcp-exists'

const exist = await tcpExistsOne('8.8.8.8', 53, 25)
// check existance of endpoint 8.8.8.8:53 with timeout in 25ms

console.log(exist) // true

tcpExistsChunk(endpoints[, options])

It is an async function to check multiple endpoints. If size of endpoints you want to check more than 4096 then recommended to use generator function tcpExistsMany or increase timeout.

Arguments:

  • endpoints <[string, string|number][]> - array of [host, port]
  • options <object> - optional
    • timeout <number> - optional number of ms to execute on chunk. How to pick the best timeout Default: DEFAULT_TIMEOUT
    • returnOnlyExisted <boolean> - optional flag to exclude all non-existed results. Default: true
    • signal <AbortSignal> - optional. An AbortSignal that may be used to close a sockets and return result ASAP.

Returns:

  • <Promise<[string, string|number, boolean][]>> - will return array of [host, port, existed]

Usage:

import { tcpExistsChunk } from 'tcp-exists'

const endpoints = [
  ['8.8.8.8', 53],
  ['8.8.8.8', 80],
  ['8.8.8.8', 443],
  ['8.8.8.8', 8080]
]

const result = await tcpExistsChunk(endpoints)

console.log(result)
// all existed endpoints in format [host, port, existed][]

tcpExistsMany(endpoints[, options])

It is an async generator. So you can use it with for await (... of ...) or as a stream (check nodejs documentation).

Useful to use with large amount of endpoints.

Arguments:

  • endpoints <[string, string|number][]|string> - array of [host, port] or string in format host:port,port2; host2; host3:port0-port9
  • options <object> - optional
    • chunkSize <number> - optional chunk size of endpoints to process at once. Default: DEFAULT_CHUNK_SIZE
    • timeout <number> - optional number of ms to execute on chunk. How to pick the best timeout Default: DEFAULT_TIMEOUT
    • returnOnlyExisted <boolean> - optional flag to exclude all non-existed results. Default: true
    • signal <AbortSignal> - optional. An AbortSignal that may be used to close a sockets, stop iteration and return last chunk result ASAP.

Returns:

  • <AsyncIterable<[host:string, port:string|number, exist:boolean][]>> - generator will yield array of [host, port, existed]

Usage

import { tcpExistsMany } from 'tcp-exists'

const result = []

for await (const existedEndpoints of tcpExistsMany('localhost:1-65535')) {
  result.push(...existedEndpoints)
}

console.log(result)
// all existed endpoints in format [host, port, existed][]

getEndpoints(argument[, defaultPorts])

It is a generator. So you can use it with for (... of ...) or destruct into array [...getEndpoints('example.com:1-65535')]

Arguments:

  • argument <string|string[]> - string in format host:port,port2; host2; host3:port0-port9 or array like this ['host1', 'host2:port1,port2', 'host3:port0-port9']
  • defaultPorts <string> - optional. Comma separated string of ports. Default: DEFAULT_PORTS

Returns:

  • <Generator<[string, string|number]>> - generator will yield array of [host, port]

Usage

import { getEndpoints, tcpExistsOne } from 'tcp-exists'

for (const [host, port] of getEndpoints('localhost:1-65535')) {
  if (await tcpExistsOne(host, port)) console.log(host, port, 'exists')
}

Constants

DEFAULT_CHUNK_SIZE

  • <number> : 2300

DEFAULT_TIMEOUT

  • <number> : 250 ms

DEFAULT_PORTS

  • <string> : '21,22,23,25,53,80,110,111,135,139,143,443,445,993,995,1723,3306,3389,5900,8080'

Notes

Best timeout and chunkSize

The best timeout usually is the ninth of the endpoint's size, but at least 100ms.

For example, better to pick timeout as 220ms for a chunk of 2000 endpoints.

Also, you can take into account latency to the endpoint. If your endpoint has latency 300ms then better to pick timeout as 350ms and chunkSize as 3100.

P.S.

There is better alternative of port scanner to use in shell written in rust RustScan (scans 65536 ports in 3s)

License (MIT)