Pingus

A simple ping tool. Supports TCP / UDP / ICMP protocol.
Currently some functions are WIP.

Table of Content

• Installation
• Simple Example
• API
  • Class: pingus.Ping
    • Event: 'ready'
    • Event: 'result'
    • Event: 'error'
    • ping.send()
  • Class: pingus.PingTCP Extends: pingus.Ping
    • new PingTCP(options)
    • pingtcp.send()
    • pingtcp.scan()
  • Class: pingus.PingUDP Extends: pingus.Ping
    • new PingUDP(options)
    • pingudp.send()
    • pingudp.scan()
  • Class: pingus.PingICMP Extends: pingus.Ping
    • new PingICMP(options)
    • pingicmp.send()
    • pingicmp.traceroute()
  • Class: pingus.RangeScanner (WIP)
    • new RangeScanner(options) (WIP)
  • pingus.tcp(options[, callback])
  • pingus.tcpscan(options[, callback])
  • pingus.udp(options[, callback])
  • pingus.udpscan(options[, callback])
  • pingus.icmp(options[, callback])
  • pingus.traceroute(options[, callback])
• Usage
  • Send Ping Styles
  • TCP Ping
  • Scan TCP Ports
  • UDP Ping
  • Scan UDP Ports
  • ICMP Ping
  • Traceroute
  • Using RangeScanner (WIP)

Installation

npm i pingus

Simple Example

// TCP Ping to localhost:22
import pingus from 'pingus'; // ESM
pingus.tcp({ host: 'localhost', port: 22 }).then(console.log);

// Result
{
  error: undefined,
  type: 'ping/tcp',
  status: 'open',
  host: 'localhost',
  ip: '127.0.0.1',
  ips: [ '127.0.0.1' ],
  time: 2,
  port: 22,
  name: 'ssh',
  banner: 'SSH-2.0-OpenSSH_8.9p1 Ubuntu-3'
}

API

Class: pingus.Ping

pingus.Ping is EventEmitter with the following events:

Event: 'ready'

• result <Object>

Emitted when ready (Resolve DNS, Filter Bogon IP) to send ping after call ping.send().

import pingus from 'pingus';

const ping = new pingus.PingTCP({
  host: 'example.com',
});
ping.on('ready', (result) => {
  console.log('ping\ttarget:\t', result.host);
  console.log('\tips:\t', result.ips);
});
ping.send();

ping    target: example.com
        ips: [ '93.184.216.34', '2606:2800:220:1:248:1893:25c8:1946' ]

Event: 'result'

• result <Object>

Result of ping data.

import pingus from 'pingus';

const ping = new pingus.PingTCP({
  host: 'example.com',
});
ping.on('result', (result) => {
  console.log(result);
});
ping.send();

{
  error: undefined,
  type: 'ping/tcp',
  status: 'open',
  host: 'example.com',
  ip: '93.184.216.34',
  ips: [ '93.184.216.34', '2606:2800:220:1:248:1893:25c8:1946' ],
  time: 127,
  port: 80,
  name: 'http',
  banner: ''
}

Event: 'error'

• <Error>
• result <Object>

Emitted when an error occurs. result has last statement before error occurs and error code.

ping.send()

Send ping. See some of examples in Usage

Class: pingus.PingTCP Extends: pingus.Ping

Class for TCP ping.
pingus.PingTCP is type of pingus.Ping

new PingTCP(options)

• options <Object>
  • host <string> Set target hostname (domain) or ip address.
  • port <number> Set target port when using pingtcp.send(). Default: 80
  • ports <Array> Set target ports when using pingtcp.scan().
  • timeout <number> Set timeout. Default: 2000
  • dnsResolve <boolean> Resolve DNS A and AAAA records when host is domain address. Default: true
  • dnsServer <string> Set DNS server to resolve DNS records.
  • filterBogon <boolean> Filter bogon ip address in host. Default: true

pingtcp.send()

See ping.send(). Some of examples in Usage.

pingtcp.scan()

Scan ports using TCP ping. Return result on Event: 'result'. See some of examples in Usage.

Class: pingus.PingUDP Extends: pingus.Ping

Class for UDP ping.
pingus.PingUDP is type of pingus.Ping

new PingUDP(options)

