Gathering detailed insights and metrics for tunnel-ssh
Installations
npm install tunnel-sshDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS
Node Version
23.1.0
NPM Version
10.9.0
Score
88.2
Supply Chain
96.5
Quality
76.5
Maintenance
100
Vulnerability
98.9
License
Releases
Unable to fetch releases
Contributors
29
Unable to fetch Contributors
Languages
1
JavaScript
JavaScript (100%)
Love this project? Help keep it running — sponsor us today! 🚀
Developer
agebrock
Download Statistics
Total Downloads
36,874,224
Last Day
6,197
Last Week
153,524
Last Month
798,124
Last Year
7,621,542
GitHub Statistics
MIT License
362 Stars
156 Commits
96 Forks
18 Watchers
8 Branches
29 Contributors
Updated on Jan 23, 2025
Bundle Size
326.16 kB
Minified
92.56 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
5.2.0
Package Id
tunnel-ssh@5.2.0
Unpacked Size
16.06 kB
Size
5.51 kB
File Count
7
NPM Version
10.9.0
Node Version
23.1.0
Published on
Dec 15, 2024
Total Downloads
Cumulative downloads
Total Downloads
36,874,224
Last Day
0.3%
6,197
Compared to previous day
Last Week
-17.6%
153,524
Compared to previous week
Last Month
65.1%
798,124
Compared to previous month
Last Year
14%
7,621,542
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
1
Tunnel-SSH
==========
1ssh -L [LOCAL_IP:]LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER
History and Credits
Once upon a time this package was created to show my colleges how to create and publish a npm package. That time we used ssh tunnels on our unix machines on a daily bases, so decided to to do it with node. This was about 6 years ago, where javascript was a callback hell.
Since then this project is pretty much community driven by pull requests and suggestions.
Thank you for your support.
Special thanks goes to the following brothers in arms: Tunnel-ssh is based on the fantastic ssh2 library by Brian White.
Vlad Barboni for the initial brainstorming. derekrliang for providing the type definitions. lenchvolodymyr for the idea of the dynamic port mapping.
Changelog
5.1.0
- Improved Typescript support
- sshOptions.username default is root
- forwardOptions.dstAddr default to 0.0.0.0 (all interfaces)
Concept
Tunnel-ssh v5 is designed to be very extendable and does not provide as much sematic sugar as prio versions.
The design goal was to use the original settings for each part used in the project to be able to use all possible binding features from client and server.
The configuration is separated in the following parts:
- Tunnel server
- TCP Server
- SSH Client
- SSH Forwarding
Tunnel Server Options
This configuration controls be behaviour of the tunnel server. Currently there is only one option available.
Example:
1const tunnelOptions = { 2 autoClose:true 3}
autoclose - closes the Tunnel-Server once all clients disconnect from the server. Its useful for tooling or scripts that require a temporary ssh tunnel to operate. For example a mongodump.
Set this option to false will keep the server alive until you close it manually.
TCP Server options
Controls the behaviour of the tcp server on your local machine. For all possible options please refere to the official node.js documentation: ServerListenOptions
Example:
1const serverOptions = { 2 host:'127.0.0.1', 3 port: 27017 4}
If port is omitted or is 0, the operating system will assign an arbitrary unused port, which can be retrieved by using server.address().port after the 'listening' event has been emitted.
To use the automatic assigned port in the forwardOptions make sure forwardOptions.srcPort is not defined.
SSH client options
Options to tell the ssh client how to connect to your remote machine. For all possible options please refere to the ssh2 documentation: ssh2 documentation You will find different examples there for using a privateKey, password etc..
SSH Agent additional information.
The most common settings for the agent are :
1 // for linux 2 { 3 host:'myhost.com' 4 agent:process.env.SSH_AUTH_SOCK 5 } 6 // for windows 7 { 8 agent:'pageant' 9 } 10 // for windows with unix port (wsl docker 11 { 12 agent:'\\\\.\\pipe\\openssh-ssh-agent' 13 } 14
Example:
1const sshOptions = { 2 host: '192.168.100.100', 3 port: 22, 4 username: 'frylock', 5 password: 'nodejsrules' 6};
SSH Forwarding options
Options to control the source and destination of the tunnel.
Example:
1const forwardOptions = { 2 srcAddr:'0.0.0.0', 3 srcPort:27017, 4 dstAddr:'127.0.0.1', 5 dstPort:27017 6}
Note: If the srcAddr or srcPort is not defined, the adress will be taken from the local TCP server. This is usefull if you want to create a tunnel and let the OS decide what port should be used.
Example:
1 const tunnelOptions = { 2 autoClose:true 3 } 4 5 const sshOptions = { 6 host: '192.168.100.100', 7 port: 22, 8 username: 'frylock', 9 password: 'nodejsrules' 10 }; 11 12 // Here is where the magic happens... 13 const serverOptions = null; // automatic assign port by OS 14 15 // Note that the forwarding options does not define the srcAddr and srcPort here. 16 // to use the server configuration. 17 const forwardOptions = { 18 dstAddr:'127.0.0.1', 19 dstPort:27017 20 } 21 22 23 let [server, client] = await createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions); 24 25 // Example how to get the server port information. 26 console.log(`server listen on ${server.address().port}`)
API
Tunnel-SSH exposes currently only one method: createTunnel
1createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions);Typescript
Since 5.0.9 we added our own types to the project. For Typescript we export the configuration objects as well. The recommented way of import is as follows:
1import {createTunnel, ForwardOptions, ServerOptions, SshOptions} from 'tunnel-ssh'; 2 3// please note that the ForwardingOptions, ServerOptions and SshOptions are Types
The method retuns a promise containing the server and ssh-client instance. For most cases you will not need those instances. But in case you want to extend the functionallity you can use them to bind to there events like that:
1createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions). 2then(([server, conn], error)=>{ 3 4 server.on('error',(e)=>{ 5 console.log(e); 6 }); 7 8 conn.on('error',(e)=>{ 9 console.log(e); 10 }); 11});
For a list of all possible Events please refere to the node.js documentation for the server and the ssh2 documentation for the client.
Usage Example
The following example shows how to connect to a remote mongodb and bind it to all local interfaces.
1import {createTunnel} from 'tunnel-ssh'; 2 3const port = 27017; 4 5const tunnelOptions = { 6 autoClose:true 7}; 8const serverOptions = { 9 port: port 10}; 11const sshOptions = { 12 host: '192.168.100.100', 13 port: 22, 14 username: 'frylock', 15 password: 'nodejsrules' 16}; 17const forwardOptions = { 18 srcAddr:'0.0.0.0', 19 srcPort:port, 20 dstAddr:'127.0.0.1', 21 dstPort:port 22}; 23 24let [server, conn] = await createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions); 25 26server.on('connection', (connection) =>{ 27 console.log('new connection'); 28});
Too complicated ?
If you just searching for an easy way to forward a remote port to your local machine try the following:
1 2import {createTunnel} from 'tunnel-ssh'; 3const sshOptions = { 4 host: '192.168.100.100', 5 port: 22, 6 username: 'frylock', 7 password: 'nodejsrules' 8}; 9 10function mySimpleTunnel(sshOptions, port, autoClose = true){ 11 let forwardOptions = { 12 srcAddr:'127.0.0.1', 13 srcPort:port, 14 dstAddr:'127.0.0.1', 15 dstPort:port 16 } 17 18 let tunnelOptions = { 19 autoClose:autoClose 20 } 21 22 let serverOptions = { 23 port: port 24 } 25 26 return createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions); 27} 28 29await mySimpleTunnel(sshOptions, 27017); 30
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
no dangerous workflow patterns detected
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
0 existing vulnerabilities detected
Reason
dependency not pinned by hash detected -- score normalized to 3
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/agebrock/tunnel-ssh/npm-publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/agebrock/tunnel-ssh/npm-publish.yml/master?enable=pin
- Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
- Info: 1 out of 1 npmCommand dependencies pinned
Reason
3 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 2
Reason
Found 6/22 approved changesets -- score normalized to 2
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/npm-publish.yml:1
- Info: no jobLevel write permissions found
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 14 are checked with a SAST tool
Score
4
/10
Last Scanned on 2025-02-10
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More