Registry / http-networking / node-netstat

node-netstat

JSON →
library1.9.0jsnpmunverified

node-netstat is a JavaScript utility library designed to programmatically read and parse `netstat` data on various operating systems. It is currently at version 1.9.0 and provides a callback-based API for processing network connection information line by line. The library supports filtering results by properties like PID or protocol and offers both synchronous and asynchronous execution. Key differentiators include its cross-platform compatibility (tested on Ubuntu 14.04/16.04, Windows 7, and OS X Yosemite), extensibility via custom parsers and filters, and the ability to cancel ongoing `watch` operations. While `netstat` itself is considered obsolete on some Linux systems in favor of `ss`, node-netstat provides a unified interface for accessing this data where available, making it suitable for system monitoring and debugging tools in Node.js environments.

http-networkingobservabilitydevops
npm install node-netstat
github ↗package ↗
INSTALL
IMPORT
SIG · NODE-NETSTAT
N
node-netstat
http-networkingjavascriptv1.9.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

netstat
✓ const netstat = require('node-netstat');
✗ import netstat from 'node-netstat';
This library primarily uses CommonJS `require()` syntax. There is no explicit ESM export listed in the README, so direct ES module import might not work without a transpiler or Node.js loader configuration.
netstat.parsers.linux
✓ const netstat = require('node-netstat'); netstat.parsers.linux = netstat.parserFactories.linux({ parseName: true });
To customize platform-specific parsers, like enabling process name parsing for Linux, access them via the `netstat` object. This pattern is for modifying internal behavior rather than direct import.
netstat.version
✓ const netstat = require('node-netstat'); console.log(netstat.version);
The library version is exposed as a property on the main `netstat` object, not as a separate import.

This quickstart demonstrates how to use `node-netstat` to asynchronously retrieve and filter network connection data. It shows how to apply filters for PID and protocol, limit the output, handle errors with the `done` callback, and conditionally stop processing results early from within the line handler function.

const netstat = require('node-netstat'); // Get network connections, filtering by a specific PID and protocol, // limiting the results to the first 5 entries. netstat({ filter: { pid: process.env.TARGET_PID ? parseInt(process.env.TARGET_PID) : 1, // Example PID, adjust as needed protocol: 'tcp' }, limit: 5, done: (err) => { if (err) { console.error('Netstat command failed:', err); return; } console.log('Netstat command completed.'); } }, function (data) { // Process each line of netstat data console.log('Netstat item:', data); // Example: stop processing after finding a specific state if (data.state === 'ESTABLISHED') { console.log('Found an ESTABLISHED connection, stopping further processing.'); return false; // Returning false stops the stream } });
Debug
Known issues
gotchaThe `parseName` option for the Linux parser is `false` by default. If you require `processName` in your results on Linux, you must explicitly enable it by reconfiguring the parser via `netstat.parsers.linux = netstat.parserFactories.linux({ parseName: true });`.
fix
Set `parseName: true` when initializing the Linux parser factory for `netstat.parsers.linux` to include process names in the output.
affects: >=1.0.0
gotchaReturning `false` from the `handler` function will immediately stop processing any further netstat results. This is a design feature for early termination but can be a gotcha if not intended, potentially leading to incomplete data collection.
fix
Ensure your `handler` function only returns `false` when you explicitly want to stop processing the stream of netstat results. Otherwise, omit an explicit return or return `true`.
affects: >=1.0.0
gotchaOn some modern Linux distributions, the `netstat` command-line utility is considered obsolete and `ss` is the recommended replacement. While `node-netstat` wraps the `netstat` command, its underlying reliability might be affected by system-level changes or deprecations of the `netstat` command itself. Ensure `net-tools` (which provides `netstat`) is installed on Linux systems if you encounter issues.
fix
Verify that the `netstat` utility is available and correctly installed on the target system. For new projects or critical applications, consider alternatives that use newer tools like `ss` or `procfs` for network statistics if `node-netstat` encounters issues on a specific OS version.
affects: >=1.0.0
gotchaWhen using the `watch` option for continuous monitoring, the `netstat` function returns a handler object with a `cancel()` method. Forgetting to call `cancel()` when monitoring is no longer needed can lead to resource leaks or indefinitely running processes.
fix
Store the return value of `netstat()` when using `watch: true`. Call `handler.cancel()` to stop the watching process when it's no longer required, typically in cleanup routines or when the application is shutting down.
affects: >=1.0.0
Errors
Common errors & fixes
Error: spawn netstat ENOENT
The `netstat` command-line utility is not found in the system's PATH. This often occurs on minimal Linux installations or Windows systems where `netstat.exe` might not be readily accessible to Node.js.
fix
Install the `net-tools` package on Linux (e.g., `sudo apt-get install net-tools` or `sudo yum install net-tools`) or ensure the `netstat` executable's directory is included in the system's PATH environment variable on Windows or other OS. Alternatively, verify if the `platform` option is correctly set if overriding `os.platform()`.
Netstat is not finding a running localhost on MacOS Sonoma.
Specific operating system versions (like MacOS Sonoma) might have changes in `netstat` output or behavior that `node-netstat`'s parsers are not yet equipped to handle, leading to incomplete or incorrect results.
fix
Check the `node-netstat` GitHub issues for known compatibility problems with your specific OS version. If no solution is available, consider contributing a fix or using a different system monitoring tool. Temporary workarounds might involve adjusting `filter` options or inspecting the raw `netstat` output to identify parsing discrepancies.
Upgrade
Version history
1.9.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
2
Resources
githubhttps://github.com/danielkrainas/node-netstat ↗
packagehttps://www.npmjs.com/package/node-netstat ↗
node-netstat — npm install node-netstat · libregistry