• options <Object>
  • host <string> Set target hostname (domain) or ip address.
  • port <number> Set target port when using pingudp.send(). Default: 68
  • ports <Array> Set target ports when using pingudp.scan().
  • bytes <number> Set random bytes length when send on UDP ping socket connected. Ignored when body options set. Default: 32
  • body <string> Set body when send on UDP ping socket connected.
  • timeout <number> Set timeout. Default: 2000
  • dnsResolve <boolean> Resolve DNS A and AAAA records when host is domain address. Default: true
  • dnsServer <string> Set DNS server to resolve DNS records.
  • filterBogon <boolean> Filter bogon ip address in host. Default: true

pingudp.send()

See ping.send(). Some of examples in Usage.

pingudp.scan()

Similar with pingtcp.scan().
Scan ports using UDP ping. Return result on Event: 'result'. See some of examples in Usage.

Class: pingus.PingICMP Extends: pingus.Ping

Class for ICMP ping.
pingus.PingICMP is type of pingus.Ping

new PingICMP(options)

• options <Object>
  • host <string> Set target hostname (domain) or ip address.
  • ttl <number> Set ttl. Default: 128
  • ttln <number> Set start ttl when using pingicmp.traceroute(). Default: 1
  • ttlx <number> Set max ttl when using pingicmp.traceroute(). Default: 64
  • timeout <number> Set timeout. Default: 2000
  • timeoutx <number> Set max timeout-stack when using pingicmp.traceroute(). Default: 8
  • dnsResolve <boolean> Resolve DNS A and AAAA records when host is domain address. Default: true
  • dnsServer <string> Set DNS server to resolve DNS records.
  • filterBogon <boolean> Filter bogon ip address in host. Default: true

pingicmp.send()

See ping.send(). Some of examples in Usage.

pingicmp.traceroute()

Run traceroute. Some of examples in Usage.

pingus.tcp(options[, callback])

Send TCP ping using Callback or Promise (async/await).
See some of examples in Send Ping Styles.

pingus.tcpscan(options[, callback])

Scan ports using TCP ping in Callback or Promise (async/await).
See some of examples in Send Ping Styles.

pingus.udp(options[, callback])

Send UDP ping using Callback or Promise (async/await).
See some of examples in Send Ping Styles.

pingus.udpscan(options[, callback])

Scan ports using UDP ping in Callback or Promise (async/await).
See some of examples in Send Ping Styles.

pingus.icmp(options[, callback])

Send ICMP ping using Callback or Promise (async/await).
See some of examples in Send Ping Styles.

pingus.traceroute(options[, callback])

Run traceroute using Callback or Promise (async/await).
See some of examples in Send Ping Styles.

Usage

ESM

import pingus from 'pingus';

CJS

const pingus = require('pingus').default;

Send Ping Styles

Using Class extends EventEmitter

// TCP ping to localhost:80
new pingus.PingTCP({ host: 'localhost' })
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();

Using Callback

// TCP ping to localhost:80
pingus.tcp({ host: 'localhost' }, (err, result) => {
  if (err) {
    throw err;
  }
  console.log(result);
});

Using Promise

// TCP ping to localhost:80
pingus
  .tcp({ host: 'localhost' })
  .then((result) => {
    console.log(result);
  })
  .catch((err) => {
    throw err;
  });

Using async/await

// TCP ping to localhost:80
const result = await pingus.tcp({ host: 'localhost' });
console.log(result);

{
  error: undefined,
  type: 'ping/tcp',
  status: 'open',
  host: 'localhost',
  ip: '127.0.0.1',
  ips: [ '127.0.0.1' ],
  time: 2,
  port: 80,
  name: 'http',
  banner: ''
}

TCP Ping

// TCP ping to localhost:22
new pingus.PingTCP({ host: 'localhost', port: 22 })
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();

{
  error: undefined,
  type: 'ping/tcp',
  status: 'open',
  host: 'localhost',
  ip: '127.0.0.1',
  ips: [ '127.0.0.1' ],
  time: 1,
  port: 22,
  name: 'ssh',
  banner: 'SSH-2.0-OpenSSH_8.9p1 Ubuntu-3'
}

Scan TCP Ports

// TCP ping scan to localhost
new pingus.PingTCP({
  host: 'localhost',
  ports: [21, 22, 80, 443, 3306, 8080],
})
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .scan();

