❤

npm

Sign UpSign In

pingus

1.1.12 • Public • Published

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.


Currently some functions are WIP (IP Range Scan).

Table of Content

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'

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();
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
    • 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

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
    • 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)

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(options[, callback])

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

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);
Result (Console Output) 
{
  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();
Result (Console Output) 
{
  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();
Result (Console Output) 
{
  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();
Result (Console Output) 
{
  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();
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({ mac: '00-00-00-00-00-00' })
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    throw error;
  });
Result (Console Output) 
{
  error: undefined,
  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);
  })
  .on('error', (err, result) => {
    throw err;
  })
  .send();
Result (Console Output) 
{
  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();
Result (Console Output) 
{
  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();
Result (Console Output) 
{
  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 }
  ]
}

Keywords

Install

npm i pingus

Repository

Gitgithub.com/wnynya/Pingus

Homepage

github.com/wnynya/Pingus#readme

DownloadsWeekly Downloads

15

Version

1.1.12

License

MIT

Unpacked Size

410 kB

Total Files

17

Last publish

Collaborators

  • wnynya
Try on RunKit
Report malware