ssh_tunnel_proxy 1.2.10 → 2.0.1

package/README.md

@@ -1,111 +1,188 @@
 # ssh_tunnel_proxy
 Initiate a ssh reverse tunnel proxy with forwarding ports
 
-ssh_tunnel_proxy can function as a stand-alone api, nodejs command line script or as part of an electron_js app. To setup a ssh tunnel, parameters are suppled for host, port, authentication and a list of proxy ports. If a ngrok api key is provided the host and port of the ngrok tunnel are obtained. A list of port forwards is provided and is validated to restrict connections to system ports on the remote host to a list of pre-defined ports such as http or https. After establishing a ssh connection on the remote server, local proxy port forwards are opened. If the connection is interrupted or connection errors occur, attempts are made re-establish the tunnel.
+ssh_tunnel_proxy is a wrapper to ssh2 that provides async functionality as well as an extension to the api to include methods to setup a list of proxy forwards, exec a list of commands or startup a terminal shell. To setup a ssh tunnel, parameters are suppled for host, port, authentication and a list of proxy ports or commands to invoke. If a ngrok api key is provided the host and port of the ngrok tunnel are obtained. If the connection is interrupted or connection errors occur, attempts are made re-establish the tunnel.
 
-Example command line to establish a list of local forwards:
+In addition to the node api, a command line function called ssh-node2 is included to start ssh sessions in a manner similar to the ssh command line utility.
+
+### Command line examples
+
+Initialize ssh2 command:
+```
+npm i ssh_tunnel_proxy -g
+```
+Connect to remote host and establish local forwards:
 
 ```
-node main.js -c
+ssh2-node -i=~/.ssh/<private_key> -L=8180:192.168.1.1:80 <username>@<hostname>
+```
+
+Connect to host with parameters stored in ~/.config/ssh_tunnel_proxy/config.json:
+
+```
+ssh2-node rh2
 ```
 
 default config file, located at:
 ~/.config/ssh_tunnel_proxy/config.json
 ```json
 [{
-  "enabled": true,
+  "hostname":"rh2",
   "username": "<username>",
-  "password": "",
-  "host": "",
-  "port": "",
   "proxy_ports": [
     "8280:127.0.0.1:80",
     "9000:127.0.0.1:9000",
     "8122:192.168.2.1:22"
   ],
-  "whitelist": {
-    "80": true,
-    "443": true,
-    "22": true
-  },
-  "service_name": "ssh_proxy_client",
-  "server_name": "test",
+  "private_key_filename":"~/.ssh/<private key>",
   "ngrok_api": "<ngrok api key>"
 }]
 ```
 
-Command line to execute a series of commands on remote host:
+Execute command on remote host
 ```
-node main.js -c -e='uptime' -e='ls -all'
+ssh2-node rh2 "ls -all"
 ```
 
