Pingus

A simple ping tool. Supports TCP / UDP / ICMP protocol.

Pingus can...

Send ICMP echo request & ttl traceroute.
Send ping, scan to TCP / UDP ports & banner grabbing.
Send magic packet (Wake on LAN) using UDP ping.

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()
  • Using Callback or Promise (async/await)
    • pingus.tcp(options[, callback])
    • pingus.tcpscan(options[, callback])
    • pingus.udp(options[, callback])
    • pingus.udpscan(options[, callback])
    • pingus.wol(mac, options[, callback])
    • pingus.icmp(options[, callback])
    • pingus.traceroute(options[, callback])
• Usage
  • Use Pingus
  • Send Ping Styles
  • TCP Ping
  • Scan TCP Ports
  • UDP Ping
  • Scan UDP Ports
  • Wake on LAN
  • ICMP Ping
  • Traceroute

Installation

npm i pingus

If an error occurs during installation, it may be due to the installation failure of the following packages.

• raw-socket

It can be fixed by installing the GCC compiler.

• In Ubuntu:

  sudo apt-get install -y build-essential

• In Windows:

  Install Visual Studio including the Desktop development with C++ workload.

Simple Example

// TCP Ping to localhost:22
import pingus from 'pingus'; // ESM, Typescript
const pingus = require('pingus'); // CJS

pingus.tcp({ host: 'localhost', port: 22 }).then(console.log);

// Result
{
  type: 'ping/tcp',
  status: 'open',
  host: 'localhost',
  ip: IP { label: '127.0.0.1' },
  ips: [ IP { label: '127.0.0.1' } ],
  time: 2,
  port: 22,
  name: 'ssh',
  banner: 'SSH-2.0-OpenSSH_8.9p1 Ubuntu-3'
  toPrimitiveJSON: [Function (anonymous)]
}

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) => {
  const data = result.toPrimitiveJSON();
  console.log('ping\ttarget:\t', data.host);
  console.log('\tips:\t', data.ips);
});
ping.send();

Result (Console Output)

ping    target:  example.com
        ips:     [ '93.184.215.14', '2606:2800:021f:cb07:6820:80da:af6b:8b2c' ]

Event: 'result'

• result <Object>

Result of ping data.

import pingus from 'pingus';

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

Result (Console Output)

{
  type: 'ping/tcp',
  status: 'open',
  host: 'example.com',
  ip: '93.184.215.14',
  ips: [ '93.184.215.14', '2606:2800:021f:cb07:6820:80da:af6b:8b2c' ],
  time: 134,
  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>|<string> Set target ports when using pingtcp.scan(). Use array of port numbers or query strings. See example.
  • timeout <number> Set timeout. Default: 2000
  • resolveDNS <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

Example of options.ports

ports: [21, 22, 80, 443]; // Scan port 21, 22, 80, 443

ports: '21,22,80,443'; // Scan port 21, 22, 80, 443

ports: '21-80'; // Scan ports in range 21 to 80 (21, 22, 23 ... 78, 79, 80)

ports: '21-25,80,443'; // Scan ports in range 21 to 25 and 80, 443

ports: '@'; // Scan most used 1024 ports in protocol

ports: '*'; // Scan all ports (1 to 65535)

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>|<string> Set target ports when using pingudp.scan(). Use array of port numbers or query strings. Same as PingTCP. See example.
  • buffer <Buffer> Set buffer when send on UDP ping socket connected.
  • body <string> Set body when send on UDP ping socket connected. Ignored when buffer options set.
  • bytes <number> Set random bytes length when send on UDP ping socket connected. Ignored when body options set. Default: 32
  • timeout <number> Set timeout. Default: 2000
  • resolveDNS <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
  • resolveDNS <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.

Using Callback or Promise (async/await)

See examples in Send Ping Styles.

pingus.tcp(options[, callback])

Send TCP ping.

pingus.tcpscan(options[, callback])

Scan ports using TCP ping.

pingus.udp(options[, callback])

Send UDP ping.

pingus.udpscan(options[, callback])

Scan ports using UDP ping.

pingus.wol(mac, options[, callback])

• mac <string> Set target MAC address.
• options <Object> Same as options of new PingUDP(options)

Send magic packet UDP ping to use WOL feature.

pingus.icmp(options[, callback])

Send ICMP ping.

pingus.traceroute(options[, callback])

Run traceroute.

Usage

Use Pingus

ESM (TypeScript)

import pingus from 'pingus';

CJS

const pingus = require('pingus');

Send Ping Styles

Using Class extends EventEmitter

// TCP ping to localhost:80
new pingus.PingTCP({ host: 'localhost' })
  .on('result', (result) => {
    console.log(result.toPrimitiveJSON());
  })
  .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.toPrimitiveJSON());
  })
  .catch((err) => {
    throw err;
  });

