Skip to content
/ Pingus Public

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

License

Notifications You must be signed in to change notification settings

Amuject/Pingus

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

75 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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'
  toPrimitiveJSON: [Function (anonymous)]
}

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) => {
  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 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'

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)

pingicmp.send()

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

pingicmp.traceroute()

Run traceroute. Some of examples in Usage.

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

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;
  });
// 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 }
    }
  ]
}