-Or execute commands defined in default config:
+### List of command-line options (compatible with original ssh2 command):
 ```
-node main.js -c
-```
-```json
-[{
-  "enabled": true,
-  "username": "<username>",
-  "service_name": "ssh_proxy_client",
-  "server_name": "test",
-  "exec" : [
-    "uptime",
-    "ls -all"
-  ],
-  "ngrok_api": "<ngrok api key>"
-}]
+Usage: ssh2-node [options] [userhost] [exec...]
+
+Nodejs ssh2 command line client
+
+Arguments:
+  userhost                                          Connect to hostname in config.
+  exec                                              Command to exec on remote host (must be in quotes)
+
+Options:
+  -V, --version                                     output the version number
+  -2 --protocolv2 [protocolv2]                      Forces ssh to try protocol version 2 only.
+  -4 --ipv4only [ipv4only]                          Forces ssh to use IPv4 addresses only.
+  -6 --ipv6only [ipv6only]                          Forces ssh to use IPv6 addresses only.
+  -A --forward_enable [forward_enable]              Enables forwarding of the authentication agent
+                                                    connection.
+  -a --forward_disable [forward_disable]            Disables forwarding of the authentication agent
+                                                    connection.
+  -b --bind [bind]                                  bind_address
+  -C --compress [compress]                          Requests compression of all data
+  -c --cipher [cipher]                              cipher_spec
+  -D --dynamic_forward [dynamic_forward]             Specifies a local 'dynamic' application-level
+                                                    port forwarding.
+  -e --escape [escape]                              escape_char Sets the escape character for
+                                                    sessions with a pty.
+  -F --config [config]                              configfile
+  -f --background [background]                      Requests ssh to go to background just before
+                                                    command execution.
+  -g --local_forward_remote [local_forward_remote]  Allows remote hosts to connect to local forwarded
+                                                    ports.
+  -I --smartcard [smartcard]                        smartcard_device Specify the device ssh.
+  -i --identity [identity]                          Private key filename.
+  -K --gssapi_auth [gssapi_auth]                    Enables GSSAPI-based authentication and
+                                                    forwarding (delegation) of GSSAPI credentials to
+                                                    the server.
+  -k --gssapi_disable [gssapi_disable]              Disables forwarding (delegation) of GSSAPI
+                                                    credentials to the server.
+  -L --local_forward_out [local_forward_out...]     bind_address:port:host:hostport
+  -l --login_name [login_name]                      login_name
+  -M --master_mode [master_mode]                    Places the ssh client into 'master' mode for
+                                                    connection sharing. Multiple -M options
+  -m --mac_spec [mac_spec]                          mac_spec
+  -N --no_exec [no_exec]                            Do not execute a remote command.
+  -n --redirect_stdin [redirect_stdin]              Redirects stdin from /dev/null
+  -O --ctl_cmd [ctl_cmd]                            ctl_cmd
+  -o --option [option]                              option
+  -p --port [port]                                  port Port to connect to on the remote host.
+  -q --quiet [quiet]                                Quiet mode. Causes most warning and diagnostic
+                                                    messages to be suppressed.
+  -R --local_forward_in [local_forward_in...]       bind_address:port:host:hostport
+  -S --ctl_path [ctl_path]                          ctl_path Specifies the location of a control
+                                                    socket for connection sharing.
+  -s --subsystem [subsystem]                        May be used to request invocation of a subsystem
+                                                    on the remote system.
+  -T --disable_tty [disable_tty]                    Disable pseudo-tty allocation.
+  -t --force_tty [force_tty]                        Force pseudo-tty allocation.
+  -V --version [version]                            Display the version number and exit.
+  -v --verbose [verbose]                            Verbose mode. Causes ssh to print debugging
+                                                    messages about its progress.
+  -W --forward_stdin_stdout [forward_stdin_stdout]  host:port Requests that standard input and output
+                                                    on the client be forwarded to host on port ver
+                                                    the secure channel.
+  -w --tunnel [tunnel]                              Requests tunnel device forwarding with the
+                                                    specified tun(4) devices between the client
+                                                    (local_tun) and the server (remote_tun).
+  -X --x11 [x11]                                    Enables X11 forwarding.
+  -x --x11_disable [x11_disable]                    Disables X11 forwarding.
+  -Y --x11_trusted [x11_trusted]                    Enables trusted X11 forwarding.
+  -y --log [log]                                    Send log information using the syslog(3)
+  -H --ngrok [ngrok]                                Obtain connectiion hostport from ngrok
+  -J --keychain_service [keychain_service]          Service name to obtain private key from system
+                                                    keychain.
+  -j --keychain_account [keychain_account]          Account name to obtain private key from system
+                                                    keychain.
+  -h, --help                                        display help for command
 ```
+### Api examples
 
