Pingus icon indicating copy to clipboard operation
Pingus copied to clipboard

Published 20 hours ago • verified publisher icon Amuject
→

Metadata

A simple network ping tool in nodejs. Supports TCP / UDP / ICMP protocol.

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.

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

API

Class: pingus.Ping

pingus.Ping is EventEmitter with the following events:

Event: 'ready'

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('result', (result) => {
  console.log('ping\ttarget:\t', result.host);
  console.log('\tips:\t', result.ips);
});
ping.send();
Result (Console Output) 
ping    target: example.com
        ips: [ '93.184.216.34', '2606:2800:220:1:248:1893:25c8:1946' ]

Event: 'result'

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();
Result (Console Output) 
{
  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'

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);
  })
  .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);
Result (Console Output) 
{
  type: 'ping/tcp',
  status: 'open',
  host: 'localhost',
  ip: IP { label: '127.0.0.1' },
  ips: [ IP { label: '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();
Result (Console Output) 
{
  type: 'ping/tcp',
  status: 'open',
  host: 'localhost',
  ip: IP { label: '127.0.0.1' },
  ips: [ IP { label: '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();
Result (Console Output) 
{
  type: 'ping/tcp/scan',
  status: 'finish',
  host: 'localhost',
  ip: IP { label: '127.0.0.1' },
  ips: [ IP { label: '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);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();
Result (Console Output) 
{
  type: 'ping/udp',
  status: 'close',
  host: 'localhost',
  ip: IP { label: '127.0.0.1' },
  ips: [ IP { label: '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();
Result (Console Output) 
{
  error: undefined,
  type: 'ping/udp/scan',
  status: 'finish',
  host: 'localhost',
  ip: IP { label: '127.0.0.1' },
  ips: [ IP { label: '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);
  })
  .catch((error) => {
    throw error;
  });
Result (Console Output) 
{
  type: 'ping/udp',
  status: 'open',
  host: '255.255.255.255',
  ip: IP { label: '255.255.255.255' },
  ips: [ IP { label: '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);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();
Result (Console Output) 
{
  type: 'ping/icmp',
  status: 'reply',
  host: 'example.com',
  ip: IP { label: '93.184.216.34' },
  ips: [
    IP { label: '93.184.216.34' },
    IP { label: '2606:2800:0220:0001:0248:1893:25c8:1946' }
  ],
  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);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();
Result (Console Output) 
{
  type: 'ping/icmp',
  status: 'exception',
  host: 'example.com',
  ip: IP { label: '93.184.216.34' },
  ips: [
    IP { label: '93.184.216.34' },
    IP { label: '2606:2800:0220:0001:0248:1893:25c8:1946' }
  ],
  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);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .traceroute();
Result (Console Output) 
{
  type: 'ping/icmp/traceroute',
  status: 'finish',
  host: 'example.com',
  ip: IP { label: '93.184.216.34' },
  ips: [
    IP { label: '93.184.216.34' },
    IP { label: '2606:2800:0220:0001:0248:1893:25c8:1946' }
  ],
  time: 1040,
  ttl: 128,
  bytes: 32,
  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.86.130', ttl: 7 },
    { status: 'time_exceeded', ip: '112.174.88.218', ttl: 8 },
    { status: 'time_exceeded', ip: '206.72.210.112', ttl: 9 },
    { status: 'time_exceeded', ip: '152.195.76.133', ttl: 10 },
    { status: 'reply', ip: '93.184.216.34', ttl: 11 }
  ]
}

← Metadata

16
Stars
3
Forks
Watchers

Owner

verified publisher icon Amuject

Metadata

A simple network ping tool in nodejs. Supports TCP / UDP / ICMP protocol.

Back