netport

Fast, CPU-friendly, minimalist, light-weight promise-based network utility tool for the Node.

Features

• Fast and Efficient: Designed to minimize CPU usage while providing quick results.
• Promise-Based: Utilizes JavaScript promises for better asynchronous handling.
• Supports TCP and UDP: Check both TCP and UDP ports with ease.
• Minimalistic Design: Simple and straightforward API for easy integration.

Installation

To get started with netport, simply run the following command in your terminal:

npm command

$ npm i netport

yarn command

$ yarn add netport

Getting started

First, require this library to your project as follows:

const netport = require("netport");

If it's an ES Module then import it to your project as follows:

import netport from "netport";

Note

New to Promises?

If you're not familiar with promises, check out the MDN documentation to learn more.

Api usage

Once you've imported netport into your project, you're ready to start working using netport!

scanPort() function

The scanPort() function scans a specified port on a specified host and checks whether it is open for the specified protocol (TCP or UDP).

Parameters

The scanPort() function parameters are as follows -

• type: The type of port to scan ("TCP" or "UDP"). Default is "TCP".
• port: The port number to check.
• host: The hostname or IP address of the target.
• timeout: The timeout duration in milliseconds. Default is 1000 ms.

TCP port scan

Example demonstrating TCP port scan:

// First example regarding TCP port scan.
(async () => {
    try {
        const result = await netport.scanPort({
            type: "TCP", // Specify the type of port to scan (TCP)
            port: 53,    // DNS port (commonly used for DNS queries)
            host: "8.8.8.8", // Google Public DNS IP address
            timeout: 1000 // Set timeout to 1000 milliseconds
        });

        console.log(`TCP Port ${result.port}: ${result.success ? 'Open' : 'Closed'} - ${result.message}`);
        // result object contains -
        // - port: The port number that was scanned
        // - success: Indicates if the port is open
        // - message: A message providing additional information about the scan
    } catch (err) {
        // Handling the error.
        console.error(err);
    }
})();

UDP port scan

Example demonstrating UDP port scan:

// Second example regarding UDP port scan.
(async () => {
    try {
        const result = await netport.scanPort({
            type: "UDP", // Specify the type of port to scan (UDP)
            port: 123,   // NTP port (commonly used for Network Time Protocol)
            host: "pool.ntp.org", // Public NTP server
            timeout: 1000 // Set timeout to 1000 milliseconds
        });

        console.log(`UDP Port ${result.port}: ${result.success ? 'Open' : 'Closed'} - ${result.message}`);
        // result object contains -
        // - port: The port number that was scanned
        // - success: Indicates if the port is open
        // - message: A message providing additional information about the scan
    } catch (err) {
        // Handling the error.
        console.error(err);
    }
})();

scanPorts() Function

The scanPorts() function scans a range of ports on a specified host and checks whether they are open for the specified protocol (TCP or UDP).

Parameter

The scanPorts() function parameters are as follows -

• type: The type of port to scan ("TCP" or "UDP"). Default is "TCP".
• from: The starting port number.
• to: The ending port number.
• host: The hostname or IP address of the target.
• timeout: The timeout duration in milliseconds. Default is 1000 ms.
• maxConcurrency: The maximum number of concurrent port checks to perform. Default is 100.

TCP ports scan

Example demonstrating TCP ports scan:

// First example regarding TCP ports scan.
(async () => {
    try {
        const results = await netport.scanPorts({
            type: "TCP",        // Specify the type of ports to scan (TCP)
            from: 1,           // Starting from port 1
            to: 100,           // Scanning up to port 100
            host: "8.8.8.8",   // Google Public DNS IP address
            timeout: 1000,     // Set timeout to 1000 milliseconds for each port check
            maxConcurrency: 50  // Optional: Set maximum concurrent connections (default is 100)
        });

        // Results returned is an array of objects.
        results.forEach(result => {
            console.log(`TCP Port ${result.port}: ${result.success ? 'Open' : 'Closed'} - ${result.message}`);
            // - result.port: The port number that was scanned
            // - result.success: Indicates if the port is open (true) or closed (false)
            // - result.message: Additional information about the scan result
        });
    } catch (err) {
        // Handling any errors that occur during the scan.
        console.error('Error during port scan:', err);
    }
})();

UDP ports scan

Example demonstrating UDP ports scan:

// Second example regarding UDP ports scan.
(async () => {
    try {
        const results = await netport.scanPorts({
            type: "UDP",            // Specify the type of ports to scan (UDP)
            from: 1,               // Starting from port 1
            to: 100,               // Scanning up to port 100
            host: "pool.ntp.org",  // Public NTP server for time synchronization
            timeout: 1000,         // Set timeout to 1000 milliseconds for each port check
            maxConcurrency: 50      // Optional: Set maximum concurrent connections (default is 100)
        });

        // Results returned is an array of objects.
        results.forEach(result => {
            console.log(`UDP Port ${result.port}: ${result.success ? 'Open' : 'Closed'} - ${result.message}`);
            // - result.port: The port number that was scanned
            // - result.success: Indicates if the port is open (true) or closed (false)
            // - result.message: Additional information about the scan result
        });
    } catch (err) {
        // Handling any errors that occur during the scan.
        console.error('Error during UDP port scan:', err);
    }
})();

discoverLocalDevices()

The discoverLocalDevices() function performs a high-performance "smart scan" of your local network. It identifies active devices, guesses their Operating System via TTL (Time To Live), and attempts to grab banners from common ports to increase detection confidence.

The discoverLocalDevices() function accepts an optional configuration object:

• timeout: The timeout for each device probe in milliseconds. Default is 1000 ms.
• maxConcurrency: The maximum number of IP addresses to probe simultaneously. Default is 50.

(async () => {
    try {
        console.log("Scanning local network... please wait.");
        
        const devices = await netport.discoverLocalDevices({
            timeout: 800,
            maxConcurrency: 60
        });

        console.log(`Found ${devices.length} active devices:`);
        
        devices.forEach(device => {
            console.log(`IP Address : ${device.ip}`);
            console.log(`Status     : ${device.status}`);
            console.log(`OS (Guess) : ${device.os}`);
            console.log(`Confidence : ${device.confidence}%`);
            
            if (device.services.length > 0) {
                console.log(`Services   : ${device.services.join(', ')}`);
            }
        });
    } catch (err) {
        console.error('Error during network discovery:', err);
    }
})();

LICENSE

netport is released under the MIT License.

View the full license terms here.

Bugs & Issues

Found a bug or want a new feature?

Report issues and request features on the netport issue tracker.

Thanks for reading!

Have a great day ahead :D