{
  error: undefined,
  type: 'ping/tcp/scan',
  status: 'finish',
  host: 'localhost',
  ip: '127.0.0.1',
  ips: [ '127.0.0.1' ],
  time: 2008,
  ports: [ 21, 22, 80, 443, 3306, 8080 ],
  statuses: {
    open: [ 22, 80, 8080 ],
    reset: [],
    close: [ 21, 443, 3306 ],
    filtered: [],
    error: []
  },
  names: {
    '21': 'ftp',
    '22': 'ssh',
    '80': 'http',
    '443': 'https',
    '3306': 'mysql',
    '8080': 'http-alt'
  },
  banners: { '22': 'SSH-2.0-OpenSSH_8.9p1 Ubuntu-3' },
  errors: {}
}

UDP Ping

// UDP ping to localhost:19132
new pingus.PingUDP({ host: 'localhost', port: 19132 })
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();

{
  error: undefined,
  type: 'ping/udp',
  status: 'close',
  host: 'localhost',
  ip: '127.0.0.1',
  ips: [ '127.0.0.1' ],
  time: 2,
  port: 19132,
  name: 'minecraft-be'
}

Scan UDP Ports

// UDP ping scan to localhost
new pingus.PingUDP({
  host: 'localhost',
  ports: [67, 68, 161, 162, 445],
})
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .scan();

{
  error: undefined,
  type: 'ping/udp/scan',
  status: 'finish',
  host: 'localhost',
  ip: '127.0.0.1',
  ips: [ '127.0.0.1' ],
  time: 2003,
  ports: [ 67, 68, 161, 162, 445 ],
  statuses: {
    open: [ 68 ],
    reset: [],
    close: [ 67, 161, 162, 445 ],
    filtered: [],
    error: []
  },
  names: {
    '67': 'bootps',
    '68': 'bootpc',
    '161': 'snmp',
    '162': 'snmptrap',
    '445': 'microsoft-ds'
  },
  banners: {},
  errors: {}
}

ICMP Ping

// ICMP ping to example.com
new pingus.PingICMP({ host: 'example.com' })
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();

{
  error: undefined,
  type: 'ping/icmp',
  status: 'reply',
  host: 'example.com',
  ip: '93.184.216.34',
  ips: [ '93.184.216.34', '2606:2800:220:1:248:1893:25c8:1946' ],
  time: 122,
  ttl: 128,
  bytes: 8,
  reply: {
    source: '93.184.216.34',
    type: 0,
    code: 0,
    typestr: 'ECHO_REPLY',
    codestr: 'NO_CODE'
  }
}

// ICMP ping to example.com using ttl = 10
new pingus.PingICMP({ host: 'example.com', ttl: 10 })
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();

{
  error: undefined,
  type: 'ping/icmp',
  status: 'exception',
  host: 'example.com',
  ip: '93.184.216.34',
  ips: [ '93.184.216.34', '2606:2800:220:1:248:1893:25c8:1946' ],
  time: 127,
  ttl: 10,
  bytes: 8,
  reply: {
    source: '152.195.76.133',
    type: 11,
    code: 0,
    typestr: 'TIME_EXCEEDED',
    codestr: 'NO_CODE'
  }

Traceroute

// Traceroute to example.com
new pingus.PingICMP({ host: 'example.com', timeout: 500 })
  .on('result', (result) => {
    console.log(result);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .traceroute();

{
  error: undefined,
  type: 'ping/icmp/traceroute',
  status: 'finish',
  host: 'example.com',
  ip: '93.184.216.34',
  ips: [ '93.184.216.34', '2606:2800:220:1:248:1893:25c8:1946' ],
  time: 1174,
  hops: [
    { status: 'time_exceeded', ip: '10.0.0.1', ttl: 1 },
    { status: 'time_exceeded', ip: '121.175.134.1', ttl: 2 },
    { status: 'time_exceeded', ip: '112.173.92.9', ttl: 3 },
    { status: 'time_exceeded', ip: '112.174.173.177', ttl: 4 },
    { status: 'timeout', ip: null, ttl: 5 },
    { status: 'time_exceeded', ip: '112.190.28.17', ttl: 6 },
    { status: 'time_exceeded', ip: '112.174.91.82', ttl: 7 },
    { status: 'time_exceeded', ip: '112.174.87.102', ttl: 8 },
    { status: 'time_exceeded', ip: '206.223.123.14', ttl: 9 },
    { status: 'time_exceeded', ip: '152.195.76.133', ttl: 10 },
    { status: 'reply', ip: '93.184.216.34', ttl: 11 }
  ]
}