-Start a terminal session on the remote host:
-```
-node main.js -c -S
-```
-
-Example use of api to exec remote commands using async await and processing result through streams. Complete example is in test/test_remote_exec.js:
+Exec remote commands using async await and processing result through streams.
 
 ```js
-// lsLongShellProc to json stream test
-async function lsTest(sshTunnelProxy) {
-    return new Promise(async (resolve) => {
-
-        // exec remote command and pipe data through tunnel until end of data
-        const tunnel = new PassThrough();
-        pipeline(tunnel,
-            split(),
-            to_lsParse(),
-            to_JSONString(),
-            process.stdout,
-            () => { }
-        );
-
-        const lscmd = 'ls -all';
-        console.log('\ninvoking ' + lscmd + ' on remote host:\n');
-        await sshTunnelProxy.execCmd(lscmd, tunnel);
-
-        // stream processing complete
-        console.log('ls -all completed');
-        resolve();
+// send result of cmd through pipeline, generating a stream of json objects
+function lsTest(cmdProxy, cmd, destination) {
+
+    return new Promise( (resolveCmd) => {
+
+             // set input of pipeline to split data into lines (npm i split)
+            const tunnel = split();
+
+            // when pipeline is ready exec shell cmd
+            const pipelineReady = (socket) => {
+
+                return new Promise((resolve) => {
+
+                  // invoke command on remote host and send results to pipeline
+                  cmdProxy.execCmd(cmd, tunnel)
+
+                        // stream processing complete, cleanup pipeline and exit
+                        .then(() => {
+                            //self.cleanupPipeline(socket);
+                            resolveCmd();
+                        });
+                    resolve();
+                })
+            }
+
+            // pipe shell cmd result through json parser pipeline to destination
+            pipeline(tunnel,
+                self.parse(),
+                self.toJSONString(),
+                destination,
+                pipelineReady
+            );
     })
 }
 
-async function runTests() {
+async function runCmd() {
 
-    const sshTunnelProxy = new SSHTunnelProxy();
+  const opts = {
+    "hostname":"rh2",
+    "username": "<username>",
+    "private_key_filename":"~/.ssh/<private key>",
+    "ngrok_api": "<ngrok api key>"
+  }
 
-    // connect to remote host
-    await sshTunnelProxy.connectSSH(opts);
+  const sshTunnelProxy = new SSHTunnelProxy();
 
-    // invoke ls -all on remote host and parse result to json object string
-    await lsTest(sshTunnelProxy);
+  // connect to remote host
+  await sshTunnelProxy.connectSSH(opts);
 
-    process.exit();
+  // invoke ls -all on remote host and parse result to json object string
+  await lsTest(sshTunnelProxy, 'ls -all', process.stdout);
 }
 
-runTests();
+runCmd();
 ```
 
-The following code is an example of use of the api with electronjs.
+Example of use of the api with electronjs.
 
 main.js:
 ```js

package/dist/cjs/index.d.ts

@@ -0,0 +1,65 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { Server, Socket } from 'net';
+import { Writable } from 'stream';
+import { EventEmitter } from 'events';
+import { Client, Channel } from 'electron-ssh2';
+import { KeypairStorage } from './keypair_storage';
+import { NgrokApi } from './ngrok_service';
+import { main } from './ssh2-node';
+interface Listener {
+    [key: string]: Server;
+}
+export type SSHConfig = {
+    hostname: string;
+    username: string;
+    password?: string;
+    host?: string;
+    port?: string;
+    proxy_ports?: Array<string>;
+    remote_ports?: Array<string>;
+    private_key?: string | null;
+    private_key_filename?: string | null;
+    disabled?: boolean;
+    server_name?: string;
+    service_name?: string;
+    compress?: string;
+    cypher?: string;
+    exec?: Array<string>;
+    shell?: boolean;
+    ngrok_api?: string;
+    keepaliveInterval?: number;
+};
+export declare class SSHTunnelProxy extends EventEmitter {
+    protected client: Client;
+    protected keypairStorage: KeypairStorage;
+    protected config: SSHConfig;
+    protected listener: Listener;
+    protected retries: number;
+    protected networkOnline: boolean;
+    protected _tunnelReadyTimeout: ReturnType<typeof setTimeout>;
+    debug_en: boolean;
+    debug_ssh: boolean;
+    constructor();
+    protected close_sockets(proxy_ports: Array<string>): void;
+    protected setup_ssh_forward(socket: Socket, remote_hostname: string, remote_port: string): void;
+    setupProxyPorts(proxy_ports: Array<string>): Promise<void>;
+    execCmd(cmd: string, dataStream?: Writable, errStream?: Writable): Promise<void>;
+    protected remote_shell(err: Error, stream: Channel): void;
+    protected cleanup_events(client: Client): void;
+    do_ssh_connect(opts: SSHConfig): Promise<void>;
+    validate_port_number(port: number, whitelist: object): boolean;
+    validate_local_forward(proxy_ports: Array<string>, whitelist: object): boolean;
+    protected ssh_retry_connect(opts: SSHConfig): void;
+    protected ssh_start_tunnel(opts: SSHConfig): Promise<unknown>;
+    connectSSH(opts: SSHConfig, whitelist: object | null): Promise<void>;
+    onNetworkOnline(): void;
+    onNetworkOffline(): void;
+    generateAndStoreKeypair(serviceName: string, account: string): void;
+    getPublicKey(serviceName: string, account: string): void;
+    getClient(): Client;
+    protected debug(...args: any[]): void;
+}
+export { KeypairStorage, NgrokApi, main as sshcli };