Using async/await

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

Result (Console Output)

{
  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.toPrimitiveJSON());
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();

Result (Console Output)

{
  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'
}

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.toPrimitiveJSON());
  })
  .on('error', (err, result) => {
    throw err;
  })
  .scan();

Result (Console Output)

{
  type: 'ping/tcp/scan',
  status: 'finish',
  host: 'localhost',
  ip: '127.0.0.1',
  ips: [ '127.0.0.1' ],
  time: 2009,
  port: 80,
  name: 'http',
  banner: '',
  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.toPrimitiveJSON());
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();

Result (Console Output)

{
  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.toPrimitiveJSON());
  })
  .on('error', (err, result) => {
    throw err;
  })
  .scan();

Result (Console Output)

{
  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: {}
}

Wake on LAN

// Send magic packet using UDP ping to 00-00-00-00-00-00
pingus
  .wol('00-00-00-00-00-00')
  .then((result) => {
    console.log(result.toPrimitiveJSON());
  })
  .catch((error) => {
    throw error;
  });

Result (Console Output)

{
  type: 'ping/udp',
  status: 'open',
  host: '255.255.255.255',
  ip: '255.255.255.255',
  ips: [ '255.255.255.255' ],
  time: 2,
  port: 9,
  name: 'discard'
}

ICMP Ping

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

Result (Console Output)

{
  type: 'ping/icmp',
  status: 'reply',
  host: 'example.com',
  ip: '93.184.215.14',
  ips: [ '93.184.215.14', '2606:2800:021f:cb07:6820:80da:af6b:8b2c' ],
  time: 130,
  ttl: 128,
  bytes: 32,
  reply: {
    source: '93.184.216.34',
    type: 0,
    code: 0,
    typestr: 'ECHO_REPLY',
    codestr: 'NO_CODE',
    body: '767284c4'
  }
}

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

Result (Console Output)

{
  type: 'ping/icmp',
  status: 'exception',
  host: 'example.com',
  ip: '93.184.215.14',
  ips: [ '93.184.215.14', '2606:2800:021f:cb07:6820:80da:af6b:8b2c' ],
  time: 133,
  ttl: 10,
  bytes: 32,
  reply: {
    source: '152.195.76.133',
    type: 11,
    code: 0,
    typestr: 'TIME_EXCEEDED',
    codestr: 'NO_CODE',
    body: ']8X"\b\x00CQ\x00\x00\x00\x00'
  }
}

Traceroute

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

Result (Console Output)

{
  type: 'ping/icmp/traceroute',
  status: 'finish',
  host: 'example.com',
  ip: '93.184.215.14',
  ips: [ '93.184.215.14', '2606:2800:021f:cb07:6820:80da:af6b:8b2c' ],
  time: 7614,
  ttl: 128,
  bytes: 32,
  hops: [
    {
      status: 'time_exceeded',
      ip: '172.19.80.1',
      ttl: 1,
      rtt: { min: 0, max: 1, avg: 1 }
    },
    {
      status: 'time_exceeded',
      ip: '172.30.1.254',
      ttl: 2,
      rtt: { min: 0, max: 1, avg: 1 }
    },
    {
      status: 'timeout',
      ip: null,
      ttl: 3,
      rtt: { min: 2001, max: 2002, avg: 2002 }
    },
    {
      status: 'time_exceeded',
      ip: '112.188.59.77',
      ttl: 4,
      rtt: { min: 2, max: 3, avg: 3 }
    },
    {
      status: 'time_exceeded',
      ip: '112.188.53.13',
      ttl: 5,
      rtt: { min: 1, max: 2, avg: 2 }
    },
    {
      status: 'time_exceeded',
      ip: '112.174.47.177',
      ttl: 6,
      rtt: { min: 7, max: 8, avg: 8 }
    },
    {
      status: 'time_exceeded',
      ip: '112.174.91.130',
      ttl: 7,
      rtt: { min: 7, max: 8, avg: 8 }
    },
    {
      status: 'time_exceeded',
      ip: '112.174.87.102',
      ttl: 8,
      rtt: { min: 129, max: 130, avg: 130 }
    },
    {
      status: 'time_exceeded',
      ip: '206.72.210.112',
      ttl: 9,
      rtt: { min: 127, max: 128, avg: 128 }
    },
    {
      status: 'time_exceeded',
      ip: '152.195.76.151',
      ttl: 10,
      rtt: { min: 132, max: 134, avg: 133 }
    },
    {
      status: 'reply',
      ip: '93.184.215.14',
      ttl: 11,
      rtt: { min: 126, max: 126, avg: 126 }
    }
